home *** CD-ROM | disk | FTP | other *** search
Text File | 1991-07-30 | 76.7 KB | 2,705 lines |
- \&
- .sp 1
- .ce 3
- \s+1\fBChapter 12\fP\s-1
-
- \s+1\fBInput Device Functions\fP\s-1
- .sp 2
- .nr H1 12
- .nr H2 0
- .nr H3 0
- .nr H4 0
- .nr H5 0
- .na
- .LP
- .XS
- Chapter 12: Input Device Functions
- .XE
- You can use the Xlib input device functions to:
- .IP \(bu 5
- Grab the pointer and individual buttons on the pointer
- .IP \(bu 5
- Grab the keyboard and individual keys on the keyboard
- .IP \(bu 5
- Move the pointer
- .IP \(bu 5
- Set the input focus
- .IP \(bu 5
- Manipulate the keyboard and pointer settings
- .IP \(bu 5
- Manipulate the keyboard encoding
- .RE
- .NH 2
- Pointer Grabbing
- .XS
- \*(SN Pointer Grabbing
- .XE
- .LP
- 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.
- .LP
- 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
- .PN XAllowEvents ).
- The keyboard or pointer is considered frozen during this
- interval.
- The event that triggered the grab can also be replayed.
- .LP
- Note that the logical state of a device (as seen by client applications)
- may lag the physical state if device event processing is frozen.
- .LP
- .IN "Active grab" "" "@DEF@"
- 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
- .PN XGrabPointer
- and
- .PN XGrabKeyboard ).
- .IN "Passive grab"
- 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.
- .LP
- For many operations,
- there are functions that take a time argument.
- The X server includes a timestamp in various events.
- One special time, called
- .IN "CurrentTime" "" "@DEF@"
- .IN "time" "" "@DEF@"
- .PN 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.
- .LP
- 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
- .PN CurrentTime ,
- is never generated by the server.
- This value is reserved for use in requests to represent the current server time.
- .LP
- For many functions in this section,
- you pass pointer event mask bits.
- The valid pointer event mask bits are:
- .PN ButtonPressMask ,
- .PN ButtonReleaseMask ,
- .PN EnterWindowMask ,
- .PN LeaveWindowMask ,
- .PN PointerMotionMask ,
- .PN PointerMotionHintMask ,
- .PN Button1MotionMask ,
- .PN Button2MotionMask ,
- .PN Button3MotionMask ,
- .PN Button4MotionMask ,
- .PN Button5MotionMask ,
- .PN ButtonMotionMask ,
- and
- .PN KeyMapStateMask .
- For other functions in this section,
- you pass keymask bits.
- The valid keymask bits are:
- .PN ShiftMask ,
- .PN LockMask ,
- .PN ControlMask ,
- .PN Mod1Mask ,
- .PN Mod2Mask ,
- .PN Mod3Mask ,
- .PN Mod4Mask ,
- and
- .PN Mod5Mask .
- .LP
- .sp
- To grab the pointer, use
- .PN XGrabPointer .
- .IN "Grabbing" "pointer"
- .IN "Pointer" "grabbing"
- .IN "XGrabPointer" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XGrabPointer.f,v 1.1 88/02/26 10:01:06 mento Exp $
- int XGrabPointer\^(\^\fIdisplay\fP, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIevent_mask\fP\^, \fIpointer_mode\fP\^,
- \fIkeyboard_mode\fP\^, \fIconfine_to\fP\^, \fIcursor\fP\^, \fItime\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Window \fIgrab_window\fP\^;
- .br
- Bool \fIowner_events\fP\^;
- .br
- unsigned int \fIevent_mask\fP\^;
- .br
- int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^;
- .br
- Window \fIconfine_to\fP\^;
- .br
- Cursor \fIcursor\fP\^;
- .br
- Time \fItime\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .IP \fIgrab_window\fP 1i
- Specifies the grab window.
- .\" $Header: ownerevents2.a,v 1.3 88/05/14 07:32:25 mento Exp $
- .IP \fIowner_events\fP 1i
- Specifies a Boolean value that indicates whether the pointer
- events are to be reported as usual or reported with respect to the grab window
- if selected by the event mask.
- .\" $Header: pointermask.a,v 1.3 88/05/14 07:34:39 mento Exp $
- .IP \fIevent_mask\fP 1i
- Specifies which pointer events are reported to the client.
- The mask is the bitwise inclusive OR of the valid pointer event mask bits.
- .\" $Header: pointermode.a,v 1.3 88/04/06 14:21:24 mento Exp $
- .IP \fIpointer_mode\fP 1i
- Specifies further processing of pointer events.
- You can pass
- .PN GrabModeSync
- or
- .PN GrabModeAsync .
- .\" $Header: keybdmode.a,v 1.3 88/04/06 14:22:10 mento Exp $
- .IP \fIkeyboard_mode\fP 1i
- Specifies further processing of keyboard events.
- You can pass
- .PN GrabModeSync
- or
- .PN GrabModeAsync .
- .\" $Header: confineto.a,v 1.2 88/05/14 07:01:28 mento Exp $
- .IP \fIconfine_to\fP 1i
- Specifies the window to confine the pointer in or
- .PN None .
- .\" $Header: cursor_grab.a,v 1.2 88/04/06 14:23:01 mento Exp $
- .IP \fIcursor\fP 1i
- Specifies the cursor that is to be displayed during the grab or
- .PN None .
- .IP \fItime\fP 1i
- Specifies the time.
- You can pass either a timestamp or
- .PN CurrentTime .
- .\" End marker code here
- .LP
- .\" $Header: XGrabPointer.d,v 1.3 88/08/19 20:19:16 mento Exp $
- The
- .PN XGrabPointer
- function actively grabs control of the pointer and returns
- .PN GrabSuccess
- if the grab was successful.
- Further pointer events are reported only to the grabbing client.
- .PN XGrabPointer
- overrides any active pointer grab by this client.
- If owner_events is
- .PN 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
- .PN 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.
- .LP
- If the pointer_mode is
- .PN 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
- .PN 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
- .PN 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.
- .LP
- If the keyboard_mode is
- .PN GrabModeAsync ,
- keyboard event processing is unaffected by activation of the grab.
- If the keyboard_mode is
- .PN 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
- .PN 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.
- .LP
- If a cursor is specified, it is displayed regardless of what
- window the pointer is in.
- If
- .PN 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.
- .LP
- 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.
- .LP
- 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.
- .LP
- .PN XGrabPointer
- generates
- .PN EnterNotify
- and
- .PN LeaveNotify
- events.
- .LP
- 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,
- .PN XGrabPointer
- fails and returns
- .PN GrabNotViewable .
- If the pointer is actively grabbed by some other client,
- it fails and returns
- .PN AlreadyGrabbed .
- If the pointer is frozen by an active grab of another client,
- it fails and returns
- .PN 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
- .PN GrabInvalidTime .
- Otherwise, the last-pointer-grab time is set to the specified time
- .Pn ( CurrentTime
- is replaced by the current X server time).
- .LP
- .PN XGrabPointer
- can generate
- .PN BadCursor ,
- .PN BadValue ,
- and
- .PN BadWindow
- errors.
- .LP
- .sp
- To ungrab the pointer, use
- .PN XUngrabPointer .
- .IN "Ungrabbing" "pointer"
- .IN "Pointer" "ungrabbing"
- .IN "XUngrabPointer" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XUngrabPntr.f,v 1.1 88/02/26 10:04:06 mento Exp $
- XUngrabPointer\^(\^\fIdisplay\fP, \fItime\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Time \fItime\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .IP \fItime\fP 1i
- Specifies the time.
- You can pass either a timestamp or
- .PN CurrentTime .
- .\" End marker code here
- .LP
- .\" $Header: XUngrabPntr.d,v 1.4 88/08/19 20:21:36 mento Exp $
- The
- .PN XUngrabPointer
- function releases the pointer and any queued events
- if this client has actively grabbed the pointer from
- .PN XGrabPointer ,
- .PN XGrabButton ,
- or from a normal button press.
- .PN 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
- .PN EnterNotify
- and
- .PN LeaveNotify
- events.
- The X server performs an
- .PN 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.
- .LP
- .sp
- To change an active pointer grab, use
- .PN XChangeActivePointerGrab .
- .IN "Pointer" "grabbing"
- .IN "Changing" "pointer grab"
- .IN "XChangeActivePointerGrab" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XChActPGrab.f,v 1.1 88/02/26 09:58:29 mento Exp $
- XChangeActivePointerGrab\^(\^\fIdisplay\fP, \fIevent_mask\fP\^, \fIcursor\fP\^, \fItime\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- unsigned int \fIevent_mask\fP\^;
- .br
- Cursor \fIcursor\fP\^;
- .br
- Time \fItime\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" $Header: pointermask.a,v 1.3 88/05/14 07:34:39 mento Exp $
- .IP \fIevent_mask\fP 1i
- Specifies which pointer events are reported to the client.
- The mask is the bitwise inclusive OR of the valid pointer event mask bits.
- .\" $Header: cursor_def.a,v 1.2 88/05/13 13:12:57 mento Exp $
- .IP \fIcursor\fP 1i
- Specifies the cursor that is to be displayed or
- .PN None .
- .IP \fItime\fP 1i
- Specifies the time.
- You can pass either a timestamp or
- .PN CurrentTime .
- .\" End marker code here
- .LP
- .\" $Header: XChActPGrab.d,v 1.2 88/06/11 07:48:55 mento Exp $
- The
- .PN 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
- .PN XGrabButton .
- The interpretation of event_mask and cursor is the same as described in
- .PN XGrabPointer .
- .LP
- .PN XChangeActivePointerGrab
- can generate
- .PN BadCursor
- and
- .PN BadValue
- errors.
- .LP
- .sp
- To grab a pointer button, use
- .PN XGrabButton .
- .IN "Grabbing" "buttons"
- .IN "Button" "grabbing"
- .IN "XGrabButton" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XGrabButton.f,v 1.2 88/05/14 07:20:38 mento Exp $
- XGrabButton\^(\^\fIdisplay\fP, \fIbutton\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIevent_mask\fP\^,
- .br
- \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^, \fIconfine_to\fP\^, \fIcursor\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- unsigned int \fIbutton\fP\^;
- .br
- unsigned int \fImodifiers\fP\^;
- .br
- Window \fIgrab_window\fP\^;
- .br
- Bool \fIowner_events\fP\^;
- .br
- unsigned int \fIevent_mask\fP\^;
- .br
- int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^;
- .br
- Window \fIconfine_to\fP\^;
- .br
- Cursor \fIcursor\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .ds Bu grabbed
- .\" $Header: button_gen.a,v 1.2 88/08/04 11:06:39 mento Exp $
- .IP \fIbutton\fP 1i
- Specifies the pointer button that is to be \*(Bu or
- .PN AnyButton .
- .\" $Header: modifiers.a,v 1.4 88/05/14 07:28:56 mento Exp $
- .IP \fImodifiers\fP 1i
- Specifies the set of keymasks or
- .PN AnyModifier .
- The mask is the bitwise inclusive OR of the valid keymask bits.
- .IP \fIgrab_window\fP 1i
- Specifies the grab window.
- .\" $Header: ownerevents2.a,v 1.3 88/05/14 07:32:25 mento Exp $
- .IP \fIowner_events\fP 1i
- Specifies a Boolean value that indicates whether the pointer
- events are to be reported as usual or reported with respect to the grab window
- if selected by the event mask.
- .\" $Header: pointermask.a,v 1.3 88/05/14 07:34:39 mento Exp $
- .IP \fIevent_mask\fP 1i
- Specifies which pointer events are reported to the client.
- The mask is the bitwise inclusive OR of the valid pointer event mask bits.
- .\" $Header: pointermode.a,v 1.3 88/04/06 14:21:24 mento Exp $
- .IP \fIpointer_mode\fP 1i
- Specifies further processing of pointer events.
- You can pass
- .PN GrabModeSync
- or
- .PN GrabModeAsync .
- .\" $Header: keybdmode.a,v 1.3 88/04/06 14:22:10 mento Exp $
- .IP \fIkeyboard_mode\fP 1i
- Specifies further processing of keyboard events.
- You can pass
- .PN GrabModeSync
- or
- .PN GrabModeAsync .
- .\" $Header: confineto.a,v 1.2 88/05/14 07:01:28 mento Exp $
- .IP \fIconfine_to\fP 1i
- Specifies the window to confine the pointer in or
- .PN None .
- .\" $Header: cursor_def.a,v 1.2 88/05/13 13:12:57 mento Exp $
- .IP \fIcursor\fP 1i
- Specifies the cursor that is to be displayed or
- .PN None .
- .\" End marker code here
- .LP
- .\" $Header: XGrabButton.d,v 1.4 88/08/19 20:24:59 mento Exp $
- The
- .PN XGrabButton
- function establishes a passive grab.
- In the future,
- the pointer is actively grabbed (as for
- .PN XGrabPointer ),
- the last-pointer-grab time is set to the time at which the button was pressed
- (as transmitted in the
- .PN ButtonPress
- event), and the
- .PN ButtonPress
- event is reported if all of the following conditions are true:
- .IP \(bu 5
- The pointer is not grabbed, and the specified button is logically pressed
- when the specified modifier keys are logically down,
- and no other buttons or modifier keys are logically down.
- .IP \(bu 5
- The grab_window contains the pointer.
- .IP \(bu 5
- The confine_to window (if any) is viewable.
- .IP \(bu 5
- A passive grab on the same button/key combination does not exist
- on any ancestor of grab_window.
- .LP
- The interpretation of the remaining arguments is as for
- .PN 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).
- .LP
- Note that the logical state of a device (as seen by client applications)
- may lag the physical state if device event processing is frozen.
- .LP
- This request overrides all previous grabs by the same client on the same
- button/key combinations on the same window.
- A modifiers of
- .PN 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
- .PN 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.
- .LP
- If some other client has already issued a
- .PN XGrabButton
- with the same button/key combination on the same window, a
- .PN BadAccess
- error results.
- When using
- .PN AnyModifier
- or
- .PN AnyButton ,
- the request fails completely,
- and a
- .PN BadAccess
- error results (no grabs are
- established) if there is a conflicting grab for any combination.
- .PN XGrabButton
- has no effect on an active grab.
- .LP
- .PN XGrabButton
- can generate
- .PN BadCursor ,
- .PN BadValue ,
- and
- .PN BadWindow
- errors.
- .LP
- .sp
- To ungrab a pointer button, use
- .PN XUngrabButton .
- .IN "Ungrabbing" "buttons"
- .IN "Button" "ungrabbing"
- .IN "XUngrabButton" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XUngrabBut.f,v 1.2 88/05/14 07:50:53 mento Exp $
- XUngrabButton\^(\^\fIdisplay\fP, \fIbutton\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- unsigned int \fIbutton\fP\^;
- .br
- unsigned int \fImodifiers\fP\^;
- .br
- Window \fIgrab_window\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .ds Bu released
- .\" $Header: button_gen.a,v 1.2 88/08/04 11:06:39 mento Exp $
- .IP \fIbutton\fP 1i
- Specifies the pointer button that is to be \*(Bu or
- .PN AnyButton .
- .\" $Header: modifiers.a,v 1.4 88/05/14 07:28:56 mento Exp $
- .IP \fImodifiers\fP 1i
- Specifies the set of keymasks or
- .PN AnyModifier .
- The mask is the bitwise inclusive OR of the valid keymask bits.
- .IP \fIgrab_window\fP 1i
- Specifies the grab window.
- .\" End marker code here
- .LP
- .\" $Header: XUngrabBut.d,v 1.2 88/06/11 07:54:20 mento Exp $
- The
- .PN XUngrabButton
- function releases the passive button/key combination on the specified window if
- it was grabbed by this client.
- A modifiers of
- .PN AnyModifier
- is
- equivalent to issuing
- the ungrab request for all possible modifier combinations, including
- the combination of no modifiers.
- A button of
- .PN AnyButton
- is equivalent to issuing the
- request for all possible buttons.
- .PN XUngrabButton
- has no effect on an active grab.
- .LP
- .PN XUngrabButton
- can generate
- .PN BadValue
- and
- .PN BadWindow
- errors.
- .NH 2
- Keyboard Grabbing
- .XS
- \*(SN Keyboard Grabbing
- .XE
- .LP
- Xlib provides functions that you can use to grab or ungrab the keyboard
- as well as allow events.
- .LP
- For many functions in this section,
- you pass keymask bits.
- The valid keymask bits are:
- .PN ShiftMask ,
- .PN LockMask ,
- .PN ControlMask ,
- .PN Mod1Mask ,
- .PN Mod2Mask ,
- .PN Mod3Mask ,
- .PN Mod4Mask ,
- and
- .PN Mod5Mask .
- .LP
- .sp
- To grab the keyboard, use
- .PN XGrabKeyboard .
- .IN "Keyboard" "grabbing"
- .IN "Grabbing" "keyboard"
- .IN "XGrabKeyboard" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XGrabKeybd.f,v 1.1 88/02/26 10:01:05 mento Exp $
- int XGrabKeyboard\^(\^\fIdisplay\fP, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^, \fItime\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Window \fIgrab_window\fP\^;
- .br
- Bool \fIowner_events\fP\^;
- .br
- int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^;
- .br
- Time \fItime\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .IP \fIgrab_window\fP 1i
- Specifies the grab window.
- .\" $Header: ownerevents2.a,v 1.3 88/05/14 07:32:25 mento Exp $
- .IP \fIowner_events\fP 1i
- Specifies a Boolean value that indicates whether the keyboard events
- are to be reported as usual.
- .\" $Header: pointermode.a,v 1.3 88/04/06 14:21:24 mento Exp $
- .IP \fIpointer_mode\fP 1i
- Specifies further processing of pointer events.
- You can pass
- .PN GrabModeSync
- or
- .PN GrabModeAsync .
- .\" $Header: keybdmode.a,v 1.3 88/04/06 14:22:10 mento Exp $
- .IP \fIkeyboard_mode\fP 1i
- Specifies further processing of keyboard events.
- You can pass
- .PN GrabModeSync
- or
- .PN GrabModeAsync .
- .IP \fItime\fP 1i
- Specifies the time.
- You can pass either a timestamp or
- .PN CurrentTime .
- .\" End marker code here
- .LP
- .\" $Header: XGrabKeybd.d,v 1.4 88/08/19 20:27:03 mento Exp $
- The
- .PN XGrabKeyboard
- function actively grabs control of the keyboard and generates
- .PN FocusIn
- and
- .PN FocusOut
- events.
- Further key events are reported only to the
- grabbing client.
- .PN XGrabKeyboard
- overrides any active keyboard grab by this client.
- If owner_events is
- .PN False ,
- all generated key events are reported with
- respect to grab_window.
- If owner_events is
- .PN 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
- .PN KeyPress
- and
- .PN KeyRelease
- events are always reported,
- independent of any event selection made by the client.
- .LP
- If the keyboard_mode argument is
- .PN 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
- .PN 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
- .PN 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.
- .LP
- If pointer_mode is
- .PN GrabModeAsync ,
- pointer event processing is unaffected
- by activation of the grab.
- If pointer_mode is
- .PN 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
- .PN 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.
- .LP
- If the keyboard is actively grabbed by some other client,
- .PN XGrabKeyboard
- fails and returns
- .PN AlreadyGrabbed .
- If grab_window is not viewable,
- it fails and returns
- .PN GrabNotViewable .
- If the keyboard is frozen by an active grab of another client,
- it fails and returns
- .PN 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
- .PN GrabInvalidTime .
- Otherwise, the last-keyboard-grab time is set to the specified time
- .Pn ( CurrentTime
- is replaced by the current X server time).
- .LP
- .PN XGrabKeyboard
- can generate
- .PN BadValue
- and
- .PN BadWindow
- errors.
- .LP
- .sp
- To ungrab the keyboard, use
- .PN XUngrabKeyboard .
- .IN "Keyboard" "ungrabbing"
- .IN "Ungrabbing" "keyboard"
- .IN "XUngrabKeyboard" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XUngrabKeybd.f,v 1.1 88/02/26 10:04:05 mento Exp $
- XUngrabKeyboard\^(\^\fIdisplay\fP, \fItime\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Time \fItime\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .IP \fItime\fP 1i
- Specifies the time.
- You can pass either a timestamp or
- .PN CurrentTime .
- .\" End marker code here
- .LP
- .\" $Header: XUngrabKeybd.d,v 1.2 88/06/11 07:54:22 mento Exp $
- The
- .PN XUngrabKeyboard
- function
- releases the keyboard and any queued events if this client has it actively grabbed from
- either
- .PN XGrabKeyboard
- or
- .PN XGrabKey .
- .PN 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
- .PN FocusIn
- and
- .PN FocusOut
- events.
- The X server automatically performs an
- .PN UngrabKeyboard
- request if the event window for an
- active keyboard grab becomes not viewable.
- .LP
- .sp
- To passively grab a single key of the keyboard, use
- .PN XGrabKey .
- .IN "Key" "grabbing"
- .IN "Grabbing" "keys"
- .IN "XGrabKey" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XGrabKey.f,v 1.1 88/02/26 10:01:04 mento Exp $
- XGrabKey\^(\^\fIdisplay\fP, \fIkeycode\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIpointer_mode\fP\^,
- .br
- \fIkeyboard_mode\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- int \fIkeycode\fP\^;
- .br
- unsigned int \fImodifiers\fP\^;
- .br
- Window \fIgrab_window\fP\^;
- .br
- Bool \fIowner_events\fP\^;
- .br
- int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" $Header: keycode1.a,v 1.1 88/05/14 08:09:00 mento Exp $
- .IP \fIkeycode\fP 1i
- Specifies the KeyCode or
- .PN AnyKey .
- .\" $Header: modifiers.a,v 1.4 88/05/14 07:28:56 mento Exp $
- .IP \fImodifiers\fP 1i
- Specifies the set of keymasks or
- .PN AnyModifier .
- The mask is the bitwise inclusive OR of the valid keymask bits.
- .IP \fIgrab_window\fP 1i
- Specifies the grab window.
- .\" $Header: ownerevents2.a,v 1.3 88/05/14 07:32:25 mento Exp $
- .IP \fIowner_events\fP 1i
- Specifies a Boolean value that indicates whether the keyboard events
- are to be reported as usual.
- .\" $Header: pointermode.a,v 1.3 88/04/06 14:21:24 mento Exp $
- .IP \fIpointer_mode\fP 1i
- Specifies further processing of pointer events.
- You can pass
- .PN GrabModeSync
- or
- .PN GrabModeAsync .
- .\" $Header: keybdmode.a,v 1.3 88/04/06 14:22:10 mento Exp $
- .IP \fIkeyboard_mode\fP 1i
- Specifies further processing of keyboard events.
- You can pass
- .PN GrabModeSync
- or
- .PN GrabModeAsync .
- .\" End marker code here
- .LP
- .\" $Header: XGrabKey.d,v 1.4 88/08/19 20:28:57 mento Exp $
- The
- .PN XGrabKey
- function establishes a passive grab on the keyboard.
- In the future,
- the keyboard is actively grabbed (as for
- .PN XGrabKeyboard ),
- the last-keyboard-grab time is set to the time at which the key was pressed
- (as transmitted in the
- .PN KeyPress
- event), and the
- .PN KeyPress
- event is reported if all of the following conditions are true:
- .IP \(bu 5
- The keyboard is not grabbed and the specified key
- (which can itself be a modifier key) is logically pressed
- when the specified modifier keys are logically down,
- and no other modifier keys are logically down.
- .IP \(bu 5
- Either the grab_window is an ancestor of (or is) the focus window,
- or the grab_window is a descendant of the focus window and contains the pointer.
- .IP \(bu 5
- A passive grab on the same key combination does not exist
- on any ancestor of grab_window.
- .LP
- The interpretation of the remaining arguments is as for
- .PN 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).
- .LP
- Note that the logical state of a device (as seen by client applications)
- may lag the physical state if device event processing is frozen.
- .LP
- A modifiers argument of
- .PN 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
- .PN 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
- .PN BadValue
- error results.
- .LP
- If some other client has issued a
- .PN XGrabKey
- with the same key combination on the same window, a
- .PN BadAccess
- error results.
- When using
- .PN AnyModifier
- or
- .PN AnyKey ,
- the request fails completely,
- and a
- .PN BadAccess
- error results (no grabs are established)
- if there is a conflicting grab for any combination.
- .LP
- .PN XGrabKey
- can generate
- .PN BadAccess ,
- .PN BadValue ,
- and
- .PN BadWindow
- errors.
- .LP
- .sp
- To ungrab a key, use
- .PN XUngrabKey .
- .IN "Key" "ungrabbing"
- .IN "Ungrabbing" "keys"
- .IN "XUngrabKey" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XUngrabKey.f,v 1.2 88/05/14 08:28:06 mento Exp $
- XUngrabKey\^(\^\fIdisplay\fP, \fIkeycode\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- int \fIkeycode\fP\^;
- .br
- unsigned int \fImodifiers\fP\^;
- .br
- Window \fIgrab_window\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" $Header: keycode1.a,v 1.1 88/05/14 08:09:00 mento Exp $
- .IP \fIkeycode\fP 1i
- Specifies the KeyCode or
- .PN AnyKey .
- .\" $Header: modifiers.a,v 1.4 88/05/14 07:28:56 mento Exp $
- .IP \fImodifiers\fP 1i
- Specifies the set of keymasks or
- .PN AnyModifier .
- The mask is the bitwise inclusive OR of the valid keymask bits.
- .IP \fIgrab_window\fP 1i
- Specifies the grab window.
- .\" End marker code here
- .LP
- .\" $Header: XUngrabKey.d,v 1.3 88/08/19 20:29:50 mento Exp $
- The
- .PN 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
- .PN AnyModifier
- is equivalent to issuing
- the request for all possible modifier combinations
- (including the combination of no modifiers).
- A keycode argument of
- .PN AnyKey
- is equivalent to issuing the request for all possible key codes.
- .LP
- .PN XUngrabKey
- can generate
- .PN BadValue
- and
- .PN BadWindow
- errors.
- .NH 2
- Resuming Event Processing
- .XS
- \*(SN Resuming Event Processing
- .XE
- .LP
- 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.
- .LP
- .sp
- To allow further events to be processed when the device has been frozen, use
- .PN XAllowEvents .
- .IN "XAllowEvents" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XAllowEvents.f,v 1.1 88/02/26 09:58:11 mento Exp $
- XAllowEvents\^(\^\fIdisplay\fP, \fIevent_mode\fP\^, \fItime\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- int \fIevent_mode\fP\^;
- .br
- Time \fItime\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" $Header: eventmode.a,v 1.2 88/04/04 11:13:37 mento Exp $
- .IP \fIevent_mode\fP 1i
- Specifies the event mode.
- You can pass
- .PN AsyncPointer ,
- .PN SyncPointer ,
- .PN AsyncKeyboard ,
- .PN SyncKeyboard ,
- .PN ReplayPointer ,
- .PN ReplayKeyboard ,
- .PN AsyncBoth ,
- or
- .PN SyncBoth .
- .IP \fItime\fP 1i
- Specifies the time.
- You can pass either a timestamp or
- .PN CurrentTime .
- .\" End marker code here
- .LP
- .\" $Header: XAllowEvents.d,v 1.2 88/06/11 07:48:36 mento Exp $
- The
- .PN 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:
- .TS
- lw(1.25i) lw(4.5i).
- T{
- .PN AsyncPointer
- T} T{
- If the pointer is frozen by the client,
- pointer event processing continues as usual.
- If the pointer is frozen twice by the client on behalf of two separate grabs,
- .PN AsyncPointer
- thaws for both.
- .PN AsyncPointer
- has no effect if the pointer is not frozen by the client,
- but the pointer need not be grabbed by the client.
- T}
- .sp 6p
- T{
- .PN SyncPointer
- T} T{
- If the pointer is frozen and actively grabbed by the client,
- pointer event processing continues as usual until the next
- .PN ButtonPress
- or
- .PN ButtonRelease
- event is reported to the client.
- At this time,
- the pointer again appears to freeze.
- However, if the reported event causes the pointer grab to be released,
- the pointer does not freeze.
- .PN SyncPointer
- has no effect if the pointer is not frozen by the client
- or if the pointer is not grabbed by the client.
- T}
- .sp 6p
- T{
- .PN ReplayPointer
- T} T{
- If the pointer is actively grabbed by the client and is frozen as the result of
- an event having been sent to the client (either from the activation of a
- .PN XGrabButton
- or from a previous
- .PN XAllowEvents
- with mode
- .PN SyncPointer
- but not from a
- .PN XGrabPointer ),
- the pointer grab is released and that event is completely reprocessed.
- This time, however, the function ignores any passive grabs at or above
- (towards the root of) the grab_window of the grab just released.
- The request has no effect if the pointer is not grabbed by the client
- or if the pointer is not frozen as the result of an event.
- T}
- .sp 6p
- T{
- .PN AsyncKeyboard
- T} T{
- If the keyboard is frozen by the client,
- keyboard event processing continues as usual.
- If the keyboard is frozen twice by the client on behalf of two separate grabs,
- .PN AsyncKeyboard
- thaws for both.
- .PN AsyncKeyboard
- has no effect if the keyboard is not frozen by the client,
- but the keyboard need not be grabbed by the client.
- T}
- .sp 6p
- T{
- .PN SyncKeyboard
- T} T{
- If the keyboard is frozen and actively grabbed by the client,
- keyboard event processing continues as usual until the next
- .PN KeyPress
- or
- .PN KeyRelease
- event is reported to the client.
- At this time,
- the keyboard again appears to freeze.
- However, if the reported event causes the keyboard grab to be released,
- the keyboard does not freeze.
- .PN SyncKeyboard
- has no effect if the keyboard is not frozen by the client
- or if the keyboard is not grabbed by the client.
- T}
- .sp 6p
- T{
- .PN ReplayKeyboard
- T} T{
- If the keyboard is actively grabbed by the client and is frozen
- as the result of an event having been sent to the client (either from the
- activation of a
- .PN XGrabKey
- or from a previous
- .PN XAllowEvents
- with mode
- .PN SyncKeyboard
- but not from a
- .PN XGrabKeyboard ),
- the keyboard grab is released and that event is completely reprocessed.
- This time, however, the function ignores any passive grabs at or above
- (towards the root of)
- the grab_window of the grab just released.
- The request has no effect if the keyboard is not grabbed by the client
- or if the keyboard is not frozen as the result of an event.
- T}
- .sp 6p
- T{
- .PN SyncBoth
- T} T{
- If both pointer and keyboard are frozen by the client,
- event processing for both devices continues as usual until the next
- .PN ButtonPress ,
- .PN ButtonRelease ,
- .PN KeyPress ,
- or
- .PN KeyRelease
- event is reported to the client for a grabbed device
- (button event for the pointer, key event for the keyboard),
- at which time the devices again appear to freeze.
- However, if the reported event causes the grab to be released,
- then the devices do not freeze (but if the other device is still
- grabbed, then a subsequent event for it will still cause both devices
- to freeze).
- .PN SyncBoth
- has no effect unless both pointer and keyboard
- are frozen by the client.
- If the pointer or keyboard is frozen twice
- by the client on behalf of two separate grabs,
- .PN SyncBoth
- thaws for both (but a subsequent freeze for
- .PN SyncBoth
- will only freeze each device once).
- T}
- .sp 6p
- T{
- .PN AsyncBoth
- T} T{
- If the pointer and the keyboard are frozen by the
- client, event processing for both devices continues as usual.
- If a device is frozen twice by the client on behalf of two separate grabs,
- .PN AsyncBoth
- thaws for both.
- .PN AsyncBoth
- has no effect unless both
- pointer and keyboard are frozen by the client.
- T}
- .TE
- .LP
- .PN AsyncPointer ,
- .PN SyncPointer ,
- and
- .PN ReplayPointer
- have no effect on the
- processing of keyboard events.
- .PN AsyncKeyboard ,
- .PN SyncKeyboard ,
- and
- .PN 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
- .PN AllowEvents
- releases both.
- .LP
- .PN XAllowEvents
- can generate a
- .PN BadValue
- error.
- .NH 2
- Moving the Pointer
- .XS
- \*(SN Moving the Pointer
- .XE
- .LP
- 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.
- .LP
- .sp
- To move the pointer to an arbitrary point in a window, use
- .PN XWarpPointer .
- .IN "XWarpPointer" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XWarpPointer.f,v 1.1 88/02/26 10:04:13 mento Exp $
- .\" $Header: XWarpPointer.f,v 1.1 88/02/26 10:04:13 mento Exp $
- XWarpPointer\^(\^\fIdisplay\fP, \fIsrc_w\fP\^, \fIdest_w\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIsrc_width\fP\^, \fIsrc_height\fP\^, \fIdest_x\fP\^,
- .br
- \fIdest_y\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Window \fIsrc_w\fP\^, \fIdest_w\fP\^;
- .br
- int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
- .br
- unsigned int \fIsrc_width\fP\^, \fIsrc_height\fP\^;
- .br
- int \fIdest_x\fP\^, \fIdest_y\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" $Header: sw1.a,v 1.1 88/05/14 08:43:03 mento Exp $
- .IP \fIsrc_w\fP 1i
- Specifies the source window or
- .PN None .
- .\" $Header: dw1.a,v 1.1 88/05/14 08:44:37 mento Exp $
- .IP \fIdest_w\fP 1i
- Specifies the destination window or
- .PN None .
- .\" $Header: srcwdht.a,v 1.2 88/04/28 06:03:00 mento Exp $
- .IP \fIsrc_x\fP 1i
- .br
- .ns
- .IP \fIsrc_y\fP 1i
- .br
- .ns
- .IP \fIsrc_width\fP 1i
- .br
- .ns
- .IP \fIsrc_height\fP 1i
- Specify a rectangle in the source window.
- .\" $Header: destxy2.a,v 1.1 88/02/26 10:06:50 mento Exp $
- .IP \fIdest_x\fP 1i
- .br
- .ns
- .IP \fIdest_y\fP 1i
- Specify the x and y coordinates within the destination window.
- .\" End marker code here
- .LP
- .\" $Header: XWarpPointer.d,v 1.3 88/06/11 07:54:36 mento Exp $
- If dest_w is
- .PN None ,
- .PN 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,
- .PN 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.
- .LP
- 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.
- .LP
- 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
- .PN 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.
- .LP
- .PN XWarpPointer
- can generate a
- .PN BadWindow
- error.
- .NH 2
- Controlling Input Focus
- .XS
- \*(SN Controlling Input Focus
- .XE
- .LP
- 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
- \fIInter-Client Communication Conventions Manual\fP
- for input focus policy.
- .LP
- .sp
- To set the input focus, use
- .PN XSetInputFocus .
- .IN "XSetInputFocus" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XSetInFocus.f,v 1.1 88/02/26 10:03:18 mento Exp $
- XSetInputFocus\^(\^\fIdisplay\fP, \fIfocus\fP\^, \fIrevert_to\fP\^, \fItime\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Window \fIfocus\fP\^;
- .br
- int \fIrevert_to\fP\^;
- .br
- Time \fItime\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .IP \fIfocus\fP 1i
- Specifies the window,
- .PN PointerRoot ,
- or
- .PN None .
- .\" $Header: revertto.a,v 1.4 88/08/19 20:33:14 mento Exp $
- .IP \fIrevert_to\fP 1i
- Specifies where the input focus reverts to if the window becomes not
- viewable.
- You can pass
- .PN RevertToParent ,
- .PN RevertToPointerRoot ,
- or
- .PN RevertToNone .
- .IP \fItime\fP 1i
- Specifies the time.
- You can pass either a timestamp or
- .PN CurrentTime .
- .\" End marker code here
- .LP
- .\" $Header: XSetInFocus.d,v 1.2 88/06/11 07:53:17 mento Exp $
- The
- .PN 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
- .Pn ( CurrentTime
- is replaced by the current X server time).
- .PN XSetInputFocus
- causes the X server to generate
- .PN FocusIn
- and
- .PN FocusOut
- events.
- .LP
- Depending on the focus argument,
- the following occurs:
- .IP \(bu 5
- If focus is
- .PN None ,
- all keyboard events are discarded until a new focus window is set,
- and the revert_to argument is ignored.
- .IP \(bu 5
- If focus is a window,
- it becomes the keyboard's focus window.
- If a generated keyboard event would normally be reported to this window
- or one of its inferiors, the event is reported as usual.
- Otherwise, the event is reported relative to the focus window.
- .IP \(bu 5
- If focus is
- .PN PointerRoot ,
- the focus window is dynamically taken to be the root window of whatever screen
- the pointer is on at each keyboard event.
- In this case, the revert_to argument is ignored.
- .LP
- The specified focus window must be viewable at the time
- .PN XSetInputFocus
- is called,
- or a
- .PN 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:
- .IP \(bu 5
- If revert_to is
- .PN RevertToParent ,
- the focus reverts to the parent (or the closest viewable ancestor),
- and the new revert_to value is taken to be
- .PN RevertToNone .
- .IP \(bu 5
- If revert_to is
- .PN RevertToPointerRoot
- or
- .PN RevertToNone ,
- the focus reverts to
- .PN PointerRoot
- or
- .PN None ,
- respectively.
- When the focus reverts,
- the X server generates
- .PN FocusIn
- and
- .PN FocusOut
- events, but the last-focus-change time is not affected.
- .LP
- .PN XSetInputFocus
- can generate
- .PN BadMatch ,
- .PN BadValue ,
- and
- .PN BadWindow
- errors.
- .LP
- .sp
- To obtain the current input focus, use
- .PN XGetInputFocus .
- .IN "XGetInputFocus" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XGetInFocus.f,v 1.1 88/02/26 10:00:48 mento Exp $
- XGetInputFocus\^(\^\fIdisplay\fP, \fIfocus_return\fP\^, \fIrevert_to_return\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Window *\fIfocus_return\fP\^;
- .br
- int *\fIrevert_to_return\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" $Header: focus.a,v 1.2 88/05/14 08:56:12 mento Exp $
- .IP \fIfocus_return\fP 1i
- Returns the focus window,
- .PN PointerRoot ,
- or
- .PN None .
- .\" $Header: reverttoret.a,v 1.3 88/05/14 08:57:31 mento Exp $
- .IP \fIrevert_to_return\fP 1i
- Returns the current focus state
- .Pn ( RevertToParent ,
- .PN RevertToPointerRoot ,
- or
- .PN RevertToNone ).
- .\" End marker code here
- .LP
- .\" $Header: XGetInFocus.d,v 1.2 88/05/14 08:58:23 mento Exp $
- The
- .PN XGetInputFocus
- function returns the focus window and the current focus state.
- .NH 2
- Keyboard and Pointer Settings
- .XS
- \*(SN Keyboard and Pointer Settings
- .XE
- .LP
- 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.
- .LP
- .IN "Keyboard" "bell volume"
- .IN "Keyboard" "keyclick volume"
- .IN "Keyboard" "bit vector"
- .IN "Mouse" "programming"
- 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
- .PN /etc/ttys
- file.
- .IN "Files" "/etc/ttys"
- Not all implementations will actually be able to control all of these
- parameters.
- .LP
- The
- .PN XChangeKeyboardControl
- function changes control of a keyboard and operates on a
- .PN XKeyboardControl
- structure:
- .\" Start marker code here
- .LP
- /* Mask bits for ChangeKeyboardControl */
- .TS
- lw(.5i) lw(2.5i) lw(.8i).
- T{
- #define
- T} T{
- .PN KBKeyClickPercent
- T} T{
- (1L<<0)
- T}
- T{
- #define
- T} T{
- .PN KBBellPercent
- T} T{
- (1L<<1)
- T}
- T{
- #define
- T} T{
- .PN KBBellPitch
- T} T{
- (1L<<2)
- T}
- T{
- #define
- T} T{
- .PN KBBellDuration
- T} T{
- (1L<<3)
- T}
- T{
- #define
- T} T{
- .PN KBLed
- T} T{
- (1L<<4)
- T}
- T{
- #define
- T} T{
- .PN KBLedMode
- T} T{
- (1L<<5)
- T}
- T{
- #define
- T} T{
- .PN KBKey
- T} T{
- (1L<<6)
- T}
- T{
- #define
- T} T{
- .PN KBAutoRepeatMode
- T} T{
- (1L<<7)
- T}
- .TE
- .IN "XKeyboardControl" "" "@DEF@"
- .Ds 0
- .TA .5i 2.5i
- .ta .5i 2.5i
- /* 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;
- .De
- .\" End marker code here
- .LP
- 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
- .PN BadValue
- error.
- .LP
- 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
- .PN 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
- .PN 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
- .PN BadValue
- error.
- .LP
- 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
- .PN LedModeOn
- or
- .PN 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
- .PN BadMatch
- error results.
- .LP
- If both the auto_repeat_mode and key members are specified,
- the auto_repeat_mode of that key is changed (according to
- .PN AutoRepeatModeOn ,
- .PN AutoRepeatModeOff ,
- or
- .PN 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
- .PN 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
- .PN AutoRepeatModeOn ,
- keys should obey their individual auto-repeat modes.
- When global mode is
- .PN AutoRepeatModeOff ,
- no keys should auto-repeat.
- An auto-repeating key generates alternating
- .PN KeyPress
- and
- .PN 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.
- .LP
- 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.
- .LP
- .sp
- .IN "XChangeKeyboardControl" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XChKeyCon.f,v 1.1 88/02/26 09:58:32 mento Exp $
- XChangeKeyboardControl\^(\^\fIdisplay\fP, \fIvalue_mask\fP\^, \fIvalues\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- unsigned long \fIvalue_mask\fP\^;
- .br
- XKeyboardControl *\fIvalues\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" $Header: value_mask1.a,v 1.3 88/04/28 06:04:45 mento Exp $
- .IP \fIvalue_mask\fP 1i
- Specifies which controls to change.
- This mask is the bitwise inclusive OR of the valid control mask bits.
- .\" $Header: values2.a,v 1.2 88/04/06 17:16:22 mento Exp $
- .IP \fIvalues\fP 1i
- Specifies one value for each bit set to 1 in the mask.
- .\" End marker code here
- .LP
- .\" $Header: XChKeyCon.d,v 1.2 88/05/16 10:04:53 mento Exp $
- The
- .PN XChangeKeyboardControl
- function controls the keyboard characteristics defined by the
- .PN XKeyboardControl
- structure.
- The value_mask argument specifies which values are to be changed.
- .LP
- .PN XChangeKeyboardControl
- can generate
- .PN BadMatch
- and
- .PN BadValue
- errors.
- .LP
- .sp
- To obtain the current control values for the keyboard, use
- .PN XGetKeyboardControl .
- .IN "XGetKeyboardControl" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XGetKeybdCnt.f,v 1.1 88/02/26 10:00:50 mento Exp $
- XGetKeyboardControl\^(\^\fIdisplay\fP, \fIvalues_return\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- XKeyboardState *\fIvalues_return\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" $Header: values3.a,v 1.2 88/04/06 17:19:04 mento Exp $
- .IP \fIvalues_return\fP 1i
- Returns the current keyboard controls in the specified
- .PN XKeyboardState
- structure.
- .\" End marker code here
- .LP
- .\" $Header: XGetKeybdCnt.d,v 1.1 88/02/26 10:48:27 mento Exp $
- The
- .PN XGetKeyboardControl
- function returns the current control values for the keyboard to the
- .PN XKeyboardState
- structure.
- .LP
- .IN "XGetKeyboardControl"
- .IN "XKeyboardState" "" "@DEF@"
- .\" Start marker code here
- .Ds 0
- .TA .5i
- .ta .5i
- 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;
- .De
- .\" End marker code here
- .LP
- 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
- .PN AutoRepeatModeOn
- or
- .PN 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.
- .LP
- .sp
- To turn on keyboard auto-repeat, use
- .PN XAutoRepeatOn .
- .IN "XAutoRepeatOn" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XAutoReptOn.f,v 1.1 88/02/26 09:58:16 mento Exp $
- XAutoRepeatOn\^(\^\fIdisplay\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" End marker code here
- .LP
- .\" $Header: XAutoReptOn.d,v 1.1 88/02/26 10:41:06 mento Exp $
- The
- .PN XAutoRepeatOn
- function turns on auto-repeat for the keyboard on the specified display.
- .LP
- .sp
- To turn off keyboard auto-repeat, use
- .PN XAutoRepeatOff .
- .IN "XAutoRepeatOff" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XAutoReptOff.f,v 1.1 88/02/26 09:58:13 mento Exp $
- XAutoRepeatOff\^(\^\fIdisplay\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" End marker code here
- .LP
- .\" $Header: XAutoReptOff.d,v 1.1 88/02/26 10:41:05 mento Exp $
- The
- .PN XAutoRepeatOff
- function turns off auto-repeat for the keyboard on the specified display.
- .LP
- .sp
- To ring the bell, use
- .PN XBell .
- .IN "XBell" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XBell.f,v 1.1 88/02/26 09:58:18 mento Exp $
- XBell\^(\^\fIdisplay\fP, \fIpercent\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- int \fIpercent\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" $Header: percent.a,v 1.2 88/04/06 17:20:22 mento Exp $
- .IP \fIpercent\fP 1i
- Specifies the volume for the bell,
- which can range from \-100 to 100 inclusive.
- .\" End marker code here
- .LP
- .\" $Header: XBell.d,v 1.2 88/06/11 07:48:47 mento Exp $
- The
- .PN 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
- .PN BadValue
- error results.
- The volume at which the bell rings
- when the percent argument is nonnegative is:
- .IP
- base \- [(base * percent) / 100] + percent
- .LP
- The volume at which the bell rings
- when the percent argument is negative is:
- .IP
- base + [(base * percent) / 100]
- .LP
- To change the base volume of the bell, use
- .PN XChangeKeyboardControl .
- .LP
- .PN XBell
- can generate a
- .PN BadValue
- error.
- .LP
- .sp
- To obtain a bit vector that describes the state of the keyboard, use
- .PN XQueryKeymap .
- .IN "XQueryKeymap" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XQueryKeybd.f,v 1.1 88/02/26 10:02:17 mento Exp $
- XQueryKeymap\^(\^\fIdisplay\fP, \fIkeys_return\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- char \fIkeys_return\fP[32]\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" $Header: keys.a,v 1.1 88/02/26 10:28:26 mento Exp $
- .IP \fIkeys_return\fP 1i
- Returns an array of bytes that identifies which keys are pressed down.
- Each bit represents one key of the keyboard.
- .\" End marker code here
- .LP
- .\" $Header: XQueryKeybd.d,v 1.3 88/06/11 07:52:42 mento Exp $
- The
- .PN 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.
- .LP
- Note that the logical state of a device (as seen by client applications)
- may lag the physical state if device event processing is frozen.
- .LP
- .sp
- To set the mapping of the pointer buttons, use
- .PN XSetPointerMapping .
- .IN "XSetPointerMapping" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- int XSetPointerMapping\^(\^\fIdisplay\fP, \fImap\fP, \fInmap\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- unsigned char \fImap\fP\^[]\^;
- .br
- int \fInmap\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .IP \fImap\fP 1i
- Specifies the mapping list.
- .IP \fInmap\fP 1i
- Specifies the number of items in the mapping list.
- .\" End marker code here
- .LP
- .\" $Header: XSetPMap.d,v 1.3 88/06/11 07:53:27 mento Exp $
- The
- .PN XSetPointerMapping
- function sets the mapping of the pointer.
- If it succeeds, the X server generates a
- .PN MappingNotify
- event, and
- .PN XSetPointerMapping
- returns
- .PN 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
- .PN XGetPointerMapping
- would return,
- or a
- .PN 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
- .PN BadValue
- error results.
- If any of the buttons to be altered are logically in the down state,
- .PN XSetPointerMapping
- returns
- .PN MappingBusy ,
- and the mapping is not changed.
- .LP
- .PN XSetPointerMapping
- can generate a
- .PN BadValue
- error.
- .LP
- .sp
- To get the pointer mapping, use
- .PN XGetPointerMapping .
- .IN "XGetPointerMapping" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- int XGetPointerMapping\^(\^\fIdisplay\fP, \fImap_return\fP, \fInmap\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- unsigned char \fImap_return\fP\^[]\^;
- .br
- int \fInmap\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .IP \fImap_return\fP 1i
- Returns the mapping list.
- .IP \fInmap\fP 1i
- Specifies the number of items in the mapping list.
- .\" End marker code here
- .LP
- .\" $Header: XGetPMap.d,v 1.2 88/06/11 07:51:13 mento Exp $
- The
- .PN XGetPointerMapping
- function returns the current mapping of the pointer.
- Pointer buttons are numbered starting from one.
- .PN 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.
- .LP
- .sp
- To control the pointer's interactive feel, use
- .PN XChangePointerControl .
- .IN "XChangePointerControl" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XChPointCon.f,v 1.1 88/02/26 09:58:33 mento Exp $
- XChangePointerControl\^(\^\fIdisplay\fP, \fIdo_accel\fP\^, \fIdo_threshold\fP\^, \fIaccel_numerator\fP\^,
- .br
- \fIaccel_denominator\fP\^, \fIthreshold\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- Bool \fIdo_accel\fP\^, \fIdo_threshold\fP\^;
- .br
- int \fIaccel_numerator\fP\^, \fIaccel_denominator\fP\^;
- .br
- int \fIthreshold\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" $Header: doaccel.a,v 1.4 88/05/14 09:22:57 mento Exp $
- .IP \fIdo_accel\fP 1i
- Specifies a Boolean value that controls whether the values for
- the accel_numerator or accel_denominator are used.
- .\" $Header: dothreshold.a,v 1.5 88/05/14 09:24:07 mento Exp $
- .IP \fIdo_threshold\fP 1i
- Specifies a Boolean value that controls whether the value for the
- threshold is used.
- .\" $Header: accelnum.a,v 1.1 88/02/26 10:04:44 mento Exp $
- .IP \fIaccel_numerator\fP 1i
- Specifies the numerator for the acceleration multiplier.
- .\" $Header: acceldenom.a,v 1.1 88/02/26 10:04:37 mento Exp $
- .IP \fIaccel_denominator\fP 1i
- Specifies the denominator for the acceleration multiplier.
- .\" $Header: threshold.a,v 1.1 88/02/26 10:31:38 mento Exp $
- .IP \fIthreshold\fP 1i
- Specifies the acceleration threshold.
- .\" End marker code here
- .LP
- .\" $Header: XChPointCon.d,v 1.2 88/06/11 07:49:03 mento Exp $
- The
- .PN 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
- .PN True
- for the pointer values to be set,
- or the parameters are unchanged.
- Negative values (other than \-1) generate a
- .PN BadValue
- error, as does a zero value
- for the accel_denominator argument.
- .LP
- .PN XChangePointerControl
- can generate a
- .PN BadValue
- error.
- .LP
- .sp
- To get the current pointer parameters, use
- .PN XGetPointerControl .
- .IN "XGetPointerControl" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .\" $Header: XGetPntrCnt.f,v 1.1 88/02/26 10:00:55 mento Exp $
- XGetPointerControl\^(\^\fIdisplay\fP, \fIaccel_numerator_return\fP\^, \fIaccel_denominator_return\fP\^,
- .br
- \fIthreshold_return\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- int *\fIaccel_numerator_return\fP\^, *\fIaccel_denominator_return\fP\^;
- .br
- int *\fIthreshold_return\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" $Header: accelnumret.a,v 1.1 88/02/26 10:04:45 mento Exp $
- .IP \fIaccel_numerator_return\fP 1i
- Returns the numerator for the acceleration multiplier.
- .\" $Header: acceldenomrt.a,v 1.1 88/02/26 10:04:37 mento Exp $
- .IP \fIaccel_denominator_return\fP 1i
- Returns the denominator for the acceleration multiplier.
- .\" $Header: thresholdret.a,v 1.1 88/02/26 10:31:39 mento Exp $
- .IP \fIthreshold_return\fP 1i
- Returns the acceleration threshold.
- .\" End marker code here
- .LP
- .\" $Header: XGetPntrCnt.d,v 1.1 88/02/26 10:48:32 mento Exp $
- The
- .PN XGetPointerControl
- function returns the pointer's current acceleration multiplier
- and acceleration threshold.
- .NH 2
- Keyboard Encoding
- .XS
- \*(SN Keyboard Encoding
- .XE
- .LP
- 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.
- .LP
- 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
- .Pn < 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
- .Pn < X11/keysym.h >,
- which defines symbols for ISO Latin 1\-4, Greek, and miscellaneous.
- .LP
- 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 ``\fIK\fP,''
- then the list is treated as if it were the list
- ``\fIK\fP NoSymbol \fIK\fP NoSymbol.''
- If the list (ignoring trailing NoSymbol entries) is
- a pair of KeySyms ``\fIK1 K2\fP,''
- then the list is treated as if it were the list ``\fIK1 K2 K1 K2\fP.''
- If the list (ignoring trailing NoSymbol entries) is
- a triple of KeySyms ``\fIK1 K2 K3\fP,''
- then the list is treated as if it were the list ``\fIK1 K2 K3\fP NoSymbol.''
- When an explicit ``void'' element is desired in the list,
- the value VoidSymbol can be used.
- .LP
- 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 ``\fIK\fP''
- 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 ``\fIK\fP'' and the second element were
- the uppercase form of ``\fIK\fP.''
- .LP
- The standard rules for obtaining a KeySym from a
- .PN 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.
- .LP
- 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.
- .LP
- 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.
- .LP
- 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.
- .sp
- .LP
- To obtain the legal KeyCodes for a display, use
- .PN XDisplayKeycodes .
- .IN "XDisplayKeycodes" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- XDisplayKeycodes\^(\^\fIdisplay\fP\^, \fImin_keycodes_return\fP\^, \
- \fImax_keycodes_return\fP\^)
- .br
- Display *\^\fIdisplay\fP\^;
- .br
- int *\^\fImin_keycodes_return\fP\^, *\^\fImax_keycodes_return\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .IP \fImin_keycodes_return\fP 1i
- Returns the minimum number of KeyCodes.
- .IP \fImax_keycodes_return\fP 1i
- Returns the maximum number of KeyCodes.
- .\" End marker code here
- .LP
- The
- .PN 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.
- .sp
- .LP
- To obtain the symbols for the specified KeyCodes, use
- .PN XGetKeyboardMapping .
- .IN "XGetKeyboardMapping" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- KeySym *XGetKeyboardMapping(\^\fIdisplay\fP, \fIfirst_keycode\fP, \fIkeycode_count\fP,
- .br
- \fIkeysyms_per_keycode_return\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- KeyCode \fIfirst_keycode\fP\^;
- .br
- int \fIkeycode_count\fP\^;
- .br
- int *\fIkeysyms_per_keycode_return\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .ds Kc returned
- .IP \fIfirst_keycode\fP 1i
- Specifies the first KeyCode that is to be \*(Kc.
- .IP \fIkeycode_count\fP 1i
- Specifies the number of KeyCodes that are to be returned.
- .IP \fIkeysyms_per_keycode_return\fP 1i
- Returns the number of KeySyms per KeyCode.
- .\" End marker code here
- .LP
- .\" $Header: XGetKeyMap.d,v 1.5 88/07/10 11:18:06 mento Exp $
- The
- .PN 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
- .PN XDisplayKeycodes ,
- or a
- .PN BadValue
- error results.
- In addition, the following expression must be less than or equal
- to max_keycode as returned by
- .PN XDisplayKeycodes :
- .LP
- .Ds
- first_keycode + keycode_count \- 1
- .De
- .LP
- If this is not the case, a
- .PN BadValue
- error results.
- The number of elements in the KeySyms list is:
- .LP
- .Ds
- keycode_count * keysyms_per_keycode_return
- .De
- .LP
- KeySym number N, counting from zero, for KeyCode K has the following index
- in the list, counting from zero:
- .Ds
- (K \- first_code) * keysyms_per_code_return + N
- .De
- .LP
- 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
- .PN NoSymbol
- is used to fill in unused elements for
- individual KeyCodes.
- To free the storage returned by
- .PN XGetKeyboardMapping ,
- use
- .PN XFree .
- .LP
- .PN XGetKeyboardMapping
- can generate a
- .PN BadValue
- error.
- .LP
- .sp
- To change the keyboard mapping, use
- .PN XChangeKeyboardMapping .
- .IN "XChangeKeyboardMapping" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- XChangeKeyboardMapping(\^\fIdisplay\fP, \fIfirst_keycode\fP, \fIkeysyms_per_keycode\fP, \fIkeysyms\fP, \fInum_codes\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- int \fIfirst_keycode\fP\^;
- .br
- int \fIkeysyms_per_keycode\fP\^;
- .br
- KeySym *\fIkeysyms\fP\^;
- .br
- int \fInum_codes\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .ds Kc changed
- .IP \fIfirst_keycode\fP 1i
- Specifies the first KeyCode that is to be \*(Kc.
- .IP \fIkeysyms_per_keycode\fP 1i
- Specifies the number of KeySyms per KeyCode.
- .IP \fIkeysyms\fP 1i
- Specifies an array of KeySyms.
- .IP \fInum_codes\fP 1i
- Specifies the number of KeyCodes that are to be changed.
- .\" End marker code here
- .LP
- .\" $Header: XCKMap.d,v 1.6 88/08/19 20:53:42 mento Exp $
- The
- .PN 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:
- .LP
- .Ds
- num_codes * keysyms_per_keycode
- .De
- .LP
- The specified first_keycode must be greater than or equal to min_keycode
- returned by
- .PN XDisplayKeycodes ,
- or a
- .PN BadValue
- error results.
- In addition, the following expression must be less than or equal to
- max_keycode as returned by
- .PN XDisplayKeycodes ,
- or a
- .PN BadValue
- error results:
- .LP
- .Ds
- first_keycode + num_codes \- 1
- .De
- .LP
- KeySym number N, counting from zero, for KeyCode K has the following index
- in keysyms, counting from zero:
- .LP
- .Ds
- (K \- first_keycode) * keysyms_per_keycode + N
- .De
- .LP
- 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
- .PN NoSymbol
- should be used to fill in unused elements
- for individual KeyCodes.
- It is legal for
- .PN NoSymbol
- to appear in nontrailing positions
- of the effective list for a KeyCode.
- .PN XChangeKeyboardMapping
- generates a
- .PN MappingNotify
- event.
- .LP
- There is no requirement that the X server interpret this mapping.
- It is merely stored for reading and writing by clients.
- .LP
- .PN XChangeKeyboardMapping
- can generate
- .PN BadAlloc
- and
- .PN BadValue
- errors.
- .LP
- The next four functions make use of the
- .PN XModifierKeymap
- data structure, which contains:
- .LP
- .IN "XModifierKeymap" "" "@DEF@"
- .\" Start marker code here
- .Ds 0
- .TA .5i 2.5i
- .ta .5i 2.5i
- typedef struct {
- int max_keypermod; /* This server's max number of keys per modifier */
- KeyCode *modifiermap; /* An 8 by max_keypermod array of the modifiers */
- } XModifierKeymap;
- .De
- .\" End marker code here
- .LP
- To create an
- .PN XModifierKeymap
- structure, use
- .PN XNewModifiermap .
- .IN "XNewModifiermap" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- XModifierKeymap *XNewModifiermap(\^\fImax_keys_per_mod\fP\^)
- .br
- int \fImax_keys_per_mod\fP\^;
- .FN
- .IP \fImax_keys_per_mod\fP 1i
- Specifies the number of KeyCode entries preallocated to the modifiers
- in the map.
- .\" End marker code here
- .LP
- .\" $Header: XNewModMap.d,v 1.5 88/08/19 20:54:43 mento Exp $
- The
- .PN XNewModifiermap
- function returns a pointer to
- .PN XModifierKeymap
- structure for later use.
- .LP
- .sp
- To add a new entry to an
- .PN XModifierKeymap
- structure, use
- .PN XInsertModifiermapEntry .
- .IN "XInsertModifiermapEntry" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- XModifierKeymap *XInsertModifiermapEntry\^(\^\fImodmap\fP, \
- \fIkeycode_entry\fP, \fImodifier\fP\^)
- .br
- XModifierKeymap *\fImodmap\fP\^;
- .br
- KeyCode \fIkeycode_entry\fP\^;
- .br
- int \fImodifier\fP\^;
- .FN
- .IP \fImodmap\fP 1i
- Specifies the
- .PN XModifierKeymap
- structure.
- .IP \fIkeycode_entry\fP 1i
- Specifies the KeyCode.
- .IP \fImodifier\fP 1i
- Specifies the modifier.
- .\" End marker code here
- .LP
- The
- .PN XInsertModifiermapEntry
- function adds the specified KeyCode to the set that controls the specified
- modifier and returns the resulting
- .PN XModifierKeymap
- structure (expanded as needed).
- .LP
- .sp
- To delete an entry from an
- .PN XModifierKeymap
- structure, use
- .PN XDeleteModifiermapEntry .
- .IN "XDeleteModifiermapEntry" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- XModifierKeymap *XDeleteModifiermapEntry\^(\^\fImodmap\fP, \
- \fIkeycode_entry\fP, \fImodifier\fP\^)
- .br
- XModifierKeymap *\fImodmap\fP\^;
- .br
- KeyCode \fIkeycode_entry\fP\^;
- .br
- int \fImodifier\fP\^;
- .FN
- .IP \fImodmap\fP 1i
- Specifies the
- .PN XModifierKeymap
- structure.
- .IP \fIkeycode_entry\fP 1i
- Specifies the KeyCode.
- .IP \fImodifier\fP 1i
- Specifies the modifier.
- .\" End marker code here
- .LP
- The
- .PN XDeleteModifiermapEntry
- function deletes the specified KeyCode from the set that controls the
- specified modifier and returns a pointer to the resulting
- .PN XModifierKeymap
- structure.
- .LP
- .sp
- To destroy an
- .PN XModifierKeymap
- structure, use
- .PN XFreeModifiermap .
- .IN "XFreeModifiermap" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- XFreeModifiermap(\^\fImodmap\fP\^)
- .br
- XModifierKeymap *\fImodmap\fP;
- .FN
- .IP \fImodmap\fP 1i
- Specifies the
- .PN XModifierKeymap
- structure.
- .\" End marker code here
- .LP
- .\" $Header: XFreeModMap.d,v 1.3 88/04/23 10:21:33 mento Exp $
- The
- .PN XFreeModifiermap
- function frees the specified
- .PN XModifierKeymap
- structure.
- .LP
- .sp
- To set the KeyCodes to be used as modifiers, use
- .PN XSetModifierMapping .
- .IN "XSetModifierMapping" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- int XSetModifierMapping(\^\fIdisplay\fP, \fImodmap\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- XModifierKeymap *\fImodmap\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .IP \fImodmap\fP 1i
- Specifies the
- .PN XModifierKeymap
- structure.
- .\" End marker code here
- .LP
- .\" $Header: XSetModMap.d,v 1.6 88/08/19 20:58:48 mento Exp $
- The
- .PN 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
- .PN MappingNotify
- event, and
- .PN XSetModifierMapping
- returns
- .PN MappingSuccess .
- X permits at most eight modifier keys.
- If more than eight are specified in the
- .PN XModifierKeymap
- structure, a
- .PN BadLength
- error results.
- .LP
- The modifiermap member of the
- .PN XModifierKeymap
- structure contains eight sets of max_keypermod KeyCodes,
- one for each modifier in the order
- .PN Shift ,
- .PN Lock ,
- .PN Control ,
- .PN Mod1 ,
- .PN Mod2 ,
- .PN Mod3 ,
- .PN Mod4 ,
- and
- .PN 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
- .PN Display
- structure,
- or a
- .PN BadValue
- error results.
- .LP
- 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
- .PN 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,
- .PN XSetModifierMapping
- returns
- .PN MappingBusy ,
- and none of the modifiers is changed.
- .LP
- .PN XSetModifierMapping
- can generate
- .PN BadAlloc
- and
- .PN BadValue
- errors.
- .LP
- .sp
- To obtain the KeyCodes used as modifiers, use
- .PN XGetModifierMapping .
- .IN "XGetModifierMapping" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- XModifierKeymap *XGetModifierMapping(\^\fIdisplay\fP\^)
- .br
- Display *\fIdisplay\fP\^;
-
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" End marker code here
- .LP
- .\" $Header: XGetModMap.d,v 1.3 88/08/19 21:00:28 mento Exp $
- The
- .PN XGetModifierMapping
- function returns a pointer to a newly created
- .PN XModifierKeymap
- structure that contains the keys being used as modifiers.
- The structure should be freed after use by calling
- .PN XFreeModifiermap .
- If only zero values appear in the set for any modifier,
- that modifier is disabled.
- .bp
-