| Summary: | Xkb{Get,Set}NamedIndicator spec & implementation don't match | ||
|---|---|---|---|
| Product: | XStandards | Reporter: | Alan Coopersmith <alan.coopersmith> |
| Component: | XKB | Assignee: | Daniel Stone <daniel> |
| Status: | RESOLVED FIXED | QA Contact: | Xorg Project Team <xorg-team> |
| Severity: | normal | ||
| Priority: | medium | ||
| Version: | X11R6.6 | ||
| Hardware: | All | ||
| OS: | All | ||
| Whiteboard: | |||
| i915 platform: | i915 features: | ||
| Bug Depends on: | |||
| Bug Blocks: | 6141 | ||
we really need to fix the documentation; i'll be needing to do some big updates as well. alan, do you know if we ever managed to get the framemaker stuff converted to something sensible? my kingdon for a fix for #874 http://people.freedesktop.org/~alanc/xkb/ has the conversions to MIF, HTML & XML (not sure what DTD) I did a few months ago when this last came up. Unfortunately, while I have access to a licensed version of Framemaker, I don't know how to use it, so this was the best I could figure out quickly on my own. If there's something better I can do, and you can point me to instructions for how to do it, let me know. (At least the HTML version seems to have questionable formatting.) thanks. i'll see what I can do with the XML. The XkbSetNamedIndicator & XkbGetNamedIndicator man pages recently committed to
libX11 also share this problem, since they were based on the library spec.
The bug in the Sun bug database for those notes:
The man page for XkbSetNamedIndicator lists a device_spec argument that
XkbSetNamedIndicator does not take, and does not document the XkbSetNamedDeviceIndicator variant that does take the device_spec.
The man page should be updated to correctly cover both forms of this function:
XkbSetNamedIndicator(dpy,name,changeState,state,createNewMap,pMap)
Display * dpy;
Atom name;
Bool changeState;
Bool state;
Bool createNewMap;
XkbIndicatorMapPtr pMap;
XkbSetNamedDeviceIndicator(dpy,device,class,id,name,changeState,
state,createNewMap,pMap)
Display * dpy;
unsigned device;
unsigned class;
unsigned id;
Atom name;
Bool changeState;
Bool state;
Bool createNewMap;
XkbIndicatorMapPtr pMap;
It should note that calling
XkbSetNamedIndicator(dpy,name,changeState,state,createNewMap,pMap)
is equivalent to calling
XkbSetNamedDeviceIndicator(dpy,XkbUseCoreKbd,
XkbDfltXIClass,XkbDfltXIId,
name,changeState,state,
createNewMap,pMap);
Additionally, in the description section, the phrase "and the optional parameter, state, is not NULL" should be removed from the second paragraph.
The state parameter is not optional and since it's not a pointer, can't be NULL.
The XkbGetNamedIndicator man page has a similar problem - the correct function
definitions for it are:
XkbGetNamedIndicator( Display * dpy,
Atom name,
int * pNdxRtrn,
Bool * pStateRtrn,
XkbIndicatorMapPtr pMapRtrn,
Bool * pRealRtrn)
XkbGetNamedDeviceIndicator( Display * dpy,
unsigned device,
unsigned class,
unsigned id,
Atom name,
int * pNdxRtrn,
Bool * pStateRtrn,
XkbIndicatorMapPtr pMapRtrn,
Bool * pRealRtrn)
XkbGetNamedIndicator(dpy,name,pNdxRtrn,pStateRtrn,pMapRtrn,pRealRtrn)
is equivalent to
XkbGetNamedDeviceIndicator(dpy,XkbUseCoreKbd, XkbDfltXIClass,XkbDfltXIId,
name,pNdxRtrn,pStateRtrn,pMapRtrn,pRealRtrn)
<http://bugs.opensolaris.org/bugdatabase/view_bug.do?bug_id=4528016>
|
Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.
The XKB Library Spec (Library Version 1.0 / Document Revision 1.1) in xc/docs/spec/XKB/XKBlib gives the following function definitions: Bool XkbGetNamedIndicator(dpy, dev_spec, name, ndx_rtrn, state_rtrn, map_rtrn, real_rtrn) [Section 8.3.3] Bool XkbSetNamedIndicator(dpy, device_spec, name, change_state, state, create_new, map) [Section 8.4.3] However, in the X.org libX11 implementation, neither function takes a device_spec argument - instead, variants named XkbGetNamedDeviceIndicator and XkbSetNamedDeviceIndicator are provided that add arguments device, class, and id to the above functions. Additionally, section 8.4.3 states: If change_state is True, and the optional parameter, state, is not NULL, XkbSetNamedIndicator tells the server to change the state of the named indicator to the value specified by state. However, state is a Bool, so can only be True or False, not NULL, so the phrase \""and the optional parameter, state, is not NULL\"" should be removed from the description.