| Page: | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | |
|---|---|---|---|---|---|---|---|---|---|
| 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 |
You can use the Xlib input device functions to:
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 that 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 XGrabPointer and XGrabKeyboard). 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 timestamp 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 timestamp 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 timestamp is a time value, expressed in milliseconds. It typically is the time since the last server reset. Timestamp values wrap around (after about 49.7 days). The server, given its current time is represented by timestamp T, always interprets timestamps from clients by treating half of the timestamp space as being later in time than T. One timestamp value, named CurrentTime, is never generated by the server. This value is reserved for use in requests to represent the current server time.
For many functions in this section, you pass pointer event mask bits. The valid pointer event mask bits are: ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask, Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask, and KeyMapStateMask. For other functions in this section, you pass keymask bits. The valid keymask bits are: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask.
| Home |
|---|
To grab the pointer, use XGrabPointer.
int XGrabPointer(display, grab_window, owner_events, event_mask, pointer_mode,
keyboard_mode, confine_to, cursor, time)
Display *display;
Window grab_window;
Bool owner_events;
unsigned int event_mask;
int pointer_mode, keyboard_mode;
Window confine_to;
Cursor cursor;
Time time;
The XGrabPointer function actively grabs control of the pointer and returns GrabSuccess if the grab was successful. Further pointer events are reported only to the grabbing client. XGrabPointer overrides any active pointer grab by this client. If owner_events is False, all generated pointer events are reported with respect to grab_window and are reported only if selected by event_mask. If owner_events is True and if a generated pointer event would normally be reported to this client, it is reported as usual. Otherwise, the event is reported with respect to the grab_window and is reported only if selected by event_mask. For either value of owner_events, unreported events are discarded.
If the pointer_mode is GrabModeAsync, pointer event processing continues as usual. If the pointer is currently frozen by this client, the processing of events for the pointer is resumed. If the pointer_mode is GrabModeSync, the state of the pointer, as seen by client applications, appears to freeze, and the X server generates no further pointer events until the grabbing client calls XAllowEvents or until the pointer grab is released. Actual pointer changes are not lost while the pointer is frozen; they are simply queued in the server for later processing.
If the keyboard_mode is GrabModeAsync, keyboard event processing is unaffected by activation of the grab. If the keyboard_mode is GrabModeSync, the state of the keyboard, as seen by client applications, appears to freeze, and the X server generates no further keyboard events until the grabbing client calls XAllowEvents or until the pointer grab is released. Actual keyboard changes are not lost while the pointer is frozen; they are simply queued in the server for later processing.
If a cursor is specified, it is displayed regardless of what window the pointer is in. If None is specified, the normal cursor for that window is displayed when the pointer is in grab_window or one of its subwindows; otherwise, the cursor for grab_window is displayed.
If a confine_to window is specified, the pointer is restricted to stay contained in that window. The confine_to window need have no relationship to the grab window. If the pointer is not initially in the confine_to window, it is warped automatically to the closest edge just before the grab activates and enter/leave events are generated as usual. If the confine_to window is subsequently reconfigured, the pointer is warped automatically, as necessary, to keep it contained in the window.
The time argument allows you to avoid certain circumstances that come up if applications take a long time to respond or if there are long network delays. Consider a situation where you have two applications, both of which normally grab the pointer when clicked on. If both applications specify the timestamp from the event, the second application may wake up faster and successfully grab the pointer before the first application. The first application then will get an indication that the other application grabbed the pointer before its request was processed.
| Home |
|---|
XGrabPointer generates EnterNotify and LeaveNotify events.
Either if grab_window or confine_to window is not viewable or if the confine_to window lies completely outside the boundaries of the root window, XGrabPointer fails and returns GrabNotViewable. If the pointer is actively grabbed by some other client, it fails and returns AlreadyGrabbed. If the pointer is frozen by an active grab of another client, it fails and returns GrabFrozen. If the specified time is earlier than the last-pointer-grab time or later than the current X server time, it fails and returns GrabInvalidTime. Otherwise, the last-pointer-grab time is set to the specified time (CurrentTime is replaced by the current X server time).
XGrabPointer can generate BadCursor, BadValue, and BadWindow errors.
To ungrab the pointer, use XUngrabPointer.
XUngrabPointer(display, time)
Display *display;
Time time;
The XUngrabPointer function releases the pointer and any queued events if this client has actively grabbed the pointer from XGrabPointer, XGrabButton, or from a normal button press. XUngrabPointer does not release the pointer if the specified time is earlier than the last-pointer-grab time or is later than the current X server time. It also generates EnterNotify and LeaveNotify events. The X server performs an UngrabPointer request automatically if the event window or confine_to window for an active pointer grab becomes not viewable or if window reconfiguration causes the confine_to window to lie completely outside the boundaries of the root window.
To change an active pointer grab, use XChangeActivePointerGrab.
XChangeActivePointerGrab(display, event_mask, cursor, time)
Display *display;
unsigned int event_mask;
Cursor cursor;
Time time;
The XChangeActivePointerGrab function changes the specified dynamic parameters if the pointer is actively grabbed by the client and if the specified time is no earlier than the last-pointer-grab time and no later than the current X server time. This function has no effect on the passive parameters of a XGrabButton. The interpretation of event_mask and cursor is the same as described in XGrabPointer.
XChangeActivePointerGrab can generate BadCursor and BadValue errors.
To grab a pointer button, use XGrabButton.
XGrabButton(display, button, modifiers, grab_window, owner_events, event_mask,
pointer_mode, keyboard_mode, confine_to, cursor)
Display *display;
unsigned int button;
unsigned int modifiers;
Window grab_window;
Bool owner_events;
unsigned int event_mask;
int pointer_mode, keyboard_mode;
Window confine_to;
Cursor cursor;
| Home |
|---|
The XGrabButton function establishes a passive grab. In the future, the pointer is actively grabbed (as for XGrabPointer), the last-pointer-grab time is set to the time at which the button was pressed (as transmitted in the ButtonPress event), and the ButtonPress event is reported if all of the following conditions are true:
The interpretation of the remaining arguments is as for XGrabPointer. The active grab is terminated automatically when the logical state of the pointer has all buttons released (independent of the state of the logical modifier keys).
Note that the logical state of a device (as seen by client applications) may lag the physical state if device event processing is frozen.
This request overrides all previous grabs by the same client on the same button/key combinations on the same window. A modifiers of AnyModifier is equivalent to issuing the grab request for all possible modifier combinations (including the combination of no modifiers). It is not required that all modifiers specified have currently assigned KeyCodes. A button of AnyButton is equivalent to issuing the request for all possible buttons. Otherwise, it is not required that the specified button currently be assigned to a physical button.
If some other client has already issued a XGrabButton with the same button/key combination on the same window, a BadAccess error results. When using AnyModifier or AnyButton, the request fails completely, and a BadAccess error results (no grabs are established) if there is a conflicting grab for any combination. XGrabButton has no effect on an active grab.
XGrabButton can generate BadCursor, BadValue, and BadWindow errors.
To ungrab a pointer button, use XUngrabButton.
XUngrabButton(display, button, modifiers, grab_window)
Display *display;
unsigned int button;
unsigned int modifiers;
Window grab_window;
The XUngrabButton function releases the passive button/key combination on the specified window if it was grabbed by this client. A modifiers of AnyModifier is equivalent to issuing the ungrab request for all possible modifier combinations, including the combination of no modifiers. A button of AnyButton is equivalent to issuing the request for all possible buttons. XUngrabButton has no effect on an active grab.
XUngrabButton can generate BadValue and BadWindow errors.
Xlib provides functions that you can use to grab or ungrab the keyboard as well as allow events.
For many functions in this section, you pass keymask bits. The valid keymask bits are: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask.
To grab the keyboard, use XGrabKeyboard.
int XGrabKeyboard(display, grab_window, owner_events, pointer_mode, keyboard_mode, time)
Display *display;
Window grab_window;
Bool owner_events;
int pointer_mode, keyboard_mode;
Time time;
The XGrabKeyboard function actively grabs control of the keyboard and generates FocusIn and FocusOut events. Further key events are reported only to the grabbing client. XGrabKeyboard overrides any active keyboard grab by this client. If owner_events is False, all generated key events are reported with respect to grab_window. If owner_events is True and if a generated key event would normally be reported to this client, it is reported normally; otherwise, the event is reported with respect to the grab_window. Both KeyPress and KeyRelease events are always reported, independent of any event selection made by the client.
If the keyboard_mode argument is GrabModeAsync, keyboard event processing continues as usual. If the keyboard is currently frozen by this client, then processing of keyboard events is resumed. If the keyboard_mode argument is GrabModeSync, the state of the keyboard (as seen by client applications) appears to freeze, and the X server generates no further keyboard events until the grabbing client issues a releasing XAllowEvents call or until the keyboard grab is released. Actual keyboard changes are not lost while the keyboard is frozen; they are simply queued in the server for later processing.
If pointer_mode is GrabModeAsync, pointer event processing is unaffected by activation of the grab. If pointer_mode is GrabModeSync, the state of the pointer (as seen by client applications) appears to freeze, and the X server generates no further pointer events until the grabbing client issues a releasing XAllowEvents call or until the keyboard grab is released. Actual pointer changes are not lost while the pointer is frozen; they are simply queued in the server for later processing.
If the keyboard is actively grabbed by some other client, XGrabKeyboard fails and returns AlreadyGrabbed. If grab_window is not viewable, it fails and returns GrabNotViewable. If the keyboard is frozen by an active grab of another client, it fails and returns GrabFrozen. If the specified time is earlier than the last-keyboard-grab time or later than the current X server time, it fails and returns GrablnvalidTime. Otherwise, the last-keyboard-grab time is set to the specified time (CurrentTime is replaced by the current X server time).
XGrabKeyboard can generate BadValue and BadWindow errors.
To ungrab the keyboard, use XUngrabKeyboard.
XUngrabKeyboard(display, time)
Display *display;
Time time;
The XUngrabKeyboard function releases the keyboard and any queued events if this client has it actively grabbed from either XGrabKeyboard or XGrabKey. XUngrabKeyboard does not release the keyboard and any queued events if the specified time is earlier than the last-keyboard-grab time or is later than the current X server time. It also generates FocusIn and FocusOut events. The X server automatically performs an UngrabKeyboard request if the event window for an active keyboard grab becomes not viewable.
| Home |
|---|
To passively grab a single key of the keyboard, use XGrabKey.
XGrabKey(dispiay, keycode, modifiers, grab_window, owner_evenrs, pointer_mode,
keyboard_mode)
Display *display;
int keycode;
unsigned int modifiers;
Window grab_window;
Bool owner_events;
int pointer_mode, keyboard_mode;
The XGrabKey function establishes a passive grab on the keyboard. In the future, the keyboard is actively grabbed (as for XGrabKeyboard), the last-keyboard-grab time is set to the time at which the key was pressed (as transmitted in the KeyPress event), and the KeyPress event is reported if all of the following conditions are true:
The interpretation of the remaining arguments is as for XGrabKeyboard. The active grab is terminated automatically when the logical state of the keyboard has the specified key released (independent of the logical state of the modifier keys).
Note that the logical state of a device (as seen by client applications) may lag the physical state if device event processing is frozen.
A modifiers argument of AnyModifier is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). It is not required that all modifiers specified have currently assigned KeyCodes. A keycode argument of AnyKey is equivalent to issuing the request for all possible KeyCodes. Otherwise, the specified keycode must be in the range specified by min_keycode and max_keycode in the connection setup, or a BadValue error results.
If some other client has issued a XGrabKey with the same key combination on the same window, a BadAccess error results. When using AnyModifier or AnyKey, the request fails completely, and a BadAccess error results (no grabs are established) if there is a conflicting grab for any combination.
XGrabKey can generate BadAccess, BadValue, and BadWindow errors.
To ungrab a key, use XUngrabKey.
XUngrabKey(display, keycode, modifiers, grab_window)
Display *display;
int keycode;
unsigned int modifiers;
Window grab_window;
The XUngrabKey function releases the key combination on the specified window if it was grabbed by this client. It has no effect on an active grab. A modifiers of AnyModifier is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). A keycode argument of AnyKey is equivalent to issuing the request for all possible key codes.
XUngrabKey can generate BadValue and BadWindow errors.
The previous sections discussed grab mechanisms with which processing of events by the server can be temporarily suspended. This section describes the mechanism for resuming event processing.
To allow further events to be processed when the device has been frozen, use XAllowEvents.
XAllowEvents(display, event_mode, time)
Display *display;
int event_mode;
Time time;
The XAllowEvents function releases some queued events if the client has caused a device to freeze. It has no effect if the specified time is earlier than the last-grab time of the most recent active grab for the client or if the specified time is later than the current X server time. Depending on the event_mode argument, the following occurs:
AsyncPointer, SyncPointer, and ReplayPointer have no effect on the processing of keyboard events. AsyncKeyboard, SyncKeyboard, and ReplayKeyboard have no effect on the processing of pointer events. It is possible for both a pointer grab and a keyboard grab (by the same or different clients) to be active simultaneously. If a device is frozen on behalf of either grab, no event processing is performed for the device. It is possible for a single device to be frozen because of both grabs. In this case, the freeze must be released on behalf of both grabs before events can again be processed. If a device is frozen twice by a single client, then a single AllowEvents releases both.
XAllowEvents can generate a BadValue error.
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.
To move the pointer to an arbitrary point in a window, use XWarpPointer.
XWarpPointer(display, src_w, dest_w, src_x, src_y, src_width, src_height, dest_x,
dest_y )
Display *display;
Window src_w, dest_w;
int src_x, src_y;
unsigned int src_width, src_height;
int dest_x, dest_y;
If dest_w is None, XWarpPointer moves the pointer by the offsets (dest_x, dest_y) relative to the current position of the pointer. If dest_w is a window, XWarpPointer moves the pointer to the offsets (dest_x, dest_y) relative to the origin of dest_w. However, if src_w is a window, the move only takes place if the window src_w contains the pointer and if the specified rectangle of src_w contains the pointer.
The src_x and src_y coordinates are relative to the origin of src_w. If src_height is zero, it is replaced with the current height of src_w minus src_y. If src_width is zero, it is replaced with the current width of src_w minus src_x.
There is seldom any reason for calling this function. The pointer should normally be left to the user. If you do use this function, however, it generates events just as if the user had instantaneously moved the pointer from one position to another. Note that you cannot use XWarpPointer to move the pointer outside the confine_to window of an active pointer grab. An attempt to do so will only move the pointer as far as the closest edge of the confine_to window.
XWarpPointer can generate a BadWindow error.
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 in the SUPER-UX X Window System Programmer's Guide for input focus policy.
To set the input focus, use XSetInputFocus.
XSetInputFocus(display, focus, revert_to, time)
Display *display;
Window focus;
int revert_to;
Time time;
The XSetInputFocus function changes the input focus and the last-focus-change time. It has no effect if the specified time is earlier than the current last-focus-change time or is later than the current X server time. Otherwise, the last-focus-change time is set to the specified time (CurrentTime is replaced by the current X server time). XSetInputFocus causes the X server to generate FocusIn and FocusOut events.
Depending on the focus argument, the following occurs:
The specified focus window must be viewable at the time XSetInputFocus is called, or a BadMatch error results. If the focus window later becomes not viewable, the X server evaluates the revert_to argument to determine the new focus window as follows:
XSetInputFocus can generate BadMatch, BadValue, and BadWindow errors.
To obtain the current input focus, use XGetInputFocus.
XGetInputFocus(display, focus_return, revert_to_return)
Display *display;
Window *focus_return;
int *revert_to_return;
The XGetInputFocus function returns the focus window and the current focus state.
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 options are server dependent. Not all implementations will actually be able to control all of these parameters.
The XChangeKeyboardControl function changes control of a keyboard and operates on a XKeyboardControl structure:
| /* Values */ | ||
| typedef struct { | ||
| int key_click_percent; int bell_percent; int bell_pitch; int bell_duration; int led; int led_mode; int key; int auto_repeat_mode; |
/* LedModeOn, LedModeOff */ /* 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 are 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.
XChangeKeyboardControl(display, value_mask, values)
Display *display;
unsigned long value_mask;
XKeyboardControl *values;
The XChangeKeyboardControl function controls the keyboard characteristics defined by the XKeyboardControl structure. The value_mask argument specifies which values are to be changed.
XChangeKeyboardControl can generate BadMatch and BadValue errors.
| Home |
|---|
To obtain the current control values for the keyboard, use XGetKeyboardControl.
XGetKeyboardControl(display, values_return)
Display *display;
XKeyboardState *values_return;
The XGetKeyboardControl function returns the current control values for the keyboard to the XKeyboardState structure.
| typedef struct { | |
| int key_click_percent; int bell_percent; unsigned int bell_pitch, bell_duration; unsigned long led_mask; int global_auto_repeat; char auto_repeats[32]; |
|
| } XKeyboardState; | |
For the LEDs, the least-significant bit of led_mask corresponds to LED one, and each bit set to 1 in led_mask indicates an LED that is lit. The global_auto_repeat member can be set to AutoRepeatModeOn or AutoRepeatModeOff. The auto_repeats member is a bit vector. Each bit set to 1 indicates that auto-repeat is enabled for the corresponding key. The vector is represented as 32 bytes. Byte N (from 0) contains the bits for keys 8N to 8N + 7 with the least-significant bit in the byte representing key 8N.
To turn on keyboard auto-repeat, use XAutoRepeatOn.
XAutoRepeatOn(display)
Display *display;
The XAutoRepeatOn function turns on auto-repeat for the keyboard on the specified display.
To turn off keyboard auto-repeat, use XAutoRepeatOff.
XAutoRepeatOff(display)
Display *display;
The XAutoRepeatOff function turns off auto-repeat for the keyboard on the specified display.
XBell(display, percent)
Display *display;
int percent;
| Home |
|---|
The XBell function rings the bell on the keyboard on the specified display, if possible. The specified volume is relative to the base volume for the keyboard. If the value for the percent argument is not in the range -100 to 100 inclusive, a BadValue error results. The volume at which the bell rings when the percent argument is nonnegaive is:
base - [(base * percent) / 100] + percent
The volume at which the bell rings when the percent argument is negative is:
base + [(base * percent) / 100]
To change the base volume of the bell, use XChangeKeyboardControl.
XBell can generate a BadValue error.
To obtain a bit vector that describes the state of the keyboard, use XQueryKeymap.
XQueryKeymap(display, keys_return)
Display *display;
char keys_return[32];
The XQueryKeymap function returns a bit vector for the logical state of the keyboard, where each bit set to 1 indicates that the corresponding key is currently pressed down. The vector is represented as 32 bytes. Byte N (from 0) contains the bits for keys 8N to 8N + 7 with the least-significant bit in the byte representing key 8N.
Note that the logical state of a device (as seen by client applications) may lag the physical state if device event processing is frozen.
To set the mapping of the pointer buttons, use XSetPointerMapping.
int XSetPointerMapping(display, map, nmap)
Display *display;
unsigned char map [];
int nmap;
The XSetPointerMapping function sets the mapping of the pointer. If it succeeds, the X server generates a MappingNotify event, and XSetPointerMapping returns MappingSuccess. Element map[i] defines the logical button number for the physical button i+1. The length of the list must be the same as XGetPointerMapping would return, or a BadValue error results. A zero element disables a button, and elements are not restricted in value by the number of physical buttons. However, no two elements can have the same nonzero value, or a BadValue error results. If any of the buttons to be altered are logically in the down state, XSetPointerMapping returns MappingBusy, and the mapping is not changed.
XSetPointerMapping can generate a BadValue error.
To get the pointer mapping, use XGetPointerMapping.
int XGetPointerMapping(display, map_return, nmap)
Display *display;
unsigned char map_return [];
int nmap;
The XGetPointerMapping function returns the current mapping of the pointer. Pointer buttons are numbered starting from one. XGetPointerMapping returns the number of physical buttons actually on the pointer. The nominal mapping for a pointer is map[i]=i+1. The nmap argument specifies the length of the array where the pointer mapping is returned, and only the first nmap elements are returned in map_return.
| Home |
|---|
To control the pointer's interactive feel, use XChangePointerControl.
XChangePointerControl(display, do_accel, do_threshold, accel_numerator, accel_denominator,
threshold)
Display *display;
Bool do_accel, do_threshold;
int accel_numerator, accel_denominator;
int threshold;
The XChangePointerControl function defines how the pointing device moves. The acceleration, expressed as a fraction, is a multiplier for movement. For example, specifying 3/1 means the pointer moves three times as fast as normal. The fraction may be rounded arbitrarily by the X server. Acceleration only takes effect if the pointer moves more than threshold pixels at once and only applies to the amount beyond the value in the threshold argument. Setting a value to -1 restores the default. The values of the do_accel and do_threshold arguments must be True for the pointer values to be set, or the parameters are unchanged. Negative values (other than-1) generate a BadValue error, as does a zero value for the accel_denominator argument.
XChangePointerControl can generate a BadValue error.
To get the current pointer parameters, use XGetPointerControl.
XGetPointerControl(display, accel_numerator_return, accel_denominator_return,
threshold_return)
Display *display;
int *accel_numerator_return, *accel_denominator_return;
int *threshold_return;
The XGetPointerControl function returns the pointer's current acceleration multiplier and acceleration threshold.
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, Thai, Korean and a 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.
The Lock modifier is interpreted as CapsLock when the KeySym named XK_Caps_Lock is attached to some KeyCode and that KeyCode is attached to the Lock modifier. The Lock modifier is interpreted as ShiftLock when the KeySym named XK_Shift_Lock is attached to some KeyCode and that KeyCode is attached to the Lock modifier. If the Lock modifier could be interpreted as both CapsLock and ShiftLock, the CapsLock interpretation is used.
The operation of keypad keys is controlled by the KeySym named XK_Num_Lock, 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 numlock modifier. The standard KeySyms with the prefix "XK_KP_" in their name are called keypad KeySyms; these are KeySyms with numeric value in the hexadecimal range 0xFF80 to 0xFFBD inclusive. In addition, vendor-specific KeySyms in the hexadecimal range 0x11000000 to 0x1100FFFF are also keypad KeySyms.
| Home |
|---|
Within a group, the choice of KeySym is determined by applying the first rule that is satisfied from the following list:
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 server-specific basis. The X server does not use the mapping between KeyCodes and KeySyms. Rather, it merely stores it for reading and writing by clients.
To obtain the legal KeyCodes for a display, use XDisplayKeycodes.
XDisplayKeycodes(display, min_keycodes_return, max_keycodes_return)
Display *display;
int *min_keycodes_return, *max_keycodes_return;
The XDisplayKeycodes function returns the min-keycodes and max-keycodes supported by the specified display. The minimum number of KeyCodes returned is never less than 8, and the maximum number of KeyCodes returned is never greater than 255. Not all KeyCodes in this range are required to have corresponding keys.
To obtain the symbols for the specified KeyCodes, use XGetKeyboardMapping.
KeySym *XGetKeyboardMapping(display, first_keycode, keycode_count,
keysyms_per_keycode_return)
Display *display;
KeyCode first_keycode;
int keycode_count;
int *keysyms_per_keycode_return;
The XGetKeyboardMapping function returns the symbols for the specified number of KeyCodes starting with first_keycode. The value specified in first_keycode must be greater than or equal to min_keycode as returned by XDisplayKeycodes, or a BadValue error results. In addition, the following expression must be less than or equal to max_keycode as returned by XDisplayKeycodes:
If this is not the case, a BadValue error results. The number of elements in the KeySyms list is:
KeySym number N, counting from zero, for KeyCode K has the following index in the list, counting from zero:
The X server arbitrarily chooses the keysyms_per_keycode_return value to be large enough to report all requested symbols. A special KeySym value of NoSymbol is used to fill in unused elements for individual KeyCodes. To free the storage returned by XGetKeyboardMapping, use XFree.
XGetKeyboardMapping can generate a BadValue error.
| Home |
|---|
To change the keyboard mapping, use XChangeKeyboardMapping.
XChangeKeyboardMapping(display, first_keycode, keysyms_per_keycode, keysyms, num_codes)
Display *display;
int first_keycode;
int keysyms_per_keycode;
KeySym *keysyms;
int num_codes;
The XChangeKeyboardMapping function defines the symbols for the specified number of KeyCodes starting with first_keycode. The symbols for KeyCodes outside this range remain unchanged. The number of elements in keysyms must be:
The specified first_keycode must be greater than or equal to min_keycode returned by XDisplayKeycodes, or a BadValue error results. In addition, the following expression must be less than or equal to max_keycode as returned by XDisplayKeycodes, or a BadValue error results:
KeySym number N, counting from zero, for KeyCode K has the following index in keysyms, counting from zero;
The specified keysyms_per_keycode can be chosen arbitrarily by the client to be large enough to hold all desired symbols. A special KeySym value of NoSymbol should be used to fill in unused elements for individual KeyCodes. It is legal for NoSymbol to appear in nontrailing positions of the effective list for a KeyCode. XChangeKeyboardMapping generates a MappingNotify event.
There is no requirement that the X server interpret this mapping. It is merely stored for reading and writing by clients.
XChangeKeyboardMapping can generate BadAlloc and BadValue errors.
The next six functions make use of the XModifierKeymap data structure, which contains:
| typedef struct { | ||
| int max_keypermod; KeyCode *modifiermap; |
/* This server's max number of keys per modifier */ /* An 8 by max_keypermod array of the modifiers */ |
|
| } XModifierKeymap; | ||
To create an XModifierKeymap structure, use XNewModifiermap.
XModifierKeymap *XNewModifiermap(max_keys_per_mod)
int max_keys_per_mod;
The XNewModifiermap function returns a pointer to XModifierKeymap structure for later use.
To add a new entry to an XModifierKeymap structure, use XInsertModifiermapEntry.
XModifierKeymap *XInsertModifiermapEntry(modmap, keycode_entry, modifer)
XModifierKeymap *modmap;
KeyCode keycode_entry;
int modifer;
The XInsertModifiermapEntry function adds the specified KeyCode to the set that controls the specified modifier and returns the resulting XModifierKeymap structure (expanded as needed).
To delete an entry from an XModifierKeymap structure, use XDeleteModifiermapEntry.
XModifierKeymap *XDeleteModifiermapEntry (modmap, keycode_entry, modifier)
XModifierKeymap *modmap;
KeyCode keycode_entry;
int modifer;
The XDeleteModifiermapEntry function deletes the specified KeyCode from the set that controls the specified modifier and returns a pointer to the resulting XModifierKeymap structure.
To destroy an XModifierKeymap structure, use XFreeModifiermap.
XFreeModifiermap(modmap)
XModifierKeymap *modmap;
The XFreeModifiermap function frees the specified XModifierKeymap structure.
To set the KeyCodes to be used as modifiers, use XSetModifierMapping.
int XSetModifierMapping(display, modmap)
Display *display;
XModifierKeymap *modmap;
The XSetModifierMapping function specifies the KeyCodes of the keys (if any) that are to be used as modifiers. If it succeeds, the X server generates a MappingNotify event, and XSetModifierMapping returns MappingSuccess. X permits at most eight modifier keys. If more than eight are specified in the XModifierKeymap structure, a BadLength error results.
The modifiermap member of the XModifierKeymap structure contains eight sets of max_keypermod KeyCodes, one for each modifier in the order Shift, Lock, Control, Mod1, Mod2, Mod3, Mod4, and Mod5. Only nonzero KeyCodes have meaning in each set, and zero KeyCodes are ignored. In addition, all of the nonzero KeyCodes must be in the range specified by min_keycode and max_keycode in the Display structure, or a BadValue error results.
An X server can impose restrictions on how modifiers can be changed, for example, if certain keys do not generate up transitions in hardware, if auto-repeat cannot be disabled on certain keys, or if multiple modifier keys are not supported. If some such restriction is violated, the status reply is MappingFailed, and none of the modifiers are changed. If the new KeyCodes specified for a modifier differ from those currently defined and any (current or new) keys for that modifier are in the logically down state, XSetModifierMapping returns MappingBusy, and none of the modifiers is changed.
XSetModifierMapping can generate BadAlloc and BadValue errors.
To obtain the KeyCodes used as modifiers, use XGetModifierMapping.
XModifierKeymap *XGetModifierMapping(display)
Display *display;
The XGetModifierMapping function returns a pointer to a newly created XModifierKeymap structure that contains the keys being used as modifiers. The structure should be freed after use by calling XFreeModifiermap. If only zero values appear in the set for any modifier, that modifier is disabled.
| Home |
|---|
| Contents | Previous Chapter | Next Chapter |