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  en‐
78       abled_ctrls  field. If any controls were just enabled or disabled (that
79       is, the contents of the enabled_ctrls field changed), they are  flagged
80       in  the enabled_ctrl_changes field. The valid bits for these fields are
81       the masks listed in Table 10.7 with "ok" in the  enabled_ctrls  column.
82       The  num_groups field reports the number of groups bound to the key be‐
83       longing to the most number of groups and is automatically updated  when
84       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 ma‐
89       jor extension opcode. Otherwise, event_type is set to the type of event
90       that  caused  the  change (one of KeyPress, KeyRelease, DeviceKeyPress,
91       DeviceKeyRelease, ButtonPress  or  ButtonRelease),  and  req_major  and
92       req_minor  are  undefined.  If  event_type is KeyPress, KeyRelease, De‐
93       viceKeyPress, or DeviceKeyRelease, the keycode field is set to the  key
94       that  caused the change. If event_type is ButtonPress or ButtonRelease,
95       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, Xk‐
103       bGetControlsChanges 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 changed*/
125           unsigned int  enabled_ctrls; /* controls currently enabled in server */
126           unsigned int  enabled_ctrl_changes; /* bits indicating enabled/disabled controls */
127           int           num_groups;    /* current number of keyboard groups */
128           KeyCode       keycode;       /* != 0 => keycode of key causing change */
129           char          event_type;    /* Type of event causing change */
130           char          req_major;     /* major event code of event causing change */
131           char          req_minor;     /* minor event code of event causing change */
132       } XkbControlsNotifyEvent;
133

DIAGNOSTICS

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