You can use the Xlib input device functions to accomplish the following:
Xlib provides functions that you can use to control input from the pointer, which usually is a mouse. Usually, as soon as keyboard and mouse events occur, the X server delivers them to the appropriate client, which is determined by the window and input focus. The X server provides sufficient control over event delivery to allow window managers to support mouse ahead and various other styles of user interface. Many of these user interfaces depend upon synchronous delivery of events. The delivery of pointer and keyboard events can be controlled independently.
When mouse buttons or keyboard keys are grabbed, events will be sent to the grabbing client rather than the normal client who would have received the event. If the keyboard or pointer is in asynchronous mode, further mouse and keyboard events will continue to be processed. If the keyboard or pointer is in synchronous mode, no further events are processed until the grabbing client allows them (see XAllowEvents). The keyboard or pointer is considered frozen during this interval. The event that triggered the grab can also be replayed.
Note: The logical state of a device (as seen by client applications) may lag the physical state if device event processing is frozen.
There are two kinds of grabs: active and passive. An active grab occurs when a single client grabs the keyboard and/or pointer explicitly (see the XGrabPointer and XGrabKeyboard functions.) A passive grab occurs when clients grab a particular keyboard key or pointer button in a window, and the grab will activate when the key or button is actually pressed. Passive grabs are convenient for implementing reliable pop-up menus. For example, you can guarantee that the pop-up is mapped before the up pointer button event occurs by grabbing a button requesting synchronous behavior. The down event will trigger the grab and freeze further processing of pointer events until you have the chance to map the pop-up window. You can then allow further event processing. The up event will then be correctly processed relative to the pop-up window.
For many operations, there are functions that take a time argument. The X server includes a time stamp in various events. One special time, called CurrentTime, represents the current server time. The X server maintains the time when the input focus was last changed, when the keyboard was last grabbed, when the pointer was last grabbed, or when a selection was last changed. Your application may be slow reacting to an event. You often need some way to specify that your request should not occur if another application has in the meanwhile taken control of the keyboard, pointer, or selection. By providing the time stamp from the event in the request, you can arrange that the operation not take effect if someone else has performed an operation in the meanwhile.
A time stamp is a time value, expressed in milliseconds. It typically is the time since the last server reset. Time stamp values wrap around (after about 49.7 days). The server, given its current time is represented by time stamp T, always interprets time stamps from clients by treating half of the time stamp space as being later in time than T. One time stamp value, named CurrentTime, is never generated by the server. This value is reserved for use in requests to represent the current server time.
The following functions are used for pointer grabbing:
| Function | Description |
|---|---|
| XGrabPointer | Grabs control of the pointer. |
| XUngrabPointer | Releases the pointer. |
| XChangeActivePointer Grab | Changes the specified dynamic parameters. |
| XGrabButton | Grabs a pointer button. |
| XUngrabButton | Releases a pointer button. |
For many of the functions used for pointer grabbing, you pass pointer event mask bits. The following are valid pointer event mask bits:
For other functions used for pointer grabbing, you pass keymask bits. The following are valid keymask bits:
Xlib provides the following functions that you can use to grab or ungrab the keyboard and to allow events:
| Function | Description |
|---|---|
| XGrabKeyboard | Grabs the keyboard. |
| XUngrabKeyboard | Releases the keyboard. |
| XGrabKey | Passively grabs a single key of the keyboard. |
| XUngrabKey | Releases the key combination of the specified window. |
For many functions used in keyboard grabbing, you pass keymask bits. The following are valid keymask bits:
Use the XAllowEvents function to resume event processing. This function allows the processing of further events when the device has been frozen.
Although movement of the pointer normally should be left to the control of the end user, sometimes it is necessary to move the pointer to a new position under program control. Use the XWarpPointer function to move the pointer to an arbitrary point in a window.
Xlib provides functions that you can use to set and get the input focus. The input focus is a shared resource, and cooperation among clients is required for correct interaction. See the Inter-Client Communication Conventions Manual (ICCCM) for input focus policy. Use the following functions to control input focus:
| Function | Description |
|---|---|
| XSetInputFocus | Changes the input focus and the last-focus-change time. |
| XGetInputFocus | Obtains the current input focus. |
Xlib provides functions that you can use to change the keyboard control, obtain a list of the auto-repeat keys, turn keyboard auto-repeat on or off, ring the bell, set or obtain the pointer button or keyboard mapping, and obtain a bit vector for the keyboard.
This section discusses the user-preference options of bell, key click, pointer behavior, and so on. The default values for many of these functions are determined by command line arguments to the X server and, on POSIX-conformant systems, are typically set in the /etc/ttys file. Not all implementations will actually be able to control all of these parameters.
Use the following functions to control keyboard and pointer settings:
The XChangeKeyboardControl function operates on a XKeyboardControl structure:
/* Mask bits for ChangeKeyboardControl */ #define KBKeyClickPercent (1L<<0) #define KBBellPercent (1L<<1) #define KBBellPitch (1L<<2) #define KBBellDuration (1L<<3) #define KBLed (1L<<4) #define KBLedMode (1L<<5) #define KBKey (1L<<6) #define KBAutoRepeatMode (1L<<7) /* Values */
typedef struct {
int key_click_percent;
int bell_percent;
int bell_pitch;
int bell_duration;
int led;
int led_mode; /* LedModeOn, LedModeOff */
int key;
int auto_repeat_mode; /* AutoRepeatModeOff,
AutoRepeatModeOn,
AutoRepeatModeDefault */
} XKeyboardControl;
The key_click_percent member sets the volume for key clicks between 0 (off) and 100 (loud) inclusive, if possible. A setting of \-1 restores the default. Other negative values generate a BadValue error.
The bell_percent sets the base volume for the bell between 0 (off) and 100 (loud) inclusive, if possible. A setting of \-1 restores the default. Other negative values generate a BadValue error. The bell_pitch member sets the pitch (specified in Hz) of the bell, if possible. A setting of \-1 restores the default. Other negative values generate a BadValue error. The bell_duration member sets the duration of the bell specified in milliseconds, if possible. A setting of \-1 restores the default. Other negative values generate a BadValue error.
If both the led_mode and led members are specified, the state of that LED is changed, if possible. The led_mode member can be set to LedModeOn or LedModeOff. If only led_mode is specified, the state of all LEDs is changed, if possible. At most, 32 LEDs numbered from one are supported. No standard interpretation of LEDs is defined. If led is specified without led_mode, a BadMatch error results.
If both the auto_repeat_mode and key members are specified, the auto_repeat_mode of that key is changed (according to AutoRepeatModeOn, AutoRepeatModeOff, or AutoRepeatModeDefault ), if possible. If only auto_repeat_mode is specified, the global auto_repeat_mode for the entire keyboard is changed, if possible, and does not affect the per key settings. If a key is specified without an auto_repeat_mode, a BadMatch error results. Each key has an individual mode of whether or not it should auto-repeat and a default setting for the mode. In addition, there is a global mode of whether auto-repeat should be enabled or not and a default setting for that mode. When global mode is AutoRepeatModeOn, keys should obey their individual auto-repeat modes. When global mode is AutoRepeatModeOff, no keys should auto-repeat. An auto-repeating key generates alternating KeyPress and KeyRelease events. When a key is used as a modifier, it is desirable for the key not to auto-repeat, regardless of its auto-repeat setting.
A bell generator connected with the console but not directly on a keyboard is treated as if it were part of the keyboard. The order in which controls are verified and altered is server-dependent. If an error is generated, a subset of the controls may have been altered.
A KeyCode represents a physical (or logical) key. KeyCodes lie in the inclusive range [8,255]. A KeyCode value carries no intrinsic information, although server implementors may attempt to encode geometry (for example, matrix) information in some fashion so that it can be interpreted in a server-dependent fashion. The mapping between keys and KeyCodes cannot be changed.
A KeySym is an encoding of a symbol on the cap of a key. The set of defined KeySyms includes the ISO Latin character sets (1\-4), Katakana, Arabic, Cyrillic, Greek, Technical, Special, Publishing, APL, Hebrew, and a special miscellany of keys found on keyboards (Return, Help, Tab, and so on). To the extent possible, these sets are derived from international standards. In areas where no standards exist, some of these sets are derived from Digital Equipment Corporation standards. The list of defined symbols can be found in<X11/keysymdef.h>. Unfortunately, some C preprocessors have limits on the number of defined symbols. If you must use KeySyms not in the Latin 1\-4, Greek, and miscellaneous classes, you may have to define a symbol for those sets. Most applications usually only include <X11/keysym.h>, which defines symbols for ISO Latin 1\-4, Greek, and miscellaneous.
A list of KeySyms is associated with each KeyCode. The list is intended to convey the set of symbols on the corresponding key. If the list (ignoring trailing NoSymbol entries) is a single KeySym K , then the list is treated as if it were the list K NoSymbol K NoSymbol . If the list (ignoring trailing NoSymbol entries) is a pair of KeySyms K1 K2 , then the list is treated as if it were the list K1 K2 K1 K2 . If the list (ignoring trailing NoSymbol entries) is a triple of KeySyms K1 K2 K3 , then the list is treated as if it were the list K1 K2 K3 NoSymbol . When an explicit void element is desired in the list, the value VoidSymbol can be used.
The first four elements of the list are split into two groups of KeySyms. Group 1 contains the first and second KeySyms; Group 2 contains the third and fourth KeySyms. Within each group, if the second element of the group is NoSymbol, then the group should be treated as if the second element were the same as the first element, except when the first element is an alphabetic KeySym "K" for which both lowercase and uppercase forms are defined. In that case, the group should be treated as if the first element were the lowercase form of K and the second element were the uppercase form of K.
The standard rules for obtaining a KeySym from a KeyPress event make use of only the Group 1 and Group 2 KeySyms; no interpretation of other KeySyms in the list is given. Which group to use is determined by the modifier state. Switching between groups is controlled by the KeySym named MODE SWITCH, by attaching that KeySym to some KeyCode and attaching that KeyCode to any one of the modifiers Mod1 through Mod5. This modifier is called the group modifier. For any KeyCode, Group 1 is used when the group modifier is off, and Group 2 is used when the group modifier is on.
Within a group, the modifier state also determines which KeySym to use. The first KeySym is used when the Shift and Lock modifiers are off. The second KeySym is used when the Shift modifier is on, when the Lock modifier is on and the second KeySym is uppercase alphabetic, or when the Lock modifier is on and is interpreted as ShiftLock. Otherwise, when the Lock modifier is on and is interpreted as CapsLock, the state of the Shift modifier is applied first to select a KeySym; but if that KeySym is lowercase alphabetic, then the corresponding uppercase KeySym is used instead.
No spatial geometry of the symbols on the key is defined by their order in the KeySym list, although a geometry might be defined on a vendor-specific basis. The X server does not use the mapping between KeyCodes and KeySyms. Rather, it stores it merely for reading and writing by clients.
The KeyMask modifier named Lock is intended to be mapped to either a CapsLock or a ShiftLock key, but which one is left as application-specific and/or user-specific. However, it is suggested that the determination be made according to the associated KeySym(s) of the corresponding KeyCode.
The following functions are used for keyboard encoding: