XkbGetControlsChanges(3)

1XkbGetControlsChanges(3)         XKB FUNCTIONS        XkbGetControlsChanges(3)
2
3
4

NAME

6       XkbGetControlsChanges  - Updates a local copy of a keyboard description
7       with the changes previously noted by one or more calls  to  XkbNoteCon‐
8       trolsChanges
9

SYNOPSIS

11       XkbGetControlsChanges  (Display *dpy, XkbDescPtr xkb, XkbNameChangesPtr
12              changes);
13

ARGUMENTS

15       - dpy  connection to X server
16
17       - xkb  xkb->ctrls will be updated
18
19       - changes
20              indicates which parts of xkb->ctrls to update
21

DESCRIPTION

23       Whenever a field in the controls structure changes in the server's key‐
24       board  description,  the server sends an XkbControlsNotify event to all
25       interested clients.To receive XkbControlsNotify events under all possi‐
26       ble  conditions,  use XkbSelectEvents and pass XkbControlsNotifyMask in
27       both bits_to_change and values_for_bits.
28
29       To receive XkbControlsNotify events only under certain conditions,  use
30       XkbSelectEventDetails  using  XkbControlsNotify  as  the event_type and
31       specifying  the  desired  state  changes  in  bits_to_change  and  val‐
32       ues_for_bits using mask bits from Table 1.
33
34       Table  1  shows  the actual values for the individual mask bits used to
35       select controls for modification and to enable and disable the control.
36       Note that the same mask bit is used to specify general modifications to
37       the parameters used to configure the control (which), and to enable and
38       disable  the  control  (enabled_ctrls).  The anomalies in the table (no
39       "ok" in column) are for controls that have no configurable  attributes;
40       and  for controls that are not boolean controls and therefore cannot be
41       enabled or disabled.
42
43
44                              Table 1 Controls Mask Bits
45       ──────────────────────────────────────────────────────────────────────────
46       Mask Bit                  which or        enabled   Value
47                                 changed_ctrls   _ctrls
48       ──────────────────────────────────────────────────────────────────────────
49       XkbRepeatKeysMask         ok              ok        (1L<<0)
50       XkbSlowKeysMask           ok              ok        (1L<<1)
51       XkbBounceKeysMask         ok              ok        (1L<<2)
52       XkbStickyKeysMask         ok              ok        (1L<<3)
53       XkbMouseKeysMask          ok              ok        (1L<<4)
54       XkbMouseKeysAccelMask     ok              ok        (1L<<5)
55       XkbAccessXKeysMask        ok              ok        (1L<<6)
56       XkbAccessXTimeoutMask     ok              ok        (1L<<7)
57       XkbAccessXFeedbackMask    ok              ok        (1L<<8)
58       XkbAudibleBellMask                        ok        (1L<<9)
59       XkbOverlay1Mask                           ok        (1L<<10)
60       XkbOverlay2Mask                           ok        (1L<<11)
61       XkbIgnoreGroupLockMask                    ok        (1L<<12)
62       XkbGroupsWrapMask         ok                        (1L<<27)
63       XkbInternalModsMask       ok                        (1L<<28)
64       XkbIgnoreLockModsMask     ok                        (1L<<29)
65       XkbPerKeyRepeatMask       ok                        (1L<<30)
66
67       XkbControlsEnabledMask    ok                        (1L<<31)
68       XkbAccessXOptionsMask     ok              ok        (XkbStickyKeysMask |
69       XkbAccessXFeedbackMask)
70       XkbAllBooleanCtrlsMask                    ok        (0x00001FFF)
71       XkbAllControlsMask        ok                        (0xF8001FFF)
72
73       The changed_ctrls field specifies the  controls  components  that  have
74       changed and consists of bits taken from the masks defined in Table 10.7
75       with "ok" in the changed_ctrls column.
76
77       The controls currently enabled  in  the  server  are  reported  in  the
78       enabled_ctrls  field.  If  any  controls  were just enabled or disabled
79       (that is, the contents of the enabled_ctrls field  changed),  they  are
80       flagged  in  the  enabled_ctrl_changes  field. The valid bits for these
81       fields  are  the  masks  listed  in  Table  10.7  with  "ok"   in   the
82       enabled_ctrls column. The num_groups field reports the number of groups
83       bound to the key belonging to the most number of groups and is automat‐
84       ically updated when the keyboard mapping changes.
85
86       If  the  change  was caused by a request from a client, the keycode and
87       event_type fields are set to  zero  and  the  req_major  and  req_minor
88       fields  identify  the  request.  The req_major value is the same as the
89       major extension opcode. Otherwise, event_type is set  to  the  type  of
90       event  that  caused the change (one of KeyPress, KeyRelease, DeviceKey‐
91       Press, DeviceKeyRelease, ButtonPress or ButtonRelease),  and  req_major
92       and  req_minor  are  undefined.  If event_type is KeyPress, KeyRelease,
93       DeviceKeyPress, or DeviceKeyRelease, the keycode field is  set  to  the
94       key  that  caused the change. If event_type is ButtonPress or ButtonRe‐
95       lease, keycode contains the button number.
96
97       When a client receives an XkbControlsNotify  event,  it  can  note  the
98       changes in a changes structure using XkbNoteControlsChanges.
99
100       XkbGetControlsChanges  examines  the  changes  parameter,  queries  the
101       server for the necessary information, and copies the results  into  the
102       xkb->ctrls  keyboard  description.  If  the ctrls field of xkb is NULL,
103       XkbGetControlsChanges allocates and initializes it. To free  the  ctrls
104       field, use XkbFreeControls.
105
106       XkbGetControlsChanges  returns  Success  if successful and can generate
107       BadAlloc, BadImplementation, and BadMatch errors.
108

RETURN VALUES

110       Success        The XkbGetControlsChanges function  returns  Success  if
111                      the query of the server was successful.
112

STRUCTURES

114       The structure for the XkbControlsNotify event is defined as follows:
115
116       typedef struct {
117           int           type;          /∗ Xkb extension base event code */
118           unsigned long serial;        /∗ X server serial number for event */
119           Bool          send_event;    /∗ True => synthetically generated */
120           Display *     display;       /∗ server connection where event generated */
121           Time          time;          /∗ server time when event generated */
122           int           xkb_type;      /∗ XkbCompatMapNotify */
123           int           device;        /∗ Xkb device ID, will not be XkbUseCoreKbd */
124           unsigned int  changed_ctrls; /∗ bits indicating which controls data have
125       changed*/
126           unsigned int  enabled_ctrls; /∗ controls currently enabled in server */
127           unsigned int  enabled_ctrl_changes; /∗ bits indicating enabled/disabled
128       controls */
129           int           num_groups;    /∗ current number of keyboard groups */
130           KeyCode       keycode;       /∗ != 0 => keycode of key causing change */
131           char          event_type;    /∗ Type of event causing change */
132           char          req_major;     /∗ major event code of event causing change */
133           char          req_minor;     /∗ minor event code of event causing change */
134       } XkbControlsNotifyEvent;
135

DIAGNOSTICS

137       BadAlloc       Unable to allocate storage
138
139       BadImplementation
140                      Invalid reply from server
141
142       BadMatch       A  compatible  version  of  Xkb was not available in the
143                      server or an argument has correct type and range, but is
144                      otherwise invalid
145