Opens a connection to the X server that controls a display.

###Arguments

• name Specifies the hardware display name, which determines the display and communications domain to be used. On a POSIX-conformant system, if the name is nil, it defaults to the value of the DISPLAY environment variable.

###Description The encoding and interpretation of the display name is implementation dependent. Strings in the Host Portable Character Encoding are supported; support for other characters is implementation dependent. On POSIX-conformant systems, the display name or DISPLAY environment variable can be a string in the format:

hostname:number.screen_number

• hostname Specifies the name of the host machine on which the display is physically attached. You follow the hostname with either a single colon (:) or a double colon (::).
• number Specifies the number of the display server on that host machine. You may optionally follow this display number with a period (.). A single CPU can have more than one display. Multiple displays are usually numbered starting with zero.
• screen_number Specifies the screen to be used on that server. Multiple screens can be controlled by a single X server. The screen_number sets an internal variable that can be accessed by using the #default_screen function. For example, the following would specify screen 1 of display 0 on the machine named dual-headed:

dual-headed:0.1

Returns the name of the display.

###Arguments

• string Specifies the character string.

###Description The .display_name function returns the name of the display that .new would attempt to use. If a nil string is specified, .display_name looks in the environment for the display and returns the display name that .new would attempt to use. This makes it easier to report to the user precisely which display the program attempted to open when the initial connection attempt failed.

###See also #error_database_text, #error_text, .new, #synchronize.

Activates the screen saver.

###See also #set_screen_saver, #force_screen_saver, #reset_screen_saver, #screen_saver.

Allocates the ExtCodes structure.

###Description For local Xlib extensions, the #add_extension function allocates the ExtCodes structure, bumps the extension number count, and chains the extension onto the extension list. (This permits extensions to Xlib without requiring server extensions.)

###See also #init_extension.

###Arguments

• host Specifies the host that is to be added.

###Description The #add_host function adds the specified host to the access control list for the display. The server must be on the same host as the client issuing the command, or a BadAccess error results.

#add_host can generate BadAccess and BadValue errors.

###Diagnostics

• BadAccess A client attempted to free a color map entry that it did not already allocate.
• BadAccess A client attempted to store into a read-only color map entry.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

###See also #add_hosts, #disable_access_control, #enable_access_control, X11::free, list_hosts, #remove_host, #remove_hosts, #set_access_control.

Adds each specified host to the access control list.

###Arguments

• hosts Specifies each host that is to be added.

###Description The #add_hosts function adds each specified host to the access control list for the display. The server must be on the same host as the client issuing the command, or a BadAccess error results.

#add_hosts can generate BadAccess and BadValue errors.

###Diagnostics

• BadAccess A client attempted to free a color map entry that it did not already allocate.
• BadAccess A client attempted to store into a read-only color map entry.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

###See also #add_host, #disable_access_control, #enable_access_control, X11::free, list_hosts, #remove_host, #remove_hosts, #set_access_control.

Adds the specified window to the client's save-set.

###Arguments

• w Specifies the window that you want to add to the client's save-set.

###Description The #add_to_save_set function adds the specified window to the client's save-set. The specified window must have been created by some other client, or a BadMatch error results. #add_to_save_set can generate BadMatch and BadWindow errors.

###Diagnostics

• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.
• BadWindow A value for a Window argument does not name a defined Window.

###See also #change_save_set, #remove_from_save_set, #reparent_window.

Allocates a read-only colormap entry.

###Arguments

• colormap Specifies the colormap.
• screen_in Specifies and returns the values actually used in the colormap.

###Description The #alloc_color function allocates a read-only colormap entry corresponding to the closest RGB value supported by the hardware. #alloc_color returns the pixel value of the color closest to the specified RGB elements supported by the hardware and returns the RGB value actually used. The corresponding colormap cell is read-only. Multiple clients that request the same effective RGB value can be assigned the same read-only entry, thus allowing entries to be shared. When the last client deallocates a shared cell, it is deallocated. #alloc_color does not use or affect the flags in the Color structure.

#alloc_color can generate a BadColor error.

###Diagnostics

• BadColor A value for a Colormap argument does not name a defined Colormap.

###See also #alloc_color_cells, #alloc_color_planes, #alloc_named_color, #create_colormap, #free_colors, #query_color, #store_colors.

Allocates read/write color cells.

###Arguments

• colormap Specifies the colormap.
• contig Specifies a Boolean value that indicates whether the planes must be contiguous.
• nplanes Specifies the number of plane masks that are to be returned in the plane masks array.
• npixels Specifies the number of pixel values that are to be returned in the pixels_return array.

###Description The #alloc_color_cells function allocates read/write color cells. The number of colors must be positive and the number of planes nonnegative, or a BadValue error results. No mask will have any bits set to 1 in common with any other mask or with any of the pixels. All of these are allocated writable by the request. For GrayScale or PseudoColor, each mask has exactly one bit set to 1. For DirectColor, each has exactly three bits set to 1. If contig is true and if all masks are ORed together, a single contiguous set of bits set to 1 will be formed for GrayScale or PseudoColor and three contiguous sets of bits set to 1 (one within each pixel subfield) for DirectColor. The RGB values of the allocated entries are undefined.

#alloc_color_cells can generate BadColor and BadValue errors.

###Diagnostics

• BadColor A value for a Colormap argument does not name a defined Colormap.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

###See also #alloc_color, #alloc_color_planes, #alloc_named_color, #create_colormap, #free_colors, #query_color, #store_colors.

Allocates color planes.

###Arguments

• colormap Specifies the colormap.
• contig Specifies a Boolean value that indicates whether the planes must be contiguous.
• ncolors Specifies the number of pixel values that are to be returned in the pixels_return array.
• nreds, ngreens, nblues Specify the number of red, green, and blue planes. The value you pass must be nonnegative.

###Description The specified ncolors must be positive; and nreds, ngreens, and nblues must be nonnegative, or a BadValue error results. If ncolors colors, nreds reds, ngreens greens, and nblues blues are requested, ncolors pixels are returned; and the masks have nreds, ngreens, and nblues bits set to 1, respectively. If contig is true, each mask will have a contiguous set of bits set to 1. No mask will have any bits set to 1 in common with any other mask or with any of the pixels. For DirectColor, each mask will lie within the corresponding pixel subfield. By ORing together subsets of masks with each pixel value, ncolors * 2^(nreds+ngreens+nblues) distinct pixel values can be produced. All of these are allocated by the request. However, in the colormap, there are only ncolors * 2^nreds independent red entries, ncolors * 2^ngreens independent green entries, and ncolors * 2^nblues independent blue entries. This is true even for PseudoColor. When the colormap entry of a pixel value is changed (using #store_colors, #store_color, or #store_named_color), the pixel is decomposed according to the masks, and the corresponding independent entries are updated. #alloc_color_planes returns nonzero if it succeeded or zero if it failed.

#alloc_color_planes can generate BadColor and BadValue errors.

###Diagnostics

• BadColor A value for a Colormap argument does not name a defined Colormap.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

###See also #alloc_color, #alloc_color_cells, #alloc_named_color, #create_colormap, #free_colors, #query_color, #store_colors.

Looks up the named color with respect to the screen that is associated with the specified colormap.

###Arguments

• colormap Specifies the colormap.
• color_name Specifies the color name string (for example, red) whose color definition structure you want returned.

###Return

• screen_def The closest RGB values provided by the hardware.
• exact_def The exact RGB values.
• status Nonzero if a cell is allocated; otherwise, it is zero.

###Description The #alloc_named_color function looks up the named color with respect to the screen that is associated with the specified colormap. It returns both the exact database definition and the closest color supported by the screen. The allocated color cell is read-only. The pixel value is returned in screen_def. If the color name is not in the Host Portable Character Encoding, the result is implementation dependent. Use of uppercase or lowercase does not matter. If screen_def and exact_def point to the same structure, the pixel field will be set correctly but the color values are undefined. #alloc_named_color returns nonzero status if a cell is allocated; otherwise, it returns zero.

#alloc_named_color can generate a BadColor error.

###Diagnostics

• BadColor A value for a Colormap argument does not name a defined Colormap.

###See also #alloc_color, #alloc_color_cells, #alloc_color_planes, #create_colormap, #free_colors, #query_color, #store_colors.

Releases some queued events if the client has caused a device to freeze.

###Arguments

• event_mode Specifies the event mode. You can pass AsyncPointer, SyncPointer, AsyncKeyboard, SyncKeyboard, ReplayPointer, ReplayKeyboard, AsyncBoth, or SyncBoth.
• time Specifies the time. You can pass either a timestamp or CurrentTime.

###Description The #allow_events function releases some queued events if the client has caused a device to freeze. It has no effect if the specified time is earlier than the last-grab time of the most recent active grab for the client or if the specified time is later than the current X server time. Depending on the event_mode argument, the following occurs:

• AsyncPointer 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, AsyncPointer thaws for both. AsyncPointer has no effect if the pointer is not frozen by the client, but the pointer need not be grabbed by the client.
• SyncPointer If the pointer is frozen and actively grabbed by the client, pointer event processing continues as usual until the next ButtonPress or 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. SyncPointer has no effect if the pointer is not frozen by the client or if the pointer is not grabbed by the client.
• ReplayPointer 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 #grab_button or from a previous #allow_events with mode SyncPointer but not from a #grab_pointer), 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.
• AsyncKeyboard 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, AsyncKeyboard thaws for both. AsyncKeyboard has no effect if the keyboard is not frozen by the client, but the keyboard need not be grabbed by the client.
• SyncKeyboard If the keyboard is frozen and actively grabbed by the client, keyboard event processing continues as usual until the next KeyPress or 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. SyncKeyboard has no effect if the keyboard is not frozen by the client or if the keyboard is not grabbed by the client.
• ReplayKeyboard 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 #grab_key or from a previous #allow_events with mode SyncKeyboard but not from a #grab_keyboard), 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.
• SyncBoth If both pointer and keyboard are frozen by the client, event processing for both devices continues as usual until the next ButtonPress, ButtonRelease, KeyPress, or 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). 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, SyncBoth thaws for both (but a subsequent freeze for SyncBoth will only freeze each device once).
• AsyncBoth 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, AsyncBoth thaws for both. AsyncBoth has no effect unless both pointer and keyboard are frozen by the client.
• AsyncPointer, SyncPointer, and ReplayPointer have no effect on the processing of keyboard events. AsyncKeyboard, SyncKeyboard, and ReplayKeyboard have no effect on the processing of pointer events. It is possible for both a pointer grab and a keyboard grab (by the same or different clients) to be active simultaneously. If a device is frozen on behalf of either grab, no event processing is performed for the device. It is possible for a single device to be frozen because of both grabs. In this case, the freeze must be released on behalf of both grabs before events can again be processed. If a device is frozen twice by a single client, then a single AllowEvents releases both.

#allow_events can generate a BadValue error.

###Diagnostics

• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

Returns the name associated with the specified atom.

###Arguments

• atom Specifies the atom for the property name you want returned.

###Description If the data returned by the server is in the Latin Portable Character Encoding, then the returned string is in the Host Portable Character Encoding. Otherwise, the result is implementation dependent.

###Diagnostics

• BadAtom A value for an Atom argument does not name a defined Atom.

###See also #atom_names, #window_property, #intern_atom, intern_atoms.

Returns the name associated with the specified atoms.

Turns off auto-repeat for the keyboard on the specified display.

Turns on auto-repeat for the keyboard on the specified display

Rings the bell on the keyboard.

###Arguments

• percent Specifies the volume for the bell, which can range from -100 to 100 inclusive.

###Description The #bell function rings the bell on the keyboard, if possible. The specified volume is relative to the base volume for the keyboard. If the value for the percent argument is not in the range -100 to 100 inclusive, a BadValue error results. The volume at which the bell rings when the percent argument is nonnegative is:

base - [(base * percent) / 100] + percent

The volume at which the bell rings when the percent argument is negative is:

base + [(base * percent) / 100]

To change the base volume of the bell, use #change_keyboard_control.

#bell can generate a BadValue error.

###Diagnostics

• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

Within each bitmap unit, the left-most bit in the bitmap as displayed on the screen is either the least-significant or most-significant bit in the unit. This function can return LSBFirst or MSBFirst.

Each scanline must be padded to a multiple of bits returned by this function.

Returns the size of a bitmap's scanline unit in bits. The scanline is calculated in multiples of this value.

Returns the black pixel value for the specified screen.

###Arguments

• screen_number Specifies the appropriate screen number on the host server.

Returns the number of entries in the default colormap.

###Arguments

• screen_number Specifies the appropriate screen number on the host server.

Changes the specified dynamic parameters if the pointer is actively grabbed by the client.

###Arguments

• event_mask Specifies which pointer events are reported to the client. The mask is the bitwise inclusive OR of the valid pointer event mask bits.
• cursor Specifies the cursor that is to be displayed or None.
• time Specifies the time. You can pass either a timestamp or CurrentTime.

###Description The #change_active_pointer_grab 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 #grab_button. The interpretation of event_mask and cursor is the same as described in #grab_pointer. #change_active_pointer_grab can generate BadCursor and BadValue errors.

###Diagnostics

• BadCursor A value for a Cursor argument does not name a defined Cursor.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

###See also #allow_events, #grab_button, #grab_key, #grab_keyboard, #grab_pointer, #ungrab_pointer.

Changes the components specified by valuemask for the specified GC.

###Arguments

• gc Specifies the GC.
• valuemask Specifies which components in the GC are to be changed using information in the specified values structure. This argument is the bitwise inclusive OR of zero or more of the valid GC component mask bits.
• values Specifies any values as specified by the valuemask.

