\&
.sp 1
.ce 3
\s+1\fBChapter 7\fP\s-1

\s+1\fBWindow Manager Functions\fP\s-1
.sp 2
.nr H1 7
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.na
.LP
.XS
Chapter 7: Window Manager Functions 
.XE
Although it is difficult to categorize functions as
application only or window manager only,
the functions in this chapter are most often used by window managers.
It is not expected that these functions will be used by most 
application programs.
You can use the Xlib window manager functions to:
.IP \(bu 5
Change the parent of a window
.IP \(bu 5
Control the lifetime of a window
.IP \(bu 5
Determine resident colormaps
.IP \(bu 5
Grab the pointer
.IP \(bu 5
Grab the keyboard
.IP \(bu 5
Grab the server
.IP \(bu 5
Control event processing 
.IP \(bu 5
Manipulate the keyboard and pointer settings
.IP \(bu 5
Control the screen saver
.IP \(bu 5
Control host access
.RE
.NH 2
Changing the Parent of a Window
.XS
\*(SN Changing the Parent of a Window 
.XE
.LP
To change a window's parent to another window on the same screen, use
.PN XReparentWindow .
There is no way to move a window between screens.
.IN "XReparentWindow" "" "@DEF@"
.FD 0
.\" $Header: XReparentWin.f,v 1.1 88/02/26 10:02:42 mento Exp $
XReparentWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIparent\fP\^, \fIx\fP\^, \fIy\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      Window \fIparent\fP\^;
.br
      int \fIx\fP\^, \fIy\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: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: parent.a,v 1.2 88/05/07 11:34:55 mento Exp $
.IP \fIparent\fP 1i
Specifies the parent window.
.ds Xy \ of the position in the new parent window
.\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
.IP \fIx\fP 1i
.br
.ns
.IP \fIy\fP 1i
Specify the x and y coordinates\*(Xy.
.LP
.\" $Header: XReparentWin.d,v 1.3 88/08/19 20:07:29 mento Exp $
If the specified window is mapped,
.PN XReparentWindow
automatically performs an
.PN UnmapWindow
request on it, removes it from its current position in the hierarchy,
and inserts it as the child of the specified parent.
The window is placed in the stacking order on top with respect to
sibling windows.
.LP
After reparenting the specified window,
.PN XReparentWindow
causes the X server to generate a
.PN ReparentNotify
event.
The override_redirect member returned in this event is
set to the window's corresponding attribute.
Window manager clients usually should ignore this window if this member
is set to
.PN True .
Finally, if the specified window was originally mapped,
the X server automatically performs a
.PN MapWindow
request on it.
.LP
The X server performs normal exposure processing on formerly obscured
windows.
The X server might not generate 
.PN Expose 
events for regions from the initial
.PN UnmapWindow
request that are immediately obscured by the final
.PN MapWindow
request.
A
.PN BadMatch
error results if:
.IP \(bu 5
The new parent window is not on the same screen as
the old parent window.
.IP \(bu 5
The new parent window is the specified window or an inferior of the
specified window.
.IP \(bu 5
The specified window has a
.PN ParentRelative
background, and the new parent window is not the same depth as the
specified window.
.LP
.PN XReparentWindow
can generate
.PN BadMatch
and
.PN BadWindow 
errors.
.NH 2
Controlling the Lifetime of a Window
.XS
\*(SN Controlling the Lifetime of a Window 
.XE
.LP
The save-set of a client is a list of other clients' windows that,
if they are inferiors of one of the client's windows at connection close,
should not be destroyed and should be remapped if they are unmapped.
For further information about close-connection processing,
see section 2.6.
To allow an application's window to survive when a window manager that
has reparented a window fails,
Xlib provides the save-set functions that you can 
use to control the longevity of subwindows
that are normally destroyed when the parent is destroyed.
For example, a window manager that wants to add decoration
to a window by adding a frame might reparent an application's
window. 
When the frame is destroyed,
the application's window should not be destroyed 
but be returned to its previous place in the window hierarchy.
.LP
The X server automatically removes windows from the save-set
when they are destroyed.
.LP
.sp
To add or remove a window from the client's save-set, use
.PN XChangeSaveSet .
.IN "XChangeSaveSet" "" "@DEF@"
.FD 0
.\" $Header: XChSaveSet.f,v 1.1 88/02/26 09:58:34 mento Exp $
XChangeSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^, \fIchange_mode\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      int \fIchange_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.
.ds Wi that you want to add to or delete from the client's save-set
.\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
.IP \fIw\fP 1i
Specifies the window \*(Wi.
.\" $Header: changemode.a,v 1.3 88/05/14 06:01:44 mento Exp $
.IP \fIchange_mode\fP 1i
Specifies the mode.
You can pass
.PN SetModeInsert 
or
.PN SetModeDelete .
.LP
.\" $Header: XChSaveSet.d,v 1.4 88/06/11 07:49:10 mento Exp $
Depending on the specified mode,
.PN XChangeSaveSet
either inserts or deletes the specified window from the client's save-set. 
The specified window must have been created by some other client,
or a
.PN BadMatch
error results.
.LP
.PN XChangeSaveSet
can generate
.PN BadMatch ,
.PN BadValue ,
and
.PN BadWindow 
errors.
.LP
.sp
To add a window to the client's save-set, use
.PN XAddToSaveSet .
.IN "XAddToSaveSet" "" "@DEF@"
.FD 0
XAddToSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\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 Wi that you want to add to the client's save-set
.\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
.IP \fIw\fP 1i
Specifies the window \*(Wi.
.LP
.\" $Header: XAddSaveSet.d,v 1.3 88/06/11 07:48:34 mento Exp $
The
.PN XAddToSaveSet
function adds the specified window to the client's save-set.
The specified window must have been created by some other client,
or a
.PN BadMatch
error results.
.LP
.PN XAddToSaveSet
can generate
.PN BadMatch
and
.PN BadWindow 
errors.
.LP
.sp
To remove a window from the client's save-set, use
.PN XRemoveFromSaveSet .
.IN "XRemoveFromSaveSet" "" "@DEF@"
.FD 0
XRemoveFromSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\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 Wi that you want to delete from the client's save-set
.\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
.IP \fIw\fP 1i
Specifies the window \*(Wi.
.LP
.\" $Header: XRmvSaveSet.d,v 1.3 88/06/11 07:52:51 mento Exp $
The
.PN XRemoveFromSaveSet
function removes the specified window from the client's save-set.
The specified window must have been created by some other client,
or a
.PN BadMatch
error results.
.LP
.PN XRemoveFromSaveSet
can generate
.PN BadMatch 
and
.PN BadWindow 
errors.
.NH 2
Determining Resident Colormaps
.XS
\*(SN Determining Resident Colormap 
.XE
.LP
Xlib provides functions that you can use to install a colormap, 
uninstall a colormap, and obtain a list of installed colormaps.
.LP
At any time,
there is a subset of the installed maps that is viewed as an ordered list
and is called the required list.
The length of the required list is at most M,
where M is the minimum number of installed colormaps specified for the screen
in the connection setup.
The required list is maintained as follows.
When a colormap is specified to
.PN XInstallColormap ,
it is added to the head of the list;
the list is truncated at the tail, if necessary, to keep its length to 
at most M.
When a colormap is specified to
.PN XUninstallColormap
and it is in the required list,
it is removed from the list.
A colormap is not added to the required list when it is implicitly installed
by the X server,
and the X server cannot implicitly uninstall a colormap that is in the
required list.
.LP
.sp
To install a colormap, use
.PN XInstallColormap .
.IN "XInstallColormap" "" "@DEF@"
.FD 0
.\" $Header: XInsCmap.f,v 1.2 88/05/14 06:22:44 mento Exp $
XInstallColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Colormap \fIcolormap\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: cmap.a,v 1.2 88/05/09 06:39:13 mento Exp $
.IP \fIcolormap\fP 1i
Specifies the colormap.
.LP
.\" $Header: XInsCmap.d,v 1.3 88/06/11 07:51:41 mento Exp $
The
.PN XInstallColormap
function installs the specified colormap for its associated screen.
All windows associated with this colormap immediately display with
true colors.
You associated the windows with this colormap when you created them by calling
.PN XCreateWindow ,
.PN XCreateSimpleWindow ,
.PN XChangeWindowAttributes ,
or
.PN XSetWindowColormap .
.LP
If the specified colormap is not already an installed colormap, 
the X server generates a
.PN ColormapNotify
event on each window that has that colormap.
In addition, for every other colormap that is installed as 
a result of a call to
.PN XInstallColormap ,
the X server generates a
.PN ColormapNotify
event on each window that has that colormap.
.LP
.PN XInstallColormap
can generate a
.PN BadColor 
error.
.LP
.sp
To uninstall a colormap, use
.PN XUninstallColormap .
.IN "XUninstallColormap" "" "@DEF@"
.FD 0
.\" $Header: XUninsCmap.f,v 1.2 88/05/14 06:28:37 mento Exp $
XUninstallColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Colormap \fIcolormap\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: cmap.a,v 1.2 88/05/09 06:39:13 mento Exp $
.IP \fIcolormap\fP 1i
Specifies the colormap.
.LP
.\" $Header: XUninsCmap.d,v 1.4 88/08/19 20:13:47 mento Exp $
The
.PN XUninstallColormap
function removes the specified colormap from the required
list for its screen.
As a result,
the specified colormap might be uninstalled, 
and the X server might implicitly install or uninstall additional colormaps.
Which colormaps get installed or uninstalled is server-dependent
except that the required list must remain installed.
.LP
If the specified colormap becomes uninstalled, 
the X server generates a
.PN ColormapNotify
event on each window that has that colormap.
In addition, for every other colormap that is installed or uninstalled as a 
result of a call to 
.PN XUninstallColormap ,
the X server generates a
.PN ColormapNotify
event on each window that has that colormap.
.LP
.PN XUninstallColormap
can generate a
.PN BadColor 
error.
.LP
.sp
To obtain a list of the currently installed colormaps for a given screen, use
.PN XListInstalledColormaps .
.IN "XListInstalledColormaps" "" "@DEF@"
.FD 0
.\" $Header: XLstInsCmaps.f,v 1.1 88/02/26 10:01:27 mento Exp $
Colormap *XListInstalledColormaps\^(\^\fIdisplay\fP, \fIw\fP, \fInum_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      int *\fInum_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 Wi that determines the screen
.\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
.IP \fIw\fP 1i
Specifies the window \*(Wi.
.IP \fInum_return\fP 1i
Returns the number of currently installed colormaps.
.LP
.\" $Header: XLstInsCmaps.d,v 1.4 88/08/19 20:16:08 mento Exp $
The
.PN XListInstalledColormaps
function returns a list of the currently installed colormaps for the screen 
of the specified window.
The order of the colormaps in the list is not significant
and is no explicit indication of the required list.
When the allocated list is no longer needed,
free it by using
.PN XFree .
.LP
.PN XListInstalledColormaps
can generate a
.PN BadWindow 
error.
.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.
Window managers most often use these facilities
to implement certain styles of user interfaces.
Some toolkits also need to use these facilities for special purposes.
.LP
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@"
.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 .
.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@"
.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 .
.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@"
.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 .
.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@"
.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 .
.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@"
.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.
.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@"
.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 .
.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@"
.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 .
.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@"
.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 .
.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@"
.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.
.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.
.LP
.sp
To allow further events to be processed when the device has been frozen, use
.PN XAllowEvents .
.IN "XAllowEvents" "" "@DEF@"
.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 .
.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
Server Grabbing 
.XS
\*(SN Server Grabbing 
.XE
.LP
Xlib provides functions that you can use to grab and ungrab the server.
These functions can be used to control processing of output on other
connections by the window system server.
While the server is grabbed,
no processing of requests or close downs on any other connection will occur.
A client closing its connection automatically ungrabs the server.
.IN "Menus"
.IN "Window" "managers"
Although grabbing the server is highly discouraged, it is sometimes necessary.
.LP
.sp
To grab the server, use
.PN XGrabServer .
.IN "Server" "grabbing"
.IN "Grabbing" "server"
.IN "XGrabServer" "" "@DEF@"
.FD 0
.\" $Header: XGrabServer.f,v 1.1 88/02/26 10:01:06 mento Exp $
XGrabServer\^(\^\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.
.LP
.\" $Header: XGrabServer.d,v 1.3 88/08/19 20:31:23 mento Exp $
The
.PN XGrabServer
function disables processing of requests and close downs on all other 
connections than the one this request arrived on.
You should not grab the X server any more than is absolutely necessary.
.LP
.sp
To ungrab the server, use
.PN XUngrabServer .
.IN "XUngrabServer" "" "@DEF@"
.FD 0
.\" $Header: XUngrbSrvr.f,v 1.1 88/02/26 10:04:07 mento Exp $
XUngrabServer\^(\^\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.
.LP
.\" $Header: XUngrbSrvr.d,v 1.3 88/08/19 20:32:06 mento Exp $
The
.PN XUngrabServer
function restarts processing of requests and close downs on other connections.
You should avoid grabbing the X server as much as possible.
.NH 2
Miscellaneous Control Functions
.XS
\*(SN Miscellaneous Control Functions
.XE
.LP
This section discusses how to:
.IP \(bu 5
Control the input focus
.IP \(bu 5
Control the pointer
.IP \(bu 5
Kill clients
.LE
.NH 3
Controlling Input Focus
.XS
\*(SN Controlling Input Focus 
.XE
.LP
Xlib provides functions that you can use to move the pointer position 
as well as to set and get the input focus.
.LP
.sp
To move the pointer to an arbitrary point on the screen, use
.PN XWarpPointer .
.IN "XWarpPointer" "" "@DEF@"
.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.
.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 pointer is contained in the specified rectangle of src_w.
.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.
.LP
.sp
To set the input focus, use
.PN XSetInputFocus .
.IN "XSetInputFocus" "" "@DEF@"
.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 .
.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@"
.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 ).
.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 3
Killing Clients
.XS
\*(SN Killing Clients 
.XE
.LP
Xlib provides functions that you can use to control the lifetime
of resources owned by a client or to cause the connection to
a client to be destroyed.
.LP
.sp
To change a client's close-down mode, use
.PN XSetCloseDownMode .
.IN "XSetCloseDownMode" "" "@DEF@"
.FD 0
.\" $Header: XChClsDwnMd.f,v 1.1 88/02/26 09:58:30 mento Exp $
XSetCloseDownMode\^(\^\fIdisplay\fP, \fIclose_mode\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fIclose_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: closemode.a,v 1.4 88/05/14 09:00:07 mento Exp $
.IP \fIclose_mode\fP 1i
Specifies the client close-down mode.
You can pass 
.PN DestroyAll , 
.PN RetainPermanent , 
or
.PN RetainTemporary . 
.LP
.\" $Header: XChClsDwnMd.d,v 1.3 88/08/19 20:35:01 mento Exp $
The
.PN XSetCloseDownMode
defines what will happen to the client's resources at connection close.
A connection starts in
.PN DestroyAll
mode.
For information on what happens to the client's resources when the
close_mode argument is
.PN RetainPermanent
or
.PN RetainTemporary ,
see section 2.6.
.LP
.PN XSetCloseDownMode
can generate a
.PN BadValue 
error.
.LP
.sp
To destroy a client, use
.PN XKillClient .
.IN "XKillClient" "" "@DEF@"
.FD 0
.\" $Header: XKillClient.f,v 1.1 88/02/26 10:01:20 mento Exp $
XKillClient\^(\^\fIdisplay\fP, \fIresource\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      XID \fIresource\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: resource.a,v 1.2 88/05/14 09:01:41 mento Exp $
.IP \fIresource\fP 1i
Specifies any resource associated with the client that you want to destroy or
.PN AllTemporary .
.LP
.\" $Header: XKillClient.d,v 1.3 88/08/19 20:35:43 mento Exp $
The
.PN XKillClient
function
forces a close-down of the client
that created the resource
if a valid resource is specified.
If the client has already terminated in
either 
.PN RetainPermanent 
or 
.PN RetainTemporary 
mode, all of the client's
resources are destroyed.
If 
.PN AllTemporary 
is specified, the resources of all clients that have terminated in
.PN RetainTemporary 
are destroyed (see section 2.6).
This permits implementation of window manager facilities that aid debugging.
A client can set its close-down mode to
.PN RetainTemporary .
If the client then crashes,
its windows would not be destroyed. 
The programmer can then inspect the application's window tree 
and use the window manager to destroy the zombie windows.
.LP
.PN XKillClient
can generate a
.PN BadValue 
error.
.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 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:
.LP
/* Mask bits for ChangeKeyboardControl */
.TS
lw(.5i) lw(2.5i) lw(.75i).
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
.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@"
.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 one value for each bit set to 1 in the mask.
.\" $Header: values2.a,v 1.2 88/04/06 17:16:22 mento Exp $
.IP \fIvalues\fP 1i
Specifies which controls to change.
This mask is the bitwise inclusive OR of the valid control mask bits.
.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@"
.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.
.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@"
.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
.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@"
.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.
.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@"
.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.
.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@"
.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. 
.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@"
.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.
.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@"
.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.
.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@"
.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.
.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@"
.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.
.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@"
.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.
.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
.IN "XLookupString"
Most applications will find the simple interface
.PN XLookupString ,
which performs simple translation of a key event to an ASCII string, 
most useful.
Keyboard-related utilities are discussed in chapter 10.
The following section explains how to completely control the bindings
of symbols to keys and modifiers.
.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 include 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 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 here.
Which group to use is determined by 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,
which KeySym to use is also determined by modifier state.
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@"
.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.
.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@"
.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.
.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@"
.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 a pointer to an array of KeySyms.
.IP \fInum_codes\fP 1i
Specifies the number of KeyCodes that are to be changed.
.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@"
.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
.LP
To create an
.PN XModifierKeymap
structure, use
.PN XNewModifiermap .
.IN "XNewModifiermap" "" "@DEF@"
.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.
.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@"
.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 a pointer to the 
.PN XModifierKeymap
structure.
.IP \fIkeycode_entry\fP 1i
Specifies the KeyCode. 
.IP \fImodifier\fP 1i
Specifies the modifier.
.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@"
.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 a pointer to the 
.PN XModifierKeymap
structure.
.IP \fIkeycode_entry\fP 1i
Specifies the KeyCode. 
.IP \fImodifier\fP 1i
Specifies the modifier.
.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@"
.FD 0
XFreeModifiermap(\^\fImodmap\fP\^)
.br
        XModifierKeymap *\fImodmap\fP;
.FN
.IP \fImodmap\fP 1i
Specifies a pointer to the 
.PN XModifierKeymap
structure.
.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@"
.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 a pointer to the 
.PN XModifierKeymap
structure.
.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.
No KeyCode may appear twice in the entire map,
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@"
.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.
.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.
.NH 2
Screen Saver Control
.XS
\*(SN Screen Saver Control
.XE
.LP
Xlib provides functions that you can use to set or reset the mode 
of the screen saver, to force or activate the screen saver,
or to obtain the current screen saver values.
.LP
.sp
To set the screen saver mode, use
.PN XSetScreenSaver .
.IN "XSetScreenSaver" "" "@DEF@"
.FD 0
.\" $Header: XSetScrnSvr.f,v 1.1 88/02/26 10:03:37 mento Exp $
XSetScreenSaver\^(\^\fIdisplay\fP, \fItimeout\fP\^, \fIinterval\fP\^, \fIprefer_blanking\fP\^, \fIallow_exposures\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fItimeout\fP\^, \fIinterval\fP\^;
.br
      int \fIprefer_blanking\fP\^; 
.br
      int \fIallow_exposures\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: timeout.a,v 1.1 88/02/26 10:31:42 mento Exp $
.IP \fItimeout\fP 1i
Specifies the timeout, in seconds, until the screen saver turns on.
.\" $Header: interval.a,v 1.2 88/04/06 18:31:20 mento Exp $
.IP \fIinterval\fP 1i
Specifies the interval, in seconds, between screen saver alterations.
.\" $Header: preferblank.a,v 1.3 88/05/14 09:42:26 mento Exp $
.IP \fIprefer_blanking\fP 1i
Specifies how to enable screen blanking.
You can pass
.PN DontPreferBlanking ,
.PN PreferBlanking ,
or
.PN DefaultBlanking .
.\" $Header: allowexp.a,v 1.3 88/05/14 09:43:06 mento Exp $
.IP \fIallow_exposures\fP 1i
Specifies the screen save control values.
You can pass
.PN DontAllowExposures ,
.PN AllowExposures ,
or
.PN DefaultExposures .
.LP
.\" $Header: XSetScrnSvr.d,v 1.3 88/08/19 21:02:13 mento Exp $
Timeout and interval are specified in seconds. 
A timeout of 0 disables the screen saver 
(but an activated screen saver is not deactivated),
and a timeout of \-1 restores the default.
Other negative values generate a
.PN BadValue
error.
If the timeout value is nonzero, 
.PN XSetScreenSaver
enables the screen saver.
An interval of 0 disables the random-pattern motion.
If no input from devices (keyboard, mouse, and so on) is generated 
for the specified number of timeout seconds once the screen saver is enabled,
the screen saver is activated.
.LP
For each screen, 
if blanking is preferred and the hardware supports video blanking, 
the screen simply goes blank.  
Otherwise, if either exposures are allowed or the screen can be regenerated 
without sending 
.PN Expose 
events to clients, 
the screen is tiled with the root window background tile randomly 
re-origined each interval minutes.
Otherwise, the screens' state do not change, 
and the screen saver is not activated.
The screen saver is deactivated,
and all screen states are restored at the next
keyboard or pointer input or at the next call to
.PN XForceScreenSaver
with mode
.PN ScreenSaverReset .  
.LP
If the server-dependent screen saver method supports periodic change,
the interval argument serves as a hint about how long the change period
should be, and zero hints that no periodic change should be made.
Examples of ways to change the screen include scrambling the colormap
periodically, moving an icon image around the screen periodically, or tiling
the screen with the root window background tile, randomly re-origined
periodically.
.LP
.PN XSetScreenSaver
can generate a
.PN BadValue 
error.
.LP
.sp
To force the screen saver on or off, use
.PN XForceScreenSaver .
.IN "XForceScreenSaver" "" "@DEF@"
.FD 0
XForceScreenSaver\^(\^\fIdisplay\fP\^, \fImode\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fImode\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 \fImode\fP 1i
Specifies the mode that is to be applied.
You can pass
.PN ScreenSaverActive
or
.PN ScreenSaverReset .
.LP
.\" $Header: XForScrnSvr.d,v 1.2 88/06/11 07:50:37 mento Exp $
If the specified mode is 
.PN ScreenSaverActive 
and the screen saver currently is deactivated,
.PN XForceScreenSaver
activates the screen saver even if the screen saver had been disabled
with a timeout of zero.
If the specified mode is 
.PN ScreenSaverReset 
and the screen saver currently is enabled,
.PN XForceScreenSaver
deactivates the screen saver if it was activated,
and the activation timer is reset to its initial state 
(as if device input had been received).
.LP
.PN XForceScreenSaver
can generate a
.PN BadValue 
error.
.LP
.sp
To activate the screen saver, use
.PN XActivateScreenSaver .
.IN "XActivateScreenSaver" "" "@DEF@"
.FD 0
XActivateScreenSaver\^(\^\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.
.LP
.sp
To reset the screen saver, use
.PN XResetScreenSaver .
.IN "XResetScreenSaver" "" "@DEF@"
.FD 0
XResetScreenSaver\^(\^\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.
.LP
.sp
To get the current screen saver values, use
.PN XGetScreenSaver .
.IN "XGetScreenSaver" "" "@DEF@"
.FD 0
.\" $Header: XGetScrnSvr.f,v 1.1 88/02/26 10:00:59 mento Exp $
XGetScreenSaver\^(\^\fIdisplay\fP, \fItimeout_return\fP\^, \fIinterval_return\fP\^, \fIprefer_blanking_return\fP\^, 
.br
                  \fIallow_exposures_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int *\fItimeout_return\fP\^, *\fIinterval_return\fP\^;
.br
      int *\fIprefer_blanking_return\fP\^;
.br
      int *\fIallow_exposures_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: timeoutret.a,v 1.1 88/02/26 10:31:43 mento Exp $
.IP \fItimeout_return\fP 1i
Returns the timeout, in seconds, until the screen saver turns on.
.\" $Header: intervalret.a,v 1.1 88/02/26 10:28:20 mento Exp $
.IP \fIinterval_return\fP 1i
Returns the interval between screen saver invocations.
.\" $Header: prefrblnkret.a,v 1.2 88/05/14 09:49:37 mento Exp $
.IP \fIprefer_blanking_return\fP 1i
Returns the current screen blanking preference
.Pn ( DontPreferBlanking ,
.PN PreferBlanking ,
or
.PN DefaultBlanking ).
.\" $Header: allowexpret.a,v 1.2 88/05/14 09:50:38 mento Exp $
.IP \fIallow_exposures_return\fP 1i
Returns the current screen save control value
.Pn ( DontAllowExposures ,
.PN AllowExposures ,
or
.PN DefaultExposures ).
.NH 2
Controlling Host Access
.XS
\*(SN Controlling Host Access 
.XE
.LP
This section discusses how to:
.IP \(bu 5
Add, get, or remove hosts from the access control list
.IP \(bu 5
Change, enable, or disable access
.LE
.LP
.IN "Access control list"
.IN "Authentication"
X does not provide any protection on a per-window basis.
If you find out the resource ID of a resource, you can manipulate it.
To provide some minimal level of protection, however,
connections are permitted only from machines you trust.
This is adequate on single-user workstations but obviously
breaks down on timesharing machines.
Although provisions exist in the X protocol for proper connection
authentication, the lack of a standard authentication server
leaves host-level access control as the only common mechanism.
.LP
.IN "Default Protection"
The initial set of hosts allowed to open connections typically consists of:
.IP \(bu 5
The host the window system is running on.
.IP \(bu 5
On POSIX systems, each host listed in the
.PN /etc/X?.hosts 
file.
The ? indicates the number of the
display.
.IN "Files" "/etc/X?.hosts"
This file should consist of host names separated by newlines.
DECnet nodes must terminate in :: to distinguish them from Internet hosts.
.LP
If a host is not in the access control list when the access control 
mechanism is enabled and if the host attempts to establish a connection,
the server refuses the connection.
To change the access list,
the client must reside on the same host as the server and/or must
have been granted permission in the initial authorization at connection
setup.
.LP
Servers also can implement other access control policies in addition to
or in place of this host access facility.
For further information about other access control implementations,
see ``X Window System Protocol.''
.NH 3
Adding, Getting, or Removing Hosts
.XS
\*(SN Adding, Getting, or Removing Hosts 
.XE
.LP
Xlib provides functions that you can use to add, get, or remove hosts
from the access control list.
All the host access control functions use the 
.PN XHostAddress 
structure, which contains:
.LP
.IN "XHostAddress" "" "@DEF@"
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	int family;	/* for example FamilyInternet */
	int length;	/* length of address, in bytes */
	char *address;	/* pointer to where to find the address */
} XHostAddress;
.De
.LP
The family member specifies which protocol address family to use 
(for example, TCP/IP or DECnet) and can be
.PN FamilyInternet ,
.PN FamilyDECnet ,
or
.PN FamilyChaos .
The length member specifies the length of the address in bytes.
The address member specifies a pointer to the address.
.LP
For TCP/IP, the address should be in network byte order.
For the DECnet family, 
the server performs no automatic swapping on the address bytes.
A Phase IV address is two bytes long.
The first byte contains the least-significant eight bits of the node number.
The second byte contains the most-significant two bits of the
node number in the least-significant two bits of the byte
and the area in the most-significant six bits of the byte.
.LP
.sp
To add a single host, use
.PN XAddHost .
.IN "XAddHost" "" "@DEF@"
.FD 0
.\" $Header: XAddHost.f,v 1.1 88/02/26 09:58:00 mento Exp $
XAddHost\^(\^\fIdisplay\fP, \fIhost\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      XHostAddress *\fIhost\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 Ho added
.\" $Header: host.a,v 1.4 88/08/04 11:14:39 mento Exp $
.IP \fIhost\fP 1i
Specifies the host that is to be \*(Ho.
.LP
.\" $Header: XAddHost.d,v 1.4 88/06/11 07:48:33 mento Exp $
The
.PN XAddHost
function adds the specified host to the access control list for that display.
The server must be on the same host as the client issuing the command, or a
.PN BadAccess
error results.
.LP
.PN XAddHost
can generate
.PN BadAccess
and
.PN BadValue 
errors.
.LP
.sp
To add multiple hosts at one time, use
.PN XAddHosts .
.IN "XAddHosts" "" "@DEF@"
.FD 0
XAddHosts\^(\^\fIdisplay\fP, \fIhosts\fP, \fInum_hosts\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      XHostAddress *\fIhosts\fP\^;
.br
      int \fInum_hosts\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 Ho added
.IP \fIhosts\fP 1i
Specifies each host that is to be \*(Ho.
.IP \fInum_hosts\fP 1i
Specifies the number of hosts.
.LP
.\" $Header: XAddHosts.d,v 1.4 88/06/11 07:48:33 mento Exp $
The
.PN XAddHosts
function adds each specified host to the access control list for that display.
The server must be on the same host as the client issuing the command, or a
.PN BadAccess
error results.
.LP
.PN XAddHosts
can generate
.PN BadAccess
and
.PN BadValue 
errors.
.LP
.sp
To obtain a host list, use
.PN XListHosts .
.IN "XListHosts" "" "@DEF@"
.IN "Files" "<sys/socket.h>"
.FD 0
.\" $Header: XGetHosts.f,v 1.1 88/02/26 10:00:39 mento Exp $
XHostAddress *XListHosts\^(\^\fIdisplay\fP, \fInhosts_return\fP, \fIstate_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int *\fInhosts_return\fP\^;
.br
      Bool *\fIstate_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: nhosts.a,v 1.1 88/02/26 10:29:33 mento Exp $
.IP \fInhosts_return\fP 1i
Returns the number of hosts currently in the access control list.
.IP \fIstate_return\fP 1i
Returns the state of the access control.
.LP
.\" $Header: XGetHosts.d,v 1.2 88/06/11 07:51:06 mento Exp $
The
.PN XListHosts
function returns the current access control list as well as whether the use 
of the list at connection setup was enabled or disabled.
.PN XListHosts
allows a program to find out what machines can make connections.
It also returns a pointer to a list of host structures that
were allocated by the function. 
When no longer needed,
this memory should be freed by calling
.PN XFree .
.LP
.sp
To remove a single host, use
.PN XRemoveHost .
.IN "XRemoveHost" "" "@DEF@"
.FD 0
.\" $Header: XRemoveHost.f,v 1.1 88/02/26 10:02:40 mento Exp $
XRemoveHost\^(\^\fIdisplay\fP, \fIhost\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      XHostAddress *\fIhost\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 Ho removed
.\" $Header: host.a,v 1.4 88/08/04 11:14:39 mento Exp $
.IP \fIhost\fP 1i
Specifies the host that is to be \*(Ho.
.LP
.\" $Header: XRemoveHost.d,v 1.4 88/06/11 07:52:48 mento Exp $
The
.PN XRemoveHost
function removes the specified host from the access control list 
for that display.
The server must be on the same host as the client process, or a
.PN BadAccess
error results.
If you remove your machine from the access list,
you can no longer connect to that server,
and this operation cannot be reversed unless you reset the server.
.LP
.PN XRemoveHost
can generate
.PN BadAccess
and
.PN BadValue 
errors.
.LP
.sp
To remove multiple hosts at one time, use
.PN XRemoveHosts .
.IN "XRemoveHosts" "" "@DEF@"
.FD 0
XRemoveHosts\^(\^\fIdisplay\fP, \fIhosts\fP, \fInum_hosts\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      XHostAddress *\fIhosts\fP\^;
.br
      int \fInum_hosts\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 Ho removed
.IP \fIhosts\fP 1i
Specifies each host that is to be \*(Ho.
.IP \fInum_hosts\fP 1i
Specifies the number of hosts.
.LP
.\" $Header: XRemoveHosts.d,v 1.3 88/06/11 07:52:49 mento Exp $
The
.PN XRemoveHosts
function removes each specified host from the access control list for that 
display.  
The X server must be on the same host as the client process, or a
.PN BadAccess
error results.
If you remove your machine from the access list, 
you can no longer connect to that server,
and this operation cannot be reversed unless you reset the server.
.LP
.PN XRemoveHosts
can generate
.PN BadAccess
and
.PN BadValue 
errors.
.NH 3
Changing, Enabling, or Disabling Access Control
.XS
\*(SN Changing, Enabling, or Disabling Access Control 
.XE
.LP
Xlib provides functions that you can use to enable, disable, 
or change access control.
.LP
For these functions to execute successfully,
the client application must reside on the same host as the X server
and/or have been given permission in the initial authorization
at connection setup.
.LP
.sp
To change access control, use
.PN XSetAccessControl .
.IN "XSetAccessControl" "" "@DEF@"
.FD 0
XSetAccessControl\^(\^\fIdisplay\fP, \fImode\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fImode\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 \fImode\fP 1i
Specifies the mode.
You can pass
.PN EnableAccess
or
.PN DisableAccess .
.LP
.\" $Header: XChAccsCntrl.d,v 1.2 88/05/14 10:03:40 mento Exp $
The
.PN XSetAccessControl
function either enables or disables the use of the access control list 
at each connection setup.
.LP
.PN XSetAccessControl
can generate
.PN BadAccess
and
.PN BadValue 
errors.
.LP
.sp
To enable access control, use
.PN XEnableAccessControl .
.IN "XEnableAccessControl" "" "@DEF@"
.FD 0
.\" $Header: XEnAccsCntrl.f,v 1.1 88/02/26 09:59:47 mento Exp $
XEnableAccessControl\^(\^\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.
.LP
.\" $Header: XEnAccsCntrl.d,v 1.2 88/05/14 10:04:37 mento Exp $
The
.PN XEnableAccessControl
function enables the use of the access control list at each connection setup.
.LP
.PN XEnableAccessControl
can generate a
.PN BadAccess 
error.
.LP
.sp
To disable access control, use
.PN XDisableAccessControl .
.IN "XDisableAccessControl" "" "@DEF@"
.FD 0
.\" $Header: XDisAcsCntrl.f,v 1.1 88/02/26 09:59:41 mento Exp $
XDisableAccessControl\^(\^\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.
.LP
.\" $Header: XDisAcsCntrl.d,v 1.2 88/05/14 10:05:51 mento Exp $
The
.PN XDisableAccessControl
function disables the use of the access control list at each connection setup.
.LP
.PN XDisableAccessControl
can generate a
.PN BadAccess 
error.
.bp
