[PATCH:libX11 1/2] Make Xkb{Get, Set}NamedIndicator spec & manpages match code
Alan Coopersmith
alan.coopersmith at oracle.com
Sun Mar 19 19:32:22 UTC 2017
The XKB Library spec and the man pages for XkbGetNamedIndicator &
XkbSetNamedIndicator included a device_spec argument neither function
takes, and do not include the XkbGetNamedDeviceIndicator &
XkbSetNamedDeviceIndicator variants that do take it (along with two
other arguments).
This updates them to match the interfaces the code has provided for
decades.
This has been reported multiple times, so this fixes:
https://bugs.freedesktop.org/show_bug.cgi?id=251
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=729812
Sun Bug 4528016 XkbSetNamedIndicator & XkbGetNamedIndicator man pages are wrong
(filed: alan.coopersmith at sun.com 2001-11-15 - now aka Oracle bug 15087506)
X.Org Group Defect Id #9418
Signed-off-by: Alan Coopersmith <alan.coopersmith at oracle.com>
---
man/xkb/Makefile.am | 2 +
man/xkb/XkbGetNamedDeviceIndicator.man | 1 +
man/xkb/XkbGetNamedIndicator.man | 58 +++++--
man/xkb/XkbSetNamedDeviceIndicator.man | 1 +
man/xkb/XkbSetNamedIndicator.man | 81 +++++++--
specs/XKB/ch08.xml | 292 ++++++++++++++++++++++++++++++---
6 files changed, 390 insertions(+), 45 deletions(-)
create mode 100644 man/xkb/XkbGetNamedDeviceIndicator.man
create mode 100644 man/xkb/XkbSetNamedDeviceIndicator.man
diff --git a/man/xkb/Makefile.am b/man/xkb/Makefile.am
index 484a85a..7632faa 100644
--- a/man/xkb/Makefile.am
+++ b/man/xkb/Makefile.am
@@ -111,6 +111,7 @@ libman_PRE = \
XkbGetKeyboardByName.man \
XkbGetMap.man \
XkbGetNameChanges.man \
+ XkbGetNamedDeviceIndicator.man \
XkbGetNamedGeometry.man \
XkbGetNamedIndicator.man \
XkbGetNames.man \
@@ -191,6 +192,7 @@ libman_PRE = \
XkbSetIndicatorMap.man \
XkbSetMap.man \
XkbSetModActionVMods.man \
+ XkbSetNamedDeviceIndicator.man \
XkbSetNamedIndicator.man \
XkbSetNames.man \
XkbSetPtrActionX.man \
diff --git a/man/xkb/XkbGetNamedDeviceIndicator.man b/man/xkb/XkbGetNamedDeviceIndicator.man
new file mode 100644
index 0000000..ebe427e
--- /dev/null
+++ b/man/xkb/XkbGetNamedDeviceIndicator.man
@@ -0,0 +1 @@
+.so man__libmansuffix__/XkbGetNamedIndicator.__libmansuffix__
diff --git a/man/xkb/XkbGetNamedIndicator.man b/man/xkb/XkbGetNamedIndicator.man
index 803d656..be65056 100644
--- a/man/xkb/XkbGetNamedIndicator.man
+++ b/man/xkb/XkbGetNamedIndicator.man
@@ -1,4 +1,4 @@
-.\" Copyright 1999 Oracle and/or its affiliates. All rights reserved.
+.\" Copyright 1999, 2017, Oracle and/or its affiliates. All rights reserved.
.\"
.\" Permission is hereby granted, free of charge, to any person obtaining a
.\" copy of this software and associated documentation files (the "Software"),
@@ -25,9 +25,19 @@ XkbGetNamedIndicator \- Look up the indicator map and other information for an
indicator by name
.SH SYNOPSIS
.HP
-.B Bool XkbGetNamedIndicator
+.B Bool XkbGetNamedDeviceIndicator
.BI "(\^Display *" "dpy" "\^,"
.BI "unsigned int " "dev_spec" "\^,"
+.BI "unsigned int " "led_class" "\^,"
+.BI "unsigned int " "led_id" "\^,"
+.BI "Atom " "name" "\^,"
+.BI "int *" "ndx_rtrn" "\^,"
+.BI "Bool *" "state_rtrn" "\^,"
+.BI "XkbIndicatorMapPtr " "map_rtrn" "\^,"
+.BI "Bool *" "real_rtrn" "\^);"
+.HP
+.B Bool XkbGetNamedIndicator
+.BI "(\^Display *" "dpy" "\^,"
.BI "Atom " "name" "\^,"
.BI "int *" "ndx_rtrn" "\^,"
.BI "Bool *" "state_rtrn" "\^,"
@@ -43,6 +53,12 @@ connection to the X server
.I \- dev_spec
keyboard device ID, or XkbUseCoreKbd
.TP
+.I \- led_class
+feedback class, or XkbDfltXIClass
+.TP
+.I \- led_id
+feedback ID, or XkbDfltXIId
+.TP
.I \- name
name of the indicator to be retrieved
.TP
@@ -65,16 +81,16 @@ to get the indicator names. Using names eliminates the need for hard-coding
bitmask values for particular keyboards. For example, instead of using
vendor-specific constants such as WSKBLed_ScrollLock mask on Digital
workstations or XLED_SCROLL_LOCK on Sun workstations, you can instead use
-.I XkbGetNamedIndicator
+.I XkbGetNamedDeviceIndicator
to look up information on the indicator named "Scroll Lock."
If the device specified by
.I device_spec
has an indicator named
-.I name, XkbGetNamedIndicator
+.IR name ", " XkbGetNamedDeviceIndicator
returns True and populates the rest of the parameters with information about the
indicator. Otherwise,
-.I XkbGetNamedIndicator
+.I XkbGetNamedDeviceIndicator
returns False.
The
@@ -95,22 +111,42 @@ Each of the "
" arguments is optional; you can pass NULL for any unneeded "
.I _rtrn
" arguments.
+
+.LP
+.I XkbGetNamedIndicator
+is a convenience function that calls
+.I XkbGetNamedDeviceIndicator
+with a
+.I device_spec
+of
+.BR XkbUseCoreKbd ,
+a
+.I led_class
+of
+.BR XkbDfltXIClass ,
+and a
+.I led_id
+of
+.BR XkbDfltXIId .
+It returns the return value from
+.IR XkbGetNamedDeviceIndicator .
+
.SH "RETURN VALUES"
.TP 15
True
The
-.I XkbGetNamedIndicator
-function returns True if the device specified by
+.IR XkbGetNamedIndicator " and " XkbGetNamedDeviceIndicator
+functions return True if the device specified by
.I device_spec
has an indicator named
-.I name.
+.IR name .
.TP 15
False
The
-.I XkbGetNamedIndicator
-function returns False if the device specified by
+.IR XkbGetNamedIndicator " and " XkbGetNamedDeviceIndicator
+functions return False if the device specified by
.I device_spec
does not have an indicator named
-.I name.
+.IR name .
.SH "SEE ALSO"
.BR XkbGetNames (__libmansuffix__)
diff --git a/man/xkb/XkbSetNamedDeviceIndicator.man b/man/xkb/XkbSetNamedDeviceIndicator.man
new file mode 100644
index 0000000..65b5e9d
--- /dev/null
+++ b/man/xkb/XkbSetNamedDeviceIndicator.man
@@ -0,0 +1 @@
+.so man__libmansuffix__/XkbSetNamedIndicator.__libmansuffix__
diff --git a/man/xkb/XkbSetNamedIndicator.man b/man/xkb/XkbSetNamedIndicator.man
index 5cd558d..52716b0 100644
--- a/man/xkb/XkbSetNamedIndicator.man
+++ b/man/xkb/XkbSetNamedIndicator.man
@@ -1,4 +1,4 @@
-.\" Copyright 1999 Oracle and/or its affiliates. All rights reserved.
+.\" Copyright 1999, 2017, Oracle and/or its affiliates. All rights reserved.
.\"
.\" Permission is hereby granted, free of charge, to any person obtaining a
.\" copy of this software and associated documentation files (the "Software"),
@@ -26,9 +26,19 @@ the state of the indicator; sets the indicator to a specified state and sets the
indicator map for the indicator
.SH SYNOPSIS
.HP
-.B Bool XkbSetNamedIndicator
+.HP
+.B Bool XkbSetNamedDeviceIndicator
.BI "(\^Display *" "dpy" "\^,"
.BI "unsigned int " "device_spec" "\^,"
+.BI "unsigned int " "led_class" "\^,"
+.BI "unsigned int " "led_id" "\^,"
+.BI "Atom " "name" "\^,"
+.BI "Bool " "change_state" "\^,"
+.BI "Bool " "state" "\^,"
+.BI "Bool " "create_new" "\^,"
+.BI "XkbIndicatorMapPtr " "map" "\^);"
+.B Bool XkbSetNamedIndicator
+.BI "(\^Display *" "dpy" "\^,"
.BI "Atom " "name" "\^,"
.BI "Bool " "change_state" "\^,"
.BI "Bool " "state" "\^,"
@@ -44,6 +54,12 @@ connection to the X server
.I \- device_spec
device ID, or XkbUseCoreKbd
.TP
+.I \- led_class
+feedback class, or XkbDfltXIClass
+.TP
+.I \- led_id
+feedback ID, or XkbDfltXIId
+.TP
.I \- name
name of the indicator to change
.TP
@@ -61,7 +77,7 @@ new map for the indicator
.SH DESCRIPTION
.LP
If a compatible version of the Xkb extension is not available in the server,
-.I XkbSetNamedIndicator
+.I XkbSetNamedDeviceIndicator
returns False. Otherwise, it sends a request to the X server to change the
indicator specified by
.I name
@@ -70,12 +86,12 @@ and returns True.
If
.I change_state
is True, and the optional parameter,
-.I state,
+.IR state ,
is not NULL,
-.I XkbSetNamedIndicator
+.I XkbSetNamedDeviceIndicator
tells the server to change the state of the named indicator to the value
specified by
-.I state.
+.IR state .
If an indicator with the name specified by
.I name
@@ -85,26 +101,45 @@ parameter tells the server whether it should create a new named indicator. If
.I create_new
is True, the server finds the first indicator that doesn't have a name and gives
it the name specified by
-.I name.
+.IR name .
If the optional parameter,
-.I map, is not NULL,
-.I XkbSetNamedIndicator
+.IR map ,
+is not NULL,
+.I XkbSetNamedDeviceIndicator
tells the server to change the indicator's map to the values specified in
-.I map.
+.IR map .
In addition, it can also generate XkbIndicatorStateNotify,
XkbIndicatorMapNotify, and XkbNamesNotify events.
+.LP
+.I XkbSetNamedIndicator
+is a convenience function that calls
+.I XkbSetNamedDeviceIndicator
+with a
+.I device_spec
+of
+.BR XkbUseCoreKbd ,
+a
+.I led_class
+of
+.BR XkbDfltXIClass ,
+and a
+.I led_id
+of
+.BR XkbDfltXIId .
+It returns the return value from
+.IR XkbSetNamedDeviceIndicator .
.SH "RETURN VALUES"
.TP 15
True
The
-.I XkbSetNamedIndicator
-function returns True if a compatible version of the Xkb extension is available in the server.
+.IR XkbSetNamedIndicator " and " XkbSetNamedDeviceIndicator
+functions return True if a compatible version of the Xkb extension is available in the server.
.TP 15
False
The
-.I XkbSetNamedIndicator
-function returns False if a compatible version of the Xkb extension is not available in the server.
+.IR XkbSetNamedIndicator " and " XkbSetNamedDeviceIndicator
+functions return False if a compatible version of the Xkb extension is not available in the server.
.SH DIAGNOSTICS
.TP 15
.B BadAtom
@@ -112,6 +147,24 @@ A name is neither a valid Atom or None
.TP 15
.B BadImplementation
Invalid reply from server
+.TP 15
+.B BadKeyboard
+.I device_spec
+does not specify a device with indicators.
+.TP 15
+.B BadMatch
+.I led_id
+is not
+.B DfltXIId
+and does not specify a feedback of the class specified by
+.I led_class
+on the device specified by
+.IR device_spec .
+.TP 15
+.B BadValue
+.I led_class
+does not specify
+.BR DfltXIClass ", " LedFeedbackClass ", or " KbdFeedbackClass .
.SH "SEE ALSO"
.BR XkbIndicatorMapNotify (__libmansuffix__),
.BR XkbIndicatorStateNotify (__libmansuffix__),
diff --git a/specs/XKB/ch08.xml b/specs/XKB/ch08.xml
index 3bb6be6..4e2872e 100644
--- a/specs/XKB/ch08.xml
+++ b/specs/XKB/ch08.xml
@@ -62,7 +62,7 @@ as discussed in <xref linkend="Symbolic_Names" />. Then set the map using
<function>XkbSetMap</function>
(see <link linkend="Changing_Map_Components_in_the_Server">section 14.3</link>)
or
-<function>XkbSetNamedIndicator</function>
+<function>XkbSetNamedDeviceIndicator</function>
(below). To retrieve indicator names, use
<function>XkbGetNames</function>
(<xref linkend="Symbolic_Names" />).
@@ -266,7 +266,7 @@ is not, and if you call a function which updates the server’s image of the
indicator map (such as
<function>XkbSetIndicatorMap</function>
or
-<function>XkbSetNamedIndicator</function>),
+<function>XkbSetNamedDeviceIndicator</function>),
Xkb changes the keyboard state and controls to reflect the other fields of
the indicator map, as described in the remainder of this section. If you
attempt to explicitly change the value of an indicator for which
@@ -840,7 +840,7 @@ implementation, uses a mask to specify the indicators. The second method, which
is more suitable for applications concerned with interoperability, uses
indicator names. The correspondence between the indicator name and the bit
position in masks is as follows: one of the parameters returned from
-<function>XkbGetNamedIndicator</function>
+<function>XkbGetNamedDeviceIndicator</function>
is an index that is the bit position to use in any function call that requires
a mask of indicator bits, as well as the indicator’s index into the
<structname>XkbIndicatorRec</structname>
@@ -1038,20 +1038,22 @@ of using vendor-specific constants such as
mask on Digital workstations or
<symbol>XLED_SCROLL_LOCK</symbol>
on Sun workstations, you can instead use
+<function>XkbGetNamedDeviceIndicator</function> or
<function>XkbGetNamedIndicator</function>
to look up information on the indicator named <quote>Scroll Lock.</quote>
</para>
<para>
Use
-<function>XkbGetNamedIndicator</function>
-to look up the indicator map and other information for an indicator by name.
+<function>XkbGetNamedDeviceIndicator</function>
+to look up the indicator map and other information for an indicator by name
+on a specific device.
</para>
-<indexterm significance="preferred" zone="XkbGetNamedIndicator"><primary><function>XkbGetNamedIndicator</function></primary></indexterm>
-<funcsynopsis id="XkbGetNamedIndicator">
+<indexterm significance="preferred" zone="XkbGetNamedDeviceIndicator"><primary><function>XkbGetNamedDeviceIndicator</function></primary></indexterm>
+<funcsynopsis id="XkbGetNamedDeviceIndicator">
<funcprototype>
- <funcdef>Bool <function>XkbGetNamedIndicator</function></funcdef>
+ <funcdef>Bool <function>XkbGetNamedDeviceIndicator</function></funcdef>
<!-- (
<parameter>dpy</parameter>,
<parameter>dev_spec</parameter>,
@@ -1064,6 +1066,8 @@ to look up the indicator map and other information for an indicator by name.
<paramdef>Display *<parameter>dpy</parameter></paramdef>
<paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
+ <paramdef>unsigned int <parameter>led_class</parameter></paramdef>
+ <paramdef>unsigned int <parameter>led_id</parameter></paramdef>
<paramdef>Atom <parameter>name</parameter></paramdef>
<paramdef>int *<parameter>ndx_rtrn</parameter></paramdef>
<paramdef>Bool *<parameter>state_rtrn</parameter></paramdef>
@@ -1094,6 +1098,26 @@ to look up the indicator map and other information for an indicator by name.
</varlistentry>
<varlistentry>
<term>
+ <parameter>led_class</parameter>
+ </term>
+ <listitem>
+ <para>
+ feedback class, or <symbol>XkbDfltXIClass</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>led_id</parameter>
+ </term>
+ <listitem>
+ <para>
+ feedback ID, or <symbol>XkbDfltXIId</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
<parameter>name</parameter>
</term>
<listitem>
@@ -1148,14 +1172,16 @@ to look up the indicator map and other information for an indicator by name.
<para>
If the device specified by
<parameter>device_spec</parameter>
+with feedback specified by
+<parameter>led_class</parameter> and <parameter>led_id</parameter>
has an indicator named
<parameter>name</parameter>,
-<function>XkbGetNamedIndicator</function>
+<function>XkbGetNamedDeviceIndicator</function>
returns
<symbol>True</symbol>
and populates the rest of the parameters with information about the indicator.
Otherwise,
-<function>XkbGetNamedIndicator</function>
+<function>XkbGetNamedDeviceIndicator</function>
returns
<symbol>False</symbol>.
</para>
@@ -1192,7 +1218,7 @@ for any unneeded "<parameter>_rtrn</parameter>" arguments.
<para>
-<function>XkbGetNamedIndicator</function>
+<function>XkbGetNamedDeviceIndicator</function>
can generate
<errorname>BadAtom</errorname>
and
@@ -1200,6 +1226,108 @@ and
errors.
</para>
+<para>
+As a convenience function, Xkb provides a function to get information about
+indicators with the default class and identifier on the default device:
+<function>XkbGetNamedIndicator</function>.
+</para>
+
+
+<indexterm significance="preferred" zone="XkbGetNamedIndicator"><primary><function>XkbGetNamedIndicator</function></primary></indexterm>
+<funcsynopsis id="XkbGetNamedIndicator">
+ <funcprototype>
+ <funcdef>Bool <function>XkbGetNamedIndicator</function></funcdef>
+ <paramdef>Display *<parameter>dpy</parameter></paramdef>
+ <paramdef>Atom <parameter>name</parameter></paramdef>
+ <paramdef>int *<parameter>ndx_rtrn</parameter></paramdef>
+ <paramdef>Bool *<parameter>state_rtrn</parameter></paramdef>
+ <paramdef>XkbIndicatorMapPtr <parameter>map_rtrn</parameter></paramdef>
+ <paramdef>Bool *<parameter>real_rtrn</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>dpy</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to the X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>name</parameter>
+ </term>
+ <listitem>
+ <para>
+ name of the indicator to be retrieved
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>ndx_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ backfilled with the index of the retrieved indicator
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>state_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ backfilled with the current state of the retrieved indicator
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>map_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ backfilled with the mapping for the retrieved indicator
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>real_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ backfilled with <symbol>True</symbol>
+ if the named indicator is real (physical)
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbGetNamedIndicator</function>
+calls
+<function>XkbGetNamedDeviceIndicator</function>
+with the specified parameters, a
+<structfield>device_spec</structfield>
+of
+<symbol>XkbUseCoreKbd</symbol>,
+a
+<structfield>led_class</structfield>
+of
+<symbol>XkbDfltXIClass</symbol>,
+and a
+<structfield>led_id</structfield>
+of
+<symbol>XkbDfltXIId</symbol>,
+and returns the value which was returned by
+<function>XkbGetNamedDeviceIndicator</function>.
+</para>
</sect2>
</sect1>
@@ -1222,7 +1350,7 @@ There are two ways to make changes to indicator maps and state: either change a
local copy of the indicator maps and use
<function>XkbSetIndicatorMap</function>
or
-<function>XkbSetNamedIndicator</function>,
+<function>XkbSetNamedDeviceIndicator</function>,
or, to reduce network traffic, use an
<structname>XkbIndicatorChangesRec</structname>
structure and use
@@ -1252,7 +1380,7 @@ is not, and if you call a function that updates the server’s image of the
indicator map (such as
<function>XkbSetIndicatorMap</function>
or
-<function>XkbSetNamedIndicator</function>),
+<function>XkbSetNamedDeviceIndicator</function>),
Xkb changes the keyboard state and controls to reflect the other fields of
the indicator map. If you attempt to explicitly change the value of an
indicator for which
@@ -1404,6 +1532,7 @@ parameter to the server.
<title>Changing Indicator Maps by Name</title>
<para>
+<function>XkbSetNamedDeviceIndicator</function> and
<function>XkbSetNamedIndicator</function>
can do several related things:
</para>
@@ -1431,10 +1560,10 @@ Set the indicator map for the indicator
</listitem>
</itemizedlist>
-<indexterm significance="preferred" zone="XkbSetNamedIndicator"><primary><function>XkbSetNamedIndicator</function></primary></indexterm>
-<funcsynopsis id="XkbSetNamedIndicator">
+<indexterm significance="preferred" zone="XkbSetNamedDeviceIndicator"><primary><function>XkbSetNamedDeviceIndicator</function></primary></indexterm>
+<funcsynopsis id="XkbSetNamedDeviceIndicator">
<funcprototype>
- <funcdef>Bool<function>XkbSetNamedIndicator</function></funcdef>
+ <funcdef>Bool<function>XkbSetNamedDeviceIndicator</function></funcdef>
<!-- (
<parameter>dpy</parameter>,
<parameter>device_spec</parameter>,
@@ -1446,6 +1575,8 @@ Set the indicator map for the indicator
<paramdef>Display *<parameter>dpy</parameter></paramdef>
<paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
+ <paramdef>unsigned int <parameter>led_class</parameter></paramdef>
+ <paramdef>unsigned int <parameter>led_id</parameter></paramdef>
<paramdef>Atom <parameter>name</parameter></paramdef>
<paramdef>Bool <parameter>change_state</parameter></paramdef>
<paramdef>Bool <parameter>state</parameter></paramdef>
@@ -1476,6 +1607,26 @@ Set the indicator map for the indicator
</varlistentry>
<varlistentry>
<term>
+ <parameter>led_class</parameter>
+ </term>
+ <listitem>
+ <para>
+ feedback class, or <symbol>XkbDfltXIClass</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>led_id</parameter>
+ </term>
+ <listitem>
+ <para>
+ feedback ID, or <symbol>XkbDfltXIId</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
<parameter>name</parameter>
</term>
<listitem>
@@ -1529,7 +1680,7 @@ Set the indicator map for the indicator
<para>
If a compatible version of the Xkb extension is not available in the server,
-<function>XkbSetNamedIndicator</function>
+<function>XkbSetNamedDeviceIndicator</function>
returns
<symbol>False</symbol>.
Otherwise, it sends a request to the X server to change the indicator
@@ -1549,7 +1700,7 @@ and the optional parameter,
<parameter>state</parameter>,
is not
<symbol>NULL</symbol>,
-<function>XkbSetNamedIndicator</function>
+<function>XkbSetNamedDeviceIndicator</function>
tells the server to change the state of the named indicator to the value
specified by
<parameter>state</parameter>.
@@ -1576,13 +1727,13 @@ If the optional parameter,
<parameter>map</parameter>,
is not
<symbol>NULL</symbol>,
-<function>XkbSetNamedIndicator</function>
+<function>XkbSetNamedDeviceIndicator</function>
tells the server to change the indicator’s map to the values specified
in <parameter>map</parameter>.
</para>
<para>
-<function>XkbSetNamedIndicator</function>
+<function>XkbSetNamedDeviceIndicator</function>
can generate
<errorname>BadAtom</errorname>
and
@@ -1596,6 +1747,107 @@ and
events (see <link linkend="Tracking_Name_Changes">section 18.5</link>).
</para>
+<para>
+As a convenience function, Xkb provides a function to set information about
+indicators with the default class and identifier on the default device:
+<function>XkbSetNamedIndicator</function>.
+</para>
+
+<indexterm significance="preferred" zone="XkbSetNamedIndicator"><primary><function>XkbSetNamedIndicator</function></primary></indexterm>
+<funcsynopsis id="XkbSetNamedIndicator">
+ <funcprototype>
+ <funcdef>Bool<function>XkbSetNamedIndicator</function></funcdef>
+ <paramdef>Display *<parameter>dpy</parameter></paramdef>
+ <paramdef>Atom <parameter>name</parameter></paramdef>
+ <paramdef>Bool <parameter>change_state</parameter></paramdef>
+ <paramdef>Bool <parameter>state</parameter></paramdef>
+ <paramdef>Bool <parameter>create_new</parameter></paramdef>
+ <paramdef>XkbIndicatorMapPtr <parameter>map</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>dpy</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to the X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>name</parameter>
+ </term>
+ <listitem>
+ <para>
+ name of the indicator to change
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>change_state</parameter>
+ </term>
+ <listitem>
+ <para>
+ whether to change the indicator state or not
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>state</parameter>
+ </term>
+ <listitem>
+ <para>
+ desired new state for the indicator
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>create_new</parameter>
+ </term>
+ <listitem>
+ <para>
+ whether a new indicator with the specified name should be
+ created when necessary
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>map</parameter>
+ </term>
+ <listitem>
+ <para>
+ new map for the indicator
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbSetNamedIndicator</function>
+calls
+<function>XkbSetNamedDeviceIndicator</function>
+with the specified parameters, a
+<structfield>device_spec</structfield>
+of
+<symbol>XkbUseCoreKbd</symbol>,
+a
+<structfield>led_class</structfield>
+of
+<symbol>XkbDfltXIClass</symbol>,
+and a
+<structfield>led_id</structfield>
+of
+<symbol>XkbDfltXIId</symbol>,
+and returns the value which was returned by
+<function>XkbSetNamedDeviceIndicator</function>.
+</para>
</sect2>
<sect2 id='XkbIndicatorChangesRec'>
--
2.7.4
More information about the xorg-devel
mailing list