###Description The #change_gc function changes the components specified by valuemask for the specified GC. The values argument contains the values to be set. The values and restrictions are the same as for #create_gc. Changing the clip-mask overrides any previous #set_clip_rectangles request on the context. Changing the dash-offset or dash-list overrides any previous #set_dashes request on the context. The order in which components are verified and altered is server-dependent. If an error is generated, a subset of the components may have been altered. #change_gc can generate BadAlloc, BadFont, BadGC, BadMatch, BadPixmap, and BadValue errors.

###Diagnostics

• BadAlloc The server failed to allocate the requested source or server memory.
• BadFont A value for a font argument does not name a defined font (or, in some cases, GContext).
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.
• BadPixmap A value for a Pixmap argument does not name a defined Pixmap.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

###See also X11::all_planes #copy_area, #copy_gc, #create_gc, X11::create_region, #draw_arc, #draw_line, #draw_rectangle, #draw_text, #fill_rectangle, #free_gc, g_context_from_gc, get_gc_values, #query_best_size, #set_arc_mode, #set_clip_origin.

Controls the keyboard characteristics.

###Arguments

• value_mask Specifies which controls to change. This mask is the bitwise inclusive OR of the valid control mask bits.
• values Specifies one value for each bit set to 1 in the mask.

###Description #change_keyboard_control function controls the keyboard characteristics defined by the KeyboardControl object. The value_mask argument specifies which values are to be changed.

#change_keyboard_control can generate BadMatch and BadValue errors.

###Diagnostics

• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

###See also #auto_repeat_off, #auto_repeat_on, #bell, #change_keyboard_mapping, #keyboard_control, #query_keymap, #set_pointer_mapping.

Defines the symbols for the specified number of KeyCodes starting with first_keycode.

###Arguments

• first_keycode Specifies the first KeyCode that is to be changed.
• keysyms_per_keycode Specifies the number of KeySyms per KeyCode.
• keysyms Specifies an array of KeySyms.

###Description The #change_keyboard_mapping 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:

kysyms.size * keysyms_per_keycode

The specified first_keycode must be greater than or equal to min_keycode returned by display_keycodes, or a BadValue error results. In addition, the following expression must be less than or equal to max_keycode as returned by display_keycodes, or a BadValue error results:

first_keycode + keysyms.size - 1

KeySym number N, counting from zero, for KeyCode K has the following index in keysyms, counting from zero:

(K - first_keycode) * keysyms_per_keycode + N

The specified keysyms_per_keycode can be chosen arbitrarily by the client to be large enough to hold all desired symbols. A special KeySym value of NoSymbol should be used to fill in unused elements for individual KeyCodes. It is legal for NoSymbol to appear in nontrailing positions of the effective list for a KeyCode. #change_keyboard_mapping generates a MappingNotify event.

There is no requirement that the X server interpret this mapping. It is merely stored for reading and writing by clients.

#change_keyboard_mapping can generate BadAlloc and BadValue errors.

###Diagnostics

• BadAlloc The server failed to allocate the requested source or server memory.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

###See also ModifierKeymap::delete_entry, #keycodes, X11::free, ModifierKeymap::finalize, #keyboard_mapping, #modifier_mapping, ModifierKeymap::insert_entry, ModifierKeymap::new, #set_modifier_mapping, #set_pointer_mapping.

Defines how the pointing device moves.

###Arguments

• do_accel Specifies a Boolean value that controls whether the values for the accel_numerator or accel_denominator are used.
• do_threshold Specifies a Boolean value that controls whether the value for the threshold is used.
• accel_numerator Specifies the numerator for the acceleration multiplier.
• accel_denominator Specifies the denominator for the acceleration multiplier.
• threshold Specifies the acceleration threshold.

###Description The #change_pointer_control function defines how the pointing device moves. The acceleration, expressed as a fraction, is a multiplier for movement. For example, specifying 3/1 means the pointer moves three times as fast as normal. The fraction may be rounded arbitrarily by the X server. Acceleration only takes effect if the pointer moves more than threshold pixels at once and only applies to the amount beyond the value in the threshold argument. Setting a value to -1 restores the default. The values of the do_accel and do_threshold arguments must be True for the pointer values to be set, or the parameters are unchanged. Negative values (other than -1) generate a BadValue error, as does a zero value for the accel_denominator argument.

#change_pointer_control can generate a BadValue error.

###Diagnostics

• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

###See also #pointer_control.

Alters the property for the specified window.

###Arguments

• w Specifies the window whose property you want to change.
• property Specifies the property name.
• type Specifies the type of the property. The X server does not interpret the type but simply passes it back to an application that later calls #window_property.
• mode Specifies the mode of the operation. You can pass PropModeReplace, PropModePrepend, or PropModeAppend.
• data Specifies the property data.

###Description The #change_property function alters the property for the specified window and causes the X server to generate a PropertyNotify event on that window. #change_property performs the following:

• If mode is PropModeReplace, #change_property discards the previous property value and stores the new data.
• If mode is PropModePrepend or PropModeAppend, #change_property inserts the specified data before the beginning of the existing data or onto the end of the existing data, respectively. The type and format must match the existing property value, or a BadMatch error results.

The lifetime of a property is not tied to the storing client. Properties remain until explicitly deleted, until the window is destroyed, or until the server resets. For a discussion of what happens when the connection to the X server is closed, see section "X Server Connection Close Operations". The maximum size of a property is server dependent and can vary dynamically depending on the amount of memory the server has available. (If there is insufficient space, a BadAlloc error results.)

#change_property can generate BadAlloc, BadAtom, BadMatch, BadValue, and BadWindow errors.

###Diagnostics

• BadAlloc The server failed to allocate the requested source or server memory.
• BadAtom A value for an Atom argument does not name a defined Atom.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.
• BadPixmap A value for a Pixmap argument does not name a defined Pixmap.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.
• BadWindow A value for a Window argument does not name a defined Window.

###See also #delete_property, #window_property, #properties, #rotate_window_properties.

Inserts or deletes the specified window from the client's save-set.

###Arguments

• w Specifies the window that you want to add to or delete from the client's save-set.
• change_mode Specifies the mode. You can pass SetModeInsert or SetModeDelete.

###Description Depending on the specified mode, #change_save_set 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 BadMatch error results.

#change_save_set can generate BadMatch, BadValue, and BadWindow errors.

###Diagnostics

• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.
• BadWindow A value for a Window argument does not name a defined Window.

###See also #add_to_save_set, #remove_from_save_set, #reparent_window.

Changes the specified window attributes

###Arguments

• w Specifies the window.
• valuemask Specifies which window attributes are defined in the attributes argument. This mask is the bitwise inclusive OR of the valid attribute mask bits. If valuemask is zero, the attributes are ignored and are not referenced. The values and restrictions are the same as for #create_window.
• attributes Specifies the structure from which the values (as specified by the value mask) are to be taken. The value mask should have the appropriate bits set to indicate which attributes have been set in the structure (see "Window Attributes").

###Description Depending on the valuemask, the #change_window_attributes function uses the window attributes in the set_window_attributes structure to change the specified window attributes. Changing the background does not cause the window contents to be changed. To repaint the window and its background, use #clear_window. Setting the border or changing the background such that the border tile origin changes causes the border to be repainted. Changing the background of a root window to None or ParentRelative restores the default background pixmap. Changing the border of a root window to CopyFromParent restores the default border pixmap. Changing the win-gravity does not affect the current position of the window. Changing the backing-store of an obscured window to WhenMapped or Always, or changing the backing-planes, backing-pixel, or save-under of a mapped window may have no immediate effect. Changing the colormap of a window (that is, defining a new map, not changing the contents of the existing map) generates a ColormapNotify event. Changing the colormap of a visible window may have no immediate effect on the screen because the map may not be installed (see #install_colormap). Changing the cursor of a root window to None restores the default cursor. Whenever possible, you are encouraged to share colormaps.

Multiple clients can select input on the same window. Their event masks are maintained separately. When an event is generated, it is reported to all interested clients. However, only one client at a time can select for SubstructureRedirectMask, ResizeRedirectMask and ButtonPressMask. If a client attempts to select any of these event masks and some other client has already selected one, a BadAccess error results. There is only one do-not-propagate-mask for a window, not one per client.

#change_window_attributes can generate BadAccess, BadColor, BadCursor, BadMatch, BadPixmap, BadValue, and BadWindow errors.

###Diagnostics

• BadAccess A client attempted to free a color map entry that it did not already allocate.
• BadAccess A client attempted to store into a read-only color map entry.
• BadColor A value for a Colormap argument does not name a defined Colormap.
• BadCursor A value for a Cursor argument does not name a defined Cursor.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.
• BadPixmap A value for a Pixmap argument does not name a defined Pixmap.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.
• BadWindow A value for a Window argument does not name a defined Window.

###See also #configure_window, #create_window, #destroy_window, #install_colormap, #map_window, #raise_window, #set_window_background, #set_window_background_pixmap, #set_window_border, #set_window_border_pixmap, #set_window_colormap, #unmap_window.

When the predicate procedure finds a match, returns the matched event.

###Arguments

• predicate Specifies the procedure that is to be called to determine if the next event in the queue matches what you want.
• arg Specifies the user-supplied argument that will be passed to the predicate procedure.

###Description When the predicate procedure finds a match, #check_if_event returns the matched event. (This event is removed from the queue.) If the predicate procedure finds no match, #check_if_event returns nil, and the output buffer will have been flushed. All earlier events stored in the queue are not discarded.

###See also #if_event, #next_event, #peek_if_event, #put_back_event, #send_event.

Removes and returns the first event that matches the specified mask.

###Arguments

• event_mask Specifies the event mask.

###Description The #check_mask_event function searches the event queue and then any events available on the server connection for the first event that matches the specified mask. If it finds a match, #check_mask_event removes that event, and returns it. The other events stored in the queue are not discarded. If the event you requested is not available, #check_mask_event returns nil, and the output buffer will have been flushed.

###See also #check_typed_event, #check_typed_window_event, #check_window_event, #if_event, #mask_event, #next_event, #peek_event, #put_back_event, #send_event, #window_event.

Removes and returns the first event that matches the specified type.

###Arguments

• event_type Specifies the event type to be compared.

###Description The #check_typed_event function searches the event queue and then any events available on the server connection for the first event that matches the specified type. If it finds a match, #check_typed_event removes that event, and returns it. The other events in the queue are not discarded. If the event is not available, #check_typed_event returns nil, and the output buffer will have been flushed.

###See also #check_mask_event, #check_typed_window_event, #check_window_event, #if_event, #mask_event, #next_event, #peek_event, #put_back_event, #send_event, #window_event.

Removes and returns the first event that matches the specified window and type.

###Arguments

• w Specifies the window.
• event_type Specifies the event type to be compared.

###Description The #check_typed_window_event function searches the event queue and then any events available on the server connection for the first event that matches the specified type and window. If it finds a match, #check_typed_window_event removes the event from the queue, and returns it. The other events in the queue are not discarded. If the event is not available, #check_typed_window_event returns nil, and the output buffer will have been flushed.

###See also #check_mask_event, #check_window_event, #if_event, #mask_event, #next_event, #peek_event, #put_back_event, #send_event, #window_event.

Removes and returns the first event that matches the specified window and event mask.

###Arguments

• w Specifies the window whose events you are interested in.
• event_mask Specifies the event mask.

###Description The #check_window_event function searches the event queue and then the events available on the server connection for the first event that matches the specified window and event mask. If it finds a match, #check_window_event removes that event, and returns it. The other events stored in the queue are not discarded. If the event you requested is not available, #check_window_event returns nil, and the output buffer will have been flushed.

###See also #check_mask_event, #check_typed_event, #check_typed_window_event, #if_event, #mask_event, #next_event, #peek_event, #put_back_event, #send_event, #window_event.

Circulates children of the specified window in the specified direction.

###Arguments

• w Specifies the window.
• direction Specifies the direction (up or down) that you want to circulate the window. You can pass RaiseLowest or LowerHighest.

###Description The #circulate_subwindows function circulates children of the specified window in the specified direction. If you specify RaiseLowest, #circulate_subwindows raises the lowest mapped child (if any) that is occluded by another child to the top of the stack. If you specify LowerHighest, #circulate_subwindows lowers the highest mapped child (if any) that occludes another child to the bottom of the stack. Exposure processing is then performed on formerly obscured windows. If some other client has selected SubstructureRedirectMask on the window, the X server generates a CirculateRequest event, and no further processing is performed. If a child is actually restacked, the X server generates a CirculateNotify event.

#circulate_subwindows can generate BadValue and BadWindow errors.

###Diagnostics

• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.
• BadWindow A value for a Window argument does not name a defined Window.

###See also #change_window_attributes, #circulate_subwindows_down, #circulate_subwindows_up, #configure_window, #create_window, #destroy_window, #lower_window, #map_window, #raise_window, #restack_windows.

Lowers the highest mapped child of the specified window that partially or completely occludes another child.

###Arguments

• w Specifies the window.

###Description The #circulate_subwindows_down function lowers the highest mapped child of the specified window that partially or completely occludes another child. Completely unobscured children are not affected. This is a convenience function equivalent to #circulate_subwindows with LowerHighest specified.

#circulate_subwindows_down can generate a BadWindow error.

###Diagnostics

• BadWindow A value for a Window argument does not name a defined Window.

###See also #change_window_attributes, #circulate_subwindows, #circulate_subwindows_up, #configure_window, #create_window, #destroy_window, #lower_window, #map_window, #raise_window, #restack_windows.

Raises the lowest mapped child of the specified window that is partially or completely occluded by another child.

###Arguments

• w Specifies the window.

###Description The #circulate_subwindows_up function raises the lowest mapped child of the specified window that is partially or completely occluded by another child. Completely unobscured children are not affected. This is a convenience function equivalent to #circulate_subwindows with RaiseLowest specified.

#circulate_subwindows_up can generate a BadWindow error.

###Diagnostics

• BadWindow A value for a Window argument does not name a defined Window.

###See also #change_window_attributes, #circulate_subwindows, #circulate_subwindows_down, #configure_window, #create_window, #destroy_window, #lower_window, #map_window, #raise_window, #restack_windows.

Paints a rectangular area in the specified window.

###Arguments

• w Specifies the window. and specify the upper-left corner of the rectangle
• x, y Specify the x and y coordinates, which are relative to the origin of the window.
• width, height Specify the width and height, which are the dimensions of the rectangle.
• exposures Specifies a Boolean value that indicates if Expose events are to be generated.

###Description The #clear_area function paints a rectangular area in the specified window according to the specified dimensions with the window's background pixel or pixmap. The subwindow-mode effectively is ClipByChildren. If width is zero, it is replaced with the current width of the window minus x. If height is zero, it is replaced with the current height of the window minus y. If the window has a defined background tile, the rectangle clipped by any children is filled with this tile. If the window has background None, the contents of the window are not changed. In either case, if exposures is True, one or more Expose events are generated for regions of the rectangle that are either visible or are being retained in a backing store. If you specify a window whose class is InputOnly, a BadMatch error results.

#clear_area can generate BadMatch, BadValue, and BadWindow errors.

###Diagnostics

• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.
• BadWindow A value for a Window argument does not name a defined Window.

###See also #clear_area, #copy_area.

Clears the entire area in the specified window.

###Arguments

• w Specifies the window.

###Description The #clear_window function clears the entire area in the specified window and is equivalent to:

clear_area(w, 0, 0, 0, 0, false)

If the window has a defined background tile, the rectangle is tiled with a plane-mask of all ones and copy function. If the window has background None, the contents of the window are not changed. If you specify a window whose class is InputOnly, a BadMatch error results.

#clear_window can generate BadMatch and BadWindow errors.

###Diagnostics

• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.
• BadWindow A value for a Window argument does not name a defined Window.

###See also #clear_area, #copy_area.

Closes the connection to the X server.

###Description #close function closes the connection to the X server for the display specified in the Display structure and destroys all windows, resource IDs (X11::C::Window, X11::C::Font, X11::C::Pixmap, X11::C::Colormap, X11::C::Cursor, and GContext), or other resources that the client has created on this display, unless the close-down mode of the resource has been changed (see #set_close_down_mode). Therefore, these windows, resource IDs, and other resources should never be referenced again or an error will be generated. Before exiting, you should call #close explicitly so that any pending errors are reported as #close performs a final #sync operation.

###Diagnostics #close can generate a BadGC error.

###See also #flush, #set_close_down_mode.

Reads the WM_COMMAND property from the specified window.

###Arguments

• w Specifies the window.

###Description The #command function reads the WM_COMMAND property from the specified window and returns a string list. If the WM_COMMAND property exists, it is of type STRING and format 8. If sufficient memory can be allocated to contain the string list, get_command returns an array of strings. Otherwise, it returns an empty array. If the data returned by the server is in the Latin Portable Character Encoding, then the returned strings are in the Host Portable Character Encoding. Otherwise, the result is implementation dependent.

See also X11::alloc_class_hint, X11::alloc_icon_size, X11::alloc_size_hints, X11::alloc_wm_hints, #set_command, set_text_property, #set_transient_for_hint, set_wm_client_machine, #set_wm_colormap_windows, set_wm_icon_name, set_wm_name, set_wm_properties, #set_wm_protocols, X11::string_list_to_text_property.

Reconfigures a window's size, position, border, and stacking order.

###Arguments

• w Specifies the window to be reconfigured.
• value_mask Specifies which values are to be set using information in the values structure. This mask is the bitwise inclusive OR of the valid configure window values bits.
• values Specifies the WindowChanges structure.

###Description The #configure_window function uses the values specified in the WindowChanges structure to reconfigure a window's size, position, border, and stacking order. Values not specified are taken from the existing geometry of the window.

If a sibling is specified without a stack_mode or if the window is not actually a sibling, a BadMatch error results. Note that the computations for BottomIf, TopIf, and Opposite are performed with respect to the window's final geometry (as controlled by the other arguments passed to #configure_window), not its initial geometry. Any backing store contents of the window, its inferiors, and other newly visible windows are either discarded or changed to reflect the current screen contents (depending on the implementation).

#configure_window can generate BadMatch, BadValue, and BadWindow errors.

###Diagnostics

• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.
• BadWindow A value for a Window argument does not name a defined Window.

###See also #change_window_attributes, #create_window, #destroy_window, #map_window, #move_window, #move_resize_window, #raise_window, #resize_window, #set_window_border_width, #unmap_window.

Returns a connection number for the specified display. On a POSIX-conformant system, this is the file descriptor of the connection.

Requests that the specified selection be converted to the specified target type.

###Arguments

• selection Specifies the selection atom.
• target Specifies the target atom.
• property Specifies the property name. You also can pass None.
• requestor Specifies the requestor.
• time Specifies the time. You can pass either a timestamp or CurrentTime.

###Description #convert_selection requests that the specified selection be converted to the specified target type:

• If the specified selection has an owner, the X server sends a SelectionRequest event to that owner.
• If no owner for the specified selection exists, the X server generates a SelectionNotify event to the requestor with property None.

The arguments are passed on unchanged in either of the events. There are two predefined selection atoms: PRIMARY and SECONDARY.

convert_selection can generate BadAtom and BadWindow errors.

###Diagnostics

• BadAtom A value for an Atom argument does not name a defined Atom.
• BadWindow A value for a Window argument does not name a defined Window.

###See also #selection_owner, set_selection_owner`.

Combines the specified rectangle of src with the specified rectangle of dest.

###Arguments

• src, dest Specify the source and destination rectangles to be combined.
• gc Specifies the GC.
• src_x, src_y Specify the x and y coordinates, which are relative to the origin of the source rectangle and specify its upper-left corner.
• width, height Specify the width and height, which are the dimensions of both the source and destination rectangles.
• dest_x, dest_y Specify the x and y coordinates, which are relative to the origin of the destination rectangle and specify its upper-left corner

###Description The #copy_area function combines the specified rectangle of src with the specified rectangle of dest. The drawables must have the same root and depth, or a BadMatch error results.

If regions of the source rectangle are obscured and have not been retained in backing store or if regions outside the boundaries of the source drawable are specified, those regions are not copied. Instead, the following occurs on all corresponding destination regions that are either visible or are retained in backing store. If the destination is a window with a background other than None, corresponding regions of the destination are tiled with that background. Regardless of tiling or whether the destination is a window or a pixmap, if graphics-exposures is true, then GraphicsExpose events for all corresponding destination regions are generated. If graphics-exposures is true but no GraphicsExpose events are generated, a NoExpose event is generated. Note that by default graphics-exposures is true in new GCs.

This function uses these GC components: function, plane-mask, subwindow-mode, graphics-exposure, clip-x-origin, clip-y-origin, and clip-mask.

#copy_area can generate BadDrawable, BadGC, and BadMatch errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also #clear_area, #copy_plane.

Creates a colormap

###Arguments

• colormap Specifies the colormap.

###Description The #copy_colormap_and_free function creates a colormap of the same visual type and for the same screen as the specified colormap and returns the new colormap ID. It also moves all of the client's existing allocation from the specified colormap to the new colormap with their color values intact and their read-only or writable characteristics intact and frees those entries in the specified colormap. Color values in other entries in the new colormap are undefined. If the specified colormap was created by the client with alloc set to AllocAll, the new colormap is also created with AllocAll, all color values for all entries are copied from the specified colormap, and then all entries in the specified colormap are freed. If the specified colormap was not created by the client with AllocAll, the allocations to be moved are all those pixels and planes that have been allocated by the client using #alloc_color, #alloc_named_color, #alloc_color_cells, or #alloc_color_planes and that have not been freed since they were allocated.

#copy_colormap_and_free can generate BadAlloc and BadColor errors.

###Diagnostics

• BadAlloc The server failed to allocate the requested source or server memory.
• BadColor A value for a Colormap argument does not name a defined Colormap.

###See Also #alloc_color, #change_window_attributes, #create_window, #query_color, #store_colors.

Copies the specified components from the source GC to the destination GC

###Arguments

• src Specifies the components of the source GC.
• valuemask Specifies which components in the GC are to be copied to the destination GC. This argument is the bitwise inclusive OR of zero or more of the valid GC component mask bits.
• dest Specifies the destination GC.

###Description The #copy_gc function copies the specified components from the source GC to the destination GC. The source and destination GCs must have the same root and depth, or a BadMatch error results. The valuemask specifies which component to copy, as for #create_gc.

#copy_gc can generate BadAlloc, BadGC, and BadMatch errors.

###Diagnostics

• BadAlloc The server failed to allocate the requested source or server memory.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also X11::all_planes, #change_gc, #copy_area, #create_gc, X11::create_region, #draw_arc, #draw_line, #draw_rectangle, #draw_text, #fill_rectangle, #free_gc, X11::g_context_from_gc, #gc_values, #query_best_size, #set_arc_mode, #set_clip_origin.

Uses a single bit plane of the specified source rectangle combined with the specified GC to modify the specified rectangle of dest.

###Arguments

• src, dest Specify the source and destination rectangles to be combined.
• gc Specifies the GC.
• src_x, src_y Specify the x and y coordinates, which are relative to the origin of the source rectangle and specify its upper-left corner.
• width, height Specify the width and height, which are the dimensions of both the source and destination rectangles.
• dest_x, dest_y Specify the x and y coordinates, which are relative to the origin of the destination rectangle and specify its upper-left corner.
• plane Specifies the bit plane. You must set exactly one bit to 1.

###Description The #copy_plane function uses a single bit plane of the specified source rectangle combined with the specified GC to modify the specified rectangle of dest. The drawables must have the same root but need not have the same depth. If the drawables do not have the same root, a BadMatch error results. If plane does not have exactly one bit set to 1 and the value of plane is not less than 2ⁿ, where n is the depth of src, a BadValue error results.

Effectively, #copy_plane forms a pixmap of the same depth as the rectangle of dest and with a size specified by the source region. It uses the foreground/background pixels in the GC (foreground everywhere the bit plane in src contains a bit set to 1, background everywhere the bit plane in src contains a bit set to 0) and the equivalent of a CopyArea protocol request is performed with all the same exposure semantics. This can also be thought of as using the specified region of the source bit plane as a stipple with a fill-style of FillOpaqueStippled for filling a rectangular area of the destination.

This function uses these GC components: function, plane-mask, foreground, background, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin, and clip-mask.

#copy_plane can generate BadDrawable, BadGC, BadMatch, and BadValue errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

###See also #copy_area, #clear_area.

Creates a pixmap from data.

###Arguments

• d Specifies the drawable that indicates the screen.
• data Specifies the location of the bitmap data.
• width, height Specify the width and height.

###Description The #create_bitmap_from_data function allows you to include in your C program (using #include) a bitmap file that was written out by #write_bitmap_file (X version 11 format only) without reading in the bitmap file. The following example creates a gray bitmap:

#include "gray.bitmap"

Pixmap bitmap;
bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height);

If insufficient working storage was allocated, #create_bitmap_from_data returns None. It is your responsibility to free the bitmap using #free_pixmap when finished.

#create_bitmap_from_data can generate a BadAlloc and BadGC errors.

###Diagnostics

• BadAlloc The server failed to allocate the requested source or server memory.
• BadGC A value for a X11::C::GContext argument does not name a defined X11::C::GContext.

###See also #create_pixmap, #create_pixmap_from_bitmap_data, #put_image, #read_bitmap_file, #write_bitmap_file.

Creates a colormap

###Arguments

• w Specifies the window on whose screen you want to create a colormap.
• visual Specifies a visual type supported on the screen. If the visual type is not one supported by the screen, a BadMatch error results.
• alloc Specifies the colormap entries to be allocated. You can pass AllocNone or AllocAll.

###Description The #create_colormap function creates a colormap of the specified visual type for the screen on which the specified window resides and returns the colormap ID# associated with it. Note that the specified window is only used to determine the screen.

The initial values of the colormap entries are undefined for the visual classes GrayScale, PseudoColor, and DirectColor. For StaticGray, StaticColor, and TrueColor, the entries have defined values, but those values are specific to the visual and are not defined by X. For StaticGray, StaticColor, and TrueColor, alloc must be AllocNone, or a BadMatch error results. For the other visual classes, if alloc is AllocNone, the colormap initially has no allocated entries, and clients can allocate them.

If alloc is **AllocAll the entire colormap is allocated writable. The initial values of all allocated entries are undefined. For GrayScale and PseudoColor, the effect is as if an #alloc_color_cells call returned all pixel values from zero to N - 1, where N is the colormap entries value in the specified visual. For DirectColor, the effect is as if an #alloc_color_planes call returned a pixel value of zero and red_mask, green_mask, and blue_mask values containing the same bits as the corresponding masks in the specified visual. However, in all cases, none of these entries can be freed by using #free_colors.

#create_colormap can generate BadAlloc, BadMatch, BadValue, and BadWindow errors.

###Diagnostics

• BadAlloc The server failed to allocate the requested source or server memory.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.
• BadPixmap A value for a Pixmap argument does not name a defined Pixmap.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.
• BadWindow A value for a Window argument does not name a defined Window.

###See also #alloc_color, #change_window_attributes, #copy_colormap_and_free, #create_window, #free_colormap, #query_color, #store_colors.

Creates a cursor.

###Arguments

• shape Specifies the shape of the cursor.

###Description X provides a set of standard cursor shapes in a special font named cursor. Applications are encouraged to use this interface for their cursors because the font can be customized for the individual display type. The shape argument specifies which glyph of the standard fonts to use.

The hotspot comes from the information stored in the cursor font. The initial colors of a cursor are a black foreground and a white background (see #recolor_cursor).

#create_font_cursor can generate BadAlloc and BadValue errors.

###Diagnostics

• BadAlloc The server failed to allocate the requested source or server memory.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

###See also #create_glyph_cursor, #create_pixmap_cursor, #define_cursor, #load_font, #recolor_cursor.

Creates a graphics context.

###Arguments

• d Specifies the drawable.
• valuemask Specifies which components in the GC are to be set using the information in the specified values structure. This argument is the bitwise inclusive OR of zero or more of the valid GC component mask bits.
• values Specifies any values as specified by the valuemask.

###Description The #create_gc function creates a graphics context and returns a GC. The GC can be used with any destination drawable having the same root and depth as the specified drawable. Use with other drawables results in a BadMatch error.

#create_gc can generate BadAlloc, BadDrawable, BadFont, BadMatch, BadPixmap, and BadValue errors.

###Diagnostics

• BadAlloc The server failed to allocate the requested source or server memory.
• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadFont A value for a font argument does not name a defined font (or, in some cases, GContext).
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.
• BadPixmap A value for a Pixmap argument does not name a defined Pixmap.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

###See also all_planes, #change_gc, #copy_area, #copy_gc, #draw_arc, #draw_line, #draw_rectangle, #draw_text, #fill_rectangle, #free_gc, g_context_from_gc, #gc_values, #query_best_size, #set_arc_mode, #set_clip_origin.

Creates a cursor.

###Arguments

• source_font Specifies the font for the source glyph.
• mask_font Specifies the font for the mask glyph or None.
• source_char Specifies the character glyph for the source.
• mask_char- Specifies the glyph character for the mask.
• foreground_color Specifies the RGB values for the foreground of the source.
• background_color Specifies the RGB values for the background of the source.

###Description The #create_glyph_cursor function is similar to #create_pixmap_cursor except that the source and mask bitmaps are obtained from the specified font glyphs. The source_char must be a defined glyph in source_font, or a BadValue error results. If mask_font is given, mask_char must be a defined glyph in mask_font, or a BadValue error results. The mask_font and character are optional. The origins of the source_char and mask_char (if defined) glyphs are positioned coincidently and define the hotspot. The source_char and mask_char need not have the same bounding box metrics, and there is no restriction on the placement of the hotspot relative to the bounding boxes. If no mask_char is given, all pixels of the source are displayed. You can free the fonts immediately by calling free_font if no further explicit references to them are to be made.

For 2-byte matrix fonts, the 16-bit value should be formed with the byte1 member in the most-significant byte and the byte2 member in the least-significant byte.

#create_glyph_cursor can generate BadAlloc, BadFont, and BadValue errors.

###Diagnostics

• BadAlloc The server failed to allocate the requested source or server memory.
• BadFont A value for a font argument does not name a defined font (or, in some cases, GContext).
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

###See also #create_font_cursor, #create_pixmap_cursor, #define_cursor, #load_font, #recolor_cursor.

Creates an Image.

###Arguments

• visual Specifies the Visual structure.
• depth Specifies the depth of the image.
• format Specifies the format for the image. You can pass XYBitmap, XYPixmap, or ZPixmap.
• offset Specifies the number of pixels to ignore at the beginning of the scanline.
• data Specifies the image data.
• width Specifies the width of the image, in pixels.
• height Specifies the height of the image, in pixels.
• bitmap_pad Specifies the quantum of a scanline (8, 16, or 32). In other words, the start of one scanline is separated in client memory from the start of the next scanline by an integer multiple of this many bits.
• bytes_per_line Specifies the number of bytes in the client image between the start of one scanline and the start of the next.

###Description The #create_image function allocates the memory needed for an Image structure for the specified display but does not allocate space for the image itself. Rather, it initializes the structure byte-order, bit-order, and bitmap-unit values from the display and returns a pointer to the Image structure. The red, green, and blue mask values are defined for Z format images only and are derived from the Visual structure passed in. Other values also are passed in. The offset permits the rapid displaying of the image without requiring each scanline to be shifted into position. If you pass a zero value in bytes_per_line, Xlib assumes that the scanlines are contiguous in memory and calculates the value of bytes_per_line itself.

Note that when the image is created using #create_image, get_image, or Image::sub_image, the destroy procedure that the Image::finalize function calls frees both the image structure and the data pointed to by the image structure.

###See also Image::add_pixel, Image::finalize, Image::pixel, Image::put_pixel, Image::sub_image.

Creates a pixmap.

###Arguments

• d Specifies which screen the pixmap is created on.
• width, height Specify the width and height, which define the dimensions of the pixmap.
• depth Specifies the depth of the pixmap.

###Description The #create_pixmap function creates a pixmap of the width, height, and depth you specified and returns a pixmap ID that identifies it. It is valid to pass an InputOnly window to the drawable argument. The width and height arguments must be nonzero, or a BadValue error results. The depth argument must be one of the depths supported by the screen of the specified drawable, or a BadValue error results.

The server uses the specified drawable to determine on which screen to create the pixmap. The pixmap can be used only on this screen and only with other drawables of the same depth (see #copy_plane for an exception to this rule). The initial contents of the pixmap are undefined.

#create_pixmap can generate BadAlloc, BadDrawable, and BadValue errors.

###Diagnostics

• BadAlloc The server failed to allocate the requested source or server memory.
• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

###See also #copy_area, #free_pixmap.

Creates a cursor.

###Arguments

• source Specifies the shape of the source cursor.
• mask Specifies the cursor's source bits to be displayed or None.
• foreground_color Specifies the RGB values for the foreground of the source.
• background_color Specifies the RGB values for the background of the source.
• x, y Specify the x and y coordinates, which indicate the hotspot relative to the source's origin.

###Description The #create_pixmap_cursor function creates a cursor and returns the cursor ID associated with it. The foreground and background RGB values must be specified using foreground_color and background_color, even if the X server only has a StaticGray or GrayScale screen. The foreground color is used for the pixels set to 1 in the source, and the background color is used for the pixels set to 0. Both source and mask, if specified, must have depth one (or a BadMatch error results) but can have any root. The mask argument defines the shape of the cursor. The pixels set to 1 in the mask define which source pixels are displayed, and the pixels set to 0 define which pixels are ignored. If no mask is given, all pixels of the source are displayed. The mask, if present, must be the same size as the pixmap defined by the source argument, or a BadMatch error results. The hotspot must be a point within the source, or a BadMatch error results.

The components of the cursor can be transformed arbitrarily to meet display limitations. The pixmaps can be freed immediately if no further explicit references to them are to be made. Subsequent drawing in the source or mask pixmap has an undefined effect on the cursor. The X server might or might not make a copy of the pixmap.

#create_pixmap_cursor can generate BadAlloc and BadPixmap errors.

###Diagnostics

• BadAlloc The server failed to allocate the requested source or server memory.
• BadPixmap A value for a Pixmap argument does not name a defined Pixmap.

###See also #create_font_cursor, #create_glyph_cursor, #define_cursor, #load_font, #recolor_cursor.

Creates a pixmap.

###Arguments

• d Specifies the drawable that indicates the screen.
• data Specifies the data in bitmap format.
• width, height Specify the width and height.
• fg, bg Specify the foreground and background pixel values to use.
• depth Specifies the depth of the pixmap.

###Description The #create_pixmap_from_bitmap_data function creates a pixmap of the given depth and then does a bitmap-format #put_image of the data into it. The depth must be supported by the screen of the specified drawable, or a BadMatch error results.

#create_pixmap_from_bitmap_data can generate BadAlloc, BadDrawable, BadGC, and BadValue errors.

###Diagnostics

• BadAlloc The server failed to allocate the requested source or server memory.
• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a X11::C::GContext argument does not name a defined X11::C::GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also #create_bitmap_from_data, #create_pixmap, #put_image, #read_bitmap_file, #write_bitmap_file.

Creates an unmapped subwindow.

###Description The create_simple_window function creates an unmapped **InputOutput** subwindow for a specified parent window, returns the window ID of the created window, and causes the X server to generate a **CreateNotify** event. The created window is placed on top in the stacking order with respect to siblings. Any part of the window that extends outside its parent window is clipped. Theborder_widthfor an **InputOnly** window must be zero, or a **BadMatch** error results.create_simple_window` inherits its depth, class, and visual from its parent. All other window attributes, except background and border, have their default values.

#create_simple_window can generate BadAlloc, BadMatch, BadValue, and BadWindow errors.

For more information see: #create_window.

Creates a window.

###Arguments

• attributes Specifies the structure from which the values (as specified by the value mask) are to be taken. The value mask should have the appropriate bits set to indicate which attributes have been set in the structure.
• background Specifies the background pixel value of the window.
• border Specifies the border pixel value of the window.
• border_width Specifies the width of the created window's border in pixels.
• class Specifies the created window's class. You can pass InputOutput, InputOnly, or CopyFromParent. A class of CopyFromParent means the class is taken from the parent.
• depth Specifies the window's depth. A depth of CopyFromParent means the depth is taken from the parent.
• parent Specifies the parent window.
• valuemask Specifies which window attributes are defined in the attributes argument. This mask is the bitwise inclusive OR of the valid attribute mask bits. If valuemask is zero, the attributes are ignored and are not referenced.
• visualSpecifies the visual type. A visual of CopyFromParent means the visual type is taken from the parent.
• width, height Specify the width and height, which are the created window's inside dimensions and do not include the created window's borders
• x, y Specify the x and y coordinates, which are the top-left outside corner of the window's borders and are relative to the inside of the parent window's borders.

###Description The #create_window function creates an unmapped subwindow for a specified parent window, returns the window ID of the created window, and causes the X server to generate a CreateNotify event. The created window is placed on top in the stacking order with respect to siblings.

The coordinate system has the X axis horizontal and the Y axis vertical with the origin [0, 0] at the upper-left corner. Coordinates are integral, in terms of pixels, and coincide with pixel centers. Each window and pixmap has its own coordinate system. For a window, the origin is inside the border at the inside, upper-left corner.

The border_width for an InputOnly window must be zero, or a BadMatch error results. For class InputOutput, the visual type and depth must be a combination supported for the screen, or a BadMatch error results. The depth need not be the same as the parent, but the parent must not be a window of class InputOnly, or a BadMatch error results. For an InputOnly window, the depth must be zero, and the visual must be one supported by the screen. If either condition is not met, a BadMatch error results. The parent window, however, may have any depth and class. If you specify any invalid window attribute for a window, a BadMatch error results.

The created window is not yet displayed (mapped) on the user's display. To display the window, call #map_window. The new window initially uses the same cursor as its parent. A new cursor can be defined for the new window by calling #define_cursor. The window will not be visible on the screen unless it and all of its ancestors are mapped and it is not obscured by any of its ancestors.

`create_window can generate BadAlloc, BadColor, BadCursor, BadMatch, BadPixmap, BadValue, and BadWindow errors.

###Diagnostics

• BadAlloc The server failed to allocate the requested resource or server memory.
• BadColor A value for a Colormap argument does not name a defined Colormap.
• BadCursor A value for a Cursor argument does not name a defined Cursor.
• BadMatch The values do not exist for an InputOnly window.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.
• BadPixmap A value for a Pixmap argument does not name a defined Pixmap.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.
• BadWindow A value for a Window argument does not name a defined Window.

###See also #change_window_attributes, #configure_window, #define_cursor, #destroy_window, #map_window, #raise_window, #unmap_window.

Returns the value of the resource prog.option

###Arguments

• display Specifies the connection to the X server.
• program Specifies the program name for the Xlib defaults (usually argv[0] of the main program).
• option Specifies the option name.

###Description The #default function returns the value of the resource prog.option, where prog is the program argument with the directory prefix removed and option must be a single component. Note that multilevel resources cannot be used with #default. The class "Program.Name" is always used for the resource lookup. If the specified option name does not exist for this program, #default returns empty String.

If a database has been set with X.rm_set_database, that database is used for the lookup. Otherwise, a database is created and is set in the display (as if by calling X.rm_set_database). The database is created in the current locale. To create a database, #default uses resources from the RESOURCE_MANAGER property on the root window of screen zero. If no such property exists, a resource file in the user's home directory is used. On a POSIX-conformant system, this file is "$HOME/.Xdefaults". After loading these defaults, #default merges additional defaults specified by the XENVIRONMENT environment variable. If XENVIRONMENT is defined, it contains a full path name for the additional resource file. If XENVIRONMENT is not defined, #default looks for "$HOME/.Xdefaults-name", where name specifies the name of the machine on which the application is running.

Returns the default colormap ID for allocation on the specified screen. Most routine allocations of color should be made out of this colormap.

###Arguments

• screen_number Specifies the appropriate screen number on the host server.

Returns the depth (number of planes) of the default root window for the specified screen. Other depths may also be supported on this screen.

###Arguments

• screen_number Specifies the appropriate screen number on the host server.

Returns the default graphics context for the root window of the specified screen.

###Arguments

• screen_number Specifies the appropriate screen number on the host server.

###Description This GC is created for the convenience of simple applications and contains the default GC components with the foreground and background pixel values initialized to the black and white pixels for the screen, respectively.

Returns the root window of the default screen.

Returns default screen.

Returns the default screen number.

Returns the default visual type for the specified screen.

###Arguments

• screen_number Specifies the appropriate screen number on the host server.

Defines a cursor.

###Arguments

• w Specifies the window.
• cursor Specifies the cursor that is to be displayed or None.

###Description If a cursor is set, it will be used when the pointer is in the window. If the cursor is None, it is equivalent to #undefine_cursor.

#define_cursor can generate BadCursor and BadWindow errors.

###Diagnostics

• BadCursor A value for a Cursor argument does not name a defined Cursor.
• BadWindow A value for a Window argument does not name a defined Window.

###See also #create_font_cursor, #recolor_cursor, #undefine_cursor.

Deletes the specified property.

###Arguments

• w Specifies the window whose property you want to delete.
• property Specifies the property name.

###Description The #delete_property function deletes the specified property only if the property was defined on the specified window and causes the X server to generate a PropertyNotify event on the window unless the property does not exist.

#delete_property can generate BadAtom and BadWindow errors.

###Diagnostics

• BadAtom A value for an Atom argument does not name a defined Atom.
• BadWindow A value for a Window argument does not name a defined Window.

###See also #change_property, #window_property, #properties, #rotate_window_properties.

Returns the array of depths that are available on the specified screen.

###Arguments

• screen_number Specifies the appropriate screen number on the host server.

###Description The #depths function returns the array of depths that are available on the specified screen. If the specified screen_number is valid and sufficient memory for the array can be allocated, otherwise it returns an empty array.

Destroys all inferior windows of the specified window, in bottom-to-top stacking order.

###Arguments

• w Specifies the window.

###Description The #destroy_subwindows function destroys all inferior windows of the specified window, in bottom-to-top stacking order. It causes the X server to generate a DestroyNotify event for each window. If any mapped subwindows were actually destroyed, #destroy_subwindows causes the X server to generate Expose events on the specified window. This is much more efficient than deleting many windows one at a time because much of the work need be performed only once for all of the windows, rather than for each window. The subwindows should never be referenced again.

#destroy_subwindows can generate a BadWindow error.

###Diagnostics

• BadWindow A value for a Window argument does not name a defined Window.

###See also #change_window_attributes, #configure_window, #create_window, #destroy_window, #map_window, #raise_window, #unmap_window.

Destroys the specified window as well as all of its subwindows.

###Arguments

• w Specifies the window.

###Description The #destroy_window function destroys the specified window as well as all of its subwindows and causes the X server to generate a DestroyNotify event for each window. The window should never be referenced again. If the window specified by the w argument is mapped, it is unmapped automatically. The ordering of the DestroyNotify events is such that for any given window being destroyed, DestroyNotify is generated on any inferiors of the window before being generated on the window itself. The ordering among siblings and across subhierarchies is not otherwise constrained. If the window you specified is a root window, no windows are destroyed. Destroying a mapped window will generate Expose events on other windows that were obscured by the window being destroyed.

#destroy_window can generate a BadWindow error.

###Diagnostics

• BadWindow A value for a Window argument does not name a defined Window.

###See also #change_window_attributes, #configure_window, #create_window, #destroy_subwindows, #map_window, #raise_window, #unmap_window.

Disables the use of the access control list at each connection setup.

###Description The #disable_access_control function disables the use of the access control list at each connection setup.

#disable_access_control can generate a BadAccess error.

###Diagnostics

• BadAccess A client attempted to free a color map entry that it did not already allocate.
• BadAccess A client attempted to store into a read-only color map entry.

###See also #add_host, #add_hosts, #enable_access_control, X11::free, #hosts, #remove_host, #remove_hosts, #set_access_control.

Returns the string that was passed to .new when the current display was opened. On POSIX-conformant systems, if the passed string was nil, these return the value of the DISPLAY environment variable when the current display was opened. These are useful to applications that invoke the fork system call and want to open a new connection to the same display from the child process as well as for printing error messages.

Pointer to the underlieing XDisplay object.

Draws a single circular or elliptical arc.

###Arguments

• d Specifies the drawable.
• gc Specifies the GC.
• x, y Specify the x and y coordinates, which are relative to the origin of the drawable and specify the upper-left corner of the bounding rectangle.
• width, height Specify the width and height, which are the major and minor axes of the arc.
• angle1 Specifies the start of the arc relative to the three-o'clock position from the center, in units of degrees * 64.
• angle2 Specifies the path and extent of the arc relative to the start of the arc, in units of degrees * 64.

###Description #draw_arc draws a single circular or elliptical arc. The arc is specified by a rectangle and two angles. The center of the circle or ellipse is the center of the rectangle, and the major and minor axes are specified by the width and height. Positive angles indicate counterclockwise motion, and negative angles indicate clockwise motion. If the magnitude of angle2 is greater than 360 degrees, #draw_arc truncates it to 360 degrees.

For an arc specified as [ x, y, width, height, angle1, angle2 ], the origin of the major and minor axes is at [ x + width / 2 , y + height / 2 ], and the infinitely thin path describing the entire circle or ellipse intersects the horizontal axis at [ x, y + height / 2 ] and [ x + width , y + height / 2 ] and intersects the vertical axis at [ x + width / 2, y ] and [ x + width / 2, y + height ]. These coordinates can be fractional and so are not truncated to discrete coordinates. The path should be defined by the ideal mathematical path. For a wide line with line-width lw, the bounding outlines for filling are given by the two infinitely thin paths consisting of all points whose perpendicular distance from the path of the circle/ellipse is equal to lw/2 (which may be a fractional value). The cap-style and join-style are applied the same as for a line corresponding to the tangent of the circle/ellipse at the endpoint.

For an arc specified as [ x, y, width, height, angle1, angle2 ], the angles must be specified in the effectively skewed coordinate system of the ellipse (for a circle, the angles and coordinate systems are identical). The relationship between these angles and angles expressed in the normal coordinate system of the screen (as measured with a protractor) is as follows:

skewed-angle = atan ( tan ( normal-angle ) * width / height ) + adjust

The skewed-angle and normal-angle are expressed in radians (rather than in degrees scaled by 64) in the range [ 0, 2 pi ] and where atan returns a value in the range [ -pi / 2 , pi / 2 ] and adjust is:

• 0 for normal-angle in the range [ 0, pi / 2 ]
• pi for normal-angle in the range [ pi / 2 , 3 pi / 2 ]
• 2 pi for normal-angle in the range [ 3 pi / 2 , 2 pi ] For any given arc, #draw_arc does not draw a pixel more than once. If two arcs join correctly and if the line-width is greater than zero and the arcs intersect, #draw_arc does not draw a pixel more than once. Otherwise, the intersecting pixels of intersecting arcs are drawn multiple times. Specifying an arc with one endpoint and a clockwise extent draws the same pixels as specifying the other endpoint and an equivalent counterclockwise extent, except as it affects joins.

If the last point in one arc coincides with the first point in the following arc, the two arcs will join correctly. If the first point in the first arc coincides with the last point in the last arc, the two arcs will join correctly. By specifying one axis to be zero, a horizontal or vertical line can be drawn. Angles are computed based solely on the coordinate system and ignore the aspect ratio.

This function uses these GC components: function, plane-mask, line-width, line-style, cap-style, join-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It also uses these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list.

#draw_arc can generate BadDrawable, BadGC, and BadMatch errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also #draw_arc, #draw_rectangle, #draw_point.

Draws multiple circular or elliptical arcs.

###Arguments

• d Specifies the drawable.
• gc Specifies the GC.
• arcs Specifies an array of arcs.
• narcs Specifies the number of arcs in the array.

###Description #draw_arcs draws multiple circular or elliptical arcs. Each arc is specified by a rectangle and two angles. The center of the circle or ellipse is the center of the rectangle, and the major and minor axes are specified by the width and height. Positive angles indicate counterclockwise motion, and negative angles indicate clockwise motion. If the magnitude of angle2 is greater than 360 degrees, #draw_arcs truncates it to 360 degrees.

For an arc specified as [ x, y, width, height, angle1, angle2 ], the origin of the major and minor axes is at [ x + width / 2 , y + height / 2 ], and the infinitely thin path describing the entire circle or ellipse intersects the horizontal axis at [ x, y + height / 2 ] and [ x + width , y + height / 2 ] and intersects the vertical axis at [ x + width / 2, y ] and [ x + width / 2, y + height ]. These coordinates can be fractional and so are not truncated to discrete coordinates. The path should be defined by the ideal mathematical path. For a wide line with line-width lw, the bounding outlines for filling are given by the two infinitely thin paths consisting of all points whose perpendicular distance from the path of the circle/ellipse is equal to lw/2 (which may be a fractional value). The cap-style and join-style are applied the same as for a line corresponding to the tangent of the circle/ellipse at the endpoint.

For an arc specified as [ x, y, width, height, angle1, angle2 ], the angles must be specified in the effectively skewed coordinate system of the ellipse (for a circle, the angles and coordinate systems are identical). The relationship between these angles and angles expressed in the normal coordinate system of the screen (as measured with a protractor) is as follows:

skewed-angle = atan ( tan ( normal-angle ) * width / height ) + adjust

The skewed-angle and normal-angle are expressed in radians (rather than in degrees scaled by 64) in the range [ 0, 2 pi ] and where atan returns a value in the range [ -pi / 2 , pi / 2 ] and adjust is:

• 0 for normal-angle in the range [ 0, pi / 2 ]
• pi for normal-angle in the range [ pi / 2 , 3 pi / 2 ]
• 2 pi for normal-angle in the range [ 3 pi / 2 , 2 pi ]

For any given arc, #draw_arcs does not draw a pixel more than once. If two arcs join correctly and if the line-width is greater than zero and the arcs intersect, #draw_arc does not draw a pixel more than once. Otherwise, the intersecting pixels of intersecting arcs are drawn multiple times. Specifying an arc with one endpoint and a clockwise extent draws the same pixels as specifying the other endpoint and an equivalent counterclockwise extent, except as it affects joins.

If the last point in one arc coincides with the first point in the following arc, the two arcs will join correctly. If the first point in the first arc coincides with the last point in the last arc, the two arcs will join correctly. By specifying one axis to be zero, a horizontal or vertical line can be drawn. Angles are computed based solely on the coordinate system and ignore the aspect ratio.

This function uses these GC components: function, plane-mask, line-width, line-style, cap-style, join-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It also uses these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list.

#draw_arcs can generate BadDrawable, BadGC, and BadMatch errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also #draw_arc, #draw_rectangle, #draw_point.

Paints text with the foreground pixel.

###Arguments

• d Specifies the drawable.
• gc Specifies the GC.
• x, y Specify the x and y coordinates, which are relative to the origin of the specified drawable and define the origin of the first character.
• string Specifies the character string.
• length Specifies the number of characters in the string argument.

###Description This function uses both the foreground and background pixels of the GC in the destination. The effect is first to fill a destination rectangle with the background pixel defined in the GC and then to paint the text with the foreground pixel. The upper-left corner of the filled rectangle is at:

[x, y - font-ascent]

The width is:

overall-width

The height is:

font-ascent + font-descent

The overall-width, font-ascent, and font-descent are as would be returned by #query_text_extents using gc and string. The function and fill-style defined in the GC are ignored for these functions. The effective function is GXcopy, and the effective fill-style is FillSolid.

For fonts defined with 2-byte matrix indexing and used with #draw_image_string, each byte is used as a byte2 with a byte1 of zero.

The function uses these GC components: plane-mask, foreground, background, font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.

#draw_image_string can generate BadDrawable, BadGC, and BadMatch errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also #draw_image_string_16, #draw_string, #draw_text, #load_font, text_extents.

Similar to #draw_image_string except that it uses 2-byte or 16-bit characters.

###Arguments

• d Specifies the drawable.
• gc Specifies the GC.
• x, y Specify the x and y coordinates, which are relative to the origin of the specified drawable and define the origin of the first character.
• string Specifies the character string.

###Description The #draw_image_string_16 function is similar to #draw_image_string except that it uses 2-byte or 16-bit characters. Both functions also use both the foreground and background pixels of the GC in the destination.

The effect is first to fill a destination rectangle with the background pixel defined in the GC and then to paint the text with the foreground pixel. The upper-left corner of the filled rectangle is at:

[x, y - font-ascent]

The width is:

overall-width

The height is:

font-ascent + font-descent

The overall-width, font-ascent, and font-descent are as would be returned by #query_text_extents using gc and string. The function and fill-style defined in the GC are ignored for these functions. The effective function is GXcopy, and the effective fill-style is FillSolid.

Both functions use these GC components: plane-mask, foreground, background, font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.

#draw_image_string_16 can generate BadDrawable, BadGC, and BadMatch errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also #draw_image_string, #draw_string, #draw_text, #load_font, text_extents.

Draws a line between the specified set of points (x1, y1) and (x2, y2).

###Arguments

• d Specifies the drawable.
• gc Specifies the GC.
• x1, y1, x2, y2 Specify the points (x1, y1) and (x2, y2) to be connected.

###Description The #draw_line function uses the components of the specified GC to draw a line between the specified set of points (x1, y1) and (x2, y2). It does not perform joining at coincident endpoints. For any given line, #draw_line does not draw a pixel more than once. If lines intersect, the intersecting pixels are drawn multiple times.

#draw_line use these GC components: function, plane-mask, line-width, line-style, cap-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. #draw_line also uses these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list.

#draw_line, can generate BadDrawable, BadGC, and BadMatch errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also #draw_arc, #draw_lines, #draw_point, #draw_rectangle, #draw_segments.

Draws lines between each pair of points array.

###Arguments

• d Specifies the drawable.
• gc Specifies the GC.
• points Specifies an array of points.
• mode Specifies the coordinate mode. You can pass CoordModeOrigin or CoordModePrevious.

###Description The #draw_lines function uses the components of the specified GC to draw points.size - 1 lines between each pair of points (point[i], point[i+1]) in the array of Point structures. It draws the lines in the order listed in the array. The lines join correctly at all intermediate points, and if the first and last points coincide, the first and last lines also join correctly. For any given line, #draw_lines does not draw a pixel more than once. If thin (zero line-width) lines intersect, the intersecting pixels are drawn multiple times. If wide lines intersect, the intersecting pixels are drawn only once, as though the entire PolyLine protocol request were a single, filled shape. CoordModeOrigin treats all coordinates as relative to the origin, and CoordModePrevious treats all coordinates after the first as relative to the previous point.

#draw_lines use these GC components: function, plane-mask, line-width, line-style, cap-style, join-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. #draw_lines also uses these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list.

#draw_lines, can generate BadDrawable, BadGC, BadMatch and BadValue errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

###See also #draw_arc, #draw_line, #draw_point, #draw_rectangle, #draw_segments.

Draws a single point into the specified drawable

###Arguments

• d Specifies the drawable.
• gc Specifies the GC.
• x, y Specify the x and y coordinates where you want the point drawn.

###Description The #draw_point function uses the foreground pixel and function components of the GC to draw a single point into the specified drawable;

This function uses these GC components: function, plane-mask, foreground, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.

#draw_point can generate BadDrawable, BadGC, and BadMatch errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also #draw_arc, #draw_line, #draw_points, #draw_rectangle.

Draws multiple points the same way #draw_point draws one point.

###Arguments

• d Specifies the drawable.
• gc Specifies the GC.
• points Specifies an array of points.
• mode Specifies the coordinate mode. You can pass CoordModeOrigin or CoordModePrevious.

###Description #draw_points draws multiple points the same way #draw_point draws one point. CoordModeOrigin treats all coordinates as relative to the origin, and CoordModePrevious treats all coordinates after the first as relative to the previous point. #draw_points draws the points in the order listed in the array.

This function uses these GC components: function, plane-mask, foreground, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. #draw_points can generate BadDrawable, BadGC, BadMatch, and BadValue errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

###See also #draw_arc, #draw_line, #draw_point, #draw_rectangle.

Draws the outlines of the specified rectangle.

###Arguments

• d Specifies the drawable.
• gc Specifies the GC.
• x, y Specify the x and y coordinates, which specify the upper-left corner of the rectangle.
• width, height Specify the width and height, which specify the dimensions of the rectangle.

###Description The #draw_rectangle function draws the outlines of the specified rectangle as if a five-point PolyLine protocol request were specified for the rectangle:

[x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y]

For the specified rectangle, this function does not draw a pixel more than once.

This function uses these GC components: function, plane-mask, line-width, line-style, cap-style, join-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It also uses these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list.

#draw_rectangle can generate BadDrawable, BadGC, and BadMatch errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also #draw_arc, #draw_rectangles, #draw_point.

Draws the outlines of the specified rectangles.

###Arguments

• d Specifies the drawable.
• gc Specifies the GC.
• rectangles Specifies an array of rectangles.

###Description The #draw_rectangles functions draw the outlines of the specified rectangles as if a five-point PolyLine protocol request were specified for each rectangle:

[x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y]

For the specified rectangles, this function does not draw a pixel more than once. #draw_rectangles draws the rectangles in the order listed in the array. If rectangles intersect, the intersecting pixels are drawn multiple times.

This function uses these GC components: function, plane-mask, line-width, line-style, cap-style, join-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It also uses these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list.

#draw_rectangles can generate BadDrawable, BadGC, and BadMatch errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also #draw_arc, #draw_rectangle, #draw_point.

Draws multiple, unconnected lines.

###Arguments

• d Specifies the drawable.
• gc Specifies the GC.
• segments Specifies an array of segments.

###Description The #draw_segments function draws multiple, unconnected lines. For each segment, #draw_segments draws a line between (x1, y1) and (x2, y2). It draws the lines in the order listed in the array of Segment structures and does not perform joining at coincident endpoints. For any given line, #draw_segments does not draw a pixel more than once. If lines intersect, the intersecting pixels are drawn multiple times.

#draw_segments use these GC components: function, plane-mask, line-width, line-style, cap-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. #draw_segments also uses these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list.

#draw_segments can generate BadDrawable, BadGC, and BadMatch errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also #draw_arc, #draw_line, #draw_lines, #draw_point, #draw_rectangle.

Draws a string.

###Arguments

• d Specifies the drawable.
• gc Specifies the GC.
• x, y Specify the x and y coordinates, which are relative to the origin of the specified drawable and define the origin of the first character.
• string Specifies the character string.

###Description Each character image, as defined by the font in the GC, is treated as an additional mask for a fill operation on the drawable. The drawable is modified only where the font character has a bit set to 1.

Both functions use these GC components: function, plane-mask, fill-style, font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also use these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, and tile-stipple-y-origin.

#draw_string can generate BadDrawable, BadGC, and BadMatch errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also #draw_image_string, #load_font, #draw_string_16, #draw_text.

Draws a string.

###Arguments

• d Specifies the drawable.
• gc Specifies the GC. which are relative to the origin of the specified drawable and define the origin of the first character.
• x, y Specify the x and y coordinates.
• string Specifies the character string.

###Description Each character image, as defined by the font in the GC, is treated as an additional mask for a fill operation on the drawable. The drawable is modified only where the font character has a bit set to 1. For fonts defined with 2-byte matrix indexing and used with #draw_string_16, each byte is used as a byte2 with a byte1 of zero.

Both functions use these GC components: function, plane-mask, fill-style, font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also use these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, and tile-stipple-y-origin.

#draw_string_16 can generate BadDrawable, BadGC, and BadMatch errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also #draw_image_string, #draw_string, #load_font, #draw_text.

Allows complex spacing and font shifts between counted strings.

###Arguments

• d Specifies the drawable.
• gc Specifies the GC.
• x, y Specify the x and y coordinates, which are relative to the origin of the specified drawable and define the origin of the first character.
• items Specifies an array of text items.

###Description The #draw_text function allows complex spacing and font shifts between counted strings.

Each text item is processed in turn. A font member other than None in an item causes the font to be stored in the GC and used for subsequent text. A text element delta specifies an additional change in the position along the x axis before the string is drawn. The delta is always added to the character origin and is not dependent on any characteristics of the font. Each character image, as defined by the font in the GC, is treated as an additional mask for a fill operation on the drawable. The drawable is modified only where the font character has a bit set to 1. If a text item generates a BadFont error, the previous text items may have been drawn.

For fonts defined with linear indexing rather than 2-byte matrix indexing, each X11::C::X::Char2b structure is interpreted as a 16-bit number with byte1 as the most-significant byte.

The function uses these GC components: function, plane-mask, fill-style, font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It also uses these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, and tile-stipple-y-origin.

#draw_text can generate BadDrawable, BadFont, BadGC, and BadMatch errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadFont A value for a font argument does not name a defined font (or, in some cases, GContext).
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also #draw_image_string, #load_font, #draw_string, #draw_text_16.

Similar to #draw_text except that it uses 2-byte or 16-bit characters.

###Arguments

• d* Specifies the drawable.
• gc Specifies the GC.
• x, y Specify the x and y coordinates, which are relative to the origin of the specified drawable and define the origin of the first character.
• items Specifies an array of text items.

###Description The #draw_text_16 function is similar to #draw_text except that it uses 2-byte or 16-bit characters. Both functions allow complex spacing and font shifts between counted strings.

Each text item is processed in turn. A font member other than None in an item causes the font to be stored in the GC and used for subsequent text. A text element delta specifies an additional change in the position along the x axis before the string is drawn. The delta is always added to the character origin and is not dependent on any characteristics of the font. Each character image, as defined by the font in the GC, is treated as an additional mask for a fill operation on the drawable. The drawable is modified only where the font character has a bit set to 1. If a text item generates a BadFont error, the previous text items may have been drawn.

For fonts defined with linear indexing rather than 2-byte matrix indexing, each X11::C::X::Char2b structure is interpreted as a 16-bit number with byte1 as the most-significant byte.

The function uses these GC components: function, plane-mask, fill-style, font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It also uses these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, and tile-stipple-y-origin.

#draw_text_16 can generate BadDrawable, BadFont, BadGC, and BadMatch errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadFont A value for a font argument does not name a defined font (or, in some cases, GContext).
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also #draw_text, #draw_image_string, #load_font, #draw_string.

Enables the use of the access control list at each connection setup.

###Description The #enable_access_control function enables the use of the access control list at each connection setup.

#enable_access_control can generate a BadAccess error.

###Diagnostics

• BadAccess A client attempted to free a color map entry that it did not already allocate.
• BadAccess A client attempted to store into a read-only color map entry.

###See also #add_host, #add_hosts, #disable_access_control, X11::free, #hosts, #remove_host, #remove_hosts, #set_access_control.

Returns a message from the error message database.

###Arguments

• name Specifies the name of the application.
• message Specifies the type of the error message.
• default_string Specifies the default error message if none is found in the database.

###Description The #error_database_text function returns a message (or the default message) from the error message database. Xlib uses this function internally to look up its error messages. The text in the default_string argument is assumed to be in the encoding of the current locale, and the text stored in the buffer_return argument is in the encoding of the current locale.

The name argument should generally be the name of your application. The message argument should indicate which type of error message you want. If the name and message are not in the Host Portable Character Encoding, the result is implementation dependent. Xlib uses three predefined +application names+ to report errors. In these names, uppercase and lowercase matter.

• XProtoError The protocol error number is used as a string for the message argument.
• XlibMessage These are the message strings that are used internally by the library.
• XRequest For a core protocol request, the major request protocol number is used for the message argument. For an extension request, the extension name (as given by #init_extension) followed by a period (.) and the minor request protocol number is used for the message argument. If no string is found in the error database, the default_string is returned to the buffer argument.

###See also name, #error_text, .new, set_error_handler, set_io_error_handler, #synchronize.

Returns a string describing the specified error code.

###Arguments

• code Specifies the error code for which you want to obtain a description.

###Description The #error_text function returns a string describing the specified error code. The returned text is in the encoding of the current locale. It is recommended that you use this function to obtain an error description because extensions to Xlib may define their own error codes and error strings.

###See also name, #error_database_text, .new, set_error_handler, set_io_error_handler, #synchronize.

Returns the number of events already in the event queue.

###Arguments

• mode Specifies the mode. You can pass QueuedAlready, QueuedAfterFlush, or QueuedAfterReading.

###Description If mode is QueuedAlready, #events_queued returns the number of events already in the event queue (and never performs a system call). If mode is QueuedAfterFlush, #events_queued returns the number of events already in the queue if the number is nonzero. If there are no events in the queue, #events_queued flushes the output buffer, attempts to read more events out of the application's connection, and returns the number read. If mode is QueuedAfterReading, #events_queued returns the number of events already in the queue if the number is nonzero. If there are no events in the queue, #events_queued attempts to read more events out of the application's connection without flushing the output buffer and returns the number read.

#events_queued always returns immediately without I/O if there are events already in the queue. #events_queued with mode QueuedAfterFlush is identical in behavior to #pending. #events_queued with mode QueuedAlready is identical to the #q_length function.

###See also #flush, #if_event, #next_event, #pending, #put_back_event, #sync.

Returns the maximum request size.

###Description The #extended_max_request_size function returns zero if the specified display does not support an extended-length protocol encoding; otherwise, it returns the maximum request size (in 4-byte units) supported by the server using the extended-length encoding. The Xlib functions #draw_lines, #draw_arcs, #fill_polygon, #change_property, #set_clip_rectangles, and set_region will use the extended-length encoding as necessary, if supported by the server. Use of the extended-length encoding in other Xlib functions (for example, #draw_points, #draw_rectangles, draw_degments, #fill_arcs, #fill_rectangles, #put_image) is permitted but not required; an Xlib implementation may choose to split the data across multiple smaller requests instead.

Lists supported extensions.

###Description

The #extensions function returns a list of all extensions supported by the server. If the data returned by the server is in the Latin Portable Character Encoding, then the returned strings are in the Host Portable Character Encoding. Otherwise, the result is implementation dependent.

###See also #query_extension.

Returns data from a specified cut buffer.

###Arguments

• buffer Specifies the buffer from which you want the stored data returned.

###Description Returns a non empty String if the buffer contains data. Returns an empty String if no dta in the buffer or the buffer is invalid.

###See also #fetch_bytes, #rotate_buffers, #store_buffer, #store_bytes.

Returns data from cut buffer 0

###Description Returns a non empty String if the buffer contains data, otherwise returns an empty String.

###See also #fetch_buffer, #rotate_buffers, #store_buffer, #store_bytes.

Returns then window name.

###Arguments

• w Specifies the window.

###Description The #fetch_name function returns the name of the specified window. If it succeeds, it returns a string; otherwise, no name has been set for the window, and it returns empty string. If the data returned by the server is in the Latin Portable Character Encoding, then the returned string is in the Host Portable Character Encoding. Otherwise, the result is implementation dependent.

#fetch_name can generate a BadWindow error.

###Diagnostics

• BadWindow A value for a Window argument does not name a defined Window.

###See also X11::alloc_class_hint, X11::alloc_icon_size, X11::alloc_size_hints, X11::alloc_wm_hints, X11::free, wm_name, #set_command, set_text_property, #set_transient_for_hint, set_wm_client_machine, #set_wm_colormap_windows, #set_wm_colormap_windows, set_wm_icon_name, set_wm_icon_name, set_wm_name, set_wm_properties, #set_wm_protocols, #store_name, X11::string_list_to_text_property.

Fills the region closed by the infinitely thin path described by the specified arc.

###Arguments

• d Specifies the drawable.
• gc Specifies the GC.
• x, y Specify the x and y coordinates, which are relative to the origin of the drawable and specify the upper-left corner of the bounding rectangle.
• width, height Specify the width and height, which are the major and minor axes of the arc.
• angle1 Specifies the start of the arc relative to the three-o'clock position from the center, in units of degrees * 64.
• angle2 Specifies the path and extent of the arc relative to the start of the arc, in units of degrees * 64.

###Description For each arc, #fill_arc fills the region closed by the infinitely thin path described by the specified arc and, depending on the arc-mode specified in the GC, one or two line segments. For ArcChord, the single line segment joining the endpoints of the arc is used. For ArcPieSlice , the two line segments joining the endpoints of the arc with the center point are used. For any given arc, #fill_arc does not draw a pixel more than once. If regions intersect, the intersecting pixels are drawn multiple times.

Both functions use these GC components: function, plane-mask, fill-style, arc-mode, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also use these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, and tile-stipple-y-origin.

#fill_arc can generate BadDrawable, BadGC, and BadMatch errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also #draw_arc, ``draw_point,draw_rectangle,fill_arcs,fill_polygon,fill_rectangle,fill_rectangles`.

Fills the region closed by the infinitely thin path described by the specified arc.

###Arguments

• d Specifies the drawable.
• gc Specifies the GC.
• arcs Specifies an array of arcs.

###Description For each arc, #fill_arcs fills the region closed by the infinitely thin path described by the specified arc and, depending on the arc-mode specified in the GC, one or two line segments. For ArcChord, the single line segment joining the endpoints of the arc is used. For ArcPieSlice, the two line segments joining the endpoints of the arc with the center point are used. #fill_arcs fills the arcs in the order listed in the array. For any given arc, #fill_arcs do not draw a pixel more than once. If regions intersect, the intersecting pixels are drawn multiple times.

Both functions use these GC components: function, plane-mask, fill-style, arc-mode, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also use these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, and tile-stipple-y-origin.

#fill_arcs can generate BadDrawable, BadGC, and BadMatch errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also #draw_arc, #draw_point, #draw_rectangle, #fill_arcs, #fill_polygon, #fill_rectangle, #fill_rectangles.

Fills the region closed by the specified path.

###Arguments

• d Specifies the drawable.
• gc Specifies the GC.
• points Specifies an array of points.
• shape Specifies a shape that helps the server to improve performance. You can pass Complex, Convex, or Nonconvex.
• mode Specifies the coordinate mode. You can pass CoordModeOrigin or CoordModePrevious.

###Description #fill_polygon fills the region closed by the specified path. The path is closed automatically if the last point in the list does not coincide with the first point. #fill_polygon does not draw a pixel of the region more than once. CoordModeOrigin treats all coordinates as relative to the origin, and CoordModePrevious treats all coordinates after the first as relative to the previous point.

Depending on the specified shape, the following occurs:

• If shape is Complex, the path may self-intersect. Note that contiguous coincident points in the path are not treated as self-intersection.
• If shape is Convex, for every pair of points inside the polygon, the line segment connecting them does not intersect the path. If known by the client, specifying Convex can improve performance. If you specify Convex for a path that is not convex, the graphics results are undefined.
• If shape is Nonconvex, the path does not self-intersect, but the shape is not wholly convex. If known by the client, specifying Nonconvex instead of Complex may improve performance. If you specify Nonconvex for a self-intersecting path, the graphics results are undefined.

The fill-rule of the GC controls the filling behavior of self-intersecting polygons.

This function uses these GC components: function, plane-mask, fill-style, fill-rule, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It also uses these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, and tile-stipple-y-origin.

#fill_polygon can generate BadDrawable, BadGC, BadMatch, and BadValue errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

###See also #draw_arc, #draw_point, #draw_rectangle, #fill_arc, #fill_arcs, #fill_rectangle, #fill_rectangles.

Fills the specified rectangle.

###Arguments

• d Specifies the drawable.
• gc Specifies the GC.
• x, y Specify the x and y coordinates, which are relative to the origin of the drawable and specify the upper-left corner of the rectangle.
• width, height Specify the width and height, which are the dimensions of the rectangle to be filled.

###Description The #fill_rectangle function fills the specified rectangle as if a four-point FillPolygon protocol request were specified for each rectangle:

[x,y] [x+width,y] [x+width,y+height] [x,y+height]

The function uses the x and y coordinates, width and height dimensions, and GC you specify.

For any given rectangle, #fill_rectangle does not draw a pixel more than once. If rectangles intersect, the intersecting pixels are drawn multiple times.

The function uses these GC components: function, plane-mask, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also use these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, and tile-stipple-y-origin.

#fill_rectangle can generate BadDrawable, BadGC, and BadMatch errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also #draw_arc, #draw_point, #draw_rectangle, #fill_arc, #fill_arcs, #fill_polygon, #fill_rectangles.

Fills the specified rectangles.

###Arguments

• d Specifies the drawable.
• gc Specifies the GC.
• rectangles Specifies an array of rectangles.

###Description The #fill_rectangles function fills rectangles as if a four-point FillPolygon protocol request were specified for each rectangle:

[x,y] [x+width,y] [x+width,y+height] [x,y+height]

The function uses the x and y coordinates, width and height dimensions, and GC you specify.

#fill_rectangles fills the rectangles in the order listed in the array. For any given rectangle, #fill_rectangles does not draw a pixel more than once. If rectangles intersect, the intersecting pixels are drawn multiple times.

The function uses these GC components: function, plane-mask, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also use these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, and tile-stipple-y-origin.

#fill_rectangles can generate BadDrawable, BadGC, and BadMatch errors.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.
• BadGC A value for a GContext argument does not name a defined GContext.
• BadMatch An InputOnly window is used as a Drawable.
• BadMatch Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request.

###See also #draw_arc, #draw_point, #draw_rectangles, #fill_arcs, #fill_arcs, #fill_polygon, #fill_rectangles.

Flushes the output buffer.

###Description The #flush function flushes the output buffer. Most client applications need not use this function because the output buffer is automatically flushed as needed by calls to #pending, #next_event, and #window_event. Events generated by the server may be enqueued into the library's event queue.

###See also #events_queued, #pending, #sync.

Forces GC component change.

###Arguments

• display Specifies the connection to the X server.
• gc Specifies the GC.

###Description Force sending GC component changes.

Returns an array of strings containing the search path.

###Description The #font_path function allocates and returns an array of strings containing the search path. The contents of these strings are implementation dependent and are not intended to be interpreted by client applications.

###See also #set_font_path, #fonts, #load_font.

Returns an array of available font names.

###Arguments

• pattern Specifies the null-terminated pattern string that can contain wildcard characters.
• max_names Specifies the maximum number of names to be returned.

###Description The #fonts function returns an array of available font names (as controlled by the font search path; see #set_font_path) that match the string you passed to the pattern argument. The pattern string can contain any characters, but each asterisk (*) is a wildcard for any number of characters, and each question mark (?) is a wildcard for a single character. If the pattern string is not in the Host Portable Character Encoding, the result is implementation dependent. Use of uppercase or lowercase does not matter. If the data returned by the server is in the Latin Portable Character Encoding, then the returned strings are in the Host Portable Character Encoding. Otherwise, the result is implementation dependent. If there are no matching font names, #fonts returns empty array.

###See also #fonts_with_info, #load_font, #set_font_path.

Returns a list of font names and infos.

###Arguments

• pattern Specifies the null-terminated pattern string that can contain wildcard characters.
• max_names Specifies the maximum number of names to be returned.

###Description The #fonts_with_info function returns a list of font names and infos that match the specified pattern and their associated font information. The list of names is limited to size specified by maxnames. The information returned for each font is identical to what #load_query_font would return except that the per-character metrics are not returned. The pattern string can contain any characters, but each asterisk (*) is a wildcard for any number of characters, and each question mark (?) is a wildcard for a single character. If the pattern string is not in the Host Portable Character Encoding, the result is implementation dependent. Use of uppercase or lowercase does not matter. If the data returned by the server is in the Latin Portable Character Encoding, then the returned strings are in the Host Portable Character Encoding. Otherwise, the result is implementation dependent. If there are no matching font names, #fonts_with_info returns empty array.

###See also list_fonts, #load_font, #set_font_path.

Activates the screen saver even if the screen saver had been disabled with a timeout of zero.

###Arguments

• mode Specifies the mode that is to be applied. You can pass ScreenSaverActive or ScreenSaverReset.

###Description If the specified mode is ScreenSaverActive and the screen saver currently is deactivated, #force_screen_saver activates the screen saver even if the screen saver had been disabled with a timeout of zero. If the specified mode is ScreenSaverReset and the screen saver currently is enabled, #force_screen_saver 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).

#force_screen_saver can generate a BadValue error.

###Diagnostics

• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

###See also #set_screen_saver, #activate_screen_saver, #reset_screen_saver, #screen_saver.

Frees the colormap storage.

###Arguments

• colormap Specifies the colormap that you want to destroy.

###Description The #free_colormap function deletes the association between the colormap resource ID and the colormap and frees the colormap storage. However, this function has no effect on the default colormap for a screen. If the specified colormap is an installed map for a screen, it is uninstalled (see #uninstall_colormap). If the specified colormap is defined as the colormap for a window (by #create_window, #set_window_colormap, or #change_window_attributes), #free_colormap changes the colormap associated with the window to None and generates a ColormapNotify event. X does not define the colors displayed for a window with a colormap of None.

#free_colormap can generate a BadColor error.

###Diagnostics

• BadColor A value for a Colormap argument does not name a defined Colormap.

###See also #alloc_color, #change_window_attributes, #copy_colormap_and_free, #create_colormap, #create_window, #query_color, #store_colors.

Frees the cells represented by pixels.

###Arguments

• colormap Specifies the colormap.
• pixels Specifies an array of pixel values that map to the cells in the specified colormap.
• planes Specifies the planes you want to free.

###Description The #free_colors function frees the cells represented by pixels whose values are in the pixels array. The planes argument should not have any bits set to 1 in common with any of the pixels. The set of all pixels is produced by ORing together subsets of the planes argument with the pixels. The request frees all of these pixels that were allocated by the client (using #alloc_color, #alloc_named_color, #alloc_color_cells, and #alloc_color_planes). Note that freeing an individual pixel obtained from #alloc_color_planes may not actually allow it to be reused until all of its related pixels are also freed. Similarly, a read-only entry is not actually freed until it has been freed by all clients, and if a client allocates the same read-only entry multiple times, it must free the entry that many times before the entry is actually freed.

All specified pixels that are allocated by the client in the colormap are freed, even if one or more pixels produce an error. If a specified pixel is not a valid index into the colormap, a BadValue error results. If a specified pixel is not allocated by the client (that is, is unallocated or is only allocated by another client) or if the colormap was created with all entries writable (by passing AllocAll to #create_colormap), a BadAccess error results. If more than one pixel is in error, the one that gets reported is arbitrary.

#free_colors can generate BadAccess, BadColor, and BadValue errors.

###Diagnostics

• BadAccess A client attempted to free a color map entry that it did not already allocate.
• BadAccess A client attempted to store into a read-only color map entry.
• BadColor A value for a Colormap argument does not name a defined Colormap.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

###See also #alloc_color, #alloc_color_cells, #alloc_color_planes, #alloc_named_color, #create_colormap, #query_color, #store_colors.

Deletes the association between the cursor resource ID and the specified cursor.

###Arguments

• cursor Specifies the cursor.

###Description The #free_cursor function deletes the association between the cursor resource ID and the specified cursor. The cursor storage is freed when no other resource references it. The specified cursor ID should not be referred to again.

#free_cursor can generate a BadCursor error.

###Diagnostics

• BadCursor A value for a Cursor argument does not name a defined Cursor.

###See also #create_colormap, #create_font_cursor, #define_cursor, #query_best_cursor, #recolor_cursor.

Destroys the specified GC.

###Arguments

• gc** Specifies the GC.

###Description The #free_gc function destroys the specified GC as well as all the associated storage.

#free_gc can generate a BadGC error.

###Diagnostics

• BadGC A value for a GContext argument does not name a defined GContext.

###See also X11::all_planes, #change_gc, #copy_area, #copy_gc, #create_gc, X11::create_region, #draw_arc, #draw_line, #draw_rectangle, #draw_text, #fill_rectangle, X11::g_context_from_gc, #gc_values, #query_best_size, #set_arc_mode, #set_clip_origin.

Frees the pixmap storage.

###Arguments

• pixmap Specifies the pixmap.

###Description The #free_pixmap function first deletes the association between the pixmap ID and the pixmap. Then, the X server frees the pixmap storage when there are no references to it. The pixmap should never be referenced again.

#free_pixmap can generate a BadPixmap error.

###Diagnostics

• BadPixmap A value for a Pixmap argument does not name a defined Pixmap.

###See also #create_pixmap, #copy_area.

Returns the components specified by valuemask for the specified GC.

###Arguments

• gc Specifies the GC.
• valuemask Specifies which components in the GC are to be returned. This argument is the bitwise inclusive OR of zero or more of the valid GC component mask bits.

###Description The #gc_values function returns the components specified by valuemask for the specified GC. If the valuemask contains a valid set of GC mask bits (GCFunction, GCPlaneMask, GCForeground, GCBackground, GCLineWidth, GCLineStyle, GCCapStyle, GCJoinStyle, GCFillStyle, GCFillRule, GCTile, GCStipple, GCTileStipXOrigin, GCTileStipYOrigin, GCFont, GCSubwindowMode, GCGraphicsExposures, GCClipXOrigin, GCCLipYOrigin, GCDashOffset, or GCArcMode) and no error occurs, #gc_values sets the requested components in values_return and returns a nonzero status. Otherwise, it returns a zero status. Note that the clip-mask and dash-list (represented by the GCClipMask and GCDashList bits, respectively, in the valuemask) cannot be requested. Also note that an invalid resource ID (with one or more of the three most-significant bits set to 1) will be returned for GCFont, GCTile, and GCStipple if the component has never been explicitly set by the client.

###See also X11::all_planes, #change_gc, #copy_area, #copy_gc, #create_gc, X11::create_region, #draw_arc, #draw_line, #draw_rectangle, #draw_text, #fill_rectangle, #free_gc, X11::g_context_from_gc, #query_best_size, #set_arc_mode, #set_clip_origin.

Determines the placement of a window using a geometry specification.

###Arguments

• screen Specifies the screen.
• position, default_position Specify the geometry specifications.
• bwidth Specifies the border width.
• fheight, fwidth Specify the font height and width in pixels (increment size).
• xadder, yadder Specify additional interior padding needed in the window.

###Return

• x, y Return the x and y offsets.
• width, height Return the width and height determined.

###Description You pass in the border width (bwidth), size of the increments fwidth and fheight (typically font width and height), and any additional interior space (xadder and yadder) to make it easy to compute the resulting size. The #geometry function returns the position the window should be placed given a position and a default position. #geometry determines the placement of a window using a geometry specification as specified by parse_geometry and the additional information about the window. Given a fully qualified default geometry specification and an incomplete geometry specification, parse_geometry returns a bitmask value as defined above in the parse_geometry call, by using the position argument.

The returned width and height will be the width and height specified by default_position as overridden by any user-specified position. They are not affected by fwidth, fheight, xadder, or yadder. The x and y coordinates are computed by using the border width, the screen width and height, padding as specified by xadder and yadder, and the fheight and fwidth times the width and height from the geometry specifications.

Returns the root window and the current geometry of the drawable.

###Arguments

• d Specifies the drawable, which can be a window or a pixmap.

###Return

• root Returns the root window.
• x, y Return the x and y coordinates that define the location of the drawable. For a window, these coordinates specify the upper-left outer corner relative to its parent's origin. For pixmaps, these coordinates are always zero.
• width, height Return the drawable's dimensions (width and height). For a window, these dimensions specify the inside size, not including the border.
• border_width Returns the border width in pixels. If the drawable is a pixmap, it returns zero.
• depth Returns the depth of the drawable (bits per pixel for the object).

###Description The #geometry function returns the root window and the current geometry of the drawable. The geometry of the drawable includes the x and y coordinates, width and height, border width, and depth. These are described in the argument list. It is legal to pass to this function a window whose class is InputOnly.

#geometry can generate a BadDrawable error.

###Diagnostics

• BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap.

###See also #window_attributes, #query_pointer, #query_tree.

Establishes a passive grab.

###Arguments

• button Specifies the pointer button that is to be grabbed or AnyButton.
• modifiers Specifies the set of keymasks or AnyModifier. The mask is the bitwise inclusive OR of the valid keymask bits.
• grab_window Specifies the grab window.
• owner_events 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.
• event_mask Specifies which pointer events are reported to the client. The mask is the bitwise inclusive OR of the valid pointer event mask bits.
• pointer_mode Specifies further processing of pointer events. You can pass GrabModeSync or GrabModeAsync.
• keyboard_mode Specifies further processing of keyboard events. You can pass GrabModeSync or GrabModeAsync.
• confine_to* Specifies the window to confine the pointer in or None.
• cursor Specifies the cursor that is to be displayed or None.

###Description The #grab_button function establishes a passive grab. In the future, the pointer is actively grabbed (as for #grab_pointer), the last-pointer-grab time is set to the time at which the button was pressed (as transmitted in the ButtonPress event), and the ButtonPress event is reported if all of the following conditions are true:

• The 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.
• The grab_window contains the pointer.
• The confine_to window (if any) is viewable.
• A passive grab on the same button/key combination does not exist on any ancestor of grab_window.

The interpretation of the remaining arguments is as for #grab_pointer. The active grab is terminated automatically when the logical state of the pointer has all buttons released (independent of the state of the logical modifier keys).

Note that the logical state of a device (as seen by client applications) may lag the physical state if device event processing is frozen.

This request overrides all previous grabs by the same client on the same button/key combinations on the same window. A modifiers of AnyModifier is equivalent to issuing the grab request for all possible modifier combinations (including the combination of no modifiers). It is not required that all modifiers specified have currently assigned KeyCodes. A button of AnyButton is equivalent to issuing the request for all possible buttons. Otherwise, it is not required that the specified button currently be assigned to a physical button.

If some other client has already issued a #grab_button with the same button/key combination on the same window, a BadAccess error results. When using AnyModifier or AnyButton, the request fails completely, and a BadAccess error results (no grabs are established) if there is a conflicting grab for any combination. #grab_button has no effect on an active grab.

#grab_button can generate BadCursor, BadValue, and BadWindow errors.

###Diagnostics

• BadCursor A value for a Cursor argument does not name a defined Cursor.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.
• BadWindow A value for a Window argument does not name a defined Window.

###See also #allow_events, #change_active_pointer_grab, #grab_key, #grab_keyboard, #grab_pointer, #ungrab_pointer.

Establishes a passive grab on the keyboard.

###Arguments

• keycode Specifies the KeyCode or AnyKey.
• modifiers Specifies the set of keymasks or AnyModifier. The mask is the bitwise inclusive OR of the valid keymask bits.
• grab_window Specifies the grab window.
• owner_events Specifies a Boolean value that indicates whether the keyboard events are to be reported as usual.
• pointer_mode Specifies further processing of pointer events. You can pass GrabModeSync or GrabModeAsync.
• keyboard_mode Specifies further processing of keyboard events. You can pass GrabModeSync or GrabModeAsync.

###Description The #grab_key function establishes a passive grab on the keyboard. In the future, the keyboard is actively grabbed (as for #grab_keyboard), the last-keyboard-grab time is set to the time at which the key was pressed (as transmitted in the KeyPress event), and the KeyPress event is reported if all of the following conditions are true:

• The 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.
• 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.
• A passive grab on the same key combination does not exist on any ancestor of grab_window.

The interpretation of the remaining arguments is as for #grab_keyboard. The active grab is terminated automatically when the logical state of the keyboard has the specified key released (independent of the logical state of the modifier keys).

Note that the logical state of a device (as seen by client applications) may lag the physical state if device event processing is frozen.

A modifiers argument of AnyModifier is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). It is not required that all modifiers specified have currently assigned KeyCodes. A keycode argument of AnyKey is equivalent to issuing the request for all possible KeyCodes. Otherwise, the specified keycode must be in the range specified by min_keycode and max_keycode in the connection setup, or a BadValue error results.

If some other client has issued a #grab_key with the same key combination on the same window, a BadAccess error results. When using AnyModifier or AnyKey, the request fails completely, and a BadAccess error results (no grabs are established) if there is a conflicting grab for any combination.

#grab_key can generate BadAccess, BadValue, and BadWindow errors.

###Diagnostics

• BadAccess A client attempted to free a color map entry that it did not already allocate.
• BadAccess A client attempted to store into a read-only color map entry.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.
• BadWindow A value for a Window argument does not name a defined Window.

###See also #allow_events, #grab_button, #grab_keyboard, #grab_pointer, #ungrab_key.

Actively grabs control of the keyboard and generates FocusIn and FocusOut events.

###Arguments

• grab_window Specifies the grab window.
• owner_events Specifies a Boolean value that indicates whether the keyboard events are to be reported as usual.
• pointer_mode Specifies further processing of pointer events. You can pass GrabModeSync or GrabModeAsync.
• keyboard_mode Specifies further processing of keyboard events. You can pass GrabModeSync or GrabModeAsync.
• time Specifies the time. You can pass either a timestamp or CurrentTime.

###Description The #grab_keyboard function actively grabs control of the keyboard and generates FocusIn and FocusOut events. Further key events are reported only to the grabbing client. #grab_keyboard overrides any active keyboard grab by this client. If owner_events is false, all generated key events are reported with respect to grab_window. If owner_events is true and if a generated key event would normally be reported to this client, it is reported normally; otherwise, the event is reported with respect to the grab_window. Both KeyPress and KeyRelease events are always reported, independent of any event selection made by the client.

If the keyboard_mode argument is GrabModeAsync, keyboard event processing continues as usual. If the keyboard is currently frozen by this client, then processing of keyboard events is resumed. If the keyboard_mode argument is GrabModeSync, the state of the keyboard (as seen by client applications) appears to freeze, and the X server generates no further keyboard events until the grabbing client issues a releasing #allow_events call or until the keyboard grab is released. Actual keyboard changes are not lost while the keyboard is frozen; they are simply queued in the server for later processing.

If pointer_mode is GrabModeAsync, pointer event processing is unaffected by activation of the grab. If pointer_mode is GrabModeSync, the state of the pointer (as seen by client applications) appears to freeze, and the X server generates no further pointer events until the grabbing client issues a releasing #allow_events call or until the keyboard grab is released. Actual pointer changes are not lost while the pointer is frozen; they are simply queued in the server for later processing.

If the keyboard is actively grabbed by some other client, #grab_keyboard fails and returns AlreadyGrabbed. If grab_window is not viewable, it fails and returns GrabNotViewable. If the keyboard is frozen by an active grab of another client, it fails and returns GrabFrozen. If the specified time is earlier than the last-keyboard-grab time or later than the current X server time, it fails and returns GrabInvalidTime. Otherwise, the last-keyboard-grab time is set to the specified time (CurrentTime is replaced by the current X server time).

#grab_keyboard can generate BadValue and BadWindow errors.

###Diagnostics

• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.
• BadWindow A value for a Window argument does not name a defined Window.

###See also #allow_events, #grab_button, #grab_key, #grab_pointer, #ungrab_keyboard.

Actively grabs control of the pointer and returns GrabSuccess if the grab was successful.

###Arguments

• grab_window Specifies the grab window.
• owner_events 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.
• event_mask Specifies which pointer events are reported to the client. The mask is the bitwise inclusive OR of the valid pointer event mask bits.
• pointer_mode Specifies further processing of pointer events. You can pass GrabModeSync or GrabModeAsync.
• keyboard_mode Specifies further processing of keyboard events. You can pass GrabModeSync or GrabModeAsync.
• confine_to Specifies the window to confine the pointer in or None.
• cursor Specifies the cursor that is to be displayed during the grab or None.
• time Specifies the time. You can pass either a timestamp or CurrentTime.

###Description The #grab_pointer function actively grabs control of the pointer and returns GrabSuccess if the grab was successful. Further pointer events are reported only to the grabbing client. #grab_pointer overrides any active pointer grab by this client. If owner_events is false, all generated pointer events are reported with respect to grab_window and are reported only if selected by event_mask. If owner_events is true and if a generated pointer event would normally be reported to this client, it is reported as usual. Otherwise, the event is reported with respect to the grab_window and is reported only if selected by event_mask. For either value of owner_events, unreported events are discarded.

If the pointer_mode is GrabModeAsync, pointer event processing continues as usual. If the pointer is currently frozen by this client, the processing of events for the pointer is resumed. If the pointer_mode is GrabModeSync, the state of the pointer, as seen by client applications, appears to freeze, and the X server generates no further pointer events until the grabbing client calls #allow_events or until the pointer grab is released. Actual pointer changes are not lost while the pointer is frozen; they are simply queued in the server for later processing.

If the keyboard_mode is GrabModeAsync, keyboard event processing is unaffected by activation of the grab. If the keyboard_mode is GrabModeSync, the state of the keyboard, as seen by client applications, appears to freeze, and the X server generates no further keyboard events until the grabbing client calls #allow_events or until the pointer grab is released. Actual keyboard changes are not lost while the pointer is frozen; they are simply queued in the server for later processing.

If a cursor is specified, it is displayed regardless of what window the pointer is in. If None is specified, the normal cursor for that window is displayed when the pointer is in grab_window or one of its subwindows; otherwise, the cursor for grab_window is displayed.

If a confine_to window is specified, the pointer is restricted to stay contained in that window. The confine_to window need have no relationship to the grab_window. If the pointer is not initially in the confine_to window, it is warped automatically to the closest edge just before the grab activates and enter/leave events are generated as usual. If the confine_to window is subsequently reconfigured, the pointer is warped automatically, as necessary, to keep it contained in the window.

The time argument allows you to avoid certain circumstances that come up if applications take a long time to respond or if there are long network delays. Consider a situation where you have two applications, both of which normally grab the pointer when clicked on. If both applications specify the timestamp from the event, the second application may wake up faster and successfully grab the pointer before the first application. The first application then will get an indication that the other application grabbed the pointer before its request was processed.

#grab_pointer generates EnterNotify and LeaveNotify events.

Either if grab_window or confine_to window is not viewable or if the confine_to window lies completely outside the boundaries of the root window, #grab_pointer fails and returns GrabNotViewable. If the pointer is actively grabbed by some other client, it fails and returns AlreadyGrabbed. If the pointer is frozen by an active grab of another client, it fails and returns GrabFrozen. If the specified time is earlier than the last-pointer-grab time or later than the current X server time, it fails and returns GrabInvalidTime. Otherwise, the last-pointer-grab time is set to the specified time (CurrentTime is replaced by the current X server time).

#grab_pointer can generate BadCursor, BadValue, and BadWindow errors.

###Diagnostics

• BadCursor A value for a Cursor argument does not name a defined Cursor.
• BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.
• BadWindow A value for a Window argument does not name a defined Window.