ACC SHELL
<!-- Creator : groff version 1.18.1 -->
<!-- CreationDate: Thu Jul 1 22:29:33 2010 -->
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta name="Content-Style" content="text/css">
<title></title>
</head>
<body>
<a href="#Release 1">Release 1</a><br>
<a href="#Release 4">Release 4</a><br>
<a href="#Release 5">Release 5</a><br>
<a href="#Release 6">Release 6</a><br>
<a href="#1.1. Overview of the X Window System">1.1. Overview of the X Window System</a><br>
<a href="#1.2. Errors">1.2. Errors</a><br>
<a href="#1.3. Standard Header Files">1.3. Standard Header Files</a><br>
<a href="#1.4. Generic Values and Types">1.4. Generic Values and Types</a><br>
<a href="#1.5. Naming and Argument Conventions within Xlib">1.5. Naming and Argument Conventions within Xlib</a><br>
<a href="#1.6. Programming Considerations">1.6. Programming Considerations</a><br>
<a href="#1.7. Character Sets and Encodings">1.7. Character Sets and Encodings</a><br>
<a href="#1.8. Formatting Conventions">1.8. Formatting Conventions</a><br>
<a href="#2.1. Opening the Display">2.1. Opening the Display</a><br>
<a href="#2.2. Obtaining Information about the Display, Image Formats, or Screens">2.2. Obtaining Information about the Display, Image Formats, or Screens</a><br>
<a href="#2.2.1. Display Macros">2.2.1. Display Macros</a><br>
<a href="#2.2.2. Image Format Functions and Macros">2.2.2. Image Format Functions and Macros</a><br>
<a href="#2.2.3. Screen Information Macros">2.2.3. Screen Information Macros</a><br>
<a href="#2.3. Generating a NoOperation Protocol Request">2.3. Generating a NoOperation Protocol Request</a><br>
<a href="#2.4. Freeing Client-Created Data">2.4. Freeing Client-Created Data</a><br>
<a href="#2.5. Closing the Display">2.5. Closing the Display</a><br>
<a href="#2.6. Using X Server Connection Close Operations">2.6. Using X Server Connection Close Operations</a><br>
<a href="#2.7. Using Xlib with Threads">2.7. Using Xlib with Threads</a><br>
<a href="#2.8. Using Internal Connections">2.8. Using Internal Connections</a><br>
<a href="#3.1. Visual Types">3.1. Visual Types</a><br>
<a href="#3.2. Window Attributes">3.2. Window Attributes</a><br>
<a href="#3.2.1. Background Attribute">3.2.1. Background Attribute</a><br>
<a href="#3.2.2. Border Attribute">3.2.2. Border Attribute</a><br>
<a href="#3.2.3. Gravity Attributes">3.2.3. Gravity Attributes</a><br>
<a href="#3.2.4. Backing Store Attribute">3.2.4. Backing Store Attribute</a><br>
<a href="#3.2.5. Save Under Flag">3.2.5. Save Under Flag</a><br>
<a href="#3.2.6. Backing Planes and Backing Pixel Attributes">3.2.6. Backing Planes and Backing Pixel Attributes</a><br>
<a href="#3.2.7. Event Mask and Do Not Propagate Mask Attributes">3.2.7. Event Mask and Do Not Propagate Mask Attributes</a><br>
<a href="#3.2.8. Override Redirect Flag">3.2.8. Override Redirect Flag</a><br>
<a href="#3.2.9. Colormap Attribute">3.2.9. Colormap Attribute</a><br>
<a href="#3.2.10. Cursor Attribute">3.2.10. Cursor Attribute</a><br>
<a href="#3.3. Creating Windows">3.3. Creating Windows</a><br>
<a href="#3.4. Destroying Windows">3.4. Destroying Windows</a><br>
<a href="#3.5. Mapping Windows">3.5. Mapping Windows</a><br>
<a href="#3.6. Unmapping Windows">3.6. Unmapping Windows</a><br>
<a href="#3.7. Configuring Windows">3.7. Configuring Windows</a><br>
<a href="#3.8. Changing Window Stacking Order">3.8. Changing Window Stacking Order</a><br>
<a href="#3.9. Changing Window Attributes">3.9. Changing Window Attributes</a><br>
<a href="#4.1. Obtaining Window Information">4.1. Obtaining Window Information</a><br>
<a href="#4.2. Translating Screen Coordinates">4.2. Translating Screen Coordinates</a><br>
<a href="#4.3. Properties and Atoms">4.3. Properties and Atoms</a><br>
<a href="#4.4. Obtaining and Changing Window Properties">4.4. Obtaining and Changing Window Properties</a><br>
<a href="#4.5. Selections">4.5. Selections</a><br>
<a href="#5.1. Creating and Freeing Pixmaps">5.1. Creating and Freeing Pixmaps</a><br>
<a href="#5.2. Creating, Recoloring, and Freeing Cursors">5.2. Creating, Recoloring, and Freeing Cursors</a><br>
<a href="#6.1. Color Structures">6.1. Color Structures</a><br>
<a href="#6.2. Color Strings">6.2. Color Strings</a><br>
<a href="#6.2.1. RGB Device String Specification">6.2.1. RGB Device String Specification</a><br>
<a href="#6.2.2. RGB Intensity String Specification">6.2.2. RGB Intensity String Specification</a><br>
<a href="#6.2.3. Device-Independent String Specifications">6.2.3. Device-Independent String Specifications</a><br>
<a href="#6.3. Color Conversion Contexts and Gamut Mapping">6.3. Color Conversion Contexts and Gamut Mapping</a><br>
<a href="#6.4. Creating, Copying, and Destroying Colormaps">6.4. Creating, Copying, and Destroying Colormaps</a><br>
<a href="#6.5. Mapping Color Names to Values">6.5. Mapping Color Names to Values</a><br>
<a href="#6.6. Allocating and Freeing Color Cells">6.6. Allocating and Freeing Color Cells</a><br>
<a href="#6.7. Modifying and Querying Colormap Cells">6.7. Modifying and Querying Colormap Cells</a><br>
<a href="#6.8. Color Conversion Context Functions">6.8. Color Conversion Context Functions</a><br>
<a href="#6.8.1. Getting and Setting the Color Conversion Context of a Colormap">6.8.1. Getting and Setting the Color Conversion Context of a Colormap</a><br>
<a href="#6.8.2. Obtaining the Default Color Conversion Context">6.8.2. Obtaining the Default Color Conversion Context</a><br>
<a href="#6.8.3. Color Conversion Context Macros">6.8.3. Color Conversion Context Macros</a><br>
<a href="#6.8.4. Modifying Attributes of a Color Conversion Context">6.8.4. Modifying Attributes of a Color Conversion Context</a><br>
<a href="#6.8.5. Creating and Freeing a Color Conversion Context">6.8.5. Creating and Freeing a Color Conversion Context</a><br>
<a href="#6.9. Converting between Color Spaces">6.9. Converting between Color Spaces</a><br>
<a href="#6.10. Callback Functions">6.10. Callback Functions</a><br>
<a href="#6.10.1. Prototype Gamut Compression Procedure">6.10.1. Prototype Gamut Compression Procedure</a><br>
<a href="#6.10.2. Supplied Gamut Compression Procedures">6.10.2. Supplied Gamut Compression Procedures</a><br>
<a href="#6.10.3. Prototype White Point Adjustment Procedure">6.10.3. Prototype White Point Adjustment Procedure</a><br>
<a href="#6.10.4. Supplied White Point Adjustment Procedures">6.10.4. Supplied White Point Adjustment Procedures</a><br>
<a href="#6.11. Gamut Querying Functions">6.11. Gamut Querying Functions</a><br>
<a href="#6.11.1. Red, Green, and Blue Queries">6.11.1. Red, Green, and Blue Queries</a><br>
<a href="#6.11.2. CIELab Queries">6.11.2. CIELab Queries</a><br>
<a href="#6.11.3. CIELuv Queries">6.11.3. CIELuv Queries</a><br>
<a href="#6.11.4. TekHVC Queries">6.11.4. TekHVC Queries</a><br>
<a href="#6.12. Color Management Extensions">6.12. Color Management Extensions</a><br>
<a href="#6.12.1. Color Spaces">6.12.1. Color Spaces</a><br>
<a href="#6.12.2. Adding Device-Independent Color Spaces">6.12.2. Adding Device-Independent Color Spaces</a><br>
<a href="#6.12.3. Querying Color Space Format and Prefix">6.12.3. Querying Color Space Format and Prefix</a><br>
<a href="#6.12.4. Creating Additional Color Spaces">6.12.4. Creating Additional Color Spaces</a><br>
<a href="#6.12.5. Parse String Callback">6.12.5. Parse String Callback</a><br>
<a href="#6.12.6. Color Specification Conversion Callback">6.12.6. Color Specification Conversion Callback</a><br>
<a href="#6.12.7. Function Sets">6.12.7. Function Sets</a><br>
<a href="#6.12.8. Adding Function Sets">6.12.8. Adding Function Sets</a><br>
<a href="#6.12.9. Creating Additional Function Sets">6.12.9. Creating Additional Function Sets</a><br>
<a href="#7.1. Manipulating Graphics Context/State">7.1. Manipulating Graphics Context/State</a><br>
<a href="#7.2. Using Graphics Context Convenience Routines">7.2. Using Graphics Context Convenience Routines</a><br>
<a href="#7.2.1. Setting the Foreground, Background, Function, or Plane Mask">7.2.1. Setting the Foreground, Background, Function, or Plane Mask</a><br>
<a href="#7.2.2. Setting the Line Attributes and Dashes">7.2.2. Setting the Line Attributes and Dashes</a><br>
<a href="#7.2.3. Setting the Fill Style and Fill Rule">7.2.3. Setting the Fill Style and Fill Rule</a><br>
<a href="#7.2.4. Setting the Fill Tile and Stipple">7.2.4. Setting the Fill Tile and Stipple</a><br>
<a href="#7.2.5. Setting the Current Font">7.2.5. Setting the Current Font</a><br>
<a href="#7.2.6. Setting the Clip Region">7.2.6. Setting the Clip Region</a><br>
<a href="#7.2.7. Setting the Arc Mode, Subwindow Mode, and Graphics Exposure">7.2.7. Setting the Arc Mode, Subwindow Mode, and Graphics Exposure</a><br>
<a href="#8.1. Clearing Areas">8.1. Clearing Areas</a><br>
<a href="#8.2. Copying Areas">8.2. Copying Areas</a><br>
<a href="#8.3. Drawing Points, Lines, Rectangles, and Arcs">8.3. Drawing Points, Lines, Rectangles, and Arcs</a><br>
<a href="#8.3.1. Drawing Single and Multiple Points">8.3.1. Drawing Single and Multiple Points</a><br>
<a href="#8.3.2. Drawing Single and Multiple Lines">8.3.2. Drawing Single and Multiple Lines</a><br>
<a href="#8.3.3. Drawing Single and Multiple Rectangles">8.3.3. Drawing Single and Multiple Rectangles</a><br>
<a href="#8.3.4. Drawing Single and Multiple Arcs">8.3.4. Drawing Single and Multiple Arcs</a><br>
<a href="#8.4. Filling Areas">8.4. Filling Areas</a><br>
<a href="#8.4.1. Filling Single and Multiple Rectangles">8.4.1. Filling Single and Multiple Rectangles</a><br>
<a href="#8.4.2. Filling a Single Polygon">8.4.2. Filling a Single Polygon</a><br>
<a href="#8.4.3. Filling Single and Multiple Arcs">8.4.3. Filling Single and Multiple Arcs</a><br>
<a href="#8.5. Font Metrics">8.5. Font Metrics</a><br>
<a href="#8.5.1. Loading and Freeing Fonts">8.5.1. Loading and Freeing Fonts</a><br>
<a href="#8.5.2. Obtaining and Freeing Font Names and Information">8.5.2. Obtaining and Freeing Font Names and Information</a><br>
<a href="#8.5.3. Computing Character String Sizes">8.5.3. Computing Character String Sizes</a><br>
<a href="#8.5.4. Computing Logical Extents">8.5.4. Computing Logical Extents</a><br>
<a href="#8.5.5. Querying Character String Sizes">8.5.5. Querying Character String Sizes</a><br>
<a href="#8.6. Drawing Text">8.6. Drawing Text</a><br>
<a href="#8.6.1. Drawing Complex Text">8.6.1. Drawing Complex Text</a><br>
<a href="#8.6.2. Drawing Text Characters">8.6.2. Drawing Text Characters</a><br>
<a href="#8.6.3. Drawing Image Text Characters">8.6.3. Drawing Image Text Characters</a><br>
<a href="#8.7. Transferring Images between Client and Server">8.7. Transferring Images between Client and Server</a><br>
<a href="#9.1. Changing the Parent of a Window">9.1. Changing the Parent of a Window</a><br>
<a href="#9.2. Controlling the Lifetime of a Window">9.2. Controlling the Lifetime of a Window</a><br>
<a href="#9.3. Managing Installed Colormaps">9.3. Managing Installed Colormaps</a><br>
<a href="#9.4. Setting and Retrieving the Font Search Path">9.4. Setting and Retrieving the Font Search Path</a><br>
<a href="#9.5. Grabbing the Server">9.5. Grabbing the Server</a><br>
<a href="#9.6. Killing Clients">9.6. Killing Clients</a><br>
<a href="#9.7. Controlling the Screen Saver">9.7. Controlling the Screen Saver</a><br>
<a href="#9.8. Controlling Host Access">9.8. Controlling Host Access</a><br>
<a href="#9.8.1. Adding, Getting, or Removing Hosts">9.8.1. Adding, Getting, or Removing Hosts</a><br>
<a href="#9.8.2. Changing, Enabling, or Disabling Access Control">9.8.2. Changing, Enabling, or Disabling Access Control</a><br>
<a href="#10.1. Event Types">10.1. Event Types</a><br>
<a href="#10.2. Event Structures">10.2. Event Structures</a><br>
<a href="#10.3. Event Masks">10.3. Event Masks</a><br>
<a href="#10.4. Event Processing Overview">10.4. Event Processing Overview</a><br>
<a href="#10.5. Keyboard and Pointer Events">10.5. Keyboard and Pointer Events</a><br>
<a href="#10.5.1. Pointer Button Events">10.5.1. Pointer Button Events</a><br>
<a href="#10.5.2. Keyboard and Pointer Events">10.5.2. Keyboard and Pointer Events</a><br>
<a href="#10.6. Window Entry/Exit Events">10.6. Window Entry/Exit Events</a><br>
<a href="#10.6.1. Normal Entry/Exit Events">10.6.1. Normal Entry/Exit Events</a><br>
<a href="#10.6.2. Grab and Ungrab Entry/Exit Events">10.6.2. Grab and Ungrab Entry/Exit Events</a><br>
<a href="#10.7. Input Focus Events">10.7. Input Focus Events</a><br>
<a href="#10.7.1. Normal Focus Events and Focus Events While Grabbed">10.7.1. Normal Focus Events and Focus Events While Grabbed</a><br>
<a href="#10.7.2. Focus Events Generated by Grabs">10.7.2. Focus Events Generated by Grabs</a><br>
<a href="#10.8. Key Map State Notification Events">10.8. Key Map State Notification Events</a><br>
<a href="#10.9. Exposure Events">10.9. Exposure Events</a><br>
<a href="#10.9.1. Expose Events">10.9.1. Expose Events</a><br>
<a href="#10.9.2. GraphicsExpose and NoExpose Events">10.9.2. GraphicsExpose and NoExpose Events</a><br>
<a href="#10.10. Window State Change Events">10.10. Window State Change Events</a><br>
<a href="#10.10.1. CirculateNotify Events">10.10.1. CirculateNotify Events</a><br>
<a href="#10.10.2. ConfigureNotify Events">10.10.2. ConfigureNotify Events</a><br>
<a href="#10.10.3. CreateNotify Events">10.10.3. CreateNotify Events</a><br>
<a href="#10.10.4. DestroyNotify Events">10.10.4. DestroyNotify Events</a><br>
<a href="#10.10.5. GravityNotify Events">10.10.5. GravityNotify Events</a><br>
<a href="#10.10.6. MapNotify Events">10.10.6. MapNotify Events</a><br>
<a href="#10.10.7. MappingNotify Events">10.10.7. MappingNotify Events</a><br>
<a href="#10.10.8. ReparentNotify Events">10.10.8. ReparentNotify Events</a><br>
<a href="#10.10.9. UnmapNotify Events">10.10.9. UnmapNotify Events</a><br>
<a href="#10.10.10. VisibilityNotify Events">10.10.10. VisibilityNotify Events</a><br>
<a href="#10.11. Structure Control Events">10.11. Structure Control Events</a><br>
<a href="#10.11.1. CirculateRequest Events">10.11.1. CirculateRequest Events</a><br>
<a href="#10.11.2. ConfigureRequest Events">10.11.2. ConfigureRequest Events</a><br>
<a href="#10.11.3. MapRequest Events">10.11.3. MapRequest Events</a><br>
<a href="#10.11.4. ResizeRequest Events">10.11.4. ResizeRequest Events</a><br>
<a href="#10.12. Colormap State Change Events">10.12. Colormap State Change Events</a><br>
<a href="#10.13. Client Communication Events">10.13. Client Communication Events</a><br>
<a href="#10.13.1. ClientMessage Events">10.13.1. ClientMessage Events</a><br>
<a href="#10.13.2. PropertyNotify Events">10.13.2. PropertyNotify Events</a><br>
<a href="#10.13.3. SelectionClear Events">10.13.3. SelectionClear Events</a><br>
<a href="#10.13.4. SelectionRequest Events">10.13.4. SelectionRequest Events</a><br>
<a href="#10.13.5. SelectionNotify Events">10.13.5. SelectionNotify Events</a><br>
<a href="#11.1. Selecting Events">11.1. Selecting Events</a><br>
<a href="#11.2. Handling the Output Buffer">11.2. Handling the Output Buffer</a><br>
<a href="#11.3. Event Queue Management">11.3. Event Queue Management</a><br>
<a href="#11.4. Manipulating the Event Queue">11.4. Manipulating the Event Queue</a><br>
<a href="#11.4.1. Returning the Next Event">11.4.1. Returning the Next Event</a><br>
<a href="#11.4.2. Selecting Events Using a Predicate Procedure">11.4.2. Selecting Events Using a Predicate Procedure</a><br>
<a href="#11.4.3. Selecting Events Using a Window or Event Mask">11.4.3. Selecting Events Using a Window or Event Mask</a><br>
<a href="#11.5. Putting an Event Back into the Queue">11.5. Putting an Event Back into the Queue</a><br>
<a href="#11.6. Sending Events to Other Applications">11.6. Sending Events to Other Applications</a><br>
<a href="#11.7. Getting Pointer Motion History">11.7. Getting Pointer Motion History</a><br>
<a href="#11.8. Handling Protocol Errors">11.8. Handling Protocol Errors</a><br>
<a href="#11.8.1. Enabling or Disabling Synchronization">11.8.1. Enabling or Disabling Synchronization</a><br>
<a href="#11.8.2. Using the Default Error Handlers">11.8.2. Using the Default Error Handlers</a><br>
<a href="#12.1. Pointer Grabbing">12.1. Pointer Grabbing</a><br>
<a href="#12.2. Keyboard Grabbing">12.2. Keyboard Grabbing</a><br>
<a href="#12.3. Resuming Event Processing">12.3. Resuming Event Processing</a><br>
<a href="#12.4. Moving the Pointer">12.4. Moving the Pointer</a><br>
<a href="#12.5. Controlling Input Focus">12.5. Controlling Input Focus</a><br>
<a href="#12.6. Manipulating the Keyboard and Pointer Settings">12.6. Manipulating the Keyboard and Pointer Settings</a><br>
<a href="#12.7. Manipulating the Keyboard Encoding">12.7. Manipulating the Keyboard Encoding</a><br>
<a href="#13.1. X Locale Management">13.1. X Locale Management</a><br>
<a href="#13.2. Locale and Modifier Dependencies">13.2. Locale and Modifier Dependencies</a><br>
<a href="#13.3. Variable Argument Lists">13.3. Variable Argument Lists</a><br>
<a href="#13.4. Output Methods">13.4. Output Methods</a><br>
<a href="#13.4.1. Output Method Overview">13.4.1. Output Method Overview</a><br>
<a href="#13.4.2. Output Method Functions">13.4.2. Output Method Functions</a><br>
<a href="#13.4.3. X Output Method Values">13.4.3. X Output Method Values</a><br>
<a href="#13.4.3.1. Required Char Set">13.4.3.1. Required Char Set</a><br>
<a href="#13.4.3.2. Query Orientation">13.4.3.2. Query Orientation</a><br>
<a href="#13.4.3.3. Directional Dependent Drawing">13.4.3.3. Directional Dependent Drawing</a><br>
<a href="#13.4.3.4. Context Dependent Drawing">13.4.3.4. Context Dependent Drawing</a><br>
<a href="#13.4.4. Output Context Functions">13.4.4. Output Context Functions</a><br>
<a href="#13.4.5. Output Context Values">13.4.5. Output Context Values</a><br>
<a href="#13.4.5.1. Base Font Name">13.4.5.1. Base Font Name</a><br>
<a href="#13.4.5.2. Missing CharSet">13.4.5.2. Missing CharSet</a><br>
<a href="#13.4.5.3. Default String">13.4.5.3. Default String</a><br>
<a href="#13.4.5.4. Orientation">13.4.5.4. Orientation</a><br>
<a href="#13.4.5.5. Resource Name and Class">13.4.5.5. Resource Name and Class</a><br>
<a href="#13.4.5.6. Font Info">13.4.5.6. Font Info</a><br>
<a href="#13.4.5.7. OM Automatic">13.4.5.7. OM Automatic</a><br>
<a href="#13.4.6. Creating and Freeing a Font Set">13.4.6. Creating and Freeing a Font Set</a><br>
<a href="#13.4.7. Obtaining Font Set Metrics">13.4.7. Obtaining Font Set Metrics</a><br>
<a href="#13.4.8. Drawing Text Using Font Sets">13.4.8. Drawing Text Using Font Sets</a><br>
<a href="#13.5. Input Methods">13.5. Input Methods</a><br>
<a href="#13.5.1. Input Method Overview">13.5.1. Input Method Overview</a><br>
<a href="#13.5.1.1. Input Method Architecture">13.5.1.1. Input Method Architecture</a><br>
<a href="#13.5.1.2. Input Contexts">13.5.1.2. Input Contexts</a><br>
<a href="#13.5.1.3. Getting Keyboard Input">13.5.1.3. Getting Keyboard Input</a><br>
<a href="#13.5.1.4. Focus Management">13.5.1.4. Focus Management</a><br>
<a href="#13.5.1.5. Geometry Management">13.5.1.5. Geometry Management</a><br>
<a href="#13.5.1.6. Event Filtering">13.5.1.6. Event Filtering</a><br>
<a href="#13.5.1.7. Callbacks">13.5.1.7. Callbacks</a><br>
<a href="#13.5.1.8. Visible Position Feedback Masks">13.5.1.8. Visible Position Feedback Masks</a><br>
<a href="#13.5.1.9. Preedit String Management">13.5.1.9. Preedit String Management</a><br>
<a href="#13.5.2. Input Method Management">13.5.2. Input Method Management</a><br>
<a href="#13.5.2.1. Hot Keys">13.5.2.1. Hot Keys</a><br>
<a href="#13.5.2.2. Preedit State Operation">13.5.2.2. Preedit State Operation</a><br>
<a href="#13.5.3. Input Method Functions">13.5.3. Input Method Functions</a><br>
<a href="#13.5.4. Input Method Values">13.5.4. Input Method Values</a><br>
<a href="#13.5.4.1. Query Input Style">13.5.4.1. Query Input Style</a><br>
<a href="#13.5.4.2. Resource Name and Class">13.5.4.2. Resource Name and Class</a><br>
<a href="#13.5.4.3. Destroy Callback">13.5.4.3. Destroy Callback</a><br>
<a href="#13.5.4.4. Query IM/IC Values List">13.5.4.4. Query IM/IC Values List</a><br>
<a href="#13.5.4.5. Visible Position">13.5.4.5. Visible Position</a><br>
<a href="#13.5.4.6. Preedit Callback Behavior">13.5.4.6. Preedit Callback Behavior</a><br>
<a href="#13.5.5. Input Context Functions">13.5.5. Input Context Functions</a><br>
<a href="#13.5.6. Input Context Values">13.5.6. Input Context Values</a><br>
<a href="#13.5.6.1. Input Style">13.5.6.1. Input Style</a><br>
<a href="#13.5.6.2. Client Window">13.5.6.2. Client Window</a><br>
<a href="#13.5.6.3. Focus Window">13.5.6.3. Focus Window</a><br>
<a href="#13.5.6.4. Resource Name and Class">13.5.6.4. Resource Name and Class</a><br>
<a href="#13.5.6.5. Geometry Callback">13.5.6.5. Geometry Callback</a><br>
<a href="#13.5.6.6. Filter Events">13.5.6.6. Filter Events</a><br>
<a href="#13.5.6.7. Destroy Callback">13.5.6.7. Destroy Callback</a><br>
<a href="#13.5.6.8. String Conversion Callback">13.5.6.8. String Conversion Callback</a><br>
<a href="#13.5.6.9. String Conversion">13.5.6.9. String Conversion</a><br>
<a href="#13.5.6.10. Reset State">13.5.6.10. Reset State</a><br>
<a href="#13.5.6.11. Hot Keys">13.5.6.11. Hot Keys</a><br>
<a href="#13.5.6.12. Hot Key State">13.5.6.12. Hot Key State</a><br>
<a href="#13.5.6.13. Preedit and Status Attributes">13.5.6.13. Preedit and Status Attributes</a><br>
<a href="#13.5.6.13.1. Area">13.5.6.13.1. Area</a><br>
<a href="#13.5.6.13.2. Area Needed">13.5.6.13.2. Area Needed</a><br>
<a href="#13.5.6.13.3. Spot Location">13.5.6.13.3. Spot Location</a><br>
<a href="#13.5.6.13.4. Colormap">13.5.6.13.4. Colormap</a><br>
<a href="#13.5.6.13.5. Foreground and Background">13.5.6.13.5. Foreground and Background</a><br>
<a href="#13.5.6.13.6. Background Pixmap">13.5.6.13.6. Background Pixmap</a><br>
<a href="#13.5.6.13.7. Font Set">13.5.6.13.7. Font Set</a><br>
<a href="#13.5.6.13.8. Line Spacing">13.5.6.13.8. Line Spacing</a><br>
<a href="#13.5.6.13.9. Cursor">13.5.6.13.9. Cursor</a><br>
<a href="#13.5.6.13.10. Preedit State">13.5.6.13.10. Preedit State</a><br>
<a href="#13.5.6.13.11. Preedit State Notify Callback">13.5.6.13.11. Preedit State Notify Callback</a><br>
<a href="#13.5.6.13.12. Preedit and Status Callbacks">13.5.6.13.12. Preedit and Status Callbacks</a><br>
<a href="#13.5.7. Input Method Callback Semantics">13.5.7. Input Method Callback Semantics</a><br>
<a href="#13.5.7.1. Geometry Callback">13.5.7.1. Geometry Callback</a><br>
<a href="#13.5.7.2. Destroy Callback">13.5.7.2. Destroy Callback</a><br>
<a href="#13.5.7.3. String Conversion Callback">13.5.7.3. String Conversion Callback</a><br>
<a href="#13.5.7.4. Preedit State Callbacks">13.5.7.4. Preedit State Callbacks</a><br>
<a href="#13.5.7.5. Preedit Draw Callback">13.5.7.5. Preedit Draw Callback</a><br>
<a href="#13.5.7.6. Preedit Caret Callback">13.5.7.6. Preedit Caret Callback</a><br>
<a href="#13.5.7.7. Status Callbacks">13.5.7.7. Status Callbacks</a><br>
<a href="#13.5.8. Event Filtering">13.5.8. Event Filtering</a><br>
<a href="#13.5.9. Getting Keyboard Input">13.5.9. Getting Keyboard Input</a><br>
<a href="#13.5.10. Input Method Conventions">13.5.10. Input Method Conventions</a><br>
<a href="#13.5.10.1. Client Conventions">13.5.10.1. Client Conventions</a><br>
<a href="#13.5.10.2. Synchronization Conventions">13.5.10.2. Synchronization Conventions</a><br>
<a href="#13.6. String Constants">13.6. String Constants</a><br>
<a href="#14.1. Client to Window Manager Communication">14.1. Client to Window Manager Communication</a><br>
<a href="#14.1.1. Manipulating Top-Level Windows">14.1.1. Manipulating Top-Level Windows</a><br>
<a href="#14.1.2. Converting String Lists">14.1.2. Converting String Lists</a><br>
<a href="#14.1.3. Setting and Reading Text Properties">14.1.3. Setting and Reading Text Properties</a><br>
<a href="#14.1.4. Setting and Reading the WM_NAME Property">14.1.4. Setting and Reading the WM_NAME Property</a><br>
<a href="#14.1.5. Setting and Reading the WM_ICON_NAME Property">14.1.5. Setting and Reading the WM_ICON_NAME Property</a><br>
<a href="#14.1.6. Setting and Reading the WM_HINTS Property">14.1.6. Setting and Reading the WM_HINTS Property</a><br>
<a href="#14.1.7. Setting and Reading the WM_NORMAL_HINTS Property">14.1.7. Setting and Reading the WM_NORMAL_HINTS Property</a><br>
<a href="#14.1.8. Setting and Reading the WM_CLASS Property">14.1.8. Setting and Reading the WM_CLASS Property</a><br>
<a href="#14.1.9. Setting and Reading the WM_TRANSIENT_FOR Property">14.1.9. Setting and Reading the WM_TRANSIENT_FOR Property</a><br>
<a href="#14.1.10. Setting and Reading the WM_PROTOCOLS Property">14.1.10. Setting and Reading the WM_PROTOCOLS Property</a><br>
<a href="#14.1.11. Setting and Reading the WM_COLORMAP_WINDOWS Property">14.1.11. Setting and Reading the WM_COLORMAP_WINDOWS Property</a><br>
<a href="#14.1.12. Setting and Reading the WM_ICON_SIZE Property">14.1.12. Setting and Reading the WM_ICON_SIZE Property</a><br>
<a href="#14.1.13. Using Window Manager Convenience Functions">14.1.13. Using Window Manager Convenience Functions</a><br>
<a href="#14.2. Client to Session Manager Communication">14.2. Client to Session Manager Communication</a><br>
<a href="#14.2.1. Setting and Reading the WM_COMMAND Property">14.2.1. Setting and Reading the WM_COMMAND Property</a><br>
<a href="#14.2.2. Setting and Reading the WM_CLIENT_MACHINE Property">14.2.2. Setting and Reading the WM_CLIENT_MACHINE Property</a><br>
<a href="#14.3. Standard Colormaps">14.3. Standard Colormaps</a><br>
<a href="#14.3.1. Standard Colormap Properties and Atoms">14.3.1. Standard Colormap Properties and Atoms</a><br>
<a href="#14.3.2. Setting and Obtaining Standard Colormaps">14.3.2. Setting and Obtaining Standard Colormaps</a><br>
<a href="#15.1. Resource File Syntax">15.1. Resource File Syntax</a><br>
<a href="#15.2. Resource Manager Matching Rules">15.2. Resource Manager Matching Rules</a><br>
<a href="#15.3. Quarks">15.3. Quarks</a><br>
<a href="#15.4. Creating and Storing Databases">15.4. Creating and Storing Databases</a><br>
<a href="#15.5. Merging Resource Databases">15.5. Merging Resource Databases</a><br>
<a href="#15.6. Looking Up Resources">15.6. Looking Up Resources</a><br>
<a href="#15.7. Storing into a Resource Database">15.7. Storing into a Resource Database</a><br>
<a href="#15.8. Enumerating Database Entries">15.8. Enumerating Database Entries</a><br>
<a href="#15.9. Parsing Command Line Options">15.9. Parsing Command Line Options</a><br>
<a href="#16.1. Using Keyboard Utility Functions">16.1. Using Keyboard Utility Functions</a><br>
<a href="#16.1.1. KeySym Classification Macros">16.1.1. KeySym Classification Macros</a><br>
<a href="#16.2. Using Latin-1 Keyboard Event Functions">16.2. Using Latin-1 Keyboard Event Functions</a><br>
<a href="#16.3. Allocating Permanent Storage">16.3. Allocating Permanent Storage</a><br>
<a href="#16.4. Parsing the Window Geometry">16.4. Parsing the Window Geometry</a><br>
<a href="#16.5. Manipulating Regions">16.5. Manipulating Regions</a><br>
<a href="#16.5.1. Creating, Copying, or Destroying Regions">16.5.1. Creating, Copying, or Destroying Regions</a><br>
<a href="#16.5.2. Moving or Shrinking Regions">16.5.2. Moving or Shrinking Regions</a><br>
<a href="#16.5.3. Computing with Regions">16.5.3. Computing with Regions</a><br>
<a href="#16.5.4. Determining if Regions Are Empty or Equal">16.5.4. Determining if Regions Are Empty or Equal</a><br>
<a href="#16.5.5. Locating a Point or a Rectangle in a Region">16.5.5. Locating a Point or a Rectangle in a Region</a><br>
<a href="#16.6. Using Cut Buffers">16.6. Using Cut Buffers</a><br>
<a href="#16.7. Determining the Appropriate Visual Type">16.7. Determining the Appropriate Visual Type</a><br>
<a href="#16.8. Manipulating Images">16.8. Manipulating Images</a><br>
<a href="#16.9. Manipulating Bitmaps">16.9. Manipulating Bitmaps</a><br>
<a href="#16.10. Using the Context Manager">16.10. Using the Context Manager</a><br>
<a href="#Basic Protocol Support Routines">Basic Protocol Support Routines</a><br>
<a href="#Hooking into Xlib">Hooking into Xlib</a><br>
<a href="#Hooks into the Library">Hooks into the Library</a><br>
<a href="#Hooks onto Xlib Data Structures">Hooks onto Xlib Data Structures</a><br>
<a href="#GC Caching">GC Caching</a><br>
<a href="#Graphics Batching">Graphics Batching</a><br>
<a href="#Writing Extension Stubs">Writing Extension Stubs</a><br>
<a href="#Requests, Replies, and Xproto.h">Requests, Replies, and Xproto.h</a><br>
<a href="#Request Format">Request Format</a><br>
<a href="#Starting to Write a Stub Procedure">Starting to Write a Stub Procedure</a><br>
<a href="#Locking Data Structures">Locking Data Structures</a><br>
<a href="#Sending the Protocol Request and Arguments">Sending the Protocol Request and Arguments</a><br>
<a href="#Variable Length Arguments">Variable Length Arguments</a><br>
<a href="#Replies">Replies</a><br>
<a href="#Synchronous Calling">Synchronous Calling</a><br>
<a href="#Allocating and Deallocating Memory">Allocating and Deallocating Memory</a><br>
<a href="#Portability Considerations">Portability Considerations</a><br>
<a href="#Deriving the Correct Extension Opcode">Deriving the Correct Extension Opcode</a><br>
<a href="#X Version 11 Compatibility Functions">X Version 11 Compatibility Functions</a><br>
<a href="#Setting Standard Properties">Setting Standard Properties</a><br>
<a href="#Setting and Getting Window Sizing Hints">Setting and Getting Window Sizing Hints</a><br>
<a href="#Getting and Setting an XStandardColormap Structure">Getting and Setting an XStandardColormap Structure</a><br>
<a href="#Parsing Window Geometry">Parsing Window Geometry</a><br>
<a href="#Getting the X Environment Defaults">Getting the X Environment Defaults</a><br>
<a href="#X Version 10 Compatibility Functions">X Version 10 Compatibility Functions</a><br>
<a href="#Drawing and Filling Polygons and Curves">Drawing and Filling Polygons and Curves</a><br>
<a href="#Associating User Data with a Value">Associating User Data with a Value</a><br>
<hr>
<p align=center><b><big>Xlib −C Language X
Interface</big></b></p>
<p align=center><b><big>X Window System
Standard</big></b></p>
<p align=center><b><big>X Version 11, Release
7</big></b></p>
<p align=center><b><big>libX11 1.3.2</big></b></p>
<p align=center>James Gettys<br>
Cambridge Research Laboratory<br>
Digital Equipment Corporation</p>
<p align=center>Robert W. Scheifler<br>
Laboratory for Computer Science<br>
Massachusetts Institute of Technology</p>
<p align=center><i>with contributions from</i></p>
<p align=center>Chuck Adams, Tektronix, Inc.</p>
<p align=center>Vania Joloboff, Open Software
Foundation</p>
<p align=center>Hideki Hiura, Sun Microsystems, Inc.</p>
<p align=center>Bill McMahon, Hewlett-Packard Company</p>
<p align=center>Ron Newman, Massachusetts Institute of
Technology</p>
<p align=center>Al Tabayoyon, Tektronix, Inc.</p>
<p align=center>Glenn Widener, Tektronix, Inc.</p>
<p align=center>Shigeru Yamada, Fujitsu OSSI</p>
<p><small>The X Window System is a trademark of The Open
Group.</small></p>
<p><small>TekHVC is a trademark of Tektronix,
Inc.</small></p>
<p><small>Copyright © 1985, 1986, 1987, 1988, 1989,
1990, 1991, 1994, 1996, 2002 The Open Group</small></p>
<p><small>Permission is hereby granted, free of charge, to
any person obtaining a copy of this software and associated
documentation files (the "Software"), to deal in
the Software without restriction, including without
limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software,
and to permit persons to whom the Software is furnished to
do so, subject to the following conditions:</small></p>
<p><small>The above copyright notice and this permission
notice shall be included in all copies or substantial
portions of the Software.</small></p>
<p><small>THE SOFTWARE IS PROVIDED "AS IS",
WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.</small></p>
<p><small>Except as contained in this notice, the name of
The Open Group shall not be used in advertising or otherwise
to promote the sale, use or other dealings in this Software
without prior written authorization from The Open
Group.</small></p>
<p><small>Copyright © 1985, 1986, 1987, 1988, 1989,
1990, 1991 by Digital Equipment Corporation</small></p>
<p><small>Portions Copyright © 1990, 1991 by
Tektronix, Inc.</small></p>
<p><small>Permission to use, copy, modify and distribute
this documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice appears in
all copies and that both that copyright notice and this
permission notice appear in all copies, and that the names
of Digital and Tektronix not be used in in advertising or
publicity pertaining to this documentation without specific,
written prior permission. Digital and Tektronix makes no
representations about the suitability of this documentation
for any purpose. It is provided ‘‘as
is’’ without express or implied
warranty.</small></p>
<p align=center><b><big>Acknowledgments</big></b></p>
<p>The design and implementation of the first 10 versions
of X were primarily the work of three individuals: Robert
Scheifler of the MIT Laboratory for Computer Science and Jim
Gettys of Digital Equipment Corporation and Ron Newman of
MIT, both at MIT Project Athena. X version 11, however, is
the result of the efforts of dozens of individuals at almost
as many locations and organizations. At the risk of
offending some of the players by exclusion, we would like to
acknowledge some of the people who deserve special credit
and recognition for their work on Xlib. Our apologies to
anyone inadvertently overlooked.</p>
<a name="Release 1"></a>
<h2>Release 1</h2>
<p>Our thanks does to Ron Newman (MIT Project Athena), who
contributed substantially to the design and implementation
of the Version 11 Xlib interface.</p>
<p>Our thanks also goes to Ralph Swick (Project Athena and
Digital) who kept it all together for us during the early
releases. He handled literally thousands of requests from
people everywhere and saved the sanity of at least one of
us. His calm good cheer was a foundation on which we could
build.</p>
<p>Our thanks also goes to Todd Brunhoff (Tektronix) who
was ‘‘loaned’’ to Project Athena at
exactly the right moment to provide very capable and
much-needed assistance during the alpha and beta releases.
He was responsible for the successful integration of sources
from multiple sites; we would not have had a release without
him.</p>
<p>Our thanks also goes to Al Mento and Al Wojtas of
Digital’s ULTRIX Documentation Group. With good humor
and cheer, they took a rough draft and made it an infinitely
better and more useful document. The work they have done
will help many everywhere. We also would like to thank Hal
Murray (Digital SRC) and Peter George (Digital VMS) who
contributed much by proofreading the early drafts of this
document.</p>
<p>Our thanks also goes to Jeff Dike (Digital UEG), Tom
Benson, Jackie Granfield, and Vince Orgovan (Digital VMS)
who helped with the library utilities implementation; to
Hania Gajewska (Digital UEG-WSL) who, along with Ellis Cohen
(CMU and Siemens), was instrumental in the semantic design
of the window manager properties; and to Dave Rosenthal (Sun
Microsystems) who also contributed to the protocol and
provided the sample generic color frame buffer
device-dependent code.</p>
<p>The alpha and beta test participants deserve special
recognition and thanks as well. It is significant that the
bug reports (and many fixes) during alpha and beta test came
almost exclusively from just a few of the alpha testers,
mostly hardware vendors working on product implementations
of X. The continued public contribution of vendors and
universities is certainly to the benefit of the entire X
community.</p>
<p>Our special thanks must go to Sam Fuller, Vice-President
of Corporate Research at Digital, who has remained committed
to the widest public availability of X and who made it
possible to greatly supplement MIT’s resources with
the Digital staff in order to make version 11 a reality.
Many of the people mentioned here are part of the Western
Software Laboratory (Digital UEG-WSL) of the ULTRIX
Engineering group and work for Smokey Wallace, who has been
vital to the project’s success. Others not mentioned
here worked on the toolkit and are acknowledged in the X
Toolkit documentation.</p>
<p>Of course, we must particularly thank Paul Asente,
formerly of Stanford University and now of Digital UEG-WSL,
who wrote W, the predecessor to X, and Brian Reid, formerly
of Stanford University and now of Digital WRL, who had much
to do with W’s design.</p>
<p>Finally, our thanks goes to MIT, Digital Equipment
Corporation, and IBM for providing the environment where it
could happen.</p>
<a name="Release 4"></a>
<h2>Release 4</h2>
<p>Our thanks go to Jim Fulton (MIT X Consortium) for
designing and specifying the new Xlib functions for
Inter-Client Communication Conventions (ICCCM) support.</p>
<p>We also thank Al Mento of Digital for his continued
effort in maintaining this document and Jim Fulton and Donna
Converse (MIT X Consortium) for their much-appreciated
efforts in reviewing the changes.</p>
<a name="Release 5"></a>
<h2>Release 5</h2>
<p>The principal authors of the Input Method facilities are
Vania Joloboff (Open Software Foundation) and Bill McMahon
(Hewlett-Packard). The principal author of the rest of the
internationalization facilities is Glenn Widener
(Tektronix). Our thanks to them for keeping their sense of
humor through a long and sometimes difficult design process.
Although the words and much of the design are due to them,
many others have contributed substantially to the design and
implementation. Tom McFarland (HP) and Frank Rojas (IBM)
deserve particular recognition for their contributions.
Other contributors were: Tim Anderson (Motorola), Alka
Badshah (OSF), Gabe Beged-Dov (HP), Chih-Chung Ko (III),
Vera Cheng (III), Michael Collins (Digital), Walt Daniels
(IBM), Noritoshi Demizu (OMRON), Keisuke Fukui (Fujitsu),
Hitoshoi Fukumoto (Nihon Sun), Tim Greenwood (Digital), John
Harvey (IBM), Hideki Hiura (Sun), Fred Horman (AT&T),
Norikazu Kaiya (Fujitsu), Yuji Kamata (IBM), Yutaka Kataoka
(Waseda University), Ranee Khubchandani (Sun), Akira Kon
(NEC), Hiroshi Kuribayashi (OMRON), Teruhiko Kurosaka (Sun),
Seiji Kuwari (OMRON), Sandra Martin (OSF), Narita Masahiko
(Fujitsu), Masato Morisaki (NTT), Nelson Ng (Sun), Takashi
Nishimura (NTT America), Makato Nishino (IBM), Akira Ohsone
(Nihon Sun), Chris Peterson (MIT), Sam Shteingart
(AT&T), Manish Sheth (AT&T), Muneiyoshi Suzuki
(NTT), Cori Mehring (Digital), Shoji Sugiyama (IBM), and
Eiji Tosa (IBM).</p>
<p>We are deeply indebted to Tatsuya Kato (NTT), Hiroshi
Kuribayashi (OMRON), Seiji Kuwari (OMRON), Muneiyoshi Suzuki
(NTT), and Li Yuhong (OMRON) for producing one of the first
complete sample implementation of the internationalization
facilities, and Hiromu Inukai (Nihon Sun), Takashi Fujiwara
(Fujitsu), Hideki Hiura (Sun), Yasuhiro Kawai (Oki
Technosystems Laboratory), Kazunori Nishihara (Fuji Xerox),
Masaki Takeuchi (Sony), Katsuhisa Yano (Toshiba), Makoto
Wakamatsu (Sony Corporation) for producing the another
complete sample implementation of the internationalization
facilities.</p>
<p>The principal authors (design and implementation) of the
Xcms color management facilities are Al Tabayoyon
(Tektronix) and Chuck Adams (Tektronix). Joann Taylor
(Tektronix), Bob Toole (Tektronix), and Keith Packard (MIT X
Consortium) also contributed significantly to the design.
Others who contributed are: Harold Boll (Kodak), Ken
Bronstein (HP), Nancy Cam (SGI), Donna Converse (MIT X
Consortium), Elias Israel (ISC), Deron Johnson (Sun), Jim
King (Adobe), Ricardo Motta (HP), Chuck Peek (IBM), Wil
Plouffe (IBM), Dave Sternlicht (MIT X Consortium), Kumar
Talluri (AT&T), and Richard Verberg (IBM).</p>
<p>We also once again thank Al Mento of Digital for his
work in formatting and reformatting text for this manual,
and for producing man pages. Thanks also to Clive Feather
(IXI) for proof-reading and finding a number of small
errors.</p>
<a name="Release 6"></a>
<h2>Release 6</h2>
<p>Stephen Gildea (X Consortium) authored the threads
support. Ovais Ashraf (Sun) and Greg Olsen (Sun) contributed
substantially by testing the facilities and reporting bugs
in a timely fashion.</p>
<p>The principal authors of the internationalization
facilities, including Input and Output Methods, are Hideki
Hiura (SunSoft) and Shigeru Yamada (Fujitsu OSSI). Although
the words and much of the design are due to them, many
others have contributed substantially to the design and
implementation. They are: Takashi Fujiwara (Fujitsu), Yoshio
Horiuchi (IBM), Makoto Inada (Digital), Hiromu Inukai (Nihon
SunSoft), Song JaeKyung (KAIST), Franky Ling (Digital), Tom
McFarland (HP), Hiroyuki Miyamoto (Digital), Masahiko Narita
(Fujitsu), Frank Rojas (IBM), Hidetoshi Tajima (HP), Masaki
Takeuchi (Sony), Makoto Wakamatsu (Sony), Masaki Wakao
(IBM), Katsuhisa Yano(Toshiba) and Jinsoo Yoon (KAIST).</p>
<p>The principal producers of the sample implementation of
the internationalization facilities are: Jeffrey Bloomfield
(Fujitsu OSSI), Takashi Fujiwara (Fujitsu), Hideki Hiura
(SunSoft), Yoshio Horiuchi (IBM), Makoto Inada (Digital),
Hiromu Inukai (Nihon SunSoft), Song JaeKyung (KAIST), Riki
Kawaguchi (Fujitsu), Franky Ling (Digital), Hiroyuki
Miyamoto (Digital), Hidetoshi Tajima (HP), Toshimitsu
Terazono (Fujitsu), Makoto Wakamatsu (Sony), Masaki Wakao
(IBM), Shigeru Yamada (Fujitsu OSSI) and Katsuhisa Yano
(Toshiba).</p>
<p>The coordinators of the integration, testing, and
release of this implementation of the internationalization
facilities are Nobuyuki Tanaka (Sony) and Makoto Wakamatsu
(Sony).</p>
<p>Others who have contributed to the architectural design
or testing of the sample implementation of the
internationalization facilities are: Hector Chan (Digital),
Michael Kung (IBM), Joseph Kwok (Digital), Hiroyuki Machida
(Sony), Nelson Ng (SunSoft), Frank Rojas (IBM), Yoshiyuki
Segawa (Fujitsu OSSI), Makiko Shimamura (Fujitsu), Shoji
Sugiyama (IBM), Lining Sun (SGI), Masaki Takeuchi (Sony),
Jinsoo Yoon (KAIST) and Akiyasu Zen (HP).</p>
<pre>Jim Gettys
Cambridge Research Laboratory
Digital Equipment Corporation
Robert W. Scheifler
Laboratory for Computer Science
Massachusetts Institute of Technology
</pre>
<p align=center><b><big>Chapter 1</big></b></p>
<p align=center><b><big>Introduction to Xlib</big></b></p>
<p>The X Window System is a network-transparent window
system that was designed at MIT. X display servers run on
computers with either monochrome or color bitmap display
hardware. The server distributes user input to and accepts
output requests from various client programs located either
on the same machine or elsewhere in the network. Xlib is a C
subroutine library that application programs (clients) use
to interface with the window system by means of a stream
connection. Although a client usually runs on the same
machine as the X server it is talking to, this need not be
the case.</p>
<p><i>Xlib − C Language X Interface</i> is a
reference guide to the low-level C language interface to the
X Window System protocol. It is neither a tutorial nor a
user’s guide to programming the X Window System.
Rather, it provides a detailed description of each function
in the library as well as a discussion of the related
background information. <i>Xlib − C Language X
Interface</i> assumes a basic understanding of a graphics
window system and of the C programming language. Other
higher-level abstractions (for example, those provided by
the toolkits for X) are built on top of the Xlib library.
For further information about these higher-level libraries,
see the appropriate toolkit documentation. The <i>X Window
System Protocol</i> provides the definitive word on the
behavior of X. Although additional information appears here,
the protocol document is the ruling document.</p>
<p>To provide an introduction to X programming, this
chapter discusses:</p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="62%">
<p>Overview of the X Window System</p>
</td>
<td width="27%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="12%">
<p>Errors</p>
</td>
<td width="77%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="42%">
<p>Standard header files</p>
</td>
<td width="47%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="48%">
<p>Generic values and types</p>
</td>
<td width="41%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="86%">
<p>Naming and argument conventions within Xlib</p>
</td>
<td width="3%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="52%">
<p>Programming considerations</p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="56%">
<p>Character sets and encodings</p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="44%">
<p>Formatting conventions</p>
</td>
<td width="45%">
</td>
</table>
<a name="1.1. Overview of the X Window System"></a>
<h2>1.1. Overview of the X Window System</h2>
<p>Some of the terms used in this book are unique to X, and
other terms that are common to other window systems have
different meanings in X. You may find it helpful to refer to
the glossary, which is located at the end of the book.</p>
<p>The X Window System supports one or more screens
containing overlapping windows or subwindows. A screen is a
physical monitor and hardware that can be color, grayscale,
or monochrome. There can be multiple screens for each
display or workstation. A single X server can provide
display services for any number of screens. A set of screens
for a single user with one keyboard and one pointer (usually
a mouse) is called a display.</p>
<p>All the windows in an X server are arranged in strict
hierarchies. At the top of each hierarchy is a root window,
which covers each of the display screens. Each root window
is partially or completely covered by child windows. All
windows, except for root windows, have parents. There is
usually at least one window for each application program.
Child windows may in turn have their own children. In this
way, an application program can create an arbitrarily deep
tree on each screen. X provides graphics, text, and raster
operations for windows.</p>
<p>A child window can be larger than its parent. That is,
part or all of the child window can extend beyond the
boundaries of the parent, but all output to a window is
clipped by its parent. If several children of a window have
overlapping locations, one of the children is considered to
be on top of or raised over the others, thus obscuring them.
Output to areas covered by other windows is suppressed by
the window system unless the window has backing store. If a
window is obscured by a second window, the second window
obscures only those ancestors of the second window that are
also ancestors of the first window.</p>
<p>A window has a border zero or more pixels in width,
which can be any pattern (pixmap) or solid color you like. A
window usually but not always has a background pattern,
which will be repainted by the window system when uncovered.
Child windows obscure their parents, and graphic operations
in the parent window usually are clipped by the
children.</p>
<p>Each window and pixmap has its own coordinate system.
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. For a window, the origin is
inside the border at the inside, upper-left corner.</p>
<p>X does not guarantee to preserve the contents of
windows. When part or all of a window is hidden and then
brought back onto the screen, its contents may be lost. The
server then sends the client program an <i>Expose</i> event
to notify it that part or all of the window needs to be
repainted. Programs must be prepared to regenerate the
contents of windows on demand.</p>
<p>X also provides off-screen storage of graphics objects,
called pixmaps. Single plane (depth 1) pixmaps are sometimes
referred to as bitmaps. Pixmaps can be used in most graphics
functions interchangeably with windows and are used in
various graphics operations to define patterns or tiles.
Windows and pixmaps together are referred to as
drawables.</p>
<p>Most of the functions in Xlib just add requests to an
output buffer. These requests later execute asynchronously
on the X server. Functions that return values of information
stored in the server do not return (that is, they block)
until an explicit reply is received or an error occurs. You
can provide an error handler, which will be called when the
error is reported.</p>
<p>If a client does not want a request to execute
asynchronously, it can follow the request with a call to
<i>XSync</i>, which blocks until all previously buffered
asynchronous events have been sent and acted on. As an
important side effect, the output buffer in Xlib is always
flushed by a call to any function that returns a value from
the server or waits for input.</p>
<p>Many Xlib functions will return an integer resource ID,
which allows you to refer to objects stored on the X server.
These can be of type <i>Window</i>, <i>Font</i>,
<i>Pixmap</i>, <i>Colormap</i>, <i>Cursor</i>, and
<i>GContext</i>, as defined in the file
<<i>X11/X.h</i>>. These resources are created by
requests and are destroyed (or freed) by requests or when
connections are closed. Most of these resources are
potentially sharable between applications, and in fact,
windows are manipulated explicitly by window manager
programs. Fonts and cursors are shared automatically across
multiple screens. Fonts are loaded and unloaded as needed
and are shared by multiple clients. Fonts are often cached
in the server. Xlib provides no support for sharing graphics
contexts between applications.</p>
<p>Client programs are informed of events. Events may
either be side effects of a request (for example, restacking
windows generates <i>Expose</i> events) or completely
asynchronous (for example, from the keyboard). A client
program asks to be informed of events. Because other
applications can send events to your application, programs
must be prepared to handle (or ignore) events of all
types.</p>
<p>Input events (for example, a key pressed or the pointer
moved) arrive asynchronously from the server and are queued
until they are requested by an explicit call (for example,
<i>XNextEvent</i> or <i>XWindowEvent</i>). In addition, some
library functions (for example, <i>XRaiseWindow</i>)
generate <i>Expose</i> and <i>ConfigureRequest</i> events.
These events also arrive asynchronously, but the client may
wish to explicitly wait for them by calling <i>XSync</i>
after calling a function that can cause the server to
generate events.</p>
<a name="1.2. Errors"></a>
<h2>1.2. Errors</h2>
<p>Some functions return <i>Status</i>, an integer error
indication. If the function fails, it returns a zero. If the
function returns a status of zero, it has not updated the
return arguments. Because C does not provide multiple return
values, many functions must return their results by writing
into client-passed storage. By default, errors are handled
either by a standard library function or by one that you
provide. Functions that return pointers to strings return
NULL pointers if the string does not exist.</p>
<p>The X server reports protocol errors at the time that it
detects them. If more than one error could be generated for
a given request, the server can report any of them.</p>
<p>Because Xlib usually does not transmit requests to the
server immediately (that is, it buffers them), errors can be
reported much later than they actually occur. For debugging
purposes, however, Xlib provides a mechanism for forcing
synchronous behavior (see section 11.8.1). When
synchronization is enabled, errors are reported as they are
generated.</p>
<p>When Xlib detects an error, it calls an error handler,
which your program can provide. If you do not provide an
error handler, the error is printed, and your program
terminates.</p>
<a name="1.3. Standard Header Files"></a>
<h2>1.3. Standard Header Files</h2>
<p>The following include files are part of the Xlib
standard:</p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="24%">
<p><<i>X11/Xlib.h</i>></p>
</td>
<td width="65%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p>This is the main header file for Xlib. The majority of
all Xlib symbols are declared by including this file. This
file also contains the preprocessor symbol
<i>XlibSpecificationRelease</i>. This symbol is defined to
have the 6 in this release of the standard. (Release 5 of
Xlib was the first release to have this symbol.)</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="18%">
<p><<i>X11/X.h</i>></p>
</td>
<td width="71%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p>This file declares types and constants for the X protocol
that are to be used by applications. It is included
automatically from <<i>X11/Xlib.h</i>>, so application
code should never need to reference this file directly.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="24%">
<p><<i>X11/Xcms.h</i>></p>
</td>
<td width="65%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p>This file contains symbols for much of the color
management facilities described in chapter 6. All functions,
types, and symbols with the prefix
‘‘Xcms’’, plus the Color Conversion
Contexts macros, are declared in this file.
<<i>X11/Xlib.h</i>> must be included before including
this file.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="26%">
<p><<i>X11/Xutil.h</i>></p>
</td>
<td width="63%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p>This file declares various functions, types, and symbols
used for inter-client communication and application utility
functions, which are described in chapters 14 and 16.
<<i>X11/Xlib.h</i>> must be included before including
this file.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="34%">
<p><<i>X11/Xresource.h</i>></p>
</td>
<td width="55%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p>This file declares all functions, types, and symbols for
the resource manager facilities, which are described in
chapter 15. <<i>X11/Xlib.h</i>> must be included
before including this file.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="26%">
<p><<i>X11/Xatom.h</i>></p>
</td>
<td width="63%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p>This file declares all predefined atoms, which are
symbols with the prefix ‘‘XA_’’.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="36%">
<p><<i>X11/cursorfont.h</i>></p>
</td>
<td width="53%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p>This file declares the cursor symbols for the standard
cursor font, which are listed in appendix B. All cursor
symbols have the prefix ‘‘XC_’’.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="34%">
<p><<i>X11/keysymdef.h</i>></p>
</td>
<td width="55%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p>This file declares all standard KeySym values, which are
symbols with the prefix ‘‘XK_’’. The
KeySyms are arranged in groups, and a preprocessor symbol
controls inclusion of each group. The preprocessor symbol
must be defined prior to inclusion of the file to obtain the
associated values. The preprocessor symbols are
XK_MISCELLANY, XK_XKB_KEYS, XK_3270, XK_LATIN1, XK_LATIN2,
XK_LATIN3, XK_LATIN4, XK_KATAKANA, XK_ARABIC, XK_CYRILLIC,
XK_GREEK, XK_TECHNICAL, XK_SPECIAL, XK_PUBLISHING, XK_APL,
XK_HEBREW, XK_THAI, and XK_KOREAN.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="28%">
<p><<i>X11/keysym.h</i>></p>
</td>
<td width="61%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p>This file defines the preprocessor symbols XK_MISCELLANY,
XK_XKB_KEYS, XK_LATIN1, XK_LATIN2, XK_LATIN3, XK_LATIN4, and
XK_GREEK and then includes
<<i>X11/keysymdef.h</i>>.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="30%">
<p><<i>X11/Xlibint.h</i>></p>
</td>
<td width="59%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p>This file declares all the functions, types, and symbols
used for extensions, which are described in appendix C. This
file automatically includes <<i>X11/Xlib.h</i>>.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="28%">
<p><<i>X11/Xproto.h</i>></p>
</td>
<td width="61%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p>This file declares types and symbols for the basic X
protocol, for use in implementing extensions. It is included
automatically from <<i>X11/Xlibint.h</i>>, so
application and extension code should never need to
reference this file directly.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="34%">
<p><<i>X11/Xprotostr.h</i>></p>
</td>
<td width="55%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p>This file declares types and symbols for the basic X
protocol, for use in implementing extensions. It is included
automatically from <<i>X11/Xproto.h</i>>, so
application and extension code should never need to
reference this file directly.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="22%">
<p><<i>X11/X10.h</i>></p>
</td>
<td width="67%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p>This file declares all the functions, types, and symbols
used for the X10 compatibility functions, which are
described in appendix D.</p></td>
</table>
<a name="1.4. Generic Values and Types"></a>
<h2>1.4. Generic Values and Types</h2>
<p>The following symbols are defined by Xlib and used
throughout the manual:</p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>Xlib defines the type <i>Bool</i> and the Boolean values
<i>True</i> and <i>False</i>.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p><i>None</i> is the universal null resource ID or
atom.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>The type <i>XID</i> is used for generic resource
IDs.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>The type <i>XPointer</i> is defined to be char* and is
used as a generic opaque pointer to data.</p>
</td>
</table>
<a name="1.5. Naming and Argument Conventions within Xlib"></a>
<h2>1.5. Naming and Argument Conventions within Xlib</h2>
<p>Xlib follows a number of conventions for the naming and
syntax of the functions. Given that you remember what
information the function requires, these conventions are
intended to make the syntax of the functions more
predictable.</p>
<p>The major naming conventions are:</p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>To differentiate the X symbols from the other symbols,
the library uses mixed case for external symbols. It leaves
lowercase for variables and all uppercase for user macros,
as per existing convention.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="84%">
<p>All Xlib functions begin with a capital X.</p>
</td>
<td width="5%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>The beginnings of all function names and symbols are
capitalized.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>All user-visible data structures begin with a capital X.
More generally, anything that a user might dereference
begins with a capital X.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>Macros and other symbols do not begin with a capital X.
To distinguish them from all user symbols, each word in the
macro is capitalized.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>All elements of or variables in a data structure are in
lowercase. Compound words, where needed, are constructed
with underscores (_).</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>The display argument, where used, is always first in the
argument list.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>All resource objects, where used, occur at the beginning
of the argument list immediately after the display
argument.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>When a graphics context is present together with another
type of resource (most commonly, a drawable), the graphics
context occurs in the argument list after the other
resource. Drawables outrank all other resources.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>Source arguments always precede the destination
arguments in the argument list.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>The x argument always precedes the y argument in the
argument list.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>The width argument always precedes the height argument
in the argument list.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>Where the x, y, width, and height arguments are used
together, the x and y arguments always precede the width and
height arguments.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>Where a mask is accompanied with a structure, the mask
always precedes the pointer to the structure in the argument
list.</p>
</td>
</table>
<a name="1.6. Programming Considerations"></a>
<h2>1.6. Programming Considerations</h2>
<p>The major programming considerations are:</p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>Coordinates and sizes in X are actually 16-bit
quantities. This decision was made to minimize the bandwidth
required for a given level of performance. Coordinates
usually are declared as an <i>int</i> in the interface.
Values larger than 16 bits are truncated silently. Sizes
(width and height) are declared as unsigned quantities.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>Keyboards are the greatest variable between different
manufacturers’ workstations. If you want your program
to be portable, you should be particularly conservative
here.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>Many display systems have limited amounts of off-screen
memory. If you can, you should minimize use of pixmaps and
backing store.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>The user should have control of his screen real estate.
Therefore, you should write your applications to react to
window management rather than presume control of the entire
screen. What you do inside of your top-level window,
however, is up to your application. For further information,
see chapter 14 and the <i>Inter-Client Communication
Conventions Manual</i>.</p>
</td>
</table>
<a name="1.7. Character Sets and Encodings"></a>
<h2>1.7. Character Sets and Encodings</h2>
<p>Some of the Xlib functions make reference to specific
character sets and character encodings. The following are
the most common:</p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="48%">
<p>X Portable Character Set</p>
</td>
<td width="41%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p>A basic set of 97 characters, which are assumed to exist
in all locales supported by Xlib. This set contains the
following characters:</p>
<!-- INDENTATION -->
<pre>a..z A..Z 0..9
!"#$%&’()*+,-./:;<=>?@[\]^_‘{|}~
<space>, <tab>, and <newline>
</pre>
<!-- INDENTATION -->
<p>This set is the left/lower half of the graphic character
set of ISO8859-1 plus space, tab, and newline. It is also
the set of graphic characters in 7-bit ASCII plus the same
three control characters. The actual encoding of these
characters on the host is system dependent.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="64%">
<p>Host Portable Character Encoding</p>
</td>
<td width="25%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p>The encoding of the X Portable Character Set on the host.
The encoding itself is not defined by this standard, but the
encoding must be the same in all locales supported by Xlib
on the host. If a string is said to be in the Host Portable
Character Encoding, then it only contains characters from
the X Portable Character Set, in the host encoding.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="14%">
<p>Latin-1</p>
</td>
<td width="75%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p>The coded character set defined by the ISO8859-1
standard.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="66%">
<p>Latin Portable Character Encoding</p>
</td>
<td width="23%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p>The encoding of the X Portable Character Set using the
Latin-1 codepoints plus ASCII control characters. If a
string is said to be in the Latin Portable Character
Encoding, then it only contains characters from the X
Portable Character Set, not all of Latin-1.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="30%">
<p>STRING Encoding</p>
</td>
<td width="59%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p>Latin-1, plus tab and newline.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="74%">
<p>POSIX Portable Filename Character Set</p>
</td>
<td width="15%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p>The set of 65 characters, which can be used in naming
files on a POSIX-compliant host, that are correctly
processed in all locales. The set is:</p>
<!-- INDENTATION -->
<pre>a..z A..Z 0..9 ._-
</pre>
</td>
</table>
<a name="1.8. Formatting Conventions"></a>
<h2>1.8. Formatting Conventions</h2>
<p><i>Xlib − C Language X Interface</i> uses the
following conventions:</p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>Global symbols are printed in <i>this special font</i>.
These can be either function names, symbols defined in
include files, or structure names. When declared and
defined, function arguments are printed in <i>italics</i>.
In the explanatory text that follows, they usually are
printed in regular type.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>Each function is introduced by a general discussion that
distinguishes it from other functions. The function
declaration itself follows, and each argument is
specifically explained. Although ANSI C function prototype
syntax is not used, Xlib header files normally declare
functions using function prototypes in ANSI C environments.
General discussion of the function, if any is required,
follows the arguments. Where applicable, the last paragraph
of the explanation lists the possible Xlib error codes that
the function can generate. For a complete discussion of the
Xlib error codes, see section 11.8.2.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>To eliminate any ambiguity between those arguments that
you pass and those that a function returns to you, the
explanations for all arguments that you pass start with the
word <i>specifies</i> or, in the case of multiple arguments,
the word <i>specify</i>. The explanations for all arguments
that are returned to you start with the word <i>returns</i>
or, in the case of multiple arguments, the word
<i>return</i>. The explanations for all arguments that you
can pass and are returned start with the words <i>specifies
and returns</i>.</p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p>•</p>
</td>
<td width="8%"></td>
<td width="90%">
<p>Any pointer to a structure that is used to return a
value is designated as such by the <i>_return</i> suffix as
part of its name. All other pointers passed to these
functions are used for reading only. A few arguments use
pointers to structures that are used for both input and
output and are indicated by using the <i>_in_out</i>
suffix.</p>
</td>
</table>
<p><b>1</b></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b>Chapter 2</b></p>
<p align=center><b>Display Functions</b></p>
<p><small>Before your program can use a display, you must
establish a connection to the X server. Once you have
established a connection, you then can use the Xlib macros
and functions discussed in this chapter to return
information about the display. This chapter discusses how
to:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="58%">
<p><small>Open (connect to) the display</small></p>
</td>
<td width="31%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Obtain information about the display, image
formats, or screens</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="78%">
<p><small>Generate a <i>NoOperation</i> protocol
request</small></p>
</td>
<td width="11%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="48%">
<p><small>Free client-created data</small></p>
</td>
<td width="41%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="66%">
<p><small>Close (disconnect from) a display</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Use X Server connection close
operations</small></p>
</td>
<td width="9%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>Use Xlib with threads</small></p>
</td>
<td width="47%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="48%">
<p><small>Use internal connections</small></p>
</td>
<td width="41%">
</td>
</table>
<a name="2.1. Opening the Display"></a>
<h2>2.1. Opening the Display</h2>
<p><small>To open a connection to the X server that
controls a display, use <i>XOpenDisplay</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Display *XOpenDisplay(<i>display_name</i>)
char *<i>display_name</i>;
</small></pre>
<p><small><i>display_name</i> Specifies the hardware
display name, which determines the display and
communications domain to be used. On a POSIX-conformant
system, if the display_name is NULL, it defaults to the
value of the DISPLAY environment variable.</small></p>
<p><small>│__</small></p>
<p><small>The encoding and interpretation of the display
name are 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:</small></p>
<p><small>__ │</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small><i>protocol</i>/<i>hostname</i>:<i>number</i>.<i>screen_number</i></small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>protocol</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies a protocol family or an alias for a
protocol family. Supported protocol families are
implementation dependent. The protocol entry is optional. If
protocol is not specified, the / separating protocol and
hostname must also not be specified.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>hostname</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>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
(::).</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>number</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>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.</small></p>
</td>
</table>
<p><small><i>screen_number</i> 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 <i>DefaultScreen</i> macro
or the <i>XDefaultScreen</i> function if you are using
languages other than C (see section 2.2.1).</small></p>
<p><small>│__</small></p>
<p><small>For example, the following would specify screen 1
of display 0 on the machine named
‘‘dual-headed’’:</small></p>
<pre><small> dual-headed:0.1
</small></pre>
<p><small>The <i>XOpenDisplay</i> function returns a
<i>Display</i> structure that serves as the connection to
the X server and that contains all the information about
that X server. <i>XOpenDisplay</i> connects your application
to the X server through TCP or DECnet communications
protocols, or through some local inter-process communication
protocol. If the protocol is specified as "tcp",
"inet", or "inet6", or if no protocol is
specified and the hostname is a host machine name and a
single colon (:) separates the hostname and display number,
<i>XOpenDisplay</i> connects using TCP streams. (If the
protocol is specified as "inet", TCP over IPv4 is
used. If the protocol is specified as "inet6", TCP
over IPv6 is used. Otherwise, the implementation determines
which IP version is used.) If the hostname and protocol are
both not specified, Xlib uses whatever it believes is the
fastest transport. If the hostname is a host machine name
and a double colon (::) separates the hostname and display
number, <i>XOpenDisplay</i> connects using DECnet. A single
X server can support any or all of these transport
mechanisms simultaneously. A particular Xlib implementation
can support many more of these transport
mechanisms.</small></p>
<p><small>If successful, <i>XOpenDisplay</i> returns a
pointer to a <i>Display</i> structure, which is defined in
<<i>X11/Xlib.h</i>>. If <i>XOpenDisplay</i> does not
succeed, it returns NULL. After a successful call to
<i>XOpenDisplay</i>, all of the screens in the display can
be used by the client. The screen number specified in the
display_name argument is returned by the
<i>DefaultScreen</i> macro (or the <i>XDefaultScreen</i>
function). You can access elements of the <i>Display</i> and
<i>Screen</i> structures only by using the information
macros or functions. For information about using macros and
functions to obtain information from the <i>Display</i>
structure, see section 2.2.1.</small></p>
<p><small>X servers may implement various types of access
control mechanisms (see section 9.8).</small></p>
<a name="2.2. Obtaining Information about the Display, Image Formats, or Screens"></a>
<h2>2.2. Obtaining Information about the Display, Image Formats, or Screens</h2>
<p><small>The Xlib library provides a number of useful
macros and corresponding functions that return data from the
<i>Display</i> structure. The macros are used for C
programming, and their corresponding function equivalents
are for other language bindings. This section discusses
the:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="28%">
<p><small>Display macros</small></p>
</td>
<td width="61%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="66%">
<p><small>Image format functions and macros</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="50%">
<p><small>Screen information macros</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>All other members of the <i>Display</i> structure
(that is, those for which no macros are defined) are private
to Xlib and must not be used. Applications must never
directly modify or inspect these private members of the
<i>Display</i> structure.</small></p>
<p align=center><small>Note</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The <i>XDisplayWidth</i>, <i>XDisplayHeight</i>,
<i>XDisplayCells</i>, <i>XDisplayPlanes</i>,
<i>XDisplayWidthMM</i>, and <i>XDisplayHeightMM</i>
functions in the next sections are misnamed. These functions
really should be named Screen<i>whatever</i> and
XScreen<i>whatever</i>, not Display<i>whatever</i> or
XDisplay<i>whatever</i>. Our apologies for the resulting
confusion.</small></p>
</td>
</table>
<a name="2.2.1. Display Macros"></a>
<h2>2.2.1. Display Macros</h2>
<p><small>Applications should not directly modify any part
of the <i>Display</i> and <i>Screen</i> structures. The
members should be considered read-only, although they may
change as the result of other operations on the
display.</small></p>
<p><small>The following lists the C language macros, their
corresponding function equivalents that are for other
language bindings, and what data both can
return.</small></p>
<p><small>__ │</small></p>
<pre><small>AllPlanes
unsigned long XAllPlanes()
</small></pre>
<p><small>│__</small></p>
<p><small>Both return a value with all bits set to 1
suitable for use in a plane argument to a
procedure.</small></p>
<p><small>Both <i>BlackPixel</i> and <i>WhitePixel</i> can
be used in implementing a monochrome application. These
pixel values are for permanently allocated entries in the
default colormap. The actual RGB (red, green, and blue)
values are settable on some screens and, in any case, may
not actually be black or white. The names are intended to
convey the expected relative intensity of the
colors.</small></p>
<p><small>__ │</small></p>
<pre><small>BlackPixel(<i>display</i>, <i>screen_number</i>)
unsigned long XBlackPixel(<i>display</i>, <i>screen_number</i>)
Display *<i>display</i>;
int <i>screen_number</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small>│__</small></p>
<p><small>Both return the black pixel value for the
specified screen.</small></p>
<p><small>__ │</small></p>
<pre><small>WhitePixel(<i>display</i>, <i>screen_number</i>)
unsigned long XWhitePixel(<i>display</i>, <i>screen_number</i>)
Display *<i>display</i>;
int <i>screen_number</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small>│__</small></p>
<p><small>Both return the white pixel value for the
specified screen.</small></p>
<p><small>__ │</small></p>
<pre><small>ConnectionNumber(<i>display</i>)
int XConnectionNumber(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return a connection number for the specified
display. On a POSIX-conformant system, this is the file
descriptor of the connection.</small></p>
<p><small>__ │</small></p>
<pre><small>DefaultColormap(<i>display</i>, <i>screen_number</i>)
Colormap XDefaultColormap(<i>display</i>, <i>screen_number</i>)
Display *<i>display</i>;
int <i>screen_number</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small>│__</small></p>
<p><small>Both return the default colormap ID for
allocation on the specified screen. Most routine allocations
of color should be made out of this colormap.</small></p>
<p><small>__ │</small></p>
<pre><small>DefaultDepth(<i>display</i>, <i>screen_number</i>)
int XDefaultDepth(<i>display</i>, <i>screen_number</i>)
Display *<i>display</i>;
int <i>screen_number</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small>│__</small></p>
<p><small>Both return the depth (number of planes) of the
default root window for the specified screen. Other depths
may also be supported on this screen (see
<i>XMatchVisualInfo</i>).</small></p>
<p><small>To determine the number of depths that are
available on a given screen, use
<i>XListDepths</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int *XListDepths(<i>display</i>, <i>screen_number</i>, <i>count_return</i>)
Display *<i>display</i>;
int <i>screen_number</i>;
int *<i>count_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small><i>count_return</i> Returns the number of
depths.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XListDepths</i> 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, <i>XListDepths</i> sets
count_return to the number of available depths. Otherwise,
it does not set count_return and returns NULL. To release
the memory allocated for the array of depths, use
<i>XFree</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>DefaultGC(<i>display</i>, <i>screen_number</i>)
GC XDefaultGC(<i>display</i>, <i>screen_number</i>)
Display *<i>display</i>;
int <i>screen_number</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small>│__</small></p>
<p><small>Both return the default graphics context for the
root window of the specified screen. 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. You can modify its contents freely
because it is not used in any Xlib function. This GC should
never be freed.</small></p>
<p><small>__ │</small></p>
<pre><small>DefaultRootWindow(<i>display</i>)
Window XDefaultRootWindow(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the root window for the default
screen.</small></p>
<p><small>__ │</small></p>
<pre><small>DefaultScreenOfDisplay(<i>display</i>)
Screen *XDefaultScreenOfDisplay(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return a pointer to the default
screen.</small></p>
<p><small>__ │</small></p>
<pre><small>ScreenOfDisplay(<i>display</i>, <i>screen_number</i>)
Screen *XScreenOfDisplay(<i>display</i>, <i>screen_number</i>)
Display *<i>display</i>;
int <i>screen_number</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small>│__</small></p>
<p><small>Both return a pointer to the indicated
screen.</small></p>
<p><small>__ │</small></p>
<pre><small>DefaultScreen(<i>display</i>)
int XDefaultScreen(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the default screen number referenced
by the <i>XOpenDisplay</i> function. This macro or function
should be used to retrieve the screen number in applications
that will use only a single screen.</small></p>
<p><small>__ │</small></p>
<pre><small>DefaultVisual(<i>display</i>, <i>screen_number</i>)
Visual *XDefaultVisual(<i>display</i>, <i>screen_number</i>)
Display *<i>display</i>;
int <i>screen_number</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small>│__</small></p>
<p><small>Both return the default visual type for the
specified screen. For further information about visual
types, see section 3.1.</small></p>
<p><small>__ │</small></p>
<pre><small>DisplayCells(<i>display</i>, <i>screen_number</i>)
int XDisplayCells(<i>display</i>, <i>screen_number</i>)
Display *<i>display</i>;
int <i>screen_number</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small>│__</small></p>
<p><small>Both return the number of entries in the default
colormap.</small></p>
<p><small>__ │</small></p>
<pre><small>DisplayPlanes(<i>display</i>, <i>screen_number</i>)
int XDisplayPlanes(<i>display</i>, <i>screen_number</i>)
Display *<i>display</i>;
int <i>screen_number</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small>│__</small></p>
<p><small>Both return the depth of the root window of the
specified screen. For an explanation of depth, see the
glossary.</small></p>
<p><small>__ │</small></p>
<pre><small>DisplayString(<i>display</i>)
char *XDisplayString(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the string that was passed to
<i>XOpenDisplay</i> when the current display was opened. On
POSIX-conformant systems, if the passed string was NULL,
these return the value of the DISPLAY environment variable
when the current display was opened. These are useful to
applications that invoke the <i>fork</i> system call and
want to open a new connection to the same display from the
child process as well as for printing error
messages.</small></p>
<p><small>__ │</small></p>
<pre><small>long XExtendedMaxRequestSize(<i>display</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *<i>display</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XExtendedMaxRequestSize</i> 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 <i>XDrawLines</i>, <i>XDrawArcs</i>,
<i>XFillPolygon</i>, <i>XChangeProperty</i>,
<i>XSetClipRectangles</i>, and <i>XSetRegion</i> 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, <i>XDrawPoints</i>,
<i>XDrawRectangles</i>, <i>XDrawSegments</i>,
<i>XFillArcs</i>, <i>XFillRectangles</i>, <i>XPutImage</i>)
is permitted but not required; an Xlib implementation may
choose to split the data across multiple smaller requests
instead.</small></p>
<p><small>__ │</small></p>
<pre><small>long XMaxRequestSize(<i>display</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *<i>display</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XMaxRequestSize</i> function returns the
maximum request size (in 4-byte units) supported by the
server without using an extended-length protocol encoding.
Single protocol requests to the server can be no larger than
this size unless an extended-length protocol encoding is
supported by the server. The protocol guarantees the size to
be no smaller than 4096 units (16384 bytes). Xlib
automatically breaks data up into multiple protocol requests
as necessary for the following functions:
<i>XDrawPoints</i>, <i>XDrawRectangles</i>,
<i>XDrawSegments</i>, <i>XFillArcs</i>,
<i>XFillRectangles</i>, and <i>XPutImage</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>LastKnownRequestProcessed(<i>display</i>)
unsigned long XLastKnownRequestProcessed(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both extract the full serial number of the last
request known by Xlib to have been processed by the X
server. Xlib automatically sets this number when replies,
events, and errors are received.</small></p>
<p><small>__ │</small></p>
<pre><small>NextRequest(<i>display</i>)
unsigned long XNextRequest(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both extract the full serial number that is to be
used for the next request. Serial numbers are maintained
separately for each display connection.</small></p>
<p><small>__ │</small></p>
<pre><small>ProtocolVersion(<i>display</i>)
int XProtocolVersion(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the major version number (11) of the
X protocol associated with the connected
display.</small></p>
<p><small>__ │</small></p>
<pre><small>ProtocolRevision(<i>display</i>)
int XProtocolRevision(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the minor protocol revision number of
the X server.</small></p>
<p><small>__ │</small></p>
<pre><small>QLength(<i>display</i>)
int XQLength(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the length of the event queue for the
connected display. Note that there may be more events that
have not been read into the queue yet (see
<i>XEventsQueued</i>).</small></p>
<p><small>__ │</small></p>
<pre><small>RootWindow(<i>display</i>, <i>screen_number</i>)
Window XRootWindow(<i>display</i>, <i>screen_number</i>)
Display *<i>display</i>;
int <i>screen_number</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small>│__</small></p>
<p><small>Both return the root window. These are useful
with functions that need a drawable of a particular screen
and for creating top-level windows.</small></p>
<p><small>__ │</small></p>
<pre><small>ScreenCount(<i>display</i>)
int XScreenCount(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the number of available
screens.</small></p>
<p><small>__ │</small></p>
<pre><small>ServerVendor(<i>display</i>)
char *XServerVendor(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return a pointer to a null-terminated string
that provides some identification of the owner of the X
server implementation. If the data returned by the server is
in the Latin Portable Character Encoding, then the string is
in the Host Portable Character Encoding. Otherwise, the
contents of the string are
implementation-dependent.</small></p>
<p><small>__ │</small></p>
<pre><small>VendorRelease(<i>display</i>)
int XVendorRelease(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return a number related to a vendor’s
release of the X server.</small></p>
<a name="2.2.2. Image Format Functions and Macros"></a>
<h2>2.2.2. Image Format Functions and Macros</h2>
<p><small>Applications are required to present data to the
X server in a format that the server demands. To help
simplify applications, most of the work required to convert
the data is provided by Xlib (see sections 8.7 and
16.8).</small></p>
<p><small>The <i>XPixmapFormatValues</i> structure provides
an interface to the pixmap format information that is
returned at the time of a connection setup. It
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int depth;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int bits_per_pixel;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int scanline_pad;</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>} XPixmapFormatValues;</small></p>
<p><small>│__</small></p>
<p><small>To obtain the pixmap format information for a
given display, use <i>XListPixmapFormats</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XPixmapFormatValues *XListPixmapFormats(<i>display</i>, <i>count_return</i>)
Display *<i>display</i>;
int *<i>count_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>count_return</i> Returns the number of pixmap
formats that are supported by the display.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XListPixmapFormats</i> function returns an
array of <i>XPixmapFormatValues</i> structures that describe
the types of Z format images supported by the specified
display. If insufficient memory is available,
<i>XListPixmapFormats</i> returns NULL. To free the
allocated storage for the <i>XPixmapFormatValues</i>
structures, use <i>XFree</i>.</small></p>
<p><small>The following lists the C language macros, their
corresponding function equivalents that are for other
language bindings, and what data they both return for the
specified server and screen. These are often used by
toolkits as well as by simple applications.</small></p>
<p><small>__ │</small></p>
<pre><small>ImageByteOrder(<i>display</i>)
int XImageByteOrder(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both specify the required byte order for images
for each scanline unit in XY format (bitmap) or for each
pixel value in Z format. The macro or function can return
either <i>LSBFirst</i> or <i>MSBFirst</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>BitmapUnit(<i>display</i>)
int XBitmapUnit(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the size of a bitmap’s scanline
unit in bits. The scanline is calculated in multiples of
this value.</small></p>
<p><small>__ │</small></p>
<pre><small>BitmapBitOrder(<i>display</i>)
int XBitmapBitOrder(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>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 macro
or function can return <i>LSBFirst</i> or
<i>MSBFirst</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>BitmapPad(<i>display</i>)
int XBitmapPad(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Each scanline must be padded to a multiple of
bits returned by this macro or function.</small></p>
<p><small>__ │</small></p>
<pre><small>DisplayHeight(<i>display</i>, <i>screen_number</i>)
int XDisplayHeight(<i>display</i>, <i>screen_number</i>)
Display *<i>display</i>;
int <i>screen_number</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small>│__</small></p>
<p><small>Both return an integer that describes the height
of the screen in pixels.</small></p>
<p><small>__ │</small></p>
<pre><small>DisplayHeightMM(<i>display</i>, <i>screen_number</i>)
int XDisplayHeightMM(<i>display</i>, <i>screen_number</i>)
Display *<i>display</i>;
int <i>screen_number</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small>│__</small></p>
<p><small>Both return the height of the specified screen in
millimeters.</small></p>
<p><small>__ │</small></p>
<pre><small>DisplayWidth(<i>display</i>, <i>screen_number</i>)
int XDisplayWidth(<i>display</i>, <i>screen_number</i>)
Display *<i>display</i>;
int <i>screen_number</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small>│__</small></p>
<p><small>Both return the width of the screen in
pixels.</small></p>
<p><small>__ │</small></p>
<pre><small>DisplayWidthMM(<i>display</i>, <i>screen_number</i>)
int XDisplayWidthMM(<i>display</i>, <i>screen_number</i>)
Display *<i>display</i>;
int <i>screen_number</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small>│__</small></p>
<p><small>Both return the width of the specified screen in
millimeters.</small></p>
<a name="2.2.3. Screen Information Macros"></a>
<h2>2.2.3. Screen Information Macros</h2>
<p><small>The following lists the C language macros, their
corresponding function equivalents that are for other
language bindings, and what data they both can return. These
macros or functions all take a pointer to the appropriate
screen structure.</small></p>
<p><small>__ │</small></p>
<pre><small>BlackPixelOfScreen(<i>screen</i>)
unsigned long XBlackPixelOfScreen(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the black pixel value of the
specified screen.</small></p>
<p><small>__ │</small></p>
<pre><small>WhitePixelOfScreen(<i>screen</i>)
unsigned long XWhitePixelOfScreen(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the white pixel value of the
specified screen.</small></p>
<p><small>__ │</small></p>
<pre><small>CellsOfScreen(<i>screen</i>)
int XCellsOfScreen(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the number of colormap cells in the
default colormap of the specified screen.</small></p>
<p><small>__ │</small></p>
<pre><small>DefaultColormapOfScreen(<i>screen</i>)
Colormap XDefaultColormapOfScreen(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the default colormap of the specified
screen.</small></p>
<p><small>__ │</small></p>
<pre><small>DefaultDepthOfScreen(<i>screen</i>)
int XDefaultDepthOfScreen(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the depth of the root
window.</small></p>
<p><small>__ │</small></p>
<pre><small>DefaultGCOfScreen(<i>screen</i>)
GC XDefaultGCOfScreen(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return a default graphics context (GC) of
the specified screen, which has the same depth as the root
window of the screen. The GC must never be
freed.</small></p>
<p><small>__ │</small></p>
<pre><small>DefaultVisualOfScreen(<i>screen</i>)
Visual *XDefaultVisualOfScreen(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the default visual of the specified
screen. For information on visual types, see section
3.1.</small></p>
<p><small>__ │</small></p>
<pre><small>DoesBackingStore(<i>screen</i>)
int XDoesBackingStore(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return a value indicating whether the screen
supports backing stores. The value returned can be one of
<i>WhenMapped</i>, <i>NotUseful</i>, or <i>Always</i> (see
section 3.2.4).</small></p>
<p><small>__ │</small></p>
<pre><small>DoesSaveUnders(<i>screen</i>)
Bool XDoesSaveUnders(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return a Boolean value indicating whether
the screen supports save unders. If <i>True</i>, the screen
supports save unders. If <i>False</i>, the screen does not
support save unders (see section 3.2.5).</small></p>
<p><small>__ │</small></p>
<pre><small>DisplayOfScreen(<i>screen</i>)
Display *XDisplayOfScreen(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the display of the specified
screen.</small></p>
<p><small>__ │</small></p>
<pre><small>int XScreenNumberOfScreen(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XScreenNumberOfScreen</i> function returns
the screen index number of the specified screen.</small></p>
<p><small>__ │</small></p>
<pre><small>EventMaskOfScreen(<i>screen</i>)
long XEventMaskOfScreen(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the event mask of the root window for
the specified screen at connection setup time.</small></p>
<p><small>__ │</small></p>
<pre><small>WidthOfScreen(<i>screen</i>)
int XWidthOfScreen(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the width of the specified screen in
pixels.</small></p>
<p><small>__ │</small></p>
<pre><small>HeightOfScreen(<i>screen</i>)
int XHeightOfScreen(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the height of the specified screen in
pixels.</small></p>
<p><small>__ │</small></p>
<pre><small>WidthMMOfScreen(<i>screen</i>)
int XWidthMMOfScreen(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the width of the specified screen in
millimeters.</small></p>
<p><small>__ │</small></p>
<pre><small>HeightMMOfScreen(<i>screen</i>)
int XHeightMMOfScreen(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the height of the specified screen in
millimeters.</small></p>
<p><small>__ │</small></p>
<pre><small>MaxCmapsOfScreen(<i>screen</i>)
int XMaxCmapsOfScreen(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the maximum number of installed
colormaps supported by the specified screen (see section
9.3).</small></p>
<p><small>__ │</small></p>
<pre><small>MinCmapsOfScreen(<i>screen</i>)
int XMinCmapsOfScreen(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the minimum number of installed
colormaps supported by the specified screen (see section
9.3).</small></p>
<p><small>__ │</small></p>
<pre><small>PlanesOfScreen(<i>screen</i>)
int XPlanesOfScreen(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the depth of the root
window.</small></p>
<p><small>__ │</small></p>
<pre><small>RootWindowOfScreen(<i>screen</i>)
Window XRootWindowOfScreen(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the appropriate <i>Screen</i>
structure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the root window of the specified
screen.</small></p>
<a name="2.3. Generating a NoOperation Protocol Request"></a>
<h2>2.3. Generating a NoOperation Protocol Request</h2>
<p><small>To execute a <i>NoOperation</i> protocol request,
use <i>XNoOp</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XNoOp(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XNoOp</i> function sends a
<i>NoOperation</i> protocol request to the X server, thereby
exercising the connection.</small></p>
<a name="2.4. Freeing Client-Created Data"></a>
<h2>2.4. Freeing Client-Created Data</h2>
<p><small>To free in-memory data that was created by an
Xlib function, use <i>XFree</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XFree(<i>data</i>)
void *<i>data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>data</i></small></p>
</td>
<td width="12%"></td>
<td width="78%">
<p><small>Specifies the data that is to be
freed.</small></p>
</td>
<td width="1%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XFree</i> function is a general-purpose
Xlib routine that frees the specified data. You must use it
to free any objects that were allocated by Xlib, unless an
alternate function is explicitly specified for the object. A
NULL pointer cannot be passed to this function.</small></p>
<a name="2.5. Closing the Display"></a>
<h2>2.5. Closing the Display</h2>
<p><small>To close a display or disconnect from the X
server, use <i>XCloseDisplay</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XCloseDisplay(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XCloseDisplay</i> function closes the
connection to the X server for the display specified in the
<i>Display</i> structure and destroys all windows, resource
IDs (<i>Window</i>, <i>Font</i>, <i>Pixmap</i>,
<i>Colormap</i>, <i>Cursor</i>, and <i>GContext</i>), or
other resources that the client has created on this display,
unless the close-down mode of the resource has been changed
(see <i>XSetCloseDownMode</i>). Therefore, these windows,
resource IDs, and other resources should never be referenced
again or an error will be generated. Before exiting, you
should call <i>XCloseDisplay</i> explicitly so that any
pending errors are reported as <i>XCloseDisplay</i> performs
a final <i>XSync</i> operation.</small></p>
<p><small><i>XCloseDisplay</i> can generate a <i>BadGC</i>
error.</small></p>
<p><small>Xlib provides a function to permit the resources
owned by a client to survive after the client’s
connection is closed. To change a client’s close-down
mode, use <i>XSetCloseDownMode</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetCloseDownMode(<i>display</i>, <i>close_mode</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<p><small>int <i>close_mode</i>;</small></p>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>close_mode</i> Specifies the client close-down
mode. You can pass <i>DestroyAll</i>,
<i>RetainPermanent</i>, or
<i>RetainTemporary</i>.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XSetCloseDownMode</i> defines what will
happen to the client’s resources at connection close.
A connection starts in <i>DestroyAll</i> mode. For
information on what happens to the client’s resources
when the close_mode argument is <i>RetainPermanent</i> or
<i>RetainTemporary</i>, see section 2.6.</small></p>
<p><small><i>XSetCloseDownMode</i> can generate a
<i>BadValue</i> error.</small></p>
<a name="2.6. Using X Server Connection Close Operations"></a>
<h2>2.6. Using X Server Connection Close Operations</h2>
<p><small>When the X server’s connection to a client
is closed either by an explicit call to <i>XCloseDisplay</i>
or by a process that exits, the X server performs the
following automatic operations:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It disowns all selections owned by the client
(see <i>XSetSelectionOwner</i>).</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It performs an <i>XUngrabPointer</i> and
<i>XUngrabKeyboard</i> if the client has actively grabbed
the pointer or the keyboard.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It performs an <i>XUngrabServer</i> if the client
has grabbed the server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It releases all passive grabs made by the
client.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It marks all resources (including colormap
entries) allocated by the client either as permanent or
temporary, depending on whether the close-down mode is
<i>RetainPermanent</i> or <i>RetainTemporary</i>. However,
this does not prevent other client applications from
explicitly destroying the resources (see
<i>XSetCloseDownMode</i>).</small></p>
</td>
</table>
<p><small>When the close-down mode is <i>DestroyAll</i>,
the X server destroys all of a client’s resources as
follows:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It examines each window in the client’s
save-set to determine if it is an inferior (subwindow) of a
window created by the client. (The save-set is a list of
other clients’ windows that are referred to as
save-set windows.) If so, the X server reparents the
save-set window to the closest ancestor so that the save-set
window is not an inferior of a window created by the client.
The reparenting leaves unchanged the absolute coordinates
(with respect to the root window) of the upper-left outer
corner of the save-set window.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It performs a <i>MapWindow</i> request on the
save-set window if the save-set window is unmapped. The X
server does this even if the save-set window was not an
inferior of a window created by the client.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It destroys all windows created by the
client.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It performs the appropriate free request on each
nonwindow resource created by the client in the server (for
example, <i>Font</i>, <i>Pixmap</i>, <i>Cursor</i>,
<i>Colormap</i>, and <i>GContext</i>).</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It frees all colors and colormap entries
allocated by a client application.</small></p>
</td>
</table>
<p><small>Additional processing occurs when the last
connection to the X server closes. An X server goes through
a cycle of having no connections and having some
connections. When the last connection to the X server closes
as a result of a connection closing with the close_mode of
<i>DestroyAll</i>, the X server does the
following:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It resets its state as if it had just been
started. The X server begins by destroying all lingering
resources from clients that have terminated in
<i>RetainPermanent</i> or <i>RetainTemporary</i>
mode.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It deletes all but the predefined atom
identifiers.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It deletes all properties on all root windows
(see section 4.3).</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It resets all device maps and attributes (for
example, key click, bell volume, and acceleration) as well
as the access control list.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It restores the standard root tiles and
cursors.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="68%">
<p><small>It restores the default font path.</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It restores the input focus to state
<i>PointerRoot</i>.</small></p>
</td>
</table>
<p><small>However, the X server does not reset if you close
a connection with a close-down mode set to
<i>RetainPermanent</i> or
<i>RetainTemporary</i>.</small></p>
<a name="2.7. Using Xlib with Threads"></a>
<h2>2.7. Using Xlib with Threads</h2>
<p><small>On systems that have threads, support may be
provided to permit multiple threads to use Xlib
concurrently.</small></p>
<p><small>To initialize support for concurrent threads, use
<i>XInitThreads</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XInitThreads();
</small></pre>
<p><small>│__</small></p>
<p><small>The <i>XInitThreads</i> function initializes Xlib
support for concurrent threads. This function must be the
first Xlib function a multi-threaded program calls, and it
must complete before any other Xlib call is made. This
function returns a nonzero status if initialization was
successful; otherwise, it returns zero. On systems that do
not support threads, this function always returns
zero.</small></p>
<p><small>It is only necessary to call this function if
multiple threads might use Xlib concurrently. If all calls
to Xlib functions are protected by some other access
mechanism (for example, a mutual exclusion lock in a toolkit
or through explicit client programming), Xlib thread
initialization is not required. It is recommended that
single-threaded programs not call this function.</small></p>
<p><small>To lock a display across several Xlib calls, use
<i>XLockDisplay</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XLockDisplay(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XLockDisplay</i> function locks out all
other threads from using the specified display. Other
threads attempting to use the display will block until the
display is unlocked by this thread. Nested calls to
<i>XLockDisplay</i> work correctly; the display will not
actually be unlocked until <i>XUnlockDisplay</i> has been
called the same number of times as <i>XLockDisplay</i>. This
function has no effect unless Xlib was successfully
initialized for threads using
<i>XInitThreads</i>.</small></p>
<p><small>To unlock a display, use
<i>XUnlockDisplay</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XUnlockDisplay(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XUnlockDisplay</i> function allows other
threads to use the specified display again. Any threads that
have blocked on the display are allowed to continue. Nested
locking works correctly; if <i>XLockDisplay</i> has been
called multiple times by a thread, then
<i>XUnlockDisplay</i> must be called an equal number of
times before the display is actually unlocked. This function
has no effect unless Xlib was successfully initialized for
threads using <i>XInitThreads</i>.</small></p>
<a name="2.8. Using Internal Connections"></a>
<h2>2.8. Using Internal Connections</h2>
<p><small>In addition to the connection to the X server, an
Xlib implementation may require connections to other kinds
of servers (for example, to input method servers as
described in chapter 13). Toolkits and clients that use
multiple displays, or that use displays in combination with
other inputs, need to obtain these additional connections to
correctly block until input is available and need to process
that input when it is available. Simple clients that use a
single display and block for input in an Xlib event function
do not need to use these facilities.</small></p>
<p><small>To track internal connections for a display, use
<i>XAddConnectionWatch</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>typedef void (*XConnectionWatchProc)(<i>display</i>, <i>client_data</i>, <i>fd</i>, <i>opening</i>, <i>watch_data</i>)
Display *<i>display</i>;
XPointer <i>client_data</i>;
int <i>fd</i>;
Bool <i>opening</i>;
XPointer *<i>watch_data</i>;
Status XAddConnectionWatch(<i>display</i>, <i>procedure</i>, <i>client_data</i>)
Display *<i>display</i>;
XWatchProc <i>procedure</i>;
XPointer <i>client_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>procedure</i></small></p>
</td>
<td width="2%"></td>
<td width="74%">
<p><small>Specifies the procedure to be called.</small></p>
</td>
<td width="5%">
</td>
</table>
<p><small><i>client_data</i> Specifies the additional
client data.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XAddConnectionWatch</i> function registers
a procedure to be called each time Xlib opens or closes an
internal connection for the specified display. The procedure
is passed the display, the specified client_data, the file
descriptor for the connection, a Boolean indicating whether
the connection is being opened or closed, and a pointer to a
location for private watch data. If opening is <i>True</i>,
the procedure can store a pointer to private data in the
location pointed to by watch_data; when the procedure is
later called for this same connection and opening is
<i>False</i>, the location pointed to by watch_data will
hold this same private data pointer.</small></p>
<p><small>This function can be called at any time after a
display is opened. If internal connections already exist,
the registered procedure will immediately be called for each
of them, before <i>XAddConnectionWatch</i> returns.
<i>XAddConnectionWatch</i> returns a nonzero status if the
procedure is successfully registered; otherwise, it returns
zero.</small></p>
<p><small>The registered procedure should not call any Xlib
functions. If the procedure directly or indirectly causes
the state of internal connections or watch procedures to
change, the result is not defined. If Xlib has been
initialized for threads, the procedure is called with the
display locked and the result of a call by the procedure to
any Xlib function that locks the display is not defined
unless the executing thread has externally locked the
display using <i>XLockDisplay</i>.</small></p>
<p><small>To stop tracking internal connections for a
display, use <i>XRemoveConnectionWatch</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XRemoveConnectionWatch(<i>display</i>, <i>procedure</i>, <i>client_data</i>)
Display *<i>display</i>;
XWatchProc <i>procedure</i>;
XPointer <i>client_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>procedure</i></small></p>
</td>
<td width="2%"></td>
<td width="74%">
<p><small>Specifies the procedure to be called.</small></p>
</td>
<td width="5%">
</td>
</table>
<p><small><i>client_data</i> Specifies the additional
client data.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XRemoveConnectionWatch</i> function
removes a previously registered connection watch procedure.
The client_data must match the client_data used when the
procedure was initially registered.</small></p>
<p><small>To process input on an internal connection, use
<i>XProcessInternalConnection</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XProcessInternalConnection(<i>display</i>, <i>fd</i>)
Display *<i>display</i>;
int <i>fd</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>fd</i></small></p>
</td>
<td width="16%"></td>
<td width="60%">
<p><small>Specifies the file descriptor.</small></p>
</td>
<td width="19%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XProcessInternalConnection</i> function
processes input available on an internal connection. This
function should be called for an internal connection only
after an operating system facility (for example,
<i>select</i> or <i>poll</i>) has indicated that input is
available; otherwise, the effect is not defined.</small></p>
<p><small>To obtain all of the current internal connections
for a display, use
<i>XInternalConnectionNumbers</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XInternalConnectionNumbers(<i>display</i>, <i>fd_return</i>, <i>count_return</i>)
Display *<i>display</i>;
int **<i>fd_return</i>;
int *<i>count_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>fd_return</i></small></p>
</td>
<td width="2%"></td>
<td width="58%">
<p><small>Returns the file descriptors.</small></p>
</td>
<td width="21%">
</td>
</table>
<p><small><i>count_return</i> Returns the number of file
descriptors.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XInternalConnectionNumbers</i> function
returns a list of the file descriptors for all internal
connections currently open for the specified display. When
the allocated list is no longer needed, free it by using
<i>XFree</i>. This functions returns a nonzero status if the
list is successfully allocated; otherwise, it returns
zero.</small></p>
<p><small><b>2</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b>Chapter 3</b></p>
<p align=center><b>Window Functions</b></p>
<p><small>In the X Window System, a window is a rectangular
area on the screen that lets you view graphic output. Client
applications can display overlapping and nested windows on
one or more screens that are driven by X servers on one or
more machines. Clients who want to create windows must first
connect their program to the X server by calling
<i>XOpenDisplay</i>. This chapter begins with a discussion
of visual types and window attributes. The chapter continues
with a discussion of the Xlib functions you can use
to:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="28%">
<p><small>Create windows</small></p>
</td>
<td width="61%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="30%">
<p><small>Destroy windows</small></p>
</td>
<td width="59%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="22%">
<p><small>Map windows</small></p>
</td>
<td width="67%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="26%">
<p><small>Unmap windows</small></p>
</td>
<td width="63%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="34%">
<p><small>Configure windows</small></p>
</td>
<td width="55%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="56%">
<p><small>Change window stacking order</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="48%">
<p><small>Change window attributes</small></p>
</td>
<td width="41%">
</td>
</table>
<p><small>This chapter also identifies the window actions
that may generate events.</small></p>
<p><small>Note that it is vital that your application
conform to the established conventions for communicating
with window managers for it to work well with the various
window managers in use (see section 14.1). Toolkits
generally adhere to these conventions for you, relieving you
of the burden. Toolkits also often supersede many functions
in this chapter with versions of their own. For more
information, refer to the documentation for the toolkit that
you are using.</small></p>
<a name="3.1. Visual Types"></a>
<h2>3.1. Visual Types</h2>
<p><small>On some display hardware, it may be possible to
deal with color resources in more than one way. For example,
you may be able to deal with a screen of either 12-bit depth
with arbitrary mapping of pixel to color (pseudo-color) or
24-bit depth with 8 bits of the pixel dedicated to each of
red, green, and blue. These different ways of dealing with
the visual aspects of the screen are called visuals. For
each screen of the display, there may be a list of valid
visual types supported at different depths of the screen.
Because default windows and visual types are defined for
each screen, most simple applications need not deal with
this complexity. Xlib provides macros and functions that
return the default root window, the default depth of the
default root window, and the default visual type (see
sections 2.2.1 and 16.7).</small></p>
<p><small>Xlib uses an opaque <i>Visual</i> structure that
contains information about the possible color mapping. The
visual utility functions (see section 16.7) use an
<i>XVisualInfo</i> structure to return this information to
an application. The members of this structure pertinent to
this discussion are class, red_mask, green_mask, blue_mask,
bits_per_rgb, and colormap_size. The class member specifies
one of the possible visual classes of the screen and can be
<i>StaticGray</i>, <i>StaticColor</i>, <i>TrueColor</i>,
<i>GrayScale</i>, <i>PseudoColor</i>, or
<i>DirectColor</i>.</small></p>
<p><small>The following concepts may serve to make the
explanation of visual types clearer. The screen can be color
or grayscale, can have a colormap that is writable or
read-only, and can also have a colormap whose indices are
decomposed into separate RGB pieces, provided one is not on
a grayscale screen. This leads to the following
diagram:</small></p>
<p align=center><small><img src="grohtml-143923.png"></small></p>
<p><small>Conceptually, as each pixel is read out of video
memory for display on the screen, it goes through a look-up
stage by indexing into a colormap. Colormaps can be
manipulated arbitrarily on some hardware, in limited ways on
other hardware, and not at all on other hardware. The visual
types affect the colormap and the RGB values in the
following ways:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>For <i>PseudoColor</i>, a pixel value indexes a
colormap to produce independent RGB values, and the RGB
values can be changed dynamically.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>GrayScale</i> is treated the same way as
<i>PseudoColor</i> except that the primary that drives the
screen is undefined. Thus, the client should always store
the same value for red, green, and blue in the
colormaps.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>For <i>DirectColor</i>, a pixel value is
decomposed into separate RGB subfields, and each subfield
separately indexes the colormap for the corresponding value.
The RGB values can be changed dynamically.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>TrueColor</i> is treated the same way as
<i>DirectColor</i> except that the colormap has predefined,
read-only RGB values. These RGB values are server dependent
but provide linear or near-linear ramps in each
primary.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>StaticColor</i> is treated the same way as
<i>PseudoColor</i> except that the colormap has predefined,
read-only, server-dependent RGB values.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>StaticGray</i> is treated the same way as
<i>StaticColor</i> except that the RGB values are equal for
any single pixel value, thus resulting in shades of gray.
<i>StaticGray</i> with a two-entry colormap can be thought
of as monochrome.</small></p>
</td>
</table>
<p><small>The red_mask, green_mask, and blue_mask members
are only defined for <i>DirectColor</i> and
<i>TrueColor</i>. Each has one contiguous set of bits with
no intersections. The bits_per_rgb member specifies the log
base 2 of the number of distinct color values (individually)
of red, green, and blue. Actual RGB values are unsigned
16-bit numbers. The colormap_size member defines the number
of available colormap entries in a newly created colormap.
For <i>DirectColor</i> and <i>TrueColor</i>, this is the
size of an individual pixel subfield.</small></p>
<p><small>To obtain the visual ID from a <i>Visual</i>, use
<i>XVisualIDFromVisual</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>VisualID XVisualIDFromVisual(<i>visual</i>)
Visual *<i>visual</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>visual</i></small></p>
</td>
<td width="8%"></td>
<td width="52%">
<p><small>Specifies the visual type.</small></p>
</td>
<td width="27%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XVisualIDFromVisual</i> function returns
the visual ID for the specified visual type.</small></p>
<a name="3.2. Window Attributes"></a>
<h2>3.2. Window Attributes</h2>
<p><small>All <i>InputOutput</i> windows have a border
width of zero or more pixels, an optional background, an
event suppression mask (which suppresses propagation of
events from children), and a property list (see section
4.3). The window border and background can be a solid color
or a pattern, called a tile. All windows except the root
have a parent and are clipped by their parent. If a window
is stacked on top of another window, it obscures that other
window for the purpose of input. If a window has a
background (almost all do), it obscures the other window for
purposes of output. Attempts to output to the obscured area
do nothing, and no input events (for example, pointer
motion) are generated for the obscured area.</small></p>
<p><small>Windows also have associated property lists (see
section 4.3).</small></p>
<p><small>Both <i>InputOutput</i> and <i>InputOnly</i>
windows have the following common attributes, which are the
only attributes of an <i>InputOnly</i> window:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="22%">
<p><small>win-gravity</small></p>
</td>
<td width="67%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="20%">
<p><small>event-mask</small></p>
</td>
<td width="69%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>do-not-propagate-mask</small></p>
</td>
<td width="47%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="34%">
<p><small>override-redirect</small></p>
</td>
<td width="55%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="12%">
<p><small>cursor</small></p>
</td>
<td width="77%">
</td>
</table>
<p><small>If you specify any other attributes for an
<i>InputOnly</i> window, a <i>BadMatch</i> error
results.</small></p>
<p><small><i>InputOnly</i> windows are used for controlling
input events in situations where <i>InputOutput</i> windows
are unnecessary. <i>InputOnly</i> windows are invisible; can
only be used to control such things as cursors, input event
generation, and grabbing; and cannot be used in any graphics
requests. Note that <i>InputOnly</i> windows cannot have
<i>InputOutput</i> windows as inferiors.</small></p>
<p><small>Windows have borders of a programmable width and
pattern as well as a background pattern or tile. Pixel
values can be used for solid colors. The background and
border pixmaps can be destroyed immediately after creating
the window if no further explicit references to them are to
be made. The pattern can either be relative to the parent or
absolute. If <i>ParentRelative</i>, the parent’s
background is used.</small></p>
<p><small>When windows are first created, they are not
visible (not mapped) on the screen. Any output to a window
that is not visible on the screen and that does not have
backing store will be discarded. An application may wish to
create a window long before it is mapped to the screen. When
a window is eventually mapped to the screen (using
<i>XMapWindow</i>), the X server generates an <i>Expose</i>
event for the window if backing store has not been
maintained.</small></p>
<p><small>A window manager can override your choice of
size, border width, and position for a top-level window.
Your program must be prepared to use the actual size and
position of the top window. It is not acceptable for a
client application to resize itself unless in direct
response to a human command to do so. Instead, either your
program should use the space given to it, or if the space is
too small for any useful work, your program might ask the
user to resize the window. The border of your top-level
window is considered fair game for window
managers.</small></p>
<p><small>To set an attribute of a window, set the
appropriate member of the <i>XSetWindowAttributes</i>
structure and OR in the corresponding value bitmask in your
subsequent calls to <i>XCreateWindow</i> and
<i>XChangeWindowAttributes</i>, or use one of the other
convenience functions that set the appropriate attribute.
The symbols for the value mask bits and the
<i>XSetWindowAttributes</i> structure are:</small></p>
<p><small>__ │</small></p>
<p><small>/* Window attribute value mask bits
*/</small></p>
<p align=center><small><img src="grohtml-143924.png"></small></p>
<pre><small>/* Values */
typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Pixmap background_pixmap;/* background, None, or
ParentRelative */</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long background_pixel;/* background
pixel */</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Pixmap border_pixmap;</small></p>
</td>
<td width="40%">
<p><small>/* border of the window or CopyFromParent
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long border_pixel;/* border pixel value
*/</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int bit_gravity;</small></p>
</td>
<td width="40%">
<p><small>/* one of bit gravity values */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int win_gravity;</small></p>
</td>
<td width="40%">
<p><small>/* one of the window gravity values
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int backing_store;</small></p>
</td>
<td width="40%">
<p><small>/* NotUseful, WhenMapped, Always */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long backing_planes;/* planes to be
preserved if possible */</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long backing_pixel;/* value to use in
restoring planes */</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool save_under;</small></p>
</td>
<td width="40%">
<p><small>/* should bits under be saved? (popups)
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>long event_mask;</small></p>
</td>
<td width="40%">
<p><small>/* set of events that should be saved
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>long do_not_propagate_mask;/* set of events that
should not propagate */</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool override_redirect;</small></p>
</td>
<td width="40%">
<p><small>/* boolean value for override_redirect
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Colormap colormap;</small></p>
</td>
<td width="40%">
<p><small>/* color map to be associated with window
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Cursor cursor;</small></p>
</td>
<td width="40%">
<p><small>/* cursor to be displayed (or None)
*/</small></p>
</td>
</table>
<p><small>} XSetWindowAttributes;</small></p>
<p><small>│__</small></p>
<p><small>The following lists the defaults for each window
attribute and indicates whether the attribute is applicable
to <i>InputOutput</i> and <i>InputOnly</i>
windows:</small></p>
<p align=center><small><img src="grohtml-143925.png"></small></p>
<a name="3.2.1. Background Attribute"></a>
<h2>3.2.1. Background Attribute</h2>
<p><small>Only <i>InputOutput</i> windows can have a
background. You can set the background of an
<i>InputOutput</i> window by using a pixel or a
pixmap.</small></p>
<p><small>The background-pixmap attribute of a window
specifies the pixmap to be used for a window’s
background. This pixmap can be of any size, although some
sizes may be faster than others. The background-pixel
attribute of a window specifies a pixel value used to paint
a window’s background in a single color.</small></p>
<p><small>You can set the background-pixmap to a pixmap,
<i>None</i> (default), or <i>ParentRelative</i>. You can set
the background-pixel of a window to any pixel value (no
default). If you specify a background-pixel, it overrides
either the default background-pixmap or any value you may
have set in the background-pixmap. A pixmap of an undefined
size that is filled with the background-pixel is used for
the background. Range checking is not performed on the
background pixel; it simply is truncated to the appropriate
number of bits.</small></p>
<p><small>If you set the background-pixmap, it overrides
the default. The background-pixmap and the window must have
the same depth, or a <i>BadMatch</i> error results. If you
set background-pixmap to <i>None</i>, the window has no
defined background. If you set the background-pixmap to
<i>ParentRelative</i>:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The parent window’s background-pixmap is
used. The child window, however, must have the same depth as
its parent, or a <i>BadMatch</i> error results.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If the parent window has a background-pixmap of
<i>None</i>, the window also has a background-pixmap of
<i>None</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>A copy of the parent window’s
background-pixmap is not made. The parent’s
background-pixmap is examined each time the child
window’s background-pixmap is required.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The background tile origin always aligns with the
parent window’s background tile origin. If the
background-pixmap is not <i>ParentRelative</i>, the
background tile origin is the child window’s
origin.</small></p>
</td>
</table>
<p><small>Setting a new background, whether by setting
background-pixmap or background-pixel, overrides any
previous background. The background-pixmap can be freed
immediately if no further explicit reference is made to it
(the X server will keep a copy to use when needed). If you
later draw into the pixmap used for the background, what
happens is undefined because the X implementation is free to
make a copy of the pixmap or to use the same
pixmap.</small></p>
<p><small>When no valid contents are available for regions
of a window and either the regions are visible or the server
is maintaining backing store, the server automatically tiles
the regions with the window’s background unless the
window has a background of <i>None</i>. If the background is
<i>None</i>, the previous screen contents from other windows
of the same depth as the window are simply left in place as
long as the contents come from the parent of the window or
an inferior of the parent. Otherwise, the initial contents
of the exposed regions are undefined. <i>Expose</i> events
are then generated for the regions, even if the
background-pixmap is <i>None</i> (see section
10.9).</small></p>
<a name="3.2.2. Border Attribute"></a>
<h2>3.2.2. Border Attribute</h2>
<p><small>Only <i>InputOutput</i> windows can have a
border. You can set the border of an <i>InputOutput</i>
window by using a pixel or a pixmap.</small></p>
<p><small>The border-pixmap attribute of a window specifies
the pixmap to be used for a window’s border. The
border-pixel attribute of a window specifies a pixmap of
undefined size filled with that pixel be used for a
window’s border. Range checking is not performed on
the background pixel; it simply is truncated to the
appropriate number of bits. The border tile origin is always
the same as the background tile origin.</small></p>
<p><small>You can also set the border-pixmap to a pixmap of
any size (some may be faster than others) or to
<i>CopyFromParent</i> (default). You can set the
border-pixel to any pixel value (no default).</small></p>
<p><small>If you set a border-pixmap, it overrides the
default. The border-pixmap and the window must have the same
depth, or a <i>BadMatch</i> error results. If you set the
border-pixmap to <i>CopyFromParent</i>, the parent
window’s border-pixmap is copied. Subsequent changes
to the parent window’s border attribute do not affect
the child window. However, the child window must have the
same depth as the parent window, or a <i>BadMatch</i> error
results.</small></p>
<p><small>The border-pixmap can be freed immediately if no
further explicit reference is made to it. If you later draw
into the pixmap used for the border, what happens is
undefined because the X implementation is free either to
make a copy of the pixmap or to use the same pixmap. If you
specify a border-pixel, it overrides either the default
border-pixmap or any value you may have set in the
border-pixmap. All pixels in the window’s border will
be set to the border-pixel. Setting a new border, whether by
setting border-pixel or by setting border-pixmap, overrides
any previous border.</small></p>
<p><small>Output to a window is always clipped to the
inside of the window. Therefore, graphics operations never
affect the window border.</small></p>
<a name="3.2.3. Gravity Attributes"></a>
<h2>3.2.3. Gravity Attributes</h2>
<p><small>The bit gravity of a window defines which region
of the window should be retained when an <i>InputOutput</i>
window is resized. The default value for the bit-gravity
attribute is <i>ForgetGravity</i>. The window gravity of a
window allows you to define how the <i>InputOutput</i> or
<i>InputOnly</i> window should be repositioned if its parent
is resized. The default value for the win-gravity attribute
is <i>NorthWestGravity</i>.</small></p>
<p><small>If the inside width or height of a window is not
changed and if the window is moved or its border is changed,
then the contents of the window are not lost but move with
the window. Changing the inside width or height of the
window causes its contents to be moved or lost (depending on
the bit-gravity of the window) and causes children to be
reconfigured (depending on their win-gravity). For a change
of width and height, the (x, y) pairs are
defined:</small></p>
<p align=center><small><img src="grohtml-143926.png"></small></p>
<p><small>When a window with one of these bit-gravity
values is resized, the corresponding pair defines the change
in position of each pixel in the window. When a window with
one of these win-gravities has its parent window resized,
the corresponding pair defines the change in position of the
window within the parent. When a window is so repositioned,
a <i>GravityNotify</i> event is generated (see section
10.10.5).</small></p>
<p><small>A bit-gravity of <i>StaticGravity</i> indicates
that the contents or origin should not move relative to the
origin of the root window. If the change in size of the
window is coupled with a change in position (x, y), then for
bit-gravity the change in position of each pixel is
(−x, −y), and for win-gravity the change in
position of a child when its parent is so resized is
(−x, −y). Note that <i>StaticGravity</i> still
only takes effect when the width or height of the window is
changed, not when the window is moved.</small></p>
<p><small>A bit-gravity of <i>ForgetGravity</i> indicates
that the window’s contents are always discarded after
a size change, even if a backing store or save under has
been requested. The window is tiled with its background and
zero or more <i>Expose</i> events are generated. If no
background is defined, the existing screen contents are not
altered. Some X servers may also ignore the specified
bit-gravity and always generate <i>Expose</i>
events.</small></p>
<p><small>The contents and borders of inferiors are not
affected by their parent’s bit-gravity. A server is
permitted to ignore the specified bit-gravity and use
<i>Forget</i> instead.</small></p>
<p><small>A win-gravity of <i>UnmapGravity</i> is like
<i>NorthWestGravity</i> (the window is not moved), except
the child is also unmapped when the parent is resized, and
an <i>UnmapNotify</i> event is generated.</small></p>
<a name="3.2.4. Backing Store Attribute"></a>
<h2>3.2.4. Backing Store Attribute</h2>
<p><small>Some implementations of the X server may choose
to maintain the contents of <i>InputOutput</i> windows. If
the X server maintains the contents of a window, the
off-screen saved pixels are known as backing store. The
backing store advises the X server on what to do with the
contents of a window. The backing-store attribute can be set
to <i>NotUseful</i> (default), <i>WhenMapped</i>, or
<i>Always</i>.</small></p>
<p><small>A backing-store attribute of <i>NotUseful</i>
advises the X server that maintaining contents is
unnecessary, although some X implementations may still
choose to maintain contents and, therefore, not generate
<i>Expose</i> events. A backing-store attribute of
<i>WhenMapped</i> advises the X server that maintaining
contents of obscured regions when the window is mapped would
be beneficial. In this case, the server may generate an
<i>Expose</i> event when the window is created. A
backing-store attribute of <i>Always</i> advises the X
server that maintaining contents even when the window is
unmapped would be beneficial. Even if the window is larger
than its parent, this is a request to the X server to
maintain complete contents, not just the region within the
parent window boundaries. While the X server maintains the
window’s contents, <i>Expose</i> events normally are
not generated, but the X server may stop maintaining
contents at any time.</small></p>
<p><small>When the contents of obscured regions of a window
are being maintained, regions obscured by noninferior
windows are included in the destination of graphics requests
(and source, when the window is the source). However,
regions obscured by inferior windows are not
included.</small></p>
<a name="3.2.5. Save Under Flag"></a>
<h2>3.2.5. Save Under Flag</h2>
<p><small>Some server implementations may preserve contents
of <i>InputOutput</i> windows under other <i>InputOutput</i>
windows. This is not the same as preserving the contents of
a window for you. You may get better visual appeal if
transient windows (for example, pop-up menus) request that
the system preserve the screen contents under them, so the
temporarily obscured applications do not have to
repaint.</small></p>
<p><small>You can set the save-under flag to <i>True</i> or
<i>False</i> (default). If save-under is <i>True</i>, the X
server is advised that, when this window is mapped, saving
the contents of windows it obscures would be
beneficial.</small></p>
<a name="3.2.6. Backing Planes and Backing Pixel Attributes"></a>
<h2>3.2.6. Backing Planes and Backing Pixel Attributes</h2>
<p><small>You can set backing planes to indicate (with bits
set to 1) which bit planes of an <i>InputOutput</i> window
hold dynamic data that must be preserved in backing store
and during save unders. The default value for the
backing-planes attribute is all bits set to 1. You can set
backing pixel to specify what bits to use in planes not
covered by backing planes. The default value for the
backing-pixel attribute is all bits set to 0. The X server
is free to save only the specified bit planes in the backing
store or the save under and is free to regenerate the
remaining planes with the specified pixel value. Any
extraneous bits in these values (that is, those bits beyond
the specified depth of the window) may be simply ignored. If
you request backing store or save unders, you should use
these members to minimize the amount of off-screen memory
required to store your window.</small></p>
<a name="3.2.7. Event Mask and Do Not Propagate Mask Attributes"></a>
<h2>3.2.7. Event Mask and Do Not Propagate Mask Attributes</h2>
<p><small>The event mask defines which events the client is
interested in for this <i>InputOutput</i> or
<i>InputOnly</i> window (or, for some event types, inferiors
of this window). The event mask is the bitwise inclusive OR
of zero or more of the valid event mask bits. You can
specify that no maskable events are reported by setting
<i>NoEventMask</i> (default).</small></p>
<p><small>The do-not-propagate-mask attribute defines which
events should not be propagated to ancestor windows when no
client has the event type selected in this
<i>InputOutput</i> or <i>InputOnly</i> window. The
do-not-propagate-mask is the bitwise inclusive OR of zero or
more of the following masks: <i>KeyPress</i>,
<i>KeyRelease</i>, <i>ButtonPress</i>, <i>ButtonRelease</i>,
<i>PointerMotion</i>, <i>Button1Motion</i>,
<i>Button2Motion</i>, <i>Button3Motion</i>,
<i>Button4Motion</i>, <i>Button5Motion</i>, and
<i>ButtonMotion</i>. You can specify that all events are
propagated by setting <i>NoEventMask</i>
(default).</small></p>
<a name="3.2.8. Override Redirect Flag"></a>
<h2>3.2.8. Override Redirect Flag</h2>
<p><small>To control window placement or to add decoration,
a window manager often needs to intercept (redirect) any map
or configure request. Pop-up windows, however, often need to
be mapped without a window manager getting in the way. To
control whether an <i>InputOutput</i> or <i>InputOnly</i>
window is to ignore these structure control facilities, use
the override-redirect flag.</small></p>
<p><small>The override-redirect flag specifies whether map
and configure requests on this window should override a
<i>SubstructureRedirectMask</i> on the parent. You can set
the override-redirect flag to <i>True</i> or <i>False</i>
(default). Window managers use this information to avoid
tampering with pop-up windows (see also chapter
14).</small></p>
<a name="3.2.9. Colormap Attribute"></a>
<h2>3.2.9. Colormap Attribute</h2>
<p><small>The colormap attribute specifies which colormap
best reflects the true colors of the <i>InputOutput</i>
window. The colormap must have the same visual type as the
window, or a <i>BadMatch</i> error results. X servers
capable of supporting multiple hardware colormaps can use
this information, and window managers can use it for calls
to <i>XInstallColormap</i>. You can set the colormap
attribute to a colormap or to <i>CopyFromParent</i>
(default).</small></p>
<p><small>If you set the colormap to <i>CopyFromParent</i>,
the parent window’s colormap is copied and used by its
child. However, the child window must have the same visual
type as the parent, or a <i>BadMatch</i> error results. The
parent window must not have a colormap of <i>None</i>, or a
<i>BadMatch</i> error results. The colormap is copied by
sharing the colormap object between the child and parent,
not by making a complete copy of the colormap contents.
Subsequent changes to the parent window’s colormap
attribute do not affect the child window.</small></p>
<a name="3.2.10. Cursor Attribute"></a>
<h2>3.2.10. Cursor Attribute</h2>
<p><small>The cursor attribute specifies which cursor is to
be used when the pointer is in the <i>InputOutput</i> or
<i>InputOnly</i> window. You can set the cursor to a cursor
or <i>None</i> (default).</small></p>
<p><small>If you set the cursor to <i>None</i>, the
parent’s cursor is used when the pointer is in the
<i>InputOutput</i> or <i>InputOnly</i> window, and any
change in the parent’s cursor will cause an immediate
change in the displayed cursor. By calling
<i>XFreeCursor</i>, the cursor can be freed immediately as
long as no further explicit reference to it is
made.</small></p>
<a name="3.3. Creating Windows"></a>
<h2>3.3. Creating Windows</h2>
<p><small>Xlib provides basic ways for creating windows,
and toolkits often supply higher-level functions
specifically for creating and placing top-level windows,
which are discussed in the appropriate toolkit
documentation. If you do not use a toolkit, however, you
must provide some standard information or hints for the
window manager by using the Xlib inter-client communication
functions (see chapter 14).</small></p>
<p><small>If you use Xlib to create your own top-level
windows (direct children of the root window), you must
observe the following rules so that all applications
interact reasonably across the different styles of window
management:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>You must never fight with the window manager for
the size or placement of your top-level window.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>You must be able to deal with whatever size
window you get, even if this means that your application
just prints a message like ‘‘Please make me
bigger’’ in its window.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>You should only attempt to resize or move
top-level windows in direct response to a user request. If a
request to change the size of a top-level window fails, you
must be prepared to live with what you get. You are free to
resize or move the children of top-level windows as
necessary. (Toolkits often have facilities for automatic
relayout.)</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If you do not use a toolkit that automatically
sets standard window properties, you should set these
properties for top-level windows before mapping
them.</small></p>
</td>
</table>
<p><small>For further information, see chapter 14 and the
<i>Inter-Client Communication Conventions
Manual</i>.</small></p>
<p><small><i>XCreateWindow</i> is the more general function
that allows you to set specific window attributes when you
create a window. <i>XCreateSimpleWindow</i> creates a window
that inherits its attributes from its parent
window.</small></p>
<p><small>The X server acts as if <i>InputOnly</i> windows
do not exist for the purposes of graphics requests, exposure
processing, and <i>VisibilityNotify</i> events. An
<i>InputOnly</i> window cannot be used as a drawable (that
is, as a source or destination for graphics requests).
<i>InputOnly</i> and <i>InputOutput</i> windows act
identically in other respects (properties, grabs, input
control, and so on). Extension packages can define other
classes of windows.</small></p>
<p><small>To create an unmapped window and set its window
attributes, use <i>XCreateWindow</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Window XCreateWindow(<i>display</i>, <i>parent</i>, <i>x</i>, <i>y</i>, <i>width</i>, <i>height</i>, <i>border_width</i>, <i>depth</i>,
<i> class</i>, <i>visual</i>, <i>valuemask</i>, <i>attributes</i>)
Display *<i>display</i>;
Window <i>parent</i>;
int <i>x</i>, <i>y</i>;
unsigned int <i>width</i>, <i>height</i>;
unsigned int <i>border_width</i>;
int <i>depth</i>;
unsigned int <i>class</i>;
Visual *<i>visual</i>;
unsigned long <i>valuemask</i>;
XSetWindowAttributes *<i>attributes</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>parent</i></small></p>
</td>
<td width="8%"></td>
<td width="56%">
<p><small>Specifies the parent window.</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which are the
top-left outside corner of the created window’s
borders and are relative to the inside of the parent
window’s borders.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the width and height, which are the
created window’s inside dimensions and do not include
the created window’s borders. The dimensions must be
nonzero, or a <i>BadValue</i> error results.</small></p>
</td>
</table>
<p><small><i>border_width</i> Specifies the width of the
created window’s border in pixels.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>depth</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the window’s depth. A depth of
<i>CopyFromParent</i> means the depth is taken from the
parent.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>class</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the created window’s class. You
can pass <i>InputOutput</i>, <i>InputOnly</i>, or
<i>CopyFromParent</i>. A class of <i>CopyFromParent</i>
means the class is taken from the parent.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>visual</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the visual type. A visual of
<i>CopyFromParent</i> means the visual type is taken from
the parent.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>valuemask</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>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.</small></p>
</td>
</table>
<p><small><i>attributes</i> 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.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XCreateWindow</i> 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 <i>CreateNotify</i> event. The created window
is placed on top in the stacking order with respect to
siblings.</small></p>
<p><small>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.</small></p>
<p><small>The border_width for an <i>InputOnly</i> window
must be zero, or a <i>BadMatch</i> error results. For class
<i>InputOutput</i>, the visual type and depth must be a
combination supported for the screen, or a <i>BadMatch</i>
error results. The depth need not be the same as the parent,
but the parent must not be a window of class
<i>InputOnly</i>, or a <i>BadMatch</i> error results. For an
<i>InputOnly</i> window, the depth must be zero, and the
visual must be one supported by the screen. If either
condition is not met, a <i>BadMatch</i> error results. The
parent window, however, may have any depth and class. If you
specify any invalid window attribute for a window, a
<i>BadMatch</i> error results.</small></p>
<p><small>The created window is not yet displayed (mapped)
on the user’s display. To display the window, call
<i>XMapWindow</i>. The new window initially uses the same
cursor as its parent. A new cursor can be defined for the
new window by calling <i>XDefineCursor</i>. 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.</small></p>
<p><small><i>XCreateWindow</i> can generate
<i>BadAlloc</i>, <i>BadColor</i>, <i>BadCursor</i>,
<i>BadMatch</i>, <i>BadPixmap</i>, <i>BadValue</i>, and
<i>BadWindow</i> errors.</small></p>
<p><small>To create an unmapped <i>InputOutput</i>
subwindow of a given parent window, use
<i>XCreateSimpleWindow</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Window XCreateSimpleWindow(<i>display</i>, <i>parent</i>, <i>x</i>, <i>y</i>, <i>width</i>, <i>height</i>, <i>border_width</i>,
<i> border</i>, <i>background</i>)
Display *<i>display</i>;
Window <i>parent</i>;
int <i>x</i>, <i>y</i>;
unsigned int <i>width</i>, <i>height</i>;
unsigned int <i>border_width</i>;
unsigned long <i>border</i>;
unsigned long <i>background</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>parent</i></small></p>
</td>
<td width="8%"></td>
<td width="56%">
<p><small>Specifies the parent window.</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which are the
top-left outside corner of the new window’s borders
and are relative to the inside of the parent window’s
borders.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the width and height, which are the
created window’s inside dimensions and do not include
the created window’s borders. The dimensions must be
nonzero, or a <i>BadValue</i> error results.</small></p>
</td>
</table>
<p><small><i>border_width</i> Specifies the width of the
created window’s border in pixels.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>border</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the border pixel value of the
window.</small></p>
</td>
</table>
<p><small><i>background</i> Specifies the background pixel
value of the window.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XCreateSimpleWindow</i> function creates
an unmapped <i>InputOutput</i> subwindow for a specified
parent window, returns the window ID of the created window,
and causes the X server to generate a <i>CreateNotify</i>
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. The
border_width for an <i>InputOnly</i> window must be zero, or
a <i>BadMatch</i> error results. <i>XCreateSimpleWindow</i>
inherits its depth, class, and visual from its parent. All
other window attributes, except background and border, have
their default values.</small></p>
<p><small><i>XCreateSimpleWindow</i> can generate
<i>BadAlloc</i>, <i>BadMatch</i>, <i>BadValue</i>, and
<i>BadWindow</i> errors.</small></p>
<a name="3.4. Destroying Windows"></a>
<h2>3.4. Destroying Windows</h2>
<p><small>Xlib provides functions that you can use to
destroy a window or destroy all subwindows of a
window.</small></p>
<p><small>To destroy a window and all of its subwindows,
use <i>XDestroyWindow</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XDestroyWindow(<i>display</i>, <i>w</i>)
Display *<i>display</i>;
Window <i>w</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XDestroyWindow</i> function destroys the
specified window as well as all of its subwindows and causes
the X server to generate a <i>DestroyNotify</i> 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
<i>DestroyNotify</i> events is such that for any given
window being destroyed, <i>DestroyNotify</i> 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 <i>Expose</i>
events on other windows that were obscured by the window
being destroyed.</small></p>
<p><small><i>XDestroyWindow</i> can generate a
<i>BadWindow</i> error.</small></p>
<p><small>To destroy all subwindows of a specified window,
use <i>XDestroySubwindows</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XDestroySubwindows(<i>display</i>, <i>w</i>)
Display *<i>display</i>;
Window <i>w</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XDestroySubwindows</i> function destroys
all inferior windows of the specified window, in
bottom-to-top stacking order. It causes the X server to
generate a <i>DestroyNotify</i> event for each window. If
any mapped subwindows were actually destroyed,
<i>XDestroySubwindows</i> causes the X server to generate
<i>Expose</i> 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.</small></p>
<p><small><i>XDestroySubwindows</i> can generate a
<i>BadWindow</i> error.</small></p>
<a name="3.5. Mapping Windows"></a>
<h2>3.5. Mapping Windows</h2>
<p><small>A window is considered mapped if an
<i>XMapWindow</i> call has been made on it. It may not be
visible on the screen for one of the following
reasons:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It is obscured by another opaque
window.</small></p>
</td>
<td width="9%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="70%">
<p><small>One of its ancestors is not mapped.</small></p>
</td>
<td width="19%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="76%">
<p><small>It is entirely clipped by an
ancestor.</small></p>
</td>
<td width="13%">
</td>
</table>
<p><small><i>Expose</i> events are generated for the window
when part or all of it becomes visible on the screen. A
client receives the <i>Expose</i> events only if it has
asked for them. Windows retain their position in the
stacking order when they are unmapped.</small></p>
<p><small>A window manager may want to control the
placement of subwindows. If <i>SubstructureRedirectMask</i>
has been selected by a window manager on a parent window
(usually a root window), a map request initiated by other
clients on a child window is not performed, and the window
manager is sent a <i>MapRequest</i> event. However, if the
override-redirect flag on the child had been set to
<i>True</i> (usually only on pop-up menus), the map request
is performed.</small></p>
<p><small>A tiling window manager might decide to
reposition and resize other clients’ windows and then
decide to map the window to its final location. A window
manager that wants to provide decoration might reparent the
child into a frame first. For further information, see
sections 3.2.8 and 10.10. Only a single client at a time can
select for <i>SubstructureRedirectMask</i>.</small></p>
<p><small>Similarly, a single client can select for
<i>ResizeRedirectMask</i> on a parent window. Then, any
attempt to resize the window by another client is
suppressed, and the client receives a <i>ResizeRequest</i>
event.</small></p>
<p><small>To map a given window, use
<i>XMapWindow</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XMapWindow(<i>display</i>, <i>w</i>)
Display *<i>display</i>;
Window <i>w</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XMapWindow</i> function maps the window
and all of its subwindows that have had map requests.
Mapping a window that has an unmapped ancestor does not
display the window but marks it as eligible for display when
the ancestor becomes mapped. Such a window is called
unviewable. When all its ancestors are mapped, the window
becomes viewable and will be visible on the screen if it is
not obscured by another window. This function has no effect
if the window is already mapped.</small></p>
<p><small>If the override-redirect of the window is
<i>False</i> and if some other client has selected
<i>SubstructureRedirectMask</i> on the parent window, then
the X server generates a <i>MapRequest</i> event, and the
<i>XMapWindow</i> function does not map the window.
Otherwise, the window is mapped, and the X server generates
a <i>MapNotify</i> event.</small></p>
<p><small>If the window becomes viewable and no earlier
contents for it are remembered, the X server tiles the
window with its background. If the window’s background
is undefined, the existing screen contents are not altered,
and the X server generates zero or more <i>Expose</i>
events. If backing-store was maintained while the window was
unmapped, no <i>Expose</i> events are generated. If
backing-store will now be maintained, a full-window exposure
is always generated. Otherwise, only visible regions may be
reported. Similar tiling and exposure take place for any
newly viewable inferiors.</small></p>
<p><small>If the window is an <i>InputOutput</i> window,
<i>XMapWindow</i> generates <i>Expose</i> events on each
<i>InputOutput</i> window that it causes to be displayed. If
the client maps and paints the window and if the client
begins processing events, the window is painted twice. To
avoid this, first ask for <i>Expose</i> events and then map
the window, so the client processes input events as usual.
The event list will include <i>Expose</i> for each window
that has appeared on the screen. The client’s normal
response to an <i>Expose</i> event should be to repaint the
window. This method usually leads to simpler programs and to
proper interaction with window managers.</small></p>
<p><small><i>XMapWindow</i> can generate a <i>BadWindow</i>
error.</small></p>
<p><small>To map and raise a window, use
<i>XMapRaised</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XMapRaised(<i>display</i>, <i>w</i>)
Display *<i>display</i>;
Window <i>w</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XMapRaised</i> function essentially is
similar to <i>XMapWindow</i> in that it maps the window and
all of its subwindows that have had map requests. However,
it also raises the specified window to the top of the stack.
For additional information, see
<i>XMapWindow</i>.</small></p>
<p><small><i>XMapRaised</i> can generate multiple
<i>BadWindow</i> errors.</small></p>
<p><small>To map all subwindows for a specified window, use
<i>XMapSubwindows</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XMapSubwindows(<i>display</i>, <i>w</i>)
Display *<i>display</i>;
Window <i>w</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XMapSubwindows</i> function maps all
subwindows for a specified window in top-to-bottom stacking
order. The X server generates <i>Expose</i> events on each
newly displayed window. This may be much more efficient than
mapping many windows one at a time because the server needs
to perform much of the work only once, for all of the
windows, rather than for each window.</small></p>
<p><small><i>XMapSubwindows</i> can generate a
<i>BadWindow</i> error.</small></p>
<a name="3.6. Unmapping Windows"></a>
<h2>3.6. Unmapping Windows</h2>
<p><small>Xlib provides functions that you can use to unmap
a window or all subwindows.</small></p>
<p><small>To unmap a window, use
<i>XUnmapWindow</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XUnmapWindow(<i>display</i>, <i>w</i>)
Display *<i>display</i>;
Window <i>w</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XUnmapWindow</i> function unmaps the
specified window and causes the X server to generate an
<i>UnmapNotify</i> event. If the specified window is already
unmapped, <i>XUnmapWindow</i> has no effect. Normal exposure
processing on formerly obscured windows is performed. Any
child window will no longer be visible until another map
call is made on the parent. In other words, the subwindows
are still mapped but are not visible until the parent is
mapped. Unmapping a window will generate <i>Expose</i>
events on windows that were formerly obscured by
it.</small></p>
<p><small><i>XUnmapWindow</i> can generate a
<i>BadWindow</i> error.</small></p>
<p><small>To unmap all subwindows for a specified window,
use <i>XUnmapSubwindows</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XUnmapSubwindows(<i>display</i>, <i>w</i>)
Display *<i>display</i>;
Window <i>w</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XUnmapSubwindows</i> function unmaps all
subwindows for the specified window in bottom-to-top
stacking order. It causes the X server to generate an
<i>UnmapNotify</i> event on each subwindow and <i>Expose</i>
events on formerly obscured windows. Using this function is
much more efficient than unmapping multiple windows one at a
time because the server needs to perform much of the work
only once, for all of the windows, rather than for each
window.</small></p>
<p><small><i>XUnmapSubwindows</i> can generate a
<i>BadWindow</i> error.</small></p>
<a name="3.7. Configuring Windows"></a>
<h2>3.7. Configuring Windows</h2>
<p><small>Xlib provides functions that you can use to move
a window, resize a window, move and resize a window, or
change a window’s border width. To change one of these
parameters, set the appropriate member of the
<i>XWindowChanges</i> structure and OR in the corresponding
value mask in subsequent calls to <i>XConfigureWindow</i>.
The symbols for the value mask bits and the
<i>XWindowChanges</i> structure are:</small></p>
<p><small>__ │</small></p>
<p><small>/* Configure window value mask bits
*/</small></p>
<p align=center><small><img src="grohtml-143927.png"></small></p>
<pre><small>/* Values */
typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int x, y;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int width, height;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int border_width;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window sibling;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int stack_mode;</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>} XWindowChanges;</small></p>
<p><small>│__</small></p>
<p><small>The x and y members are used to set the
window’s x and y coordinates, which are relative to
the parent’s origin and indicate the position of the
upper-left outer corner of the window. The width and height
members are used to set the inside size of the window, not
including the border, and must be nonzero, or a
<i>BadValue</i> error results. Attempts to configure a root
window have no effect.</small></p>
<p><small>The border_width member is used to set the width
of the border in pixels. Note that setting just the border
width leaves the outer-left corner of the window in a fixed
position but moves the absolute position of the
window’s origin. If you attempt to set the
border-width attribute of an <i>InputOnly</i> window
nonzero, a <i>BadMatch</i> error results.</small></p>
<p><small>The sibling member is used to set the sibling
window for stacking operations. The stack_mode member is
used to set how the window is to be restacked and can be set
to <i>Above</i>, <i>Below</i>, <i>TopIf</i>,
<i>BottomIf</i>, or <i>Opposite</i>.</small></p>
<p><small>If the override-redirect flag of the window is
<i>False</i> and if some other client has selected
<i>SubstructureRedirectMask</i> on the parent, the X server
generates a <i>ConfigureRequest</i> event, and no further
processing is performed. Otherwise, if some other client has
selected <i>ResizeRedirectMask</i> on the window and the
inside width or height of the window is being changed, a
<i>ResizeRequest</i> event is generated, and the current
inside width and height are used instead. Note that the
override-redirect flag of the window has no effect on
<i>ResizeRedirectMask</i> and that
<i>SubstructureRedirectMask</i> on the parent has precedence
over <i>ResizeRedirectMask</i> on the window.</small></p>
<p><small>When the geometry of the window is changed as
specified, the window is restacked among siblings, and a
<i>ConfigureNotify</i> event is generated if the state of
the window actually changes. <i>GravityNotify</i> events are
generated after <i>ConfigureNotify</i> events. If the inside
width or height of the window has actually changed, children
of the window are affected as specified.</small></p>
<p><small>If a window’s size actually changes, the
window’s subwindows move according to their window
gravity. Depending on the window’s bit gravity, the
contents of the window also may be moved (see section
3.2.3).</small></p>
<p><small>If regions of the window were obscured but now
are not, exposure processing is performed on these formerly
obscured windows, including the window itself and its
inferiors. As a result of increasing the width or height,
exposure processing is also performed on any new regions of
the window and any regions where window contents are
lost.</small></p>
<p><small>The restack check (specifically, the computation
for <i>BottomIf</i>, <i>TopIf</i>, and <i>Opposite</i>) is
performed with respect to the window’s final size and
position (as controlled by the other arguments of the
request), not its initial position. If a sibling is
specified without a stack_mode, a <i>BadMatch</i> error
results.</small></p>
<p><small>If a sibling and a stack_mode are specified, the
window is restacked as follows:</small></p>
<p align=center><small><img src="grohtml-143928.png"></small></p>
<p><small>If a stack_mode is specified but no sibling is
specified, the window is restacked as follows:</small></p>
<p align=center><small><img src="grohtml-143929.png"></small></p>
<p><small>Attempts to configure a root window have no
effect.</small></p>
<p><small>To configure a window’s size, location,
stacking, or border, use
<i>XConfigureWindow</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XConfigureWindow(<i>display</i>, <i>w</i>, <i>value_mask</i>, <i>values</i>)
Display *<i>display</i>;
Window <i>w</i>;
unsigned int <i>value_mask</i>;
XWindowChanges *<i>values</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the window to be
reconfigured.</small></p>
</td>
<td width="0%">
</td>
</table>
<p><small><i>value_mask</i> 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.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>values</i></small></p>
</td>
<td width="8%"></td>
<td width="78%">
<p><small>Specifies the <i>XWindowChanges</i>
structure.</small></p>
</td>
<td width="1%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XConfigureWindow</i> function uses the
values specified in the <i>XWindowChanges</i> structure to
reconfigure a window’s size, position, border, and
stacking order. Values not specified are taken from the
existing geometry of the window.</small></p>
<p><small>If a sibling is specified without a stack_mode or
if the window is not actually a sibling, a <i>BadMatch</i>
error results. Note that the computations for
<i>BottomIf</i>, <i>TopIf</i>, and <i>Opposite</i> are
performed with respect to the window’s final geometry
(as controlled by the other arguments passed to
<i>XConfigureWindow</i>), 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).</small></p>
<p><small><i>XConfigureWindow</i> can generate
<i>BadMatch</i>, <i>BadValue</i>, and <i>BadWindow</i>
errors.</small></p>
<p><small>To move a window without changing its size, use
<i>XMoveWindow</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XMoveWindow(<i>display</i>, <i>w</i>, <i>x</i>, <i>y</i>)
Display *<i>display</i>;
Window <i>w</i>;
int <i>x</i>, <i>y</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="66%">
<p><small>Specifies the window to be moved.</small></p>
</td>
<td width="13%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which define the
new location of the top-left pixel of the window’s
border or the window itself if it has no border.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XMoveWindow</i> function moves the
specified window to the specified x and y coordinates, but
it does not change the window’s size, raise the
window, or change the mapping state of the window. Moving a
mapped window may or may not lose the window’s
contents depending on if the window is obscured by
nonchildren and if no backing store exists. If the contents
of the window are lost, the X server generates <i>Expose</i>
events. Moving a mapped window generates <i>Expose</i>
events on any formerly obscured windows.</small></p>
<p><small>If the override-redirect flag of the window is
<i>False</i> and some other client has selected
<i>SubstructureRedirectMask</i> on the parent, the X server
generates a <i>ConfigureRequest</i> event, and no further
processing is performed. Otherwise, the window is
moved.</small></p>
<p><small><i>XMoveWindow</i> can generate a
<i>BadWindow</i> error.</small></p>
<p><small>To change a window’s size without changing
the upper-left coordinate, use
<i>XResizeWindow</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XResizeWindow(<i>display</i>, <i>w</i>, <i>width</i>, <i>height</i>)
Display *<i>display</i>;
Window <i>w</i>;
unsigned int <i>width</i>, <i>height</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the width and height, which are the
interior dimensions of the window after the call
completes.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XResizeWindow</i> function changes the
inside dimensions of the specified window, not including its
borders. This function does not change the window’s
upper-left coordinate or the origin and does not restack the
window. Changing the size of a mapped window may lose its
contents and generate <i>Expose</i> events. If a mapped
window is made smaller, changing its size generates
<i>Expose</i> events on windows that the mapped window
formerly obscured.</small></p>
<p><small>If the override-redirect flag of the window is
<i>False</i> and some other client has selected
<i>SubstructureRedirectMask</i> on the parent, the X server
generates a <i>ConfigureRequest</i> event, and no further
processing is performed. If either width or height is zero,
a <i>BadValue</i> error results.</small></p>
<p><small><i>XResizeWindow</i> can generate <i>BadValue</i>
and <i>BadWindow</i> errors.</small></p>
<p><small>To change the size and location of a window, use
<i>XMoveResizeWindow</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XMoveResizeWindow(<i>display</i>, <i>w</i>, <i>x</i>, <i>y</i>, <i>width</i>, <i>height</i>)
Display *<i>display</i>;
Window <i>w</i>;
int <i>x</i>, <i>y</i>;
unsigned int <i>width</i>, <i>height</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the window to be
reconfigured.</small></p>
</td>
<td width="0%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which define the
new position of the window relative to its
parent.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the width and height, which define the
interior size of the window.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XMoveResizeWindow</i> function changes the
size and location of the specified window without raising
it. Moving and resizing a mapped window may generate an
<i>Expose</i> event on the window. Depending on the new size
and location parameters, moving and resizing a window may
generate <i>Expose</i> events on windows that the window
formerly obscured.</small></p>
<p><small>If the override-redirect flag of the window is
<i>False</i> and some other client has selected
<i>SubstructureRedirectMask</i> on the parent, the X server
generates a <i>ConfigureRequest</i> event, and no further
processing is performed. Otherwise, the window size and
location are changed.</small></p>
<p><small><i>XMoveResizeWindow</i> can generate
<i>BadValue</i> and <i>BadWindow</i> errors.</small></p>
<p><small>To change the border width of a given window, use
<i>XSetWindowBorderWidth</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetWindowBorderWidth(<i>display</i>, <i>w</i>, <i>width</i>)
Display *<i>display</i>;
Window <i>w</i>;
unsigned int <i>width</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the width of the window
border.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetWindowBorderWidth</i> function sets
the specified window’s border width to the specified
width.</small></p>
<p><small><i>XSetWindowBorderWidth</i> can generate a
<i>BadWindow</i> error.</small></p>
<a name="3.8. Changing Window Stacking Order"></a>
<h2>3.8. Changing Window Stacking Order</h2>
<p><small>Xlib provides functions that you can use to
raise, lower, circulate, or restack windows.</small></p>
<p><small>To raise a window so that no sibling window
obscures it, use <i>XRaiseWindow</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XRaiseWindow(<i>display</i>, <i>w</i>)
Display *<i>display</i>;
Window <i>w</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XRaiseWindow</i> function raises the
specified window to the top of the stack so that no sibling
window obscures it. If the windows are regarded as
overlapping sheets of paper stacked on a desk, then raising
a window is analogous to moving the sheet to the top of the
stack but leaving its x and y location on the desk constant.
Raising a mapped window may generate <i>Expose</i> events
for the window and any mapped subwindows that were formerly
obscured.</small></p>
<p><small>If the override-redirect attribute of the window
is <i>False</i> and some other client has selected
<i>SubstructureRedirectMask</i> on the parent, the X server
generates a <i>ConfigureRequest</i> event, and no processing
is performed. Otherwise, the window is raised.</small></p>
<p><small><i>XRaiseWindow</i> can generate a
<i>BadWindow</i> error.</small></p>
<p><small>To lower a window so that it does not obscure any
sibling windows, use <i>XLowerWindow</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XLowerWindow(<i>display</i>, <i>w</i>)
Display *<i>display</i>;
Window <i>w</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XLowerWindow</i> function lowers the
specified window to the bottom of the stack so that it does
not obscure any sibling windows. If the windows are regarded
as overlapping sheets of paper stacked on a desk, then
lowering a window is analogous to moving the sheet to the
bottom of the stack but leaving its x and y location on the
desk constant. Lowering a mapped window will generate
<i>Expose</i> events on any windows it formerly
obscured.</small></p>
<p><small>If the override-redirect attribute of the window
is <i>False</i> and some other client has selected
<i>SubstructureRedirectMask</i> on the parent, the X server
generates a <i>ConfigureRequest</i> event, and no processing
is performed. Otherwise, the window is lowered to the bottom
of the stack.</small></p>
<p><small><i>XLowerWindow</i> can generate a
<i>BadWindow</i> error.</small></p>
<p><small>To circulate a subwindow up or down, use
<i>XCirculateSubwindows</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XCirculateSubwindows(<i>display</i>, <i>w</i>, <i>direction</i>)
Display *<i>display</i>;
Window <i>w</i>;
int <i>direction</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>direction</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the direction (up or down) that you
want to circulate the window. You can pass
<i>RaiseLowest</i> or <i>LowerHighest</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XCirculateSubwindows</i> function
circulates children of the specified window in the specified
direction. If you specify <i>RaiseLowest</i>,
<i>XCirculateSubwindows</i> raises the lowest mapped child
(if any) that is occluded by another child to the top of the
stack. If you specify <i>LowerHighest</i>,
<i>XCirculateSubwindows</i> 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
<i>SubstructureRedirectMask</i> on the window, the X server
generates a <i>CirculateRequest</i> event, and no further
processing is performed. If a child is actually restacked,
the X server generates a <i>CirculateNotify</i>
event.</small></p>
<p><small><i>XCirculateSubwindows</i> can generate
<i>BadValue</i> and <i>BadWindow</i> errors.</small></p>
<p><small>To raise the lowest mapped child of a window that
is partially or completely occluded by another child, use
<i>XCirculateSubwindowsUp</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XCirculateSubwindowsUp(<i>display</i>, <i>w</i>)
Display *<i>display</i>;
Window <i>w</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XCirculateSubwindowsUp</i> 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
<i>XCirculateSubwindows</i> with <i>RaiseLowest</i>
specified.</small></p>
<p><small><i>XCirculateSubwindowsUp</i> can generate a
<i>BadWindow</i> error.</small></p>
<p><small>To lower the highest mapped child of a window
that partially or completely occludes another child, use
<i>XCirculateSubwindowsDown</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XCirculateSubwindowsDown(<i>display</i>, <i>w</i>)
Display *<i>display</i>;
Window <i>w</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XCirculateSubwindowsDown</i> 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 <i>XCirculateSubwindows</i> with
<i>LowerHighest</i> specified.</small></p>
<p><small><i>XCirculateSubwindowsDown</i> can generate a
<i>BadWindow</i> error.</small></p>
<p><small>To restack a set of windows from top to bottom,
use <i>XRestackWindows</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XRestackWindows(<i>display</i>, <i>windows</i>, <i>nwindows</i>);
Display *<i>display</i>;
Window <i>windows</i>[];
int <i>nwindows</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>windows</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies an array containing the windows to be
restacked.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>nwindows</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the number of windows to be
restacked.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XRestackWindows</i> function restacks the
windows in the order specified, from top to bottom. The
stacking order of the first window in the windows array is
unaffected, but the other windows in the array are stacked
underneath the first window, in the order of the array. The
stacking order of the other windows is not affected. For
each window in the window array that is not a child of the
specified window, a <i>BadMatch</i> error
results.</small></p>
<p><small>If the override-redirect attribute of a window is
<i>False</i> and some other client has selected
<i>SubstructureRedirectMask</i> on the parent, the X server
generates <i>ConfigureRequest</i> events for each window
whose override-redirect flag is not set, and no further
processing is performed. Otherwise, the windows will be
restacked in top-to-bottom order.</small></p>
<p><small><i>XRestackWindows</i> can generate a
<i>BadWindow</i> error.</small></p>
<a name="3.9. Changing Window Attributes"></a>
<h2>3.9. Changing Window Attributes</h2>
<p><small>Xlib provides functions that you can use to set
window attributes. <i>XChangeWindowAttributes</i> is the
more general function that allows you to set one or more
window attributes provided by the
<i>XSetWindowAttributes</i> structure. The other functions
described in this section allow you to set one specific
window attribute, such as a window’s
background.</small></p>
<p><small>To change one or more attributes for a given
window, use <i>XChangeWindowAttributes</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XChangeWindowAttributes(<i>display</i>, <i>w</i>, <i>valuemask</i>, <i>attributes</i>)
Display *<i>display</i>;
Window <i>w</i>;
unsigned long <i>valuemask</i>;
XSetWindowAttributes *<i>attributes</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>valuemask</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>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
<i>XCreateWindow</i>.</small></p>
</td>
</table>
<p><small><i>attributes</i> 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 section 3.2).</small></p>
<p><small>│__</small></p>
<p><small>Depending on the valuemask, the
<i>XChangeWindowAttributes</i> function uses the window
attributes in the <i>XSetWindowAttributes</i> 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
<i>XClearWindow</i>. 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 <i>None</i> or <i>ParentRelative</i> restores
the default background pixmap. Changing the border of a root
window to <i>CopyFromParent</i> 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 <i>WhenMapped</i> or <i>Always</i>, 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
<i>ColormapNotify</i> event. Changing the colormap of a
visible window may have no immediate effect on the screen
because the map may not be installed (see
<i>XInstallColormap</i>). Changing the cursor of a root
window to <i>None</i> restores the default cursor. Whenever
possible, you are encouraged to share colormaps.</small></p>
<p><small>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
<i>SubstructureRedirectMask</i>, <i>ResizeRedirectMask</i>,
and <i>ButtonPressMask</i>. If a client attempts to select
any of these event masks and some other client has already
selected one, a <i>BadAccess</i> error results. There is
only one do-not-propagate-mask for a window, not one per
client.</small></p>
<p><small><i>XChangeWindowAttributes</i> can generate
<i>BadAccess</i>, <i>BadColor</i>, <i>BadCursor</i>,
<i>BadMatch</i>, <i>BadPixmap</i>, <i>BadValue</i>, and
<i>BadWindow</i> errors.</small></p>
<p><small>To set the background of a window to a given
pixel, use <i>XSetWindowBackground</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetWindowBackground(<i>display</i>, <i>w</i>, <i>background_pixel</i>)
Display *<i>display</i>;
Window <i>w</i>;
unsigned long <i>background_pixel</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>background_pixel</i> Specifies the pixel that
is to be used for the background.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XSetWindowBackground</i> function sets the
background of the window to the specified pixel value.
Changing the background does not cause the window contents
to be changed. <i>XSetWindowBackground</i> uses a pixmap of
undefined size filled with the pixel value you passed. If
you try to change the background of an <i>InputOnly</i>
window, a <i>BadMatch</i> error results.</small></p>
<p><small><i>XSetWindowBackground</i> can generate
<i>BadMatch</i> and <i>BadWindow</i> errors.</small></p>
<p><small>To set the background of a window to a given
pixmap, use <i>XSetWindowBackgroundPixmap</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetWindowBackgroundPixmap(<i>display</i>, <i>w</i>, <i>background_pixmap</i>)
Display *<i>display</i>;
Window <i>w</i>;
Pixmap <i>background_pixmap</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>background_pixmap</i> Specifies the background
pixmap, <i>ParentRelative</i>, or <i>None</i>.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XSetWindowBackgroundPixmap</i> function
sets the background pixmap of the window to the specified
pixmap. The background pixmap can immediately be freed if no
further explicit references to it are to be made. If
<i>ParentRelative</i> is specified, the background pixmap of
the window’s parent is used, or on the root window,
the default background is restored. If you try to change the
background of an <i>InputOnly</i> window, a <i>BadMatch</i>
error results. If the background is set to <i>None</i>, the
window has no defined background.</small></p>
<p><small><i>XSetWindowBackgroundPixmap</i> can generate
<i>BadMatch</i>, <i>BadPixmap</i>, and <i>BadWindow</i>
errors.</small></p>
<p align=center><small>Note</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small><i>XSetWindowBackground</i> and
<i>XSetWindowBackgroundPixmap</i> do not change the current
contents of the window.</small></p>
</td>
</table>
<p><small>To change and repaint a window’s border to
a given pixel, use <i>XSetWindowBorder</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetWindowBorder(<i>display</i>, <i>w</i>, <i>border_pixel</i>)
Display *<i>display</i>;
Window <i>w</i>;
unsigned long <i>border_pixel</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>border_pixel</i> Specifies the entry in the
colormap.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XSetWindowBorder</i> function sets the
border of the window to the pixel value you specify. If you
attempt to perform this on an <i>InputOnly</i> window, a
<i>BadMatch</i> error results.</small></p>
<p><small><i>XSetWindowBorder</i> can generate
<i>BadMatch</i> and <i>BadWindow</i> errors.</small></p>
<p><small>To change and repaint the border tile of a given
window, use <i>XSetWindowBorderPixmap</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetWindowBorderPixmap(<i>display</i>, <i>w</i>, <i>border_pixmap</i>)
Display *<i>display</i>;
Window <i>w</i>;
Pixmap <i>border_pixmap</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>border_pixmap</i> Specifies the border pixmap
or <i>CopyFromParent</i>.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XSetWindowBorderPixmap</i> function sets
the border pixmap of the window to the pixmap you specify.
The border pixmap can be freed immediately if no further
explicit references to it are to be made. If you specify
<i>CopyFromParent</i>, a copy of the parent window’s
border pixmap is used. If you attempt to perform this on an
<i>InputOnly</i> window, a <i>BadMatch</i> error
results.</small></p>
<p><small><i>XSetWindowBorderPixmap</i> can generate
<i>BadMatch</i>, <i>BadPixmap</i>, and <i>BadWindow</i>
errors.</small></p>
<p><small>To set the colormap of a given window, use
<i>XSetWindowColormap</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetWindowColormap(<i>display</i>, <i>w</i>, <i>colormap</i>)
Display *<i>display</i>;
Window <i>w</i>;
Colormap <i>colormap</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetWindowColormap</i> function sets the
specified colormap of the specified window. The colormap
must have the same visual type as the window, or a
<i>BadMatch</i> error results.</small></p>
<p><small><i>XSetWindowColormap</i> can generate
<i>BadColor</i>, <i>BadMatch</i>, and <i>BadWindow</i>
errors.</small></p>
<p><small>To define which cursor will be used in a window,
use <i>XDefineCursor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XDefineCursor(<i>display</i>, <i>w</i>, <i>cursor</i>)
Display *<i>display</i>;
Window <i>w</i>;
Cursor <i>cursor</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>cursor</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the cursor that is to be displayed or
<i>None</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>If a cursor is set, it will be used when the
pointer is in the window. If the cursor is <i>None</i>, it
is equivalent to <i>XUndefineCursor</i>.</small></p>
<p><small><i>XDefineCursor</i> can generate
<i>BadCursor</i> and <i>BadWindow</i> errors.</small></p>
<p><small>To undefine the cursor in a given window, use
<i>XUndefineCursor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XUndefineCursor(<i>display</i>, <i>w</i>)
Display *<i>display</i>;
Window <i>w</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XUndefineCursor</i> function undoes the
effect of a previous <i>XDefineCursor</i> for this window.
When the pointer is in the window, the parent’s cursor
will now be used. On the root window, the default cursor is
restored.</small></p>
<p><small><i>XUndefineCursor</i> can generate a
<i>BadWindow</i> error.</small></p>
<p><small><b>3</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b>Chapter 4</b></p>
<p align=center><b>Window Information Functions</b></p>
<p><small>After you connect the display to the X server and
create a window, you can use the Xlib window information
functions to:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="66%">
<p><small>Obtain information about a window</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="56%">
<p><small>Translate screen coordinates</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="50%">
<p><small>Manipulate property lists</small></p>
</td>
<td width="39%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="70%">
<p><small>Obtain and change window properties</small></p>
</td>
<td width="19%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>Manipulate selections</small></p>
</td>
<td width="47%">
</td>
</table>
<a name="4.1. Obtaining Window Information"></a>
<h2>4.1. Obtaining Window Information</h2>
<p><small>Xlib provides functions that you can use to
obtain information about the window tree, the window’s
current attributes, the window’s current geometry, or
the current pointer coordinates. Because they are most
frequently used by window managers, these functions all
return a status to indicate whether the window still
exists.</small></p>
<p><small>To obtain the parent, a list of children, and
number of children for a given window, use
<i>XQueryTree</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XQueryTree(<i>display</i>, <i>w</i>, <i>root_return</i>, <i>parent_return</i>, <i>children_return</i>, <i>nchildren_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
Window *<i>root_return</i>;
Window *<i>parent_return</i>;
Window **<i>children_return</i>;
unsigned int *<i>nchildren_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the window whose list of children,
root, parent, and number of children you want to
obtain.</small></p>
</td>
</table>
<p><small><i>root_return</i> Returns the root
window.</small></p>
<p><small><i>parent_return</i> Returns the parent
window.</small></p>
<p><small><i>children_return</i> Returns the list of
children.</small></p>
<p><small><i>nchildren_return</i> Returns the number of
children.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XQueryTree</i> function returns the root
ID, the parent window ID, a pointer to the list of children
windows (NULL when there are no children), and the number of
children in the list for the specified window. The children
are listed in current stacking order, from bottom-most
(first) to top-most (last). <i>XQueryTree</i> returns zero
if it fails and nonzero if it succeeds. To free a non-NULL
children list when it is no longer needed, use
<i>XFree</i>.</small></p>
<p><small><i>XQueryTree</i> can generate a <i>BadWindow</i>
error.</small></p>
<p><small>To obtain the current attributes of a given
window, use <i>XGetWindowAttributes</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetWindowAttributes(<i>display</i>, <i>w</i>, <i>window_attributes_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
XWindowAttributes *<i>window_attributes_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the window whose current attributes you
want to obtain.</small></p>
</td>
</table>
<p><small><i>window_attributes_return</i> Returns the
specified window’s attributes in the
<i>XWindowAttributes</i> structure.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetWindowAttributes</i> function returns
the current attributes for the specified window to an
<i>XWindowAttributes</i> structure.</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int x, y;</small></p>
</td>
<td width="40%">
<p><small>/* location of window */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int width, height;</small></p>
</td>
<td width="40%">
<p><small>/* width and height of window */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int border_width;</small></p>
</td>
<td width="40%">
<p><small>/* border width of window */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int depth;</small></p>
</td>
<td width="40%">
<p><small>/* depth of window */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Visual *visual;</small></p>
</td>
<td width="40%">
<p><small>/* the associated visual structure */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window root;</small></p>
</td>
<td width="40%">
<p><small>/* root of screen containing window
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int class;</small></p>
</td>
<td width="40%">
<p><small>/* InputOutput, InputOnly*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int bit_gravity;</small></p>
</td>
<td width="40%">
<p><small>/* one of the bit gravity values */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int win_gravity;</small></p>
</td>
<td width="40%">
<p><small>/* one of the window gravity values
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int backing_store;</small></p>
</td>
<td width="40%">
<p><small>/* NotUseful, WhenMapped, Always */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long backing_planes;/* planes to be
preserved if possible */</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long backing_pixel;/* value to be used
when restoring planes */</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool save_under;</small></p>
</td>
<td width="40%">
<p><small>/* boolean, should bits under be saved?
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Colormap colormap;</small></p>
</td>
<td width="40%">
<p><small>/* color map to be associated with window
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool map_installed;</small></p>
</td>
<td width="40%">
<p><small>/* boolean, is color map currently
installed*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int map_state;</small></p>
</td>
<td width="40%">
<p><small>/* IsUnmapped, IsUnviewable, IsViewable
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>long all_event_masks;</small></p>
</td>
<td width="40%">
<p><small>/* set of events all people have interest
in*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>long your_event_mask;</small></p>
</td>
<td width="40%">
<p><small>/* my event mask */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>long do_not_propagate_mask;/* set of events that
should not propagate */</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool override_redirect;</small></p>
</td>
<td width="40%">
<p><small>/* boolean value for override-redirect
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Screen *screen;</small></p>
</td>
<td width="40%">
<p><small>/* back pointer to correct screen */</small></p>
</td>
</table>
<p><small>} XWindowAttributes;</small></p>
<p><small>│__</small></p>
<p><small>The x and y members are set to the upper-left
outer corner relative to the parent window’s origin.
The width and height members are set to the inside size of
the window, not including the border. The border_width
member is set to the window’s border width in pixels.
The depth member is set to the depth of the window (that is,
bits per pixel for the object). The visual member is a
pointer to the screen’s associated <i>Visual</i>
structure. The root member is set to the root window of the
screen containing the window. The class member is set to the
window’s class and can be either <i>InputOutput</i> or
<i>InputOnly</i>.</small></p>
<p><small>The bit_gravity member is set to the
window’s bit gravity and can be one of the
following:</small></p>
<p align=center><small><img src="grohtml-1439210.png"></small></p>
<p><small>The win_gravity member is set to the
window’s window gravity and can be one of the
following:</small></p>
<p align=center><small><img src="grohtml-1439211.png"></small></p>
<p><small>For additional information on gravity, see
section 3.2.3.</small></p>
<p><small>The backing_store member is set to indicate how
the X server should maintain the contents of a window and
can be <i>WhenMapped</i>, <i>Always</i>, or
<i>NotUseful</i>. The backing_planes member is set to
indicate (with bits set to 1) which bit planes of the window
hold dynamic data that must be preserved in backing_stores
and during save_unders. The backing_pixel member is set to
indicate what values to use for planes not set in
backing_planes.</small></p>
<p><small>The save_under member is set to <i>True</i> or
<i>False</i>. The colormap member is set to the colormap for
the specified window and can be a colormap ID or
<i>None</i>. The map_installed member is set to indicate
whether the colormap is currently installed and can be
<i>True</i> or <i>False</i>. The map_state member is set to
indicate the state of the window and can be
<i>IsUnmapped</i>, <i>IsUnviewable</i>, or
<i>IsViewable</i>. <i>IsUnviewable</i> is used if the window
is mapped but some ancestor is unmapped.</small></p>
<p><small>The all_event_masks member is set to the bitwise
inclusive OR of all event masks selected on the window by
all clients. The your_event_mask member is set to the
bitwise inclusive OR of all event masks selected by the
querying client. The do_not_propagate_mask member is set to
the bitwise inclusive OR of the set of events that should
not propagate.</small></p>
<p><small>The override_redirect member is set to indicate
whether this window overrides structure control facilities
and can be <i>True</i> or <i>False</i>. Window manager
clients should ignore the window if this member is
<i>True</i>.</small></p>
<p><small>The screen member is set to a screen pointer that
gives you a back pointer to the correct screen. This makes
it easier to obtain the screen information without having to
loop over the root window fields to see which field
matches.</small></p>
<p><small><i>XGetWindowAttributes</i> can generate
<i>BadDrawable</i> and <i>BadWindow</i> errors.</small></p>
<p><small>To obtain the current geometry of a given
drawable, use <i>XGetGeometry</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetGeometry(<i>display</i>, <i>d</i>, <i>root_return</i>, <i>x_return</i>, <i>y_return</i>, <i>width_return</i>,
<i> height_return</i>, <i>border_width_return</i>, <i>depth_return</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
Window *<i>root_return</i>;
int *<i>x_return</i>, *<i>y_return</i>;
unsigned int *<i>width_return</i>, *<i>height_return</i>;
unsigned int *<i>border_width_return</i>;
unsigned int *<i>depth_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the drawable, which can be a window or
a pixmap.</small></p>
</td>
</table>
<p><small><i>root_return</i> Returns the root
window.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>x_return</i></small></p>
</td>
<td width="83%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>y_return</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>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.</small></p>
</td>
</table>
<p><small><i>width_return</i></small></p>
<p><small><i>height_return</i> Return the drawable’s
dimensions (width and height). For a window, these
dimensions specify the inside size, not including the
border.</small></p>
<p><small><i>border_width_return</i> Returns the border
width in pixels. If the drawable is a pixmap, it returns
zero.</small></p>
<p><small><i>depth_return</i> Returns the depth of the
drawable (bits per pixel for the object).</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetGeometry</i> 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
<i>InputOnly</i>.</small></p>
<p><small><i>XGetGeometry</i> can generate a
<i>BadDrawable</i> error.</small></p>
<a name="4.2. Translating Screen Coordinates"></a>
<h2>4.2. Translating Screen Coordinates</h2>
<p><small>Applications sometimes need to perform a
coordinate transformation from the coordinate space of one
window to another window or need to determine which window
the pointing device is in. <i>XTranslateCoordinates</i> and
<i>XQueryPointer</i> fulfill these needs (and avoid any race
conditions) by asking the X server to perform these
operations.</small></p>
<p><small>To translate a coordinate in one window to the
coordinate space of another window, use
<i>XTranslateCoordinates</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XTranslateCoordinates(<i>display</i>, <i>src_w</i>, <i>dest_w</i>, <i>src_x</i>, <i>src_y</i>, <i>dest_x_return</i>,
<i> dest_y_return</i>, <i>child_return</i>)
Display *<i>display</i>;
Window <i>src_w</i>, <i>dest_w</i>;
int <i>src_x</i>, <i>src_y</i>;
int *<i>dest_x_return</i>, *<i>dest_y_return</i>;
Window *<i>child_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>src_w</i></small></p>
</td>
<td width="10%"></td>
<td width="56%">
<p><small>Specifies the source window.</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>dest_w</i></small></p>
</td>
<td width="8%"></td>
<td width="66%">
<p><small>Specifies the destination window.</small></p>
</td>
<td width="13%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>src_x</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>src_y</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates within the source
window.</small></p>
</td>
</table>
<p><small><i>dest_x_return</i></small></p>
<p><small><i>dest_y_return</i> Return the x and y
coordinates within the destination window.</small></p>
<p><small><i>child_return</i> Returns the child if the
coordinates are contained in a mapped child of the
destination window.</small></p>
<p><small>│__</small></p>
<p><small>If <i>XTranslateCoordinates</i> returns
<i>True</i>, it takes the src_x and src_y coordinates
relative to the source window’s origin and returns
these coordinates to dest_x_return and dest_y_return
relative to the destination window’s origin. If
<i>XTranslateCoordinates</i> returns <i>False</i>, src_w and
dest_w are on different screens, and dest_x_return and
dest_y_return are zero. If the coordinates are contained in
a mapped child of dest_w, that child is returned to
child_return. Otherwise, child_return is set to
<i>None</i>.</small></p>
<p><small><i>XTranslateCoordinates</i> can generate a
<i>BadWindow</i> error.</small></p>
<p><small>To obtain the screen coordinates of the pointer
or to determine the pointer coordinates relative to a
specified window, use <i>XQueryPointer</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XQueryPointer(<i>display</i>, <i>w</i>, <i>root_return</i>, <i>child_return</i>, <i>root_x_return</i>, <i>root_y_return</i>,
<i> win_x_return</i>, <i>win_y_return</i>, <i>mask_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
Window *<i>root_return</i>, *<i>child_return</i>;
int *<i>root_x_return</i>, *<i>root_y_return</i>;
int *<i>win_x_return</i>, *<i>win_y_return</i>;
unsigned int *<i>mask_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>root_return</i> Returns the root window that
the pointer is in.</small></p>
<p><small><i>child_return</i> Returns the child window that
the pointer is located in, if any.</small></p>
<p><small><i>root_x_return</i></small></p>
<p><small><i>root_y_return</i> Return the pointer
coordinates relative to the root window’s
origin.</small></p>
<p><small><i>win_x_return</i></small></p>
<p><small><i>win_y_return</i> Return the pointer
coordinates relative to the specified window.</small></p>
<p><small><i>mask_return</i> Returns the current state of
the modifier keys and pointer buttons.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XQueryPointer</i> function returns the
root window the pointer is logically on and the pointer
coordinates relative to the root window’s origin. If
<i>XQueryPointer</i> returns <i>False</i>, the pointer is
not on the same screen as the specified window, and
<i>XQueryPointer</i> returns <i>None</i> to child_return and
zero to win_x_return and win_y_return. If
<i>XQueryPointer</i> returns <i>True</i>, the pointer
coordinates returned to win_x_return and win_y_return are
relative to the origin of the specified window. In this
case, <i>XQueryPointer</i> returns the child that contains
the pointer, if any, or else <i>None</i> to
child_return.</small></p>
<p><small><i>XQueryPointer</i> returns the current logical
state of the keyboard buttons and the modifier keys in
mask_return. It sets mask_return to the bitwise inclusive OR
of one or more of the button or modifier key bitmasks to
match the current state of the mouse buttons and the
modifier keys.</small></p>
<p><small>Note that the logical state of a device (as seen
through Xlib) may lag the physical state if device event
processing is frozen (see section 12.1).</small></p>
<p><small><i>XQueryPointer</i> can generate a
<i>BadWindow</i> error.</small></p>
<a name="4.3. Properties and Atoms"></a>
<h2>4.3. Properties and Atoms</h2>
<p><small>A property is a collection of named, typed data.
The window system has a set of predefined properties (for
example, the name of a window, size hints, and so on), and
users can define any other arbitrary information and
associate it with windows. Each property has a name, which
is an ISO Latin-1 string. For each named property, a unique
identifier (atom) is associated with it. A property also has
a type, for example, string or integer. These types are also
indicated using atoms, so arbitrary new types can be
defined. Data of only one type may be associated with a
single property name. Clients can store and retrieve
properties associated with windows. For efficiency reasons,
an atom is used rather than a character string.
<i>XInternAtom</i> can be used to obtain the atom for
property names.</small></p>
<p><small>A property is also stored in one of several
possible formats. The X server can store the information as
8-bit quantities, 16-bit quantities, or 32-bit quantities.
This permits the X server to present the data in the byte
order that the client expects.</small></p>
<p align=center><small>Note</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>If you define further properties of complex type,
you must encode and decode them yourself. These functions
must be carefully written if they are to be portable. For
further information about how to write a library extension,
see appendix C.</small></p>
</td>
</table>
<p><small>The type of a property is defined by an atom,
which allows for arbitrary extension in this type
scheme.</small></p>
<p><small>Certain property names are predefined in the
server for commonly used functions. The atoms for these
properties are defined in <<i>X11/Xatom.h</i>>. To
avoid name clashes with user symbols, the <i>#define</i>
name for each atom has the XA_ prefix. For an explanation of
the functions that let you get and set much of the
information stored in these predefined properties, see
chapter 14.</small></p>
<p><small>The core protocol imposes no semantics on these
property names, but semantics are specified in other X
Consortium standards, such as the <i>Inter-Client
Communication Conventions Manual</i> and the <i>X Logical
Font Description Conventions</i>.</small></p>
<p><small>You can use properties to communicate other
information between applications. The functions described in
this section let you define new properties and get the
unique atom IDs in your applications.</small></p>
<p><small>Although any particular atom can have some client
interpretation within each of the name spaces, atoms occur
in five distinct name spaces within the
protocol:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="20%">
<p><small>Selections</small></p>
</td>
<td width="69%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="28%">
<p><small>Property names</small></p>
</td>
<td width="61%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="28%">
<p><small>Property types</small></p>
</td>
<td width="61%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="30%">
<p><small>Font properties</small></p>
</td>
<td width="59%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Type of a <i>ClientMessage</i> event (none are
built into the X server)</small></p>
</td>
</table>
<p><small>The built-in selection property names
are:</small></p>
<pre><small>PRIMARY
SECONDARY
</small></pre>
<p><small>The built-in property names are:</small></p>
<p align=center><small><img src="grohtml-1439212.png"></small></p>
<p><small>The built-in property types are:</small></p>
<p align=center><small><img src="grohtml-1439213.png"></small></p>
<p><small>The built-in font property names are:</small></p>
<p align=center><small><img src="grohtml-1439214.png"></small></p>
<p><small>For further information about font properties,
see section 8.5.</small></p>
<p><small>To return an atom for a given name, use
<i>XInternAtom</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Atom XInternAtom(<i>display</i>, <i>atom_name</i>, <i>only_if_exists</i>)
Display *<i>display</i>;
char *<i>atom_name</i>;
Bool <i>only_if_exists</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>atom_name</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the name associated with the atom you
want returned.</small></p>
</td>
</table>
<p><small><i>only_if_exists</i> Specifies a Boolean value
that indicates whether the atom must be created.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XInternAtom</i> function returns the atom
identifier associated with the specified atom_name string.
If only_if_exists is <i>False</i>, the atom is created if it
does not exist. Therefore, <i>XInternAtom</i> can return
<i>None</i>. If the atom name is not in the Host Portable
Character Encoding, the result is implementation-dependent.
Uppercase and lowercase matter; the strings
‘‘thing’’,
‘‘Thing’’, and
‘‘thinG’’ all designate different
atoms. The atom will remain defined even after the
client’s connection closes. It will become undefined
only when the last connection to the X server
closes.</small></p>
<p><small><i>XInternAtom</i> can generate <i>BadAlloc</i>
and <i>BadValue</i> errors.</small></p>
<p><small>To return atoms for an array of names, use
<i>XInternAtoms</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XInternAtoms(<i>display</i>, <i>names</i>, <i>count</i>, <i>only_if_exists</i>, <i>atoms_return</i>)
Display *<i>display</i>;
char **<i>names</i>;
int <i>count</i>;
Bool <i>only_if_exists</i>;
Atom *<i>atoms_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>names</i></small></p>
</td>
<td width="10%"></td>
<td width="68%">
<p><small>Specifies the array of atom names.</small></p>
</td>
<td width="11%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>count</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the number of atom names in the
array.</small></p>
</td>
</table>
<p><small><i>only_if_exists</i> Specifies a Boolean value
that indicates whether the atom must be created.</small></p>
<p><small><i>atoms_return</i> Returns the
atoms.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XInternAtoms</i> function returns the atom
identifiers associated with the specified names. The atoms
are stored in the atoms_return array supplied by the caller.
Calling this function is equivalent to calling
<i>XInternAtom</i> for each of the names in turn with the
specified value of only_if_exists, but this function
minimizes the number of round-trip protocol exchanges
between the client and the X server.</small></p>
<p><small>This function returns a nonzero status if atoms
are returned for all of the names; otherwise, it returns
zero.</small></p>
<p><small><i>XInternAtoms</i> can generate <i>BadAlloc</i>
and <i>BadValue</i> errors.</small></p>
<p><small>To return a name for a given atom identifier, use
<i>XGetAtomName</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char *XGetAtomName(<i>display</i>, <i>atom</i>)
Display *<i>display</i>;
Atom <i>atom</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>atom</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the atom for the property name you want
returned.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetAtomName</i> function returns the name
associated with the specified atom. 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.
To free the resulting string, call <i>XFree</i>.</small></p>
<p><small><i>XGetAtomName</i> can generate a <i>BadAtom</i>
error.</small></p>
<p><small>To return the names for an array of atom
identifiers, use <i>XGetAtomNames</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetAtomNames(<i>display</i>, <i>atoms</i>, <i>count</i>, <i>names_return</i>)
Display *<i>display</i>;
Atom *<i>atoms</i>;
int <i>count</i>;
char **<i>names_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>atoms</i></small></p>
</td>
<td width="10%"></td>
<td width="58%">
<p><small>Specifies the array of atoms.</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>count</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the number of atoms in the
array.</small></p>
</td>
</table>
<p><small><i>names_return</i> Returns the atom
names.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetAtomNames</i> function returns the
names associated with the specified atoms. The names are
stored in the names_return array supplied by the caller.
Calling this function is equivalent to calling
<i>XGetAtomName</i> for each of the atoms in turn, but this
function minimizes the number of round-trip protocol
exchanges between the client and the X server.</small></p>
<p><small>This function returns a nonzero status if names
are returned for all of the atoms; otherwise, it returns
zero.</small></p>
<p><small><i>XGetAtomNames</i> can generate a
<i>BadAtom</i> error.</small></p>
<a name="4.4. Obtaining and Changing Window Properties"></a>
<h2>4.4. Obtaining and Changing Window Properties</h2>
<p><small>You can attach a property list to every window.
Each property has a name, a type, and a value (see section
4.3). The value is an array of 8-bit, 16-bit, or 32-bit
quantities, whose interpretation is left to the clients. The
type <i>char</i> is used to represent 8-bit quantities, the
type <i>short</i> is used to represent 16-bit quantities,
and the type <i>long</i> is used to represent 32-bit
quantities.</small></p>
<p><small>Xlib provides functions that you can use to
obtain, change, update, or interchange window properties. In
addition, Xlib provides other utility functions for
inter-client communication (see chapter 14).</small></p>
<p><small>To obtain the type, format, and value of a
property of a given window, use
<i>XGetWindowProperty</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XGetWindowProperty(<i>display</i>, <i>w</i>, <i>property</i>, <i>long_offset</i>, <i>long_length</i>, <i>delete</i>, <i>req_type</i>,
<i> actual_type_return</i>, <i>actual_format_return</i>, <i>nitems_return</i>, <i>bytes_after_return</i>,
<i> prop_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
Atom <i>property</i>;
long <i>long_offset</i>, <i>long_length</i>;
Bool <i>delete</i>;
Atom <i>req_type</i>;
Atom *<i>actual_type_return</i>;
int *<i>actual_format_return</i>;
unsigned long *<i>nitems_return</i>;
unsigned long *<i>bytes_after_return</i>;
unsigned char **<i>prop_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the window whose property you want to
obtain.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>property</i></small></p>
</td>
<td width="4%"></td>
<td width="56%">
<p><small>Specifies the property name.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small><i>long_offset</i> Specifies the offset in the
specified property (in 32-bit quantities) where the data is
to be retrieved.</small></p>
<p><small><i>long_length</i> Specifies the length in 32-bit
multiples of the data to be retrieved.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>delete</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies a Boolean value that determines whether
the property is deleted.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>req_type</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the atom identifier associated with the
property type or <i>AnyPropertyType</i>.</small></p>
</td>
</table>
<p><small><i>actual_type_return</i> Returns the atom
identifier that defines the actual type of the
property.</small></p>
<p><small><i>actual_format_return</i> Returns the actual
format of the property.</small></p>
<p><small><i>nitems_return</i> Returns the actual number of
8-bit, 16-bit, or 32-bit items stored in the prop_return
data.</small></p>
<p><small><i>bytes_after_return</i> Returns the number of
bytes remaining to be read in the property if a partial read
was performed.</small></p>
<p><small><i>prop_return</i> Returns the data in the
specified format.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetWindowProperty</i> function returns
the actual type of the property; the actual format of the
property; the number of 8-bit, 16-bit, or 32-bit items
transferred; the number of bytes remaining to be read in the
property; and a pointer to the data actually returned.
<i>XGetWindowProperty</i> sets the return arguments as
follows:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If the specified property does not exist for the
specified window, <i>XGetWindowProperty</i> returns
<i>None</i> to actual_type_return and the value zero to
actual_format_return and bytes_after_return. The
nitems_return argument is empty. In this case, the delete
argument is ignored.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If the specified property exists but its type
does not match the specified type, <i>XGetWindowProperty</i>
returns the actual property type to actual_type_return, the
actual property format (never zero) to actual_format_return,
and the property length in bytes (even if the
actual_format_return is 16 or 32) to bytes_after_return. It
also ignores the delete argument. The nitems_return argument
is empty.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If the specified property exists and either you
assign <i>AnyPropertyType</i> to the req_type argument or
the specified type matches the actual property type,
<i>XGetWindowProperty</i> returns the actual property type
to actual_type_return and the actual property format (never
zero) to actual_format_return. It also returns a value to
bytes_after_return and nitems_return, by defining the
following values:</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="10%">
<p><small>N = actual length of the stored property in
bytes</small></p>
</td>
<td width="69%">
</td>
<tr valign="top" align="left">
<td width="19%"></td>
<td width="10%">
<p><small>(even if the format is 16 or 32)</small></p>
</td>
<td width="69%">
</td>
<tr valign="top" align="left">
<td width="19%"></td>
<td width="10%">
<p><small>I = 4 * long_offset</small></p>
</td>
<td width="69%">
</td>
<tr valign="top" align="left">
<td width="19%"></td>
<td width="10%">
<p><small>T = N - I</small></p>
</td>
<td width="69%">
</td>
<tr valign="top" align="left">
<td width="19%"></td>
<td width="10%">
<p><small>L = MINIMUM(T, 4 * long_length)</small></p>
</td>
<td width="69%">
</td>
<tr valign="top" align="left">
<td width="19%"></td>
<td width="10%">
<p><small>A = N - (I + L)</small></p>
</td>
<td width="69%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The returned value starts at byte index I in the
property (indexing from zero), and its length in bytes is L.
If the value for long_offset causes L to be negative, a
<i>BadValue</i> error results. The value of
bytes_after_return is A, giving the number of trailing
unread bytes in the stored property.</small></p>
</td>
</table>
<p><small>If the returned format is 8, the returned data is
represented as a <i>char</i> array. If the returned format
is 16, the returned data is represented as a <i>short</i>
array and should be cast to that type to obtain the
elements. If the returned format is 32, the returned data is
represented as a <i>long</i> array and should be cast to
that type to obtain the elements.</small></p>
<p><small><i>XGetWindowProperty</i> always allocates one
extra byte in prop_return (even if the property is zero
length) and sets it to zero so that simple properties
consisting of characters do not have to be copied into yet
another string before use.</small></p>
<p><small>If delete is <i>True</i> and bytes_after_return
is zero, <i>XGetWindowProperty</i> deletes the property from
the window and generates a <i>PropertyNotify</i> event on
the window.</small></p>
<p><small>The function returns <i>Success</i> if it
executes successfully. To free the resulting data, use
<i>XFree</i>.</small></p>
<p><small><i>XGetWindowProperty</i> can generate
<i>BadAtom</i>, <i>BadValue</i>, and <i>BadWindow</i>
errors.</small></p>
<p><small>To obtain a given window’s property list,
use <i>XListProperties</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Atom *XListProperties(<i>display</i>, <i>w</i>, <i>num_prop_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
int *<i>num_prop_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the window whose property list you want
to obtain.</small></p>
</td>
</table>
<p><small><i>num_prop_return</i> Returns the length of the
properties array.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XListProperties</i> function returns a
pointer to an array of atom properties that are defined for
the specified window or returns NULL if no properties were
found. To free the memory allocated by this function, use
<i>XFree</i>.</small></p>
<p><small><i>XListProperties</i> can generate a
<i>BadWindow</i> error.</small></p>
<p><small>To change a property of a given window, use
<i>XChangeProperty</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XChangeProperty(<i>display</i>, <i>w</i>, <i>property</i>, <i>type</i>, <i>format</i>, <i>mode</i>, <i>data</i>, <i>nelements</i>)
Display *<i>display</i>;
Window <i>w</i>;
Atom <i>property</i>, <i>type</i>;
int <i>format</i>;
int <i>mode</i>;
unsigned char *<i>data</i>;
int <i>nelements</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the window whose property you want to
change.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>property</i></small></p>
</td>
<td width="4%"></td>
<td width="56%">
<p><small>Specifies the property name.</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>type</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>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
<i>XGetWindowProperty</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>format</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies whether the data should be viewed as a
list of 8-bit, 16-bit, or 32-bit quantities. Possible values
are 8, 16, and 32. This information allows the X server to
correctly perform byte-swap operations as necessary. If the
format is 16-bit or 32-bit, you must explicitly cast your
data pointer to an (unsigned char *) in the call to
<i>XChangeProperty</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>mode</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the mode of the operation. You can pass
<i>PropModeReplace</i>, <i>PropModePrepend</i>, or
<i>PropModeAppend</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>data</i></small></p>
</td>
<td width="12%"></td>
<td width="56%">
<p><small>Specifies the property data.</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>nelements</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the number of elements of the specified
data format.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XChangeProperty</i> function alters the
property for the specified window and causes the X server to
generate a <i>PropertyNotify</i> event on that window.
<i>XChangeProperty</i> performs the following:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If mode is <i>PropModeReplace</i>,
<i>XChangeProperty</i> discards the previous property value
and stores the new data.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If mode is <i>PropModePrepend</i> or
<i>PropModeAppend</i>, <i>XChangeProperty</i> 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
<i>BadMatch</i> error results. If the property is undefined,
it is treated as defined with the correct type and format
with zero-length data.</small></p>
</td>
</table>
<p><small>If the specified format is 8, the property data
must be a <i>char</i> array. If the specified format is 16,
the property data must be a <i>short</i> array. If the
specified format is 32, the property data must be a
<i>long</i> array.</small></p>
<p><small>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 2.6. 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 <i>BadAlloc</i> error
results.)</small></p>
<p><small><i>XChangeProperty</i> can generate
<i>BadAlloc</i>, <i>BadAtom</i>, <i>BadMatch</i>,
<i>BadValue</i>, and <i>BadWindow</i> errors.</small></p>
<p><small>To rotate a window’s property list, use
<i>XRotateWindowProperties</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XRotateWindowProperties(<i>display</i>, <i>w</i>, <i>properties</i>, <i>num_prop</i>, <i>npositions</i>)
Display *<i>display</i>;
Window <i>w</i>;
Atom <i>properties</i>[];
int <i>num_prop</i>;
int <i>npositions</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>properties</i> Specifies the array of
properties that are to be rotated.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>num_prop</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the length of the properties
array.</small></p>
</td>
</table>
<p><small><i>npositions</i> Specifies the rotation
amount.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XRotateWindowProperties</i> function
allows you to rotate properties on a window and causes the X
server to generate <i>PropertyNotify</i> events. If the
property names in the properties array are viewed as being
numbered starting from zero and if there are num_prop
property names in the list, then the value associated with
property name I becomes the value associated with property
name (I + npositions) mod N for all I from zero to N −
1. The effect is to rotate the states by npositions places
around the virtual ring of property names (right for
positive npositions, left for negative npositions). If
npositions mod N is nonzero, the X server generates a
<i>PropertyNotify</i> event for each property in the order
that they are listed in the array. If an atom occurs more
than once in the list or no property with that name is
defined for the window, a <i>BadMatch</i> error results. If
a <i>BadAtom</i> or <i>BadMatch</i> error results, no
properties are changed.</small></p>
<p><small><i>XRotateWindowProperties</i> can generate
<i>BadAtom</i>, <i>BadMatch</i>, and <i>BadWindow</i>
errors.</small></p>
<p><small>To delete a property on a given window, use
<i>XDeleteProperty</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XDeleteProperty(<i>display</i>, <i>w</i>, <i>property</i>)
Display *<i>display</i>;
Window <i>w</i>;
Atom <i>property</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the window whose property you want to
delete.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>property</i></small></p>
</td>
<td width="4%"></td>
<td width="56%">
<p><small>Specifies the property name.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XDeleteProperty</i> function deletes the
specified property only if the property was defined on the
specified window and causes the X server to generate a
<i>PropertyNotify</i> event on the window unless the
property does not exist.</small></p>
<p><small><i>XDeleteProperty</i> can generate
<i>BadAtom</i> and <i>BadWindow</i> errors.</small></p>
<a name="4.5. Selections"></a>
<h2>4.5. Selections</h2>
<p><small>Selections are one method used by applications to
exchange data. By using the property mechanism, applications
can exchange data of arbitrary types and can negotiate the
type of the data. A selection can be thought of as an
indirect property with a dynamic type. That is, rather than
having the property stored in the X server, the property is
maintained by some client (the owner). A selection is global
in nature (considered to belong to the user but be
maintained by clients) rather than being private to a
particular window subhierarchy or a particular set of
clients.</small></p>
<p><small>Xlib provides functions that you can use to set,
get, or request conversion of selections. This allows
applications to implement the notion of current selection,
which requires that notification be sent to applications
when they no longer own the selection. Applications that
support selection often highlight the current selection and
so must be informed when another application has acquired
the selection so that they can unhighlight the
selection.</small></p>
<p><small>When a client asks for the contents of a
selection, it specifies a selection target type. This target
type can be used to control the transmitted representation
of the contents. For example, if the selection is
‘‘the last thing the user clicked
on’’ and that is currently an image, then the
target type might specify whether the contents of the image
should be sent in XY format or Z format.</small></p>
<p><small>The target type can also be used to control the
class of contents transmitted, for example, asking for the
‘‘looks’’ (fonts, line spacing,
indentation, and so forth) of a paragraph selection, not the
text of the paragraph. The target type can also be used for
other purposes. The protocol does not constrain the
semantics.</small></p>
<p><small>To set the selection owner, use
<i>XSetSelectionOwner</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetSelectionOwner(<i>display</i>, <i>selection</i>, <i>owner</i>, <i>time</i>)
Display *<i>display</i>;
Atom <i>selection</i>;
Window <i>owner</i>;
Time <i>time</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>selection</i></small></p>
</td>
<td width="2%"></td>
<td width="58%">
<p><small>Specifies the selection atom.</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>owner</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the owner of the specified selection
atom. You can pass a window or <i>None</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>time</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the time. You can pass either a
timestamp or <i>CurrentTime</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetSelectionOwner</i> function changes
the owner and last-change time for the specified selection
and has no effect if the specified time is earlier than the
current last-change time of the specified selection or is
later than the current X server time. Otherwise, the
last-change time is set to the specified time, with
<i>CurrentTime</i> replaced by the current server time. If
the owner window is specified as <i>None</i>, then the owner
of the selection becomes <i>None</i> (that is, no owner).
Otherwise, the owner of the selection becomes the client
executing the request.</small></p>
<p><small>If the new owner (whether a client or
<i>None</i>) is not the same as the current owner of the
selection and the current owner is not <i>None</i>, the
current owner is sent a <i>SelectionClear</i> event. If the
client that is the owner of a selection is later terminated
(that is, its connection is closed) or if the owner window
it has specified in the request is later destroyed, the
owner of the selection automatically reverts to <i>None</i>,
but the last-change time is not affected. The selection atom
is uninterpreted by the X server. <i>XGetSelectionOwner</i>
returns the owner window, which is reported in
<i>SelectionRequest</i> and <i>SelectionClear</i> events.
Selections are global to the X server.</small></p>
<p><small><i>XSetSelectionOwner</i> can generate
<i>BadAtom</i> and <i>BadWindow</i> errors.</small></p>
<p><small>To return the selection owner, use
<i>XGetSelectionOwner</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Window XGetSelectionOwner(<i>display</i>, <i>selection</i>)
Display *<i>display</i>;
Atom <i>selection</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>selection</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the selection atom whose owner you want
returned.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetSelectionOwner</i> function returns
the window ID associated with the window that currently owns
the specified selection. If no selection was specified, the
function returns the constant <i>None</i>. If <i>None</i> is
returned, there is no owner for the selection.</small></p>
<p><small><i>XGetSelectionOwner</i> can generate a
<i>BadAtom</i> error.</small></p>
<p><small>To request conversion of a selection, use
<i>XConvertSelection</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XConvertSelection(<i>display</i>, <i>selection</i>, <i>target</i>, <i>property</i>, <i>requestor</i>, <i>time</i>)
Display *<i>display</i>;
Atom <i>selection</i>, <i>target</i>;
Atom <i>property</i>;
Window <i>requestor</i>;
Time <i>time</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>selection</i></small></p>
</td>
<td width="2%"></td>
<td width="58%">
<p><small>Specifies the selection atom.</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>target</i></small></p>
</td>
<td width="8%"></td>
<td width="52%">
<p><small>Specifies the target atom.</small></p>
</td>
<td width="27%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>property</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the property name. You also can pass
<i>None</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>requestor</i></small></p>
</td>
<td width="2%"></td>
<td width="48%">
<p><small>Specifies the requestor.</small></p>
</td>
<td width="31%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>time</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the time. You can pass either a
timestamp or <i>CurrentTime</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small><i>XConvertSelection</i> requests that the
specified selection be converted to the specified target
type:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If the specified selection has an owner, the X
server sends a <i>SelectionRequest</i> event to that
owner.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If no owner for the specified selection exists,
the X server generates a <i>SelectionNotify</i> event to the
requestor with property <i>None</i>.</small></p>
</td>
</table>
<p><small>The arguments are passed on unchanged in either
of the events. There are two predefined selection atoms:
PRIMARY and SECONDARY.</small></p>
<p><small><i>XConvertSelection</i> can generate
<i>BadAtom</i> and <i>BadWindow</i> errors.</small></p>
<p><small><b>4</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b>Chapter 5</b></p>
<p align=center><b>Pixmap and Cursor Functions</b></p>
<p><small>Once you have connected to an X server, you can
use the Xlib functions to:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="46%">
<p><small>Create and free pixmaps</small></p>
</td>
<td width="43%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="66%">
<p><small>Create, recolor, and free cursors</small></p>
</td>
<td width="23%">
</td>
</table>
<a name="5.1. Creating and Freeing Pixmaps"></a>
<h2>5.1. Creating and Freeing Pixmaps</h2>
<p><small>Pixmaps can only be used on the screen on which
they were created. Pixmaps are off-screen resources that are
used for various operations, such as defining cursors as
tiling patterns or as the source for certain raster
operations. Most graphics requests can operate either on a
window or on a pixmap. A bitmap is a single bit-plane
pixmap.</small></p>
<p><small>To create a pixmap of a given size, use
<i>XCreatePixmap</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Pixmap XCreatePixmap(<i>display</i>, <i>d</i>, <i>width</i>, <i>height</i>, <i>depth</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
unsigned int <i>width</i>, <i>height</i>;
unsigned int <i>depth</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies which screen the pixmap is created
on.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the width and height, which define the
dimensions of the pixmap.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>depth</i></small></p>
</td>
<td width="10%"></td>
<td width="68%">
<p><small>Specifies the depth of the pixmap.</small></p>
</td>
<td width="11%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XCreatePixmap</i> 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 <i>InputOnly</i> window to the drawable argument. The
width and height arguments must be nonzero, or a
<i>BadValue</i> error results. The depth argument must be
one of the depths supported by the screen of the specified
drawable, or a <i>BadValue</i> error results.</small></p>
<p><small>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 <i>XCopyPlane</i> for an
exception to this rule). The initial contents of the pixmap
are undefined.</small></p>
<p><small><i>XCreatePixmap</i> can generate
<i>BadAlloc</i>, <i>BadDrawable</i>, and <i>BadValue</i>
errors.</small></p>
<p><small>To free all storage associated with a specified
pixmap, use <i>XFreePixmap</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XFreePixmap(<i>display</i>, <i>pixmap</i>)
Display *<i>display</i>;
Pixmap <i>pixmap</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>pixmap</i></small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>Specifies the pixmap.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XFreePixmap</i> 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.</small></p>
<p><small><i>XFreePixmap</i> can generate a
<i>BadPixmap</i> error.</small></p>
<a name="5.2. Creating, Recoloring, and Freeing Cursors"></a>
<h2>5.2. Creating, Recoloring, and Freeing Cursors</h2>
<p><small>Each window can have a different cursor defined
for it. Whenever the pointer is in a visible window, it is
set to the cursor defined for that window. If no cursor was
defined for that window, the cursor is the one defined for
the parent window.</small></p>
<p><small>From X’s perspective, a cursor consists of
a cursor source, mask, colors, and a hotspot. The mask
pixmap determines the shape of the cursor and must be a
depth of one. The source pixmap must have a depth of one,
and the colors determine the colors of the source. The
hotspot defines the point on the cursor that is reported
when a pointer event occurs. There may be limitations
imposed by the hardware on cursors as to size and whether a
mask is implemented. <i>XQueryBestCursor</i> can be used to
find out what sizes are possible. There is a standard font
for creating cursors, but Xlib provides functions that you
can use to create cursors from an arbitrary font or from
bitmaps.</small></p>
<p><small>To create a cursor from the standard cursor font,
use <i>XCreateFontCursor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>#include <X11/cursorfont.h>
Cursor XCreateFontCursor(<i>display</i>, <i>shape</i>)
Display *<i>display</i>;
unsigned int <i>shape</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>shape</i></small></p>
</td>
<td width="10%"></td>
<td width="68%">
<p><small>Specifies the shape of the cursor.</small></p>
</td>
<td width="11%">
</td>
</table>
<p><small>│__</small></p>
<p><small>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.</small></p>
<p><small>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
<i>XRecolorCursor</i>). For further information about cursor
shapes, see appendix B.</small></p>
<p><small><i>XCreateFontCursor</i> can generate
<i>BadAlloc</i> and <i>BadValue</i> errors.</small></p>
<p><small>To create a cursor from font glyphs, use
<i>XCreateGlyphCursor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Cursor XCreateGlyphCursor(<i>display</i>, <i>source_font</i>, <i>mask_font</i>, <i>source_char</i>, <i>mask_char</i>,
<i> foreground_color</i>, <i>background_color</i>)
Display *<i>display</i>;
Font <i>source_font</i>, <i>mask_font</i>;
unsigned int <i>source_char</i>, <i>mask_char</i>;
XColor *<i>foreground_color</i>;
XColor *<i>background_color</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>source_font</i> Specifies the font for the
source glyph.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>mask_font</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the font for the mask glyph or
<i>None</i>.</small></p>
</td>
</table>
<p><small><i>source_char</i> Specifies the character glyph
for the source.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>mask_char</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the glyph character for the
mask.</small></p>
</td>
</table>
<p><small><i>foreground_color</i> Specifies the RGB values
for the foreground of the source.</small></p>
<p><small><i>background_color</i> Specifies the RGB values
for the background of the source.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XCreateGlyphCursor</i> function is similar
to <i>XCreatePixmapCursor</i> 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
<i>BadValue</i> error results. If mask_font is given,
mask_char must be a defined glyph in mask_font, or a
<i>BadValue</i> 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
<i>XFreeFont</i> if no further explicit references to them
are to be made.</small></p>
<p><small>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.</small></p>
<p><small><i>XCreateGlyphCursor</i> can generate
<i>BadAlloc</i>, <i>BadFont</i>, and <i>BadValue</i>
errors.</small></p>
<p><small>To create a cursor from two bitmaps, use
<i>XCreatePixmapCursor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Cursor XCreatePixmapCursor(<i>display</i>, <i>source</i>, <i>mask</i>, <i>foreground_color</i>, <i>background_color</i>, <i>x</i>, <i>y</i>)
Display *<i>display</i>;
Pixmap <i>source</i>;
Pixmap <i>mask</i>;
XColor *<i>foreground_color</i>;
XColor *<i>background_color</i>;
unsigned int <i>x</i>, <i>y</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>source</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the shape of the source
cursor.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>mask</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the cursor’s source bits to be
displayed or <i>None</i>.</small></p>
</td>
</table>
<p><small><i>foreground_color</i> Specifies the RGB values
for the foreground of the source.</small></p>
<p><small><i>background_color</i> Specifies the RGB values
for the background of the source.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which indicate
the hotspot relative to the source’s
origin.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XCreatePixmapCursor</i> 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 <i>StaticGray</i> or <i>GrayScale</i> 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 <i>BadMatch</i> 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
<i>BadMatch</i> error results. The hotspot must be a point
within the source, or a <i>BadMatch</i> error
results.</small></p>
<p><small>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.</small></p>
<p><small><i>XCreatePixmapCursor</i> can generate
<i>BadAlloc</i> and <i>BadPixmap</i> errors.</small></p>
<p><small>To determine useful cursor sizes, use
<i>XQueryBestCursor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XQueryBestCursor(<i>display</i>, <i>d</i>, <i>width</i>, <i>height</i>, <i>width_return</i>, <i>height_return</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
unsigned int <i>width</i>, <i>height</i>;
unsigned int *<i>width_return</i>, *<i>height_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the drawable, which indicates the
screen.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the width and height of the cursor that
you want the size information for.</small></p>
</td>
</table>
<p><small><i>width_return</i></small></p>
<p><small><i>height_return</i> Return the best width and
height that is closest to the specified width and
height.</small></p>
<p><small>│__</small></p>
<p><small>Some displays allow larger cursors than other
displays. The <i>XQueryBestCursor</i> function provides a
way to find out what size cursors are actually possible on
the display. It returns the largest size that can be
displayed. Applications should be prepared to use smaller
cursors on displays that cannot support large
ones.</small></p>
<p><small><i>XQueryBestCursor</i> can generate a
<i>BadDrawable</i> error.</small></p>
<p><small>To change the color of a given cursor, use
<i>XRecolorCursor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XRecolorCursor(<i>display</i>, <i>cursor</i>, <i>foreground_color</i>, <i>background_color</i>)
Display *<i>display</i>;
Cursor <i>cursor</i>;
XColor *<i>foreground_color</i>, *<i>background_color</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>cursor</i></small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>Specifies the cursor.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>foreground_color</i> Specifies the RGB values
for the foreground of the source.</small></p>
<p><small><i>background_color</i> Specifies the RGB values
for the background of the source.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XRecolorCursor</i> function changes the
color of the specified cursor, and if the cursor is being
displayed on a screen, the change is visible immediately.
The pixel members of the <i>XColor</i> structures are
ignored; only the RGB values are used.</small></p>
<p><small><i>XRecolorCursor</i> can generate a
<i>BadCursor</i> error.</small></p>
<p><small>To free (destroy) a given cursor, use
<i>XFreeCursor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XFreeCursor(<i>display</i>, <i>cursor</i>)
Display *<i>display</i>;
Cursor <i>cursor</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>cursor</i></small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>Specifies the cursor.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XFreeCursor</i> 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.</small></p>
<p><small><i>XFreeCursor</i> can generate a
<i>BadCursor</i> error.</small></p>
<p><small><b>5</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b>Chapter 6</b></p>
<p align=center><b>Color Management Functions</b></p>
<p><small>Each X window always has an associated colormap
that provides a level of indirection between pixel values
and colors displayed on the screen. Xlib provides functions
that you can use to manipulate a colormap. The X protocol
defines colors using values in the RGB color space. The RGB
color space is device dependent; rendering an RGB value on
differing output devices typically results in different
colors. Xlib also provides a means for clients to specify
color using device-independent color spaces for consistent
results across devices. Xlib supports device-independent
color spaces derivable from the CIE XYZ color space. This
includes the CIE XYZ, xyY, L*u*v*, and L*a*b* color spaces
as well as the TekHVC color space.</small></p>
<p><small>This chapter discusses how to:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="72%">
<p><small>Create, copy, and destroy a colormap</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Specify colors by name or value</small></p>
</td>
<td width="27%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="76%">
<p><small>Allocate, modify, and free color
cells</small></p>
</td>
<td width="13%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="52%">
<p><small>Read entries in a colormap</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="56%">
<p><small>Convert between color spaces</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="70%">
<p><small>Control aspects of color conversion</small></p>
</td>
<td width="19%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="66%">
<p><small>Query the color gamut of a screen</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="40%">
<p><small>Add new color spaces</small></p>
</td>
<td width="49%">
</td>
</table>
<p><small>All functions, types, and symbols in this chapter
with the prefix ‘‘Xcms’’ are defined
in <<i>X11/Xcms.h</i>>. The remaining functions and
types are defined in <<i>X11/Xlib.h</i>>.</small></p>
<p><small>Functions in this chapter manipulate the
representation of color on the screen. For each possible
value that a pixel can take in a window, there is a color
cell in the colormap. For example, if a window is 4 bits
deep, pixel values 0 through 15 are defined. A colormap is a
collection of color cells. A color cell consists of a triple
of red, green, and blue (RGB) values. The hardware imposes
limits on the number of significant bits in these values. As
each pixel is read out of display memory, the pixel is
looked up in a colormap. The RGB value of the cell
determines what color is displayed on the screen. On a
grayscale display with a black-and-white monitor, the values
are combined to determine the brightness on the
screen.</small></p>
<p><small>Typically, an application allocates color cells
or sets of color cells to obtain the desired colors. The
client can allocate read-only cells. In which case, the
pixel values for these colors can be shared among multiple
applications, and the RGB value of the cell cannot be
changed. If the client allocates read/write cells, they are
exclusively owned by the client, and the color associated
with the pixel value can be changed at will. Cells must be
allocated (and, if read/write, initialized with an RGB
value) by a client to obtain desired colors. The use of
pixel value for an unallocated cell results in an undefined
color.</small></p>
<p><small>Because colormaps are associated with windows, X
supports displays with multiple colormaps and, indeed,
different types of colormaps. If there are insufficient
colormap resources in the display, some windows will display
in their true colors, and others will display with incorrect
colors. A window manager usually controls which windows are
displayed in their true colors if more than one colormap is
required for the color resources the applications are using.
At any time, there is a set of installed colormaps for a
screen. Windows using one of the installed colormaps display
with true colors, and windows using other colormaps
generally display with incorrect colors. You can control the
set of installed colormaps by using <i>XInstallColormap</i>
and <i>XUninstallColormap</i>.</small></p>
<p><small>Colormaps are local to a particular screen.
Screens always have a default colormap, and programs
typically allocate cells out of this colormap. Generally,
you should not write applications that monopolize color
resources. Although some hardware supports multiple
colormaps installed at one time, many of the hardware
displays built today support only a single installed
colormap, so the primitives are written to encourage sharing
of colormap entries between applications.</small></p>
<p><small>The <i>DefaultColormap</i> macro returns the
default colormap. The <i>DefaultVisual</i> macro returns the
default visual type for the specified screen. Possible
visual types are <i>StaticGray</i>, <i>GrayScale</i>,
<i>StaticColor</i>, <i>PseudoColor</i>, <i>TrueColor</i>, or
<i>DirectColor</i> (see section 3.1).</small></p>
<a name="6.1. Color Structures"></a>
<h2>6.1. Color Structures</h2>
<p><small>Functions that operate only on RGB color space
values use an <i>XColor</i> structure, which
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned long pixel;/* pixel value */</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned short red, green, blue;/* rgb values
*/</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>char flags;</small></p>
</td>
<td width="50%">
<p><small>/* DoRed, DoGreen, DoBlue */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>char pad;</small></p>
</td>
<td width="50%">
</td>
</table>
<p><small>} XColor;</small></p>
<p><small>│__</small></p>
<p><small>The red, green, and blue values are always in the
range 0 to 65535 inclusive, independent of the number of
bits actually used in the display hardware. The server
scales these values down to the range used by the hardware.
Black is represented by (0,0,0), and white is represented by
(65535,65535,65535). In some functions, the flags member
controls which of the red, green, and blue members is used
and can be the inclusive OR of zero or more of <i>DoRed</i>,
<i>DoGreen</i>, and <i>DoBlue</i>.</small></p>
<p><small>Functions that operate on all color space values
use an <i>XcmsColor</i> structure. This structure contains a
union of substructures, each supporting color specification
encoding for a particular color space. Like the
<i>XColor</i> structure, the <i>XcmsColor</i> structure
contains pixel and color specification information (the spec
member in the <i>XcmsColor</i> structure).</small></p>
<p><small>__ │</small></p>
<pre><small>typedef unsigned long XcmsColorFormat;/* Color Specification Format */
typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%"></td>
<td width="10%">
<p><small>union {</small></p>
</td>
<td width="30%"></td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="10%">
</td>
<td width="30%">
<p><small>XcmsRGB RGB;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="10%">
</td>
<td width="30%">
<p><small>XcmsRGBi RGBi;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="10%">
</td>
<td width="30%">
<p><small>XcmsCIEXYZ CIEXYZ;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="10%">
</td>
<td width="30%">
<p><small>XcmsCIEuvY CIEuvY;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="10%">
</td>
<td width="30%">
<p><small>XcmsCIExyY CIExyY;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="10%">
</td>
<td width="30%">
<p><small>XcmsCIELab CIELab;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="10%">
</td>
<td width="30%">
<p><small>XcmsCIELuv CIELuv;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="10%">
</td>
<td width="30%">
<p><small>XcmsTekHVC TekHVC;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="10%">
</td>
<td width="30%">
<p><small>XcmsPad Pad;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%"></td>
<td width="10%">
<p><small>} spec;</small></p>
</td>
<td width="30%"></td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%"></td>
<td width="10%">
<p><small>unsigned long pixel;</small></p>
</td>
<td width="30%"></td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%"></td>
<td width="10%">
<p><small>XcmsColorFormat format;</small></p>
</td>
<td width="30%"></td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%">
<p><small>} XcmsColor;</small></p>
</td>
<td width="10%"></td>
<td width="30%"></td>
<td width="50%">
<p><small>/* Xcms Color Structure */</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Because the color specification can be encoded
for the various color spaces, encoding for the spec member
is identified by the format member, which is of type
<i>XcmsColorFormat</i>. The following macros define standard
formats.</small></p>
<p><small>__ │</small></p>
<p align=center><small><img src="grohtml-1439215.png"></small></p>
<p><small>│__</small></p>
<p><small>Formats for device-independent color spaces are
distinguishable from those for device-dependent spaces by
the 32nd bit. If this bit is set, it indicates that the
color specification is in a device-dependent form;
otherwise, it is in a device-independent form. If the 31st
bit is set, this indicates that the color space has been
added to Xlib at run time (see section 6.12.4). The format
value for a color space added at run time may be different
each time the program is executed. If references to such a
color space must be made outside the client (for example,
storing a color specification in a file), then reference
should be made by color space string prefix (see
<i>XcmsFormatOfPrefix</i> and
<i>XcmsPrefixOfFormat</i>).</small></p>
<p><small>Data types that describe the color specification
encoding for the various color spaces are defined as
follows:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef double XcmsFloat;
typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="40%">
<p><small>unsigned short red;</small></p>
</td>
<td width="50%">
<p><small>/* 0x0000 to 0xffff */</small></p>
</td>
<tr valign="top" align="left">
<td width="10%"></td>
<td width="40%">
<p><small>unsigned short green;/* 0x0000 to 0xffff
*/</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%"></td>
<td width="40%">
<p><small>unsigned short blue;/* 0x0000 to 0xffff
*/</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%">
<p><small>} XcmsRGB;</small></p>
</td>
<td width="40%"></td>
<td width="50%">
<p><small>/* RGB Device */</small></p>
</td>
</table>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="40%">
<p><small>XcmsFloat red;</small></p>
</td>
<td width="50%">
<p><small>/* 0.0 to 1.0 */</small></p>
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="40%">
<p><small>XcmsFloat green;</small></p>
</td>
<td width="50%">
<p><small>/* 0.0 to 1.0 */</small></p>
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="40%">
<p><small>XcmsFloat blue;</small></p>
</td>
<td width="50%">
<p><small>/* 0.0 to 1.0 */</small></p>
</td>
<tr valign="top" align="left">
<td width="10%">
<p><small>} XcmsRGBi;</small></p>
</td>
<td width="40%"></td>
<td width="50%">
<p><small>/* RGB Intensity */</small></p>
</td>
</table>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%"></td>
<td width="40%">
<p><small>XcmsFloat X;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="40%">
<p><small>XcmsFloat Y;</small></p>
</td>
<td width="50%">
<p><small>/* 0.0 to 1.0 */</small></p>
</td>
<tr valign="top" align="left">
<td width="10%"></td>
<td width="40%">
<p><small>XcmsFloat Z;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%">
<p><small>} XcmsCIEXYZ;</small></p>
</td>
<td width="40%"></td>
<td width="50%">
<p><small>/* CIE XYZ */</small></p>
</td>
</table>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="40%">
<p><small>XcmsFloat u_prime;</small></p>
</td>
<td width="50%">
<p><small>/* 0.0 to ~0.6 */</small></p>
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="40%">
<p><small>XcmsFloat v_prime;</small></p>
</td>
<td width="50%">
<p><small>/* 0.0 to ~0.6 */</small></p>
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="40%">
<p><small>XcmsFloat Y;</small></p>
</td>
<td width="50%">
<p><small>/* 0.0 to 1.0 */</small></p>
</td>
<tr valign="top" align="left">
<td width="10%">
<p><small>} XcmsCIEuvY;</small></p>
</td>
<td width="40%"></td>
<td width="50%">
<p><small>/* CIE u’v’Y */</small></p>
</td>
</table>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="40%">
<p><small>XcmsFloat x;</small></p>
</td>
<td width="50%">
<p><small>/* 0.0 to ~.75 */</small></p>
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="40%">
<p><small>XcmsFloat y;</small></p>
</td>
<td width="50%">
<p><small>/* 0.0 to ~.85 */</small></p>
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="40%">
<p><small>XcmsFloat Y;</small></p>
</td>
<td width="50%">
<p><small>/* 0.0 to 1.0 */</small></p>
</td>
<tr valign="top" align="left">
<td width="10%">
<p><small>} XcmsCIExyY;</small></p>
</td>
<td width="40%"></td>
<td width="50%">
<p><small>/* CIE xyY */</small></p>
</td>
</table>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="40%">
<p><small>XcmsFloat L_star;</small></p>
</td>
<td width="50%">
<p><small>/* 0.0 to 100.0 */</small></p>
</td>
<tr valign="top" align="left">
<td width="10%"></td>
<td width="40%">
<p><small>XcmsFloat a_star;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%"></td>
<td width="40%">
<p><small>XcmsFloat b_star;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%">
<p><small>} XcmsCIELab;</small></p>
</td>
<td width="40%"></td>
<td width="50%">
<p><small>/* CIE L*a*b* */</small></p>
</td>
</table>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="40%">
<p><small>XcmsFloat L_star;</small></p>
</td>
<td width="50%">
<p><small>/* 0.0 to 100.0 */</small></p>
</td>
<tr valign="top" align="left">
<td width="10%"></td>
<td width="40%">
<p><small>XcmsFloat u_star;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%"></td>
<td width="40%">
<p><small>XcmsFloat v_star;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%">
<p><small>} XcmsCIELuv;</small></p>
</td>
<td width="40%"></td>
<td width="50%">
<p><small>/* CIE L*u*v* */</small></p>
</td>
</table>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="40%">
<p><small>XcmsFloat H;</small></p>
</td>
<td width="50%">
<p><small>/* 0.0 to 360.0 */</small></p>
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="40%">
<p><small>XcmsFloat V;</small></p>
</td>
<td width="50%">
<p><small>/* 0.0 to 100.0 */</small></p>
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="40%">
<p><small>XcmsFloat C;</small></p>
</td>
<td width="50%">
<p><small>/* 0.0 to 100.0 */</small></p>
</td>
<tr valign="top" align="left">
<td width="10%">
<p><small>} XcmsTekHVC;</small></p>
</td>
<td width="40%"></td>
<td width="50%">
<p><small>/* TekHVC */</small></p>
</td>
</table>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%"></td>
<td width="40%">
<p><small>XcmsFloat pad0;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%"></td>
<td width="40%">
<p><small>XcmsFloat pad1;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%"></td>
<td width="40%">
<p><small>XcmsFloat pad2;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%"></td>
<td width="40%">
<p><small>XcmsFloat pad3;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="10%">
<p><small>} XcmsPad;</small></p>
</td>
<td width="40%"></td>
<td width="50%">
<p><small>/* four doubles */</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The device-dependent formats provided allow color
specification in:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="48%">
<p><small>RGB Intensity (<i>XcmsRGBi</i>)</small></p>
</td>
<td width="41%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Red, green, and blue linear intensity values,
floating-point values from 0.0 to 1.0, where 1.0 indicates
full intensity, 0.5 half intensity, and so on.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="40%">
<p><small>RGB Device (<i>XcmsRGB</i>)</small></p>
</td>
<td width="49%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Red, green, and blue values appropriate for the
specified output device. <i>XcmsRGB</i> values are of type
unsigned short, scaled from 0 to 65535 inclusive, and are
interchangeable with the red, green, and blue values in an
<i>XColor</i> structure.</small></p>
</td>
</table>
<p><small>It is important to note that RGB Intensity values
are not gamma corrected values. In contrast, RGB Device
values generated as a result of converting color
specifications are always gamma corrected, and RGB Device
values acquired as a result of querying a colormap or passed
in by the client are assumed by Xlib to be gamma corrected.
The term <i>RGB value</i> in this manual always refers to an
RGB Device value.</small></p>
<a name="6.2. Color Strings"></a>
<h2>6.2. Color Strings</h2>
<p><small>Xlib provides a mechanism for using string names
for colors. A color string may either contain an abstract
color name or a numerical color specification. Color strings
are case-insensitive.</small></p>
<p><small>Color strings are used in the following
functions:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="32%">
<p><small><i>XAllocNamedColor</i></small></p>
</td>
<td width="57%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="38%">
<p><small><i>XcmsAllocNamedColor</i></small></p>
</td>
<td width="51%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="24%">
<p><small><i>XLookupColor</i></small></p>
</td>
<td width="65%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="30%">
<p><small><i>XcmsLookupColor</i></small></p>
</td>
<td width="59%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="22%">
<p><small><i>XParseColor</i></small></p>
</td>
<td width="67%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="32%">
<p><small><i>XStoreNamedColor</i></small></p>
</td>
<td width="57%">
</td>
</table>
<p><small>Xlib supports the use of abstract color names,
for example, red or blue. A value for this abstract name is
obtained by searching one or more color name databases. Xlib
first searches zero or more client-side databases; the
number, location, and content of these databases is
implementation-dependent and might depend on the current
locale. If the name is not found, Xlib then looks for the
color in the X server’s database. If the color name is
not in the Host Portable Character Encoding, the result is
implementation-dependent.</small></p>
<p><small>A numerical color specification consists of a
color space name and a set of values in the following
syntax:</small></p>
<p><small>__ │</small></p>
<pre><small><i><color_space_name></i>:<i><value>/.../<value>
</i></small></pre>
<p><small>│__</small></p>
<p><small>The following are examples of valid color
strings.</small></p>
<pre><small>"CIEXYZ:0.3227/0.28133/0.2493"
"RGBi:1.0/0.0/0.0"
"rgb:00/ff/00"
"CIELuv:50.0/0.0/0.0"
</small></pre>
<p><small>The syntax and semantics of numerical
specifications are given for each standard color space in
the following sections.</small></p>
<a name="6.2.1. RGB Device String Specification"></a>
<h2>6.2.1. RGB Device String Specification</h2>
<p><small>An RGB Device specification is identified by the
prefix ‘‘rgb:’’ and conforms to the
following syntax:</small></p>
<pre><small>rgb:<i><red>/<green>/<blue>
<red></i>, <i><green></i>, <i><blue></i> := <i>h</i> | <i>hh</i> | <i>hhh</i> | <i>hhhh
h</i> := single hexadecimal digits (case insignificant)
</small></pre>
<p><small>Note that <i>h</i> indicates the value scaled in
4 bits, <i>hh</i> the value scaled in 8 bits, <i>hhh</i> the
value scaled in 12 bits, and <i>hhhh</i> the value scaled in
16 bits, respectively.</small></p>
<p><small>Typical examples are the strings
‘‘rgb:ea/75/52’’ and
‘‘rgb:ccc/320/320’’, but mixed
numbers of hexadecimal digit strings
(‘‘rgb:ff/a5/0’’ and
‘‘rgb:ccc/32/0’’) are also
allowed.</small></p>
<p><small>For backward compatibility, an older syntax for
RGB Device is supported, but its continued use is not
encouraged. The syntax is an initial sharp sign character
followed by a numeric specification, in one of the following
formats:</small></p>
<pre><small>#RGB (4 bits each)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="40%">
<p><small>#RRGGBB</small></p>
</td>
<td width="60%">
<p><small>(8 bits each)</small></p>
</td>
<tr valign="top" align="left">
<td width="40%">
<p><small>#RRRGGGBBB</small></p>
</td>
<td width="60%">
<p><small>(12 bits each)</small></p>
</td>
<tr valign="top" align="left">
<td width="40%">
<p><small>#RRRRGGGGBBBB</small></p>
</td>
<td width="60%">
<p><small>(16 bits each)</small></p>
</td>
</table>
<p><small>The R, G, and B represent single hexadecimal
digits. When fewer than 16 bits each are specified, they
represent the most significant bits of the value (unlike the
‘‘rgb:’’ syntax, in which values are
scaled). For example, the string
‘‘#3a7’’ is the same as
‘‘#3000a0007000’’.</small></p>
<a name="6.2.2. RGB Intensity String Specification"></a>
<h2>6.2.2. RGB Intensity String Specification</h2>
<p><small>An RGB intensity specification is identified by
the prefix ‘‘rgbi:’’ and conforms to
the following syntax:</small></p>
<pre><small>rgbi:<i><red>/<green>/<blue>
</i></small></pre>
<p><small>Note that red, green, and blue are floating-point
values between 0.0 and 1.0, inclusive. The input format for
these values is an optional sign, a string of numbers
possibly containing a decimal point, and an optional
exponent field containing an E or e followed by a possibly
signed integer string.</small></p>
<a name="6.2.3. Device-Independent String Specifications"></a>
<h2>6.2.3. Device-Independent String Specifications</h2>
<p><small>The standard device-independent string
specifications have the following syntax:</small></p>
<pre><small>CIEXYZ:<i><X>/<Y>/<Z>
</i>CIEuvY:<i><u>/<v>/<Y>
</i>CIExyY:<i><x>/<y>/<Y>
</i>CIELab:<i><L>/<a>/<b>
</i>CIELuv:<i><L>/<u>/<v>
</i>TekHVC:<i><H>/<V>/<C>
</i></small></pre>
<p><small>All of the values (C, H, V, X, Y, Z, a, b, u, v,
y, x) are floating-point values. The syntax for these values
is an optional plus or minus sign, a string of digits
possibly containing a decimal point, and an optional
exponent field consisting of an
‘‘E’’ or
‘‘e’’ followed by an optional plus
or minus followed by a string of digits.</small></p>
<a name="6.3. Color Conversion Contexts and Gamut Mapping"></a>
<h2>6.3. Color Conversion Contexts and Gamut Mapping</h2>
<p><small>When Xlib converts device-independent color
specifications into device-dependent specifications and vice
versa, it uses knowledge about the color limitations of the
screen hardware. This information, typically called the
device profile, is available in a Color Conversion Context
(CCC).</small></p>
<p><small>Because a specified color may be outside the
color gamut of the target screen and the white point
associated with the color specification may differ from the
white point inherent to the screen, Xlib applies gamut
mapping when it encounters certain conditions:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Gamut compression occurs when conversion of
device-independent color specifications to device-dependent
color specifications results in a color out of the target
screen’s gamut.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>White adjustment occurs when the inherent white
point of the screen differs from the white point assumed by
the client.</small></p>
</td>
</table>
<p><small>Gamut handling methods are stored as callbacks in
the CCC, which in turn are used by the color space
conversion routines. Client data is also stored in the CCC
for each callback. The CCC also contains the white point the
client assumes to be associated with color specifications
(that is, the Client White Point). The client can specify
the gamut handling callbacks and client data as well as the
Client White Point. Xlib does not preclude the X client from
performing other forms of gamut handling (for example, gamut
expansion); however, Xlib does not provide direct support
for gamut handling other than white adjustment and gamut
compression.</small></p>
<p><small>Associated with each colormap is an initial CCC
transparently generated by Xlib. Therefore, when you specify
a colormap as an argument to an Xlib function, you are
indirectly specifying a CCC. There is a default CCC
associated with each screen. Newly created CCCs inherit
attributes from the default CCC, so the default CCC
attributes can be modified to affect new CCCs.</small></p>
<p><small>Xcms functions in which gamut mapping can occur
return <i>Status</i> and have specific status values defined
for them, as follows:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>XcmsFailure</i> indicates that the function
failed.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>XcmsSuccess</i> indicates that the function
succeeded. In addition, if the function performed any color
conversion, the colors did not need to be
compressed.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>XcmsSuccessWithCompression</i> indicates the
function performed color conversion and at least one of the
colors needed to be compressed. The gamut compression method
is determined by the gamut compression procedure in the CCC
that is specified directly as a function argument or in the
CCC indirectly specified by means of the colormap
argument.</small></p>
</td>
</table>
<a name="6.4. Creating, Copying, and Destroying Colormaps"></a>
<h2>6.4. Creating, Copying, and Destroying Colormaps</h2>
<p><small>To create a colormap for a screen, use
<i>XCreateColormap</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Colormap XCreateColormap(<i>display</i>, <i>w</i>, <i>visual</i>, <i>alloc</i>)
Display *<i>display</i>;
Window <i>w</i>;
Visual *<i>visual</i>;
int <i>alloc</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the window on whose screen you want to
create a colormap.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>visual</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies a visual type supported on the screen.
If the visual type is not one supported by the screen, a
<i>BadMatch</i> error results.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>alloc</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the colormap entries to be allocated.
You can pass <i>AllocNone</i> or
<i>AllocAll</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XCreateColormap</i> 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.</small></p>
<p><small>The initial values of the colormap entries are
undefined for the visual classes <i>GrayScale</i>,
<i>PseudoColor</i>, and <i>DirectColor</i>. For
<i>StaticGray</i>, <i>StaticColor</i>, and <i>TrueColor</i>,
the entries have defined values, but those values are
specific to the visual and are not defined by X. For
<i>StaticGray</i>, <i>StaticColor</i>, and <i>TrueColor</i>,
alloc must be <i>AllocNone</i>, or a <i>BadMatch</i> error
results. For the other visual classes, if alloc is
<i>AllocNone</i>, the colormap initially has no allocated
entries, and clients can allocate them. For information
about the visual types, see section 3.1.</small></p>
<p><small>If alloc is <i>AllocAll</i>, the entire colormap
is allocated writable. The initial values of all allocated
entries are undefined. For <i>GrayScale</i> and
<i>PseudoColor</i>, the effect is as if an
<i>XAllocColorCells</i> call returned all pixel values from
zero to N − 1, where N is the colormap entries value
in the specified visual. For <i>DirectColor</i>, the effect
is as if an <i>XAllocColorPlanes</i> 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
<i>XFreeColors</i>.</small></p>
<p><small><i>XCreateColormap</i> can generate
<i>BadAlloc</i>, <i>BadMatch</i>, <i>BadValue</i>, and
<i>BadWindow</i> errors.</small></p>
<p><small>To create a new colormap when the allocation out
of a previously shared colormap has failed because of
resource exhaustion, use
<i>XCopyColormapAndFree</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Colormap XCopyColormapAndFree(<i>display</i>, <i>colormap</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XCopyColormapAndFree</i> 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 <i>AllocAll</i>, the
new colormap is also created with <i>AllocAll</i>, 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 <i>AllocAll</i>, the allocations to be moved are
all those pixels and planes that have been allocated by the
client using <i>XAllocColor</i>, <i>XAllocNamedColor</i>,
<i>XAllocColorCells</i>, or <i>XAllocColorPlanes</i> and
that have not been freed since they were
allocated.</small></p>
<p><small><i>XCopyColormapAndFree</i> can generate
<i>BadAlloc</i> and <i>BadColor</i> errors.</small></p>
<p><small>To destroy a colormap, use
<i>XFreeColormap</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XFreeColormap(<i>display</i>, <i>colormap</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the colormap that you want to
destroy.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XFreeColormap</i> 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 <i>XUninstallColormap</i>). If the
specified colormap is defined as the colormap for a window
(by <i>XCreateWindow</i>, <i>XSetWindowColormap</i>, or
<i>XChangeWindowAttributes</i>), <i>XFreeColormap</i>
changes the colormap associated with the window to
<i>None</i> and generates a <i>ColormapNotify</i> event. X
does not define the colors displayed for a window with a
colormap of <i>None</i>.</small></p>
<p><small><i>XFreeColormap</i> can generate a
<i>BadColor</i> error.</small></p>
<a name="6.5. Mapping Color Names to Values"></a>
<h2>6.5. Mapping Color Names to Values</h2>
<p><small>To map a color name to an RGB value, use
<i>XLookupColor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XLookupColor(<i>display</i>, <i>colormap</i>, <i>color_name</i>, <i>exact_def_return</i>, <i>screen_def_return</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
char *<i>color_name</i>;
XColor *<i>exact_def_return</i>, *<i>screen_def_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small><i>color_name</i> Specifies the color name string
(for example, red) whose color definition structure you want
returned.</small></p>
<p><small><i>exact_def_return</i> Returns the exact RGB
values.</small></p>
<p><small><i>screen_def_return</i> Returns the closest RGB
values provided by the hardware.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XLookupColor</i> function looks up the
string name of a color with respect to the screen associated
with the specified colormap. It returns both the exact color
values and the closest values provided by the screen with
respect to the visual type of the specified colormap. 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. <i>XLookupColor</i> returns
nonzero if the name is resolved; otherwise, it returns
zero.</small></p>
<p><small><i>XLookupColor</i> can generate a
<i>BadColor</i> error.</small></p>
<p><small>To map a color name to the exact RGB value, use
<i>XParseColor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XParseColor(<i>display</i>, <i>colormap</i>, <i>spec</i>, <i>exact_def_return</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
char *<i>spec</i>;
XColor *<i>exact_def_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>spec</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the color name string; case is
ignored.</small></p>
</td>
</table>
<p><small><i>exact_def_return</i> Returns the exact color
value for later use and sets the <i>DoRed</i>,
<i>DoGreen</i>, and <i>DoBlue</i> flags.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XParseColor</i> function looks up the
string name of a color with respect to the screen associated
with the specified colormap. It returns the exact color
value. 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.
<i>XParseColor</i> returns nonzero if the name is resolved;
otherwise, it returns zero.</small></p>
<p><small><i>XParseColor</i> can generate a <i>BadColor</i>
error.</small></p>
<p><small>To map a color name to a value in an arbitrary
color space, use <i>XcmsLookupColor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsLookupColor(<i>display</i>, <i>colormap</i>, <i>color_string</i>, <i>color_exact_return</i>, <i>color_screen_return</i>,
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
</td>
<td width="40%">
<p><small><i>result_format</i>)</small></p>
</td>
</table>
<p><small>Display *<i>display</i>;<br>
Colormap <i>colormap</i>;<br>
char *<i>color_string</i>;<br>
XcmsColor *<i>color_exact_return</i>,
*<i>color_screen_return</i>;<br>
XcmsColorFormat <i>result_format</i>;</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small><i>color_string</i> Specifies the color
string.</small></p>
<p><small><i>color_exact_return</i> Returns the color
specification parsed from the color string or parsed from
the corresponding string found in a color-name
database.</small></p>
<p><small><i>color_screen_return</i> Returns the color that
can be reproduced on the screen.</small></p>
<p><small><i>result_format</i> Specifies the color format
for the returned color specifications (color_screen_return
and color_exact_return arguments). If the format is
<i>XcmsUndefinedFormat</i> and the color string contains a
numerical color specification, the specification is returned
in the format used in that numerical color specification. If
the format is <i>XcmsUndefinedFormat</i> and the color
string contains a color name, the specification is returned
in the format used to store the color in the
database.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsLookupColor</i> function looks up the
string name of a color with respect to the screen associated
with the specified colormap. It returns both the exact color
values and the closest values provided by the screen with
respect to the visual type of the specified colormap. The
values are returned in the format specified by
result_format. 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.
<i>XcmsLookupColor</i> returns <i>XcmsSuccess</i> or
<i>XcmsSuccessWithCompression</i> if the name is resolved;
otherwise, it returns <i>XcmsFailure</i>. If
<i>XcmsSuccessWithCompression</i> is returned, the color
specification returned in color_screen_return is the result
of gamut compression.</small></p>
<a name="6.6. Allocating and Freeing Color Cells"></a>
<h2>6.6. Allocating and Freeing Color Cells</h2>
<p><small>There are two ways of allocating color cells:
explicitly as read-only entries, one pixel value at a time,
or read/write, where you can allocate a number of color
cells and planes simultaneously. A read-only cell has its
RGB value set by the server. Read/write cells do not have
defined colors initially; functions described in the next
section must be used to store values into them. Although it
is possible for any client to store values into a read/write
cell allocated by another client, read/write cells normally
should be considered private to the client that allocated
them.</small></p>
<p><small>Read-only colormap cells are shared among
clients. The server counts each allocation and freeing of
the cell by clients. When the last client frees a shared
cell, the cell is finally deallocated. If a single client
allocates the same read-only cell multiple times, the server
counts each such allocation, not just the first
one.</small></p>
<p><small>To allocate a read-only color cell with an RGB
value, use <i>XAllocColor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XAllocColor(<i>display</i>, <i>colormap</i>, <i>screen_in_out</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
XColor *<i>screen_in_out</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small><i>screen_in_out</i> Specifies and returns the
values actually used in the colormap.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XAllocColor</i> function allocates a
read-only colormap entry corresponding to the closest RGB
value supported by the hardware. <i>XAllocColor</i> 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.
In addition, <i>XAllocColor</i> returns nonzero if it
succeeded or zero if it failed. 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. <i>XAllocColor</i> does not use or affect the
flags in the <i>XColor</i> structure.</small></p>
<p><small><i>XAllocColor</i> can generate a <i>BadColor</i>
error.</small></p>
<p><small>To allocate a read-only color cell with a color
in arbitrary format, use <i>XcmsAllocColor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsAllocColor(<i>display</i>, <i>colormap</i>, <i>color_in_out</i>, <i>result_format</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
XcmsColor *<i>color_in_out</i>;
XcmsColorFormat <i>result_format</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small><i>color_in_out</i> Specifies the color to
allocate and returns the pixel and color that is actually
used in the colormap.</small></p>
<p><small><i>result_format</i> Specifies the color format
for the returned color specification.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsAllocColor</i> function is similar to
<i>XAllocColor</i> except the color can be specified in any
format. The <i>XcmsAllocColor</i> function ultimately calls
<i>XAllocColor</i> to allocate a read-only color cell
(colormap entry) with the specified color.
<i>XcmsAllocColor</i> first converts the color specified to
an RGB value and then passes this to <i>XAllocColor</i>.
<i>XcmsAllocColor</i> returns the pixel value of the color
cell and the color specification actually allocated. This
returned color specification is the result of converting the
RGB value returned by <i>XAllocColor</i> into the format
specified with the result_format argument. If there is no
interest in a returned color specification, unnecessary
computation can be bypassed if result_format is set to
<i>XcmsRGBFormat</i>. The corresponding colormap cell is
read-only. If this routine returns <i>XcmsFailure</i>, the
color_in_out color specification is left
unchanged.</small></p>
<p><small><i>XcmsAllocColor</i> can generate a
<i>BadColor</i> error.</small></p>
<p><small>To allocate a read-only color cell using a color
name and return the closest color supported by the hardware
in RGB format, use <i>XAllocNamedColor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XAllocNamedColor(<i>display</i>, <i>colormap</i>, <i>color_name</i>, <i>screen_def_return</i>, <i>exact_def_return</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
char *<i>color_name</i>;
XColor *<i>screen_def_return</i>, *<i>exact_def_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small><i>color_name</i> Specifies the color name string
(for example, red) whose color definition structure you want
returned.</small></p>
<p><small><i>screen_def_return</i> Returns the closest RGB
values provided by the hardware.</small></p>
<p><small><i>exact_def_return</i> Returns the exact RGB
values.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XAllocNamedColor</i> 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_return. 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_return and exact_def_return point
to the same structure, the pixel field will be set
correctly, but the color values are undefined.
<i>XAllocNamedColor</i> returns nonzero if a cell is
allocated; otherwise, it returns zero.</small></p>
<p><small><i>XAllocNamedColor</i> can generate a
<i>BadColor</i> error.</small></p>
<p><small>To allocate a read-only color cell using a color
name and return the closest color supported by the hardware
in an arbitrary format, use
<i>XcmsAllocNamedColor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsAllocNamedColor(<i>display</i>, <i>colormap</i>, <i>color_string</i>, <i>color_screen_return</i>, <i>color_exact_return</i>,
<i> result_format</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
char *<i>color_string</i>;
XcmsColor *<i>color_screen_return</i>;
XcmsColor *<i>color_exact_return</i>;
XcmsColorFormat <i>result_format</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small><i>color_string</i> Specifies the color string
whose color definition structure is to be
returned.</small></p>
<p><small><i>color_screen_return</i> Returns the pixel
value of the color cell and color specification that
actually is stored for that cell.</small></p>
<p><small><i>color_exact_return</i> Returns the color
specification parsed from the color string or parsed from
the corresponding string found in a color-name
database.</small></p>
<p><small><i>result_format</i> Specifies the color format
for the returned color specifications (color_screen_return
and color_exact_return arguments). If the format is
<i>XcmsUndefinedFormat</i> and the color string contains a
numerical color specification, the specification is returned
in the format used in that numerical color specification. If
the format is <i>XcmsUndefinedFormat</i> and the color
string contains a color name, the specification is returned
in the format used to store the color in the
database.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsAllocNamedColor</i> function is
similar to <i>XAllocNamedColor</i> except that the color
returned can be in any format specified. This function
ultimately calls <i>XAllocColor</i> to allocate a read-only
color cell with the color specified by a color string. The
color string is parsed into an <i>XcmsColor</i> structure
(see <i>XcmsLookupColor</i>), converted to an RGB value, and
finally passed to <i>XAllocColor</i>. 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.</small></p>
<p><small>This function returns both the color
specification as a result of parsing (exact specification)
and the actual color specification stored (screen
specification). This screen specification is the result of
converting the RGB value returned by <i>XAllocColor</i> into
the format specified in result_format. If there is no
interest in a returned color specification, unnecessary
computation can be bypassed if result_format is set to
<i>XcmsRGBFormat</i>. If color_screen_return and
color_exact_return point to the same structure, the pixel
field will be set correctly, but the color values are
undefined.</small></p>
<p><small><i>XcmsAllocNamedColor</i> can generate a
<i>BadColor</i> error.</small></p>
<p><small>To allocate read/write color cell and color plane
combinations for a <i>PseudoColor</i> model, use
<i>XAllocColorCells</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XAllocColorCells(<i>display</i>, <i>colormap</i>, <i>contig</i>, <i>plane_masks_return</i>, <i>nplanes</i>,
<i> pixels_return</i>, <i>npixels</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
Bool <i>contig</i>;
unsigned long <i>plane_masks_return</i>[];
unsigned int <i>nplanes</i>;
unsigned long <i>pixels_return</i>[];
unsigned int <i>npixels</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>contig</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies a Boolean value that indicates whether
the planes must be contiguous.</small></p>
</td>
</table>
<p><small><i>plane_mask_return</i> Returns an array of
plane masks.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>nplanes</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the number of plane masks that are to
be returned in the plane masks array.</small></p>
</td>
</table>
<p><small><i>pixels_return</i> Returns an array of pixel
values.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>npixels</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the number of pixel values that are to
be returned in the pixels_return array.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XAllocColorCells</i> function allocates
read/write color cells. The number of colors must be
positive and the number of planes nonnegative, or a
<i>BadValue</i> error results. If ncolors and nplanes are
requested, then ncolors pixels and nplane plane masks are
returned. No mask will have any bits set to 1 in common with
any other mask or with any of the pixels. By ORing together
each pixel with zero or more masks, ncolors *
<img src="grohtml-14392-18.png"> distinct pixels can be
produced. All of these are allocated writable by the
request. For <i>GrayScale</i> or <i>PseudoColor</i>, each
mask has exactly one bit set to 1. For <i>DirectColor</i>,
each has exactly three bits set to 1. If contig is
<i>True</i> and if all masks are ORed together, a single
contiguous set of bits set to 1 will be formed for
<i>GrayScale</i> or <i>PseudoColor</i> and three contiguous
sets of bits set to 1 (one within each pixel subfield) for
<i>DirectColor</i>. The RGB values of the allocated entries
are undefined. <i>XAllocColorCells</i> returns nonzero if it
succeeded or zero if it failed.</small></p>
<p><small><i>XAllocColorCells</i> can generate
<i>BadColor</i> and <i>BadValue</i> errors.</small></p>
<p><small>To allocate read/write color resources for a
<i>DirectColor</i> model, use
<i>XAllocColorPlanes</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XAllocColorPlanes(<i>display</i>, <i>colormap</i>, <i>contig</i>, <i>pixels_return</i>, <i>ncolors</i>, <i>nreds</i>, <i>ngreens</i>,
<i> nblues</i>, <i>rmask_return</i>, <i>gmask_return</i>, <i>bmask_return</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
Bool <i>contig</i>;
unsigned long <i>pixels_return</i>[];
int <i>ncolors</i>;
int <i>nreds</i>, <i>ngreens</i>, <i>nblues</i>;
unsigned long *<i>rmask_return</i>, *<i>gmask_return</i>, *<i>bmask_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>contig</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies a Boolean value that indicates whether
the planes must be contiguous.</small></p>
</td>
</table>
<p><small><i>pixels_return</i> Returns an array of pixel
values. <i>XAllocColorPlanes</i> returns the pixel values in
this array.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>ncolors</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the number of pixel values that are to
be returned in the pixels_return array.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>nreds</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>ngreens</i></small></p>
</td>
<td width="85%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>nblues</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the number of red, green, and blue
planes. The value you pass must be nonnegative.</small></p>
</td>
</table>
<p><small><i>rmask_return</i></small></p>
<p><small><i>gmask_return</i></small></p>
<p><small><i>bmask_return</i> Return bit masks for the red,
green, and blue planes.</small></p>
<p><small>│__</small></p>
<p><small>The specified ncolors must be positive; and
nreds, ngreens, and nblues must be nonnegative, or a
<i>BadValue</i> 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 <i>True</i>, 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
<i>DirectColor</i>, each mask will lie within the
corresponding pixel subfield. By ORing together subsets of
masks with each pixel value, ncolors *
<img src="grohtml-14392-20.png"> distinct pixel values can
be produced. All of these are allocated by the request.
However, in the colormap, there are only ncolors *
<img src="grohtml-14392-21.png"> independent red entries,
ncolors * <img src="grohtml-14392-22.png"> independent green
entries, and ncolors * <img src="grohtml-14392-23.png">
independent blue entries. This is true even for
<i>PseudoColor</i>. When the colormap entry of a pixel value
is changed (using <i>XStoreColors</i>, <i>XStoreColor</i>,
or <i>XStoreNamedColor</i>), the pixel is decomposed
according to the masks, and the corresponding independent
entries are updated. <i>XAllocColorPlanes</i> returns
nonzero if it succeeded or zero if it failed.</small></p>
<p><small><i>XAllocColorPlanes</i> can generate
<i>BadColor</i> and <i>BadValue</i> errors.</small></p>
<p><small>To free colormap cells, use
<i>XFreeColors</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XFreeColors(<i>display</i>, <i>colormap</i>, <i>pixels</i>, <i>npixels</i>, <i>planes</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
unsigned long <i>pixels</i>[];
int <i>npixels</i>;
unsigned long <i>planes</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>pixels</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies an array of pixel values that map to
the cells in the specified colormap.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>npixels</i></small></p>
</td>
<td width="6%"></td>
<td width="62%">
<p><small>Specifies the number of pixels.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>planes</i></small></p>
</td>
<td width="8%"></td>
<td width="76%">
<p><small>Specifies the planes you want to
free.</small></p>
</td>
<td width="3%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XFreeColors</i> 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 <i>XAllocColor</i>,
<i>XAllocNamedColor</i>, <i>XAllocColorCells</i>, and
<i>XAllocColorPlanes</i>). Note that freeing an individual
pixel obtained from <i>XAllocColorPlanes</i> 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.</small></p>
<p><small>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 <i>BadValue</i> 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 <i>AllocAll</i> to <i>XCreateColormap</i>), a
<i>BadAccess</i> error results. If more than one pixel is in
error, the one that gets reported is arbitrary.</small></p>
<p><small><i>XFreeColors</i> can generate <i>BadAccess</i>,
<i>BadColor</i>, and <i>BadValue</i> errors.</small></p>
<a name="6.7. Modifying and Querying Colormap Cells"></a>
<h2>6.7. Modifying and Querying Colormap Cells</h2>
<p><small>To store an RGB value in a single colormap cell,
use <i>XStoreColor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XStoreColor(<i>display</i>, <i>colormap</i>, <i>color</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
XColor *<i>color</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>color</i></small></p>
</td>
<td width="10%"></td>
<td width="70%">
<p><small>Specifies the pixel and RGB values.</small></p>
</td>
<td width="9%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XStoreColor</i> function changes the
colormap entry of the pixel value specified in the pixel
member of the <i>XColor</i> structure. You specified this
value in the pixel member of the <i>XColor</i> structure.
This pixel value must be a read/write cell and a valid index
into the colormap. If a specified pixel is not a valid index
into the colormap, a <i>BadValue</i> error results.
<i>XStoreColor</i> also changes the red, green, and/or blue
color components. You specify which color components are to
be changed by setting <i>DoRed</i>, <i>DoGreen</i>, and/or
<i>DoBlue</i> in the flags member of the <i>XColor</i>
structure. If the colormap is an installed map for its
screen, the changes are visible immediately.</small></p>
<p><small><i>XStoreColor</i> can generate <i>BadAccess</i>,
<i>BadColor</i>, and <i>BadValue</i> errors.</small></p>
<p><small>To store multiple RGB values in multiple colormap
cells, use <i>XStoreColors</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XStoreColors(<i>display</i>, <i>colormap</i>, <i>color</i>, <i>ncolors</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
XColor <i>color</i>[];
int <i>ncolors</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>color</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies an array of color definition structures
to be stored.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>ncolors</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the number of <i>XColor</i> structures
in the color definition array.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XStoreColors</i> function changes the
colormap entries of the pixel values specified in the pixel
members of the <i>XColor</i> structures. You specify which
color components are to be changed by setting <i>DoRed</i>,
<i>DoGreen</i>, and/or <i>DoBlue</i> in the flags member of
the <i>XColor</i> structures. If the colormap is an
installed map for its screen, the changes are visible
immediately. <i>XStoreColors</i> changes the specified
pixels if they are allocated writable in the colormap by any
client, even if one or more pixels generates an error. If a
specified pixel is not a valid index into the colormap, a
<i>BadValue</i> error results. If a specified pixel either
is unallocated or is allocated read-only, a <i>BadAccess</i>
error results. If more than one pixel is in error, the one
that gets reported is arbitrary.</small></p>
<p><small><i>XStoreColors</i> can generate
<i>BadAccess</i>, <i>BadColor</i>, and <i>BadValue</i>
errors.</small></p>
<p><small>To store a color of arbitrary format in a single
colormap cell, use <i>XcmsStoreColor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsStoreColor(<i>display</i>, <i>colormap</i>, <i>color</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
XcmsColor *<i>color</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>color</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the color cell and the color to store.
Values specified in this <i>XcmsColor</i> structure remain
unchanged on return.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XcmsStoreColor</i> function converts the
color specified in the <i>XcmsColor</i> structure into RGB
values. It then uses this RGB specification in an
<i>XColor</i> structure, whose three flags (<i>DoRed</i>,
<i>DoGreen</i>, and <i>DoBlue</i>) are set, in a call to
<i>XStoreColor</i> to change the color cell specified by the
pixel member of the <i>XcmsColor</i> structure. This pixel
value must be a valid index for the specified colormap, and
the color cell specified by the pixel value must be a
read/write cell. If the pixel value is not a valid index, a
<i>BadValue</i> error results. If the color cell is
unallocated or is allocated read-only, a <i>BadAccess</i>
error results. If the colormap is an installed map for its
screen, the changes are visible immediately.</small></p>
<p><small>Note that <i>XStoreColor</i> has no return value;
therefore, an <i>XcmsSuccess</i> return value from this
function indicates that the conversion to RGB succeeded and
the call to <i>XStoreColor</i> was made. To obtain the
actual color stored, use <i>XcmsQueryColor</i>. Because of
the screen’s hardware limitations or gamut
compression, the color stored in the colormap may not be
identical to the color specified.</small></p>
<p><small><i>XcmsStoreColor</i> can generate
<i>BadAccess</i>, <i>BadColor</i>, and <i>BadValue</i>
errors.</small></p>
<p><small>To store multiple colors of arbitrary format in
multiple colormap cells, use
<i>XcmsStoreColors</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsStoreColors(<i>display</i>, <i>colormap</i>, <i>colors</i>, <i>ncolors</i>, <i>compression_flags_return</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
XcmsColor <i>colors</i>[];
int <i>ncolors</i>;
Bool <i>compression_flags_return</i>[];
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>colors</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the color specification array of
<i>XcmsColor</i> structures, each specifying a color cell
and the color to store in that cell. Values specified in the
array remain unchanged upon return.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>ncolors</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the number of <i>XcmsColor</i>
structures in the color-specification array.</small></p>
</td>
</table>
<p><small><i>compression_flags_return</i> Returns an array
of Boolean values indicating compression status. If a
non-NULL pointer is supplied, each element of the array is
set to <i>True</i> if the corresponding color was compressed
and <i>False</i> otherwise. Pass NULL if the compression
status is not useful.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsStoreColors</i> function converts the
colors specified in the array of <i>XcmsColor</i> structures
into RGB values and then uses these RGB specifications in
<i>XColor</i> structures, whose three flags (<i>DoRed</i>,
<i>DoGreen</i>, and <i>DoBlue</i>) are set, in a call to
<i>XStoreColors</i> to change the color cells specified by
the pixel member of the corresponding <i>XcmsColor</i>
structure. Each pixel value must be a valid index for the
specified colormap, and the color cell specified by each
pixel value must be a read/write cell. If a pixel value is
not a valid index, a <i>BadValue</i> error results. If a
color cell is unallocated or is allocated read-only, a
<i>BadAccess</i> error results. If more than one pixel is in
error, the one that gets reported is arbitrary. If the
colormap is an installed map for its screen, the changes are
visible immediately.</small></p>
<p><small>Note that <i>XStoreColors</i> has no return
value; therefore, an <i>XcmsSuccess</i> return value from
this function indicates that conversions to RGB succeeded
and the call to <i>XStoreColors</i> was made. To obtain the
actual colors stored, use <i>XcmsQueryColors</i>. Because of
the screen’s hardware limitations or gamut
compression, the colors stored in the colormap may not be
identical to the colors specified.</small></p>
<p><small><i>XcmsStoreColors</i> can generate
<i>BadAccess</i>, <i>BadColor</i>, and <i>BadValue</i>
errors.</small></p>
<p><small>To store a color specified by name in a single
colormap cell, use <i>XStoreNamedColor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XStoreNamedColor(<i>display</i>, <i>colormap</i>, <i>color</i>, <i>pixel</i>, <i>flags</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
char *<i>color</i>;
unsigned long <i>pixel</i>;
int <i>flags</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>color</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the color name string (for example,
red).</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>pixel</i></small></p>
</td>
<td width="10%"></td>
<td width="72%">
<p><small>Specifies the entry in the colormap.</small></p>
</td>
<td width="7%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>flags</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies which red, green, and blue components
are set.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XStoreNamedColor</i> function looks up the
named color with respect to the screen associated with the
colormap and stores the result in the specified colormap.
The pixel argument determines the entry in the colormap. The
flags argument determines which of the red, green, and blue
components are set. You can set this member to the bitwise
inclusive OR of the bits <i>DoRed</i>, <i>DoGreen</i>, and
<i>DoBlue</i>. 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 the
specified pixel is not a valid index into the colormap, a
<i>BadValue</i> error results. If the specified pixel either
is unallocated or is allocated read-only, a <i>BadAccess</i>
error results.</small></p>
<p><small><i>XStoreNamedColor</i> can generate
<i>BadAccess</i>, <i>BadColor</i>, <i>BadName</i>, and
<i>BadValue</i> errors.</small></p>
<p><small>The <i>XQueryColor</i> and <i>XQueryColors</i>
functions take pixel values in the pixel member of
<i>XColor</i> structures and store in the structures the RGB
values for those pixels from the specified colormap. The
values returned for an unallocated entry are undefined.
These functions also set the flags member in the
<i>XColor</i> structure to all three colors. If a pixel is
not a valid index into the specified colormap, a
<i>BadValue</i> error results. If more than one pixel is in
error, the one that gets reported is arbitrary.</small></p>
<p><small>To query the RGB value of a single colormap cell,
use <i>XQueryColor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XQueryColor(<i>display</i>, <i>colormap</i>, <i>def_in_out</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
XColor *<i>def_in_out</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small><i>def_in_out</i> Specifies and returns the RGB
values for the pixel specified in the structure.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XQueryColor</i> function returns the
current RGB value for the pixel in the <i>XColor</i>
structure and sets the <i>DoRed</i>, <i>DoGreen</i>, and
<i>DoBlue</i> flags.</small></p>
<p><small><i>XQueryColor</i> can generate <i>BadColor</i>
and <i>BadValue</i> errors.</small></p>
<p><small>To query the RGB values of multiple colormap
cells, use <i>XQueryColors</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XQueryColors(<i>display</i>, <i>colormap</i>, <i>defs_in_out</i>, <i>ncolors</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
XColor <i>defs_in_out</i>[];
int <i>ncolors</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small><i>defs_in_out</i> Specifies and returns an array
of color definition structures for the pixel specified in
the structure.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>ncolors</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the number of <i>XColor</i> structures
in the color definition array.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XQueryColors</i> function returns the RGB
value for each pixel in each <i>XColor</i> structure and
sets the <i>DoRed</i>, <i>DoGreen</i>, and <i>DoBlue</i>
flags in each structure.</small></p>
<p><small><i>XQueryColors</i> can generate <i>BadColor</i>
and <i>BadValue</i> errors.</small></p>
<p><small>To query the color of a single colormap cell in
an arbitrary format, use <i>XcmsQueryColor</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsQueryColor(<i>display</i>, <i>colormap</i>, <i>color_in_out</i>, <i>result_format</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
XcmsColor *<i>color_in_out</i>;
XcmsColorFormat <i>result_format</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small><i>color_in_out</i> Specifies the pixel member
that indicates the color cell to query. The color
specification stored for the color cell is returned in this
<i>XcmsColor</i> structure.</small></p>
<p><small><i>result_format</i> Specifies the color format
for the returned color specification.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsQueryColor</i> function obtains the
RGB value for the pixel value in the pixel member of the
specified <i>XcmsColor</i> structure and then converts the
value to the target format as specified by the result_format
argument. If the pixel is not a valid index in the specified
colormap, a <i>BadValue</i> error results.</small></p>
<p><small><i>XcmsQueryColor</i> can generate
<i>BadColor</i> and <i>BadValue</i> errors.</small></p>
<p><small>To query the color of multiple colormap cells in
an arbitrary format, use <i>XcmsQueryColors</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsQueryColors(<i>display</i>, <i>colormap</i>, <i>colors_in_out</i>, <i>ncolors</i>, <i>result_format</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
XcmsColor <i>colors_in_out</i>[];
unsigned int <i>ncolors</i>;
XcmsColorFormat <i>result_format</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small><i>colors_in_out</i> Specifies an array of
<i>XcmsColor</i> structures, each pixel member indicating
the color cell to query. The color specifications for the
color cells are returned in these structures.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>ncolors</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the number of <i>XcmsColor</i>
structures in the color-specification array.</small></p>
</td>
</table>
<p><small><i>result_format</i> Specifies the color format
for the returned color specification.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsQueryColors</i> function obtains the
RGB values for pixel values in the pixel members of
<i>XcmsColor</i> structures and then converts the values to
the target format as specified by the result_format
argument. If a pixel is not a valid index into the specified
colormap, a <i>BadValue</i> error results. If more than one
pixel is in error, the one that gets reported is
arbitrary.</small></p>
<p><small><i>XcmsQueryColors</i> can generate
<i>BadColor</i> and <i>BadValue</i> errors.</small></p>
<a name="6.8. Color Conversion Context Functions"></a>
<h2>6.8. Color Conversion Context Functions</h2>
<p><small>This section describes functions to create,
modify, and query Color Conversion Contexts
(CCCs).</small></p>
<p><small>Associated with each colormap is an initial CCC
transparently generated by Xlib. Therefore, when you specify
a colormap as an argument to a function, you are indirectly
specifying a CCC. The CCC attributes that can be modified by
the X client are:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="36%">
<p><small>Client White Point</small></p>
</td>
<td width="53%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="86%">
<p><small>Gamut compression procedure and client
data</small></p>
</td>
<td width="3%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>White point adjustment procedure and client
data</small></p>
</td>
</table>
<p><small>The initial values for these attributes are
implementation specific. The CCC attributes for subsequently
created CCCs can be defined by changing the CCC attributes
of the default CCC. There is a default CCC associated with
each screen.</small></p>
<a name="6.8.1. Getting and Setting the Color Conversion Context of a Colormap"></a>
<h2>6.8.1. Getting and Setting the Color Conversion Context of a Colormap</h2>
<p><small>To obtain the CCC associated with a colormap, use
<i>XcmsCCCOfColormap</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XcmsCCC XcmsCCCOfColormap(<i>display</i>, <i>colormap</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XcmsCCCOfColormap</i> function returns the
CCC associated with the specified colormap. Once obtained,
the CCC attributes can be queried or modified. Unless the
CCC associated with the specified colormap is changed with
<i>XcmsSetCCCOfColormap</i>, this CCC is used when the
specified colormap is used as an argument to color
functions.</small></p>
<p><small>To change the CCC associated with a colormap, use
<i>XcmsSetCCCOfColormap</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XcmsCCC XcmsSetCCCOfColormap(<i>display</i>, <i>colormap</i>, <i>ccc</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
XcmsCCC <i>ccc</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="36%">
<p><small>Specifies the CCC.</small></p>
</td>
<td width="43%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XcmsSetCCCOfColormap</i> function changes
the CCC associated with the specified colormap. It returns
the CCC previously associated with the colormap. If they are
not used again in the application, CCCs should be freed by
calling <i>XcmsFreeCCC</i>. Several colormaps may share the
same CCC without restriction; this includes the CCCs
generated by Xlib with each colormap. Xlib, however, creates
a new CCC with each new colormap.</small></p>
<a name="6.8.2. Obtaining the Default Color Conversion Context"></a>
<h2>6.8.2. Obtaining the Default Color Conversion Context</h2>
<p><small>You can change the default CCC attributes for
subsequently created CCCs by changing the CCC attributes of
the default CCC. A default CCC is associated with each
screen.</small></p>
<p><small>To obtain the default CCC for a screen, use
<i>XcmsDefaultCCC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XcmsCCC XcmsDefaultCCC(<i>display</i>, <i>screen_number</i>)
Display *<i>display</i>;
int <i>screen_number</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsDefaultCCC</i> function returns the
default CCC for the specified screen. Its visual is the
default visual of the screen. Its initial gamut compression
and white point adjustment procedures as well as the
associated client data are implementation
specific.</small></p>
<a name="6.8.3. Color Conversion Context Macros"></a>
<h2>6.8.3. Color Conversion Context Macros</h2>
<p><small>Applications should not directly modify any part
of the <i>XcmsCCC</i>. The following lists the C language
macros, their corresponding function equivalents for other
language bindings, and what data they both can
return.</small></p>
<p><small>__ │</small></p>
<pre><small>DisplayOfCCC(<i>ccc</i>)
XcmsCCC <i>ccc</i>;
Display *XcmsDisplayOfCCC(<i>ccc</i>)
XcmsCCC <i>ccc</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="36%">
<p><small>Specifies the CCC.</small></p>
</td>
<td width="43%">
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the display associated with the
specified CCC.</small></p>
<p><small>__ │</small></p>
<pre><small>VisualOfCCC(<i>ccc</i>)
XcmsCCC <i>ccc</i>;
Visual *XcmsVisualOfCCC(<i>ccc</i>)
XcmsCCC <i>ccc</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="36%">
<p><small>Specifies the CCC.</small></p>
</td>
<td width="43%">
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the visual associated with the
specified CCC.</small></p>
<p><small>__ │</small></p>
<pre><small>ScreenNumberOfCCC(<i>ccc</i>)
XcmsCCC <i>ccc</i>;
int XcmsScreenNumberOfCCC(<i>ccc</i>)
XcmsCCC <i>ccc</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="36%">
<p><small>Specifies the CCC.</small></p>
</td>
<td width="43%">
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the number of the screen associated
with the specified CCC.</small></p>
<p><small>__ │</small></p>
<pre><small>ScreenWhitePointOfCCC(<i>ccc</i>)
XcmsCCC <i>ccc</i>;
XcmsColor *XcmsScreenWhitePointOfCCC(<i>ccc</i>)
XcmsCCC <i>ccc</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="36%">
<p><small>Specifies the CCC.</small></p>
</td>
<td width="43%">
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the white point of the screen
associated with the specified CCC.</small></p>
<p><small>__ │</small></p>
<pre><small>ClientWhitePointOfCCC(<i>ccc</i>)
XcmsCCC <i>ccc</i>;
XcmsColor *XcmsClientWhitePointOfCCC(<i>ccc</i>)
XcmsCCC <i>ccc</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="36%">
<p><small>Specifies the CCC.</small></p>
</td>
<td width="43%">
</td>
</table>
<p><small>│__</small></p>
<p><small>Both return the Client White Point of the
specified CCC.</small></p>
<a name="6.8.4. Modifying Attributes of a Color Conversion Context"></a>
<h2>6.8.4. Modifying Attributes of a Color Conversion Context</h2>
<p><small>To set the Client White Point in the CCC, use
<i>XcmsSetWhitePoint</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsSetWhitePoint(<i>ccc</i>, <i>color</i>)
XcmsCCC <i>ccc</i>;
XcmsColor *<i>color</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="36%">
<p><small>Specifies the CCC.</small></p>
</td>
<td width="43%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>color</i></small></p>
</td>
<td width="10%"></td>
<td width="74%">
<p><small>Specifies the new Client White Point.</small></p>
</td>
<td width="5%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XcmsSetWhitePoint</i> function changes the
Client White Point in the specified CCC. Note that the pixel
member is ignored and that the color specification is left
unchanged upon return. The format for the new white point
must be <i>XcmsCIEXYZFormat</i>, <i>XcmsCIEuvYFormat</i>,
<i>XcmsCIExyYFormat</i>, or <i>XcmsUndefinedFormat</i>. If
the color argument is NULL, this function sets the format
component of the Client White Point specification to
<i>XcmsUndefinedFormat</i>, indicating that the Client White
Point is assumed to be the same as the Screen White
Point.</small></p>
<p><small>This function returns nonzero status if the
format for the new white point is valid; otherwise, it
returns zero.</small></p>
<p><small>To set the gamut compression procedure and
corresponding client data in a specified CCC, use
<i>XcmsSetCompressionProc</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XcmsCompressionProc XcmsSetCompressionProc(<i>ccc</i>, <i>compression_proc</i>, <i>client_data</i>)
XcmsCCC <i>ccc</i>;
XcmsCompressionProc <i>compression_proc</i>;
XPointer <i>client_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="36%">
<p><small>Specifies the CCC.</small></p>
</td>
<td width="43%">
</td>
</table>
<p><small><i>compression_proc</i> Specifies the gamut
compression procedure that is to be applied when a color
lies outside the screen’s color gamut. If NULL is
specified and a function using this CCC must convert a color
specification to a device-dependent format and encounters a
color that lies outside the screen’s color gamut, that
function will return <i>XcmsFailure</i>.</small></p>
<p><small><i>client_data</i> Specifies client data for the
gamut compression procedure or NULL.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsSetCompressionProc</i> function first
sets the gamut compression procedure and client data in the
specified CCC with the newly specified procedure and client
data and then returns the old procedure.</small></p>
<p><small>To set the white point adjustment procedure and
corresponding client data in a specified CCC, use
<i>XcmsSetWhiteAdjustProc</i>.</small></p>
<pre><small>__│
XcmsWhiteAdjustProc XcmsSetWhiteAdjustProc(<i>ccc</i>, <i>white_adjust_proc</i>, <i>client_data</i>)
XcmsCCC <i>ccc</i>;
XcmsWhiteAdjustProc <i>white_adjust_proc</i>;
XPointer <i>client_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="36%">
<p><small>Specifies the CCC.</small></p>
</td>
<td width="43%">
</td>
</table>
<p><small><i>white_adjust_proc</i> Specifies the white
point adjustment procedure.</small></p>
<p><small><i>client_data</i> Specifies client data for the
white point adjustment procedure or NULL.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsSetWhiteAdjustProc</i> function first
sets the white point adjustment procedure and client data in
the specified CCC with the newly specified procedure and
client data and then returns the old procedure.</small></p>
<a name="6.8.5. Creating and Freeing a Color Conversion Context"></a>
<h2>6.8.5. Creating and Freeing a Color Conversion Context</h2>
<p><small>You can explicitly create a CCC within your
application by calling <i>XcmsCreateCCC</i>. These created
CCCs can then be used by those functions that explicitly
call for a CCC argument. Old CCCs that will not be used by
the application should be freed using
<i>XcmsFreeCCC</i>.</small></p>
<p><small>To create a CCC, use
<i>XcmsCreateCCC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XcmsCCC XcmsCreateCCC(<i>display</i>, <i>screen_number</i>, <i>visual</i>, <i>client_white_point</i>, <i>compression_proc</i>,
<i> compression_client_data</i>, <i>white_adjust_proc</i>, <i>white_adjust_client_data</i>)
Display *<i>display</i>;
int <i>screen_number</i>;
Visual *<i>visual</i>;
XcmsColor *<i>client_white_point</i>;
XcmsCompressionProc <i>compression_proc</i>;
XPointer <i>compression_client_data</i>;
XcmsWhiteAdjustProc <i>white_adjust_proc</i>;
XPointer <i>white_adjust_client_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>visual</i></small></p>
</td>
<td width="8%"></td>
<td width="52%">
<p><small>Specifies the visual type.</small></p>
</td>
<td width="27%">
</td>
</table>
<p><small><i>client_white_point</i> Specifies the Client
White Point. If NULL is specified, the Client White Point is
to be assumed to be the same as the Screen White Point. Note
that the pixel member is ignored.</small></p>
<p><small><i>compression_proc</i> Specifies the gamut
compression procedure that is to be applied when a color
lies outside the screen’s color gamut. If NULL is
specified and a function using this CCC must convert a color
specification to a device-dependent format and encounters a
color that lies outside the screen’s color gamut, that
function will return <i>XcmsFailure</i>.</small></p>
<p><small><i>compression_client_data</i> Specifies client
data for use by the gamut compression procedure or
NULL.</small></p>
<p><small><i>white_adjust_proc</i> Specifies the white
adjustment procedure that is to be applied when the Client
White Point differs from the Screen White Point. NULL
indicates that no white point adjustment is
desired.</small></p>
<p><small><i>white_adjust_client_data</i> Specifies client
data for use with the white point adjustment procedure or
NULL.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsCreateCCC</i> function creates a CCC
for the specified display, screen, and visual.</small></p>
<p><small>To free a CCC, use
<i>XcmsFreeCCC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XcmsFreeCCC(<i>ccc</i>)
XcmsCCC <i>ccc</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="36%">
<p><small>Specifies the CCC.</small></p>
</td>
<td width="43%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XcmsFreeCCC</i> function frees the memory
used for the specified CCC. Note that default CCCs and those
currently associated with colormaps are ignored.</small></p>
<a name="6.9. Converting between Color Spaces"></a>
<h2>6.9. Converting between Color Spaces</h2>
<p><small>To convert an array of color specifications in
arbitrary color formats to a single destination format, use
<i>XcmsConvertColors</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsConvertColors(<i>ccc</i>, <i>colors_in_out</i>, <i>ncolors</i>, <i>target_format</i>, <i>compression_flags_return</i>)
XcmsCCC <i>ccc</i>;
XcmsColor <i>colors_in_out</i>[];
unsigned int <i>ncolors</i>;
XcmsColorFormat <i>target_format</i>;
Bool <i>compression_flags_return</i>[];
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the CCC. If conversion is between
device-independent color spaces only (for example, TekHVC to
CIELuv), the CCC is necessary only to specify the Client
White Point.</small></p>
</td>
</table>
<p><small><i>colors_in_out</i> Specifies an array of color
specifications. Pixel members are ignored and remain
unchanged upon return.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>ncolors</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the number of <i>XcmsColor</i>
structures in the color-specification array.</small></p>
</td>
</table>
<p><small><i>target_format</i> Specifies the target color
specification format.</small></p>
<p><small><i>compression_flags_return</i> Returns an array
of Boolean values indicating compression status. If a
non-NULL pointer is supplied, each element of the array is
set to <i>True</i> if the corresponding color was compressed
and <i>False</i> otherwise. Pass NULL if the compression
status is not useful.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsConvertColors</i> function converts
the color specifications in the specified array of
<i>XcmsColor</i> structures from their current format to a
single target format, using the specified CCC. When the
return value is <i>XcmsFailure</i>, the contents of the
color specification array are left unchanged.</small></p>
<p><small>The array may contain a mixture of color
specification formats (for example, 3 CIE XYZ, 2 CIE Luv,
and so on). When the array contains both device-independent
and device-dependent color specifications and the
target_format argument specifies a device-dependent format
(for example, <i>XcmsRGBiFormat</i>, <i>XcmsRGBFormat</i>),
all specifications are converted to CIE XYZ format and then
to the target device-dependent format.</small></p>
<a name="6.10. Callback Functions"></a>
<h2>6.10. Callback Functions</h2>
<p><small>This section describes the gamut compression and
white point adjustment callbacks.</small></p>
<p><small>The gamut compression procedure specified in the
CCC is called when an attempt to convert a color
specification from <i>XcmsCIEXYZ</i> to a device-dependent
format (typically <i>XcmsRGBi</i>) results in a color that
lies outside the screen’s color gamut. If the gamut
compression procedure requires client data, this data is
passed via the gamut compression client data in the
CCC.</small></p>
<p><small>During color specification conversion between
device-independent and device-dependent color spaces, if a
white point adjustment procedure is specified in the CCC, it
is triggered when the Client White Point and Screen White
Point differ. If required, the client data is obtained from
the CCC.</small></p>
<a name="6.10.1. Prototype Gamut Compression Procedure"></a>
<h2>6.10.1. Prototype Gamut Compression Procedure</h2>
<p><small>The gamut compression callback interface must
adhere to the following:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef Status (*XcmsCompressionProc)(<i>ccc</i>, <i>colors_in_out</i>, <i>ncolors</i>, <i>index</i>, <i>compression_flags_return</i>)
XcmsCCC <i>ccc</i>;
XcmsColor <i>colors_in_out[]</i>;
unsigned int <i>ncolors</i>;
unsigned int <i>index</i>;
Bool <i>compression_flags_return[]</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="36%">
<p><small>Specifies the CCC.</small></p>
</td>
<td width="43%">
</td>
</table>
<p><small><i>colors_in_out</i> Specifies an array of color
specifications. Pixel members should be ignored and must
remain unchanged upon return.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>ncolors</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the number of <i>XcmsColor</i>
structures in the color-specification array.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>index</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the index into the array of
<i>XcmsColor</i> structures for the encountered color
specification that lies outside the screen’s color
gamut. Valid values are 0 (for the first element) to ncolors
− 1.</small></p>
</td>
</table>
<p><small><i>compression_flags_return</i> Returns an array
of Boolean values for indicating compression status. If a
non-NULL pointer is supplied and a color at a given index is
compressed, then <i>True</i> should be stored at the
corresponding index in this array; otherwise, the array
should not be modified.</small></p>
<p><small>│__</small></p>
<p><small>When implementing a gamut compression procedure,
consider the following rules and assumptions:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The gamut compression procedure can attempt to
compress one or multiple specifications at a
time.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When called, elements 0 to index − 1 in the
color specification array can be assumed to fall within the
screen’s color gamut. In addition, these color
specifications are already in some device-dependent format
(typically <i>XcmsRGBi</i>). If any modifications are made
to these color specifications, they must be in their initial
device-dependent format upon return.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When called, the element in the color
specification array specified by the index argument contains
the color specification outside the screen’s color
gamut encountered by the calling routine. In addition, this
color specification can be assumed to be in
<i>XcmsCIEXYZ</i>. Upon return, this color specification
must be in <i>XcmsCIEXYZ</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When called, elements from index to ncolors
− 1 in the color specification array may or may not
fall within the screen’s color gamut. In addition,
these color specifications can be assumed to be in
<i>XcmsCIEXYZ</i>. If any modifications are made to these
color specifications, they must be in <i>XcmsCIEXYZ</i> upon
return.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The color specifications passed to the gamut
compression procedure have already been adjusted to the
Screen White Point. This means that at this point the color
specification’s white point is the Screen White
Point.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If the gamut compression procedure uses a
device-independent color space not initially accessible for
use in the color management system, use
<i>XcmsAddColorSpace</i> to ensure that it is
added.</small></p>
</td>
</table>
<a name="6.10.2. Supplied Gamut Compression Procedures"></a>
<h2>6.10.2. Supplied Gamut Compression Procedures</h2>
<p><small>The following equations are useful in describing
gamut compression functions:</small></p>
<pre><small><i> <img src="grohtml-14392-25.png">
<img src="grohtml-14392-26.png">
<img src="grohtml-14392-27.png">
<img src="grohtml-14392-28.png">
</i></small></pre>
<p><small>The gamut compression callback procedures
provided by Xlib are as follows:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="30%">
<p><small><i>XcmsCIELabClipL</i></small></p>
</td>
<td width="59%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>This brings the encountered out-of-gamut color
specification into the screen’s color gamut by
reducing or increasing CIE metric lightness (L*) in the CIE
L*a*b* color space until the color is within the gamut. If
the Psychometric Chroma of the color specification is beyond
maximum for the Psychometric Hue Angle, then while
maintaining the same Psychometric Hue Angle, the color will
be clipped to the CIE L*a*b* coordinates of maximum
Psychometric Chroma. See <i>XcmsCIELabQueryMaxC</i>. No
client data is necessary.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="32%">
<p><small><i>XcmsCIELabClipab</i></small></p>
</td>
<td width="57%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>This brings the encountered out-of-gamut color
specification into the screen’s color gamut by
reducing Psychometric Chroma, while maintaining Psychometric
Hue Angle, until the color is within the gamut. No client
data is necessary.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="34%">
<p><small><i>XcmsCIELabClipLab</i></small></p>
</td>
<td width="55%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>This brings the encountered out-of-gamut color
specification into the screen’s color gamut by
replacing it with CIE L*a*b* coordinates that fall within
the color gamut while maintaining the original Psychometric
Hue Angle and whose vector to the original coordinates is
the shortest attainable. No client data is
necessary.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="30%">
<p><small><i>XcmsCIELuvClipL</i></small></p>
</td>
<td width="59%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>This brings the encountered out-of-gamut color
specification into the screen’s color gamut by
reducing or increasing CIE metric lightness (L*) in the CIE
L*u*v* color space until the color is within the gamut. If
the Psychometric Chroma of the color specification is beyond
maximum for the Psychometric Hue Angle, then, while
maintaining the same Psychometric Hue Angle, the color will
be clipped to the CIE L*u*v* coordinates of maximum
Psychometric Chroma. See <i>XcmsCIELuvQueryMaxC</i>. No
client data is necessary.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="32%">
<p><small><i>XcmsCIELuvClipuv</i></small></p>
</td>
<td width="57%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>This brings the encountered out-of-gamut color
specification into the screen’s color gamut by
reducing Psychometric Chroma, while maintaining Psychometric
Hue Angle, until the color is within the gamut. No client
data is necessary.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="34%">
<p><small><i>XcmsCIELuvClipLuv</i></small></p>
</td>
<td width="55%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>This brings the encountered out-of-gamut color
specification into the screen’s color gamut by
replacing it with CIE L*u*v* coordinates that fall within
the color gamut while maintaining the original Psychometric
Hue Angle and whose vector to the original coordinates is
the shortest attainable. No client data is
necessary.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="30%">
<p><small><i>XcmsTekHVCClipV</i></small></p>
</td>
<td width="59%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>This brings the encountered out-of-gamut color
specification into the screen’s color gamut by
reducing or increasing the Value dimension in the TekHVC
color space until the color is within the gamut. If Chroma
of the color specification is beyond maximum for the
particular Hue, then, while maintaining the same Hue, the
color will be clipped to the Value and Chroma coordinates
that represent maximum Chroma for that particular Hue. No
client data is necessary.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="30%">
<p><small><i>XcmsTekHVCClipC</i></small></p>
</td>
<td width="59%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>This brings the encountered out-of-gamut color
specification into the screen’s color gamut by
reducing the Chroma dimension in the TekHVC color space
until the color is within the gamut. No client data is
necessary.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="32%">
<p><small><i>XcmsTekHVCClipVC</i></small></p>
</td>
<td width="57%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>This brings the encountered out-of-gamut color
specification into the screen’s color gamut by
replacing it with TekHVC coordinates that fall within the
color gamut while maintaining the original Hue and whose
vector to the original coordinates is the shortest
attainable. No client data is necessary.</small></p></td>
</table>
<a name="6.10.3. Prototype White Point Adjustment Procedure"></a>
<h2>6.10.3. Prototype White Point Adjustment Procedure</h2>
<p><small>The white point adjustment procedure interface
must adhere to the following:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef Status (*XcmsWhiteAdjustProc)(<i>ccc</i>, <i>initial_white_point</i>, <i>target_white_point</i>, <i>target_format</i>,
<i> colors_in_out</i>, <i>ncolors</i>, <i>compression_flags_return</i>)
XcmsCCC <i>ccc</i>;
XcmsColor *<i>initial_white_point</i>;
XcmsColor *<i>target_white_point</i>;
XcmsColorFormat <i>target_format</i>;
XcmsColor <i>colors_in_out[]</i>;
unsigned int <i>ncolors</i>;
Bool <i>compression_flags_return[]</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="36%">
<p><small>Specifies the CCC.</small></p>
</td>
<td width="43%">
</td>
</table>
<p><small><i>initial_white_point</i> Specifies the initial
white point.</small></p>
<p><small><i>target_white_point</i> Specifies the target
white point.</small></p>
<p><small><i>target_format</i> Specifies the target color
specification format.</small></p>
<p><small><i>colors_in_out</i> Specifies an array of color
specifications. Pixel members should be ignored and must
remain unchanged upon return.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>ncolors</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the number of <i>XcmsColor</i>
structures in the color-specification array.</small></p>
</td>
</table>
<p><small><i>compression_flags_return</i> Returns an array
of Boolean values for indicating compression status. If a
non-NULL pointer is supplied and a color at a given index is
compressed, then <i>True</i> should be stored at the
corresponding index in this array; otherwise, the array
should not be modified.</small></p>
<p><small>│__</small></p>
<a name="6.10.4. Supplied White Point Adjustment Procedures"></a>
<h2>6.10.4. Supplied White Point Adjustment Procedures</h2>
<p><small>White point adjustment procedures provided by
Xlib are as follows:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="52%">
<p><small><i>XcmsCIELabWhiteShiftColors</i></small></p>
</td>
<td width="37%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>This uses the CIE L*a*b* color space for adjusting
the chromatic character of colors to compensate for the
chromatic differences between the source and destination
white points. This procedure simply converts the color
specifications to <i>XcmsCIELab</i> using the source white
point and then converts to the target specification format
using the destination’s white point. No client data is
necessary.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="52%">
<p><small><i>XcmsCIELuvWhiteShiftColors</i></small></p>
</td>
<td width="37%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>This uses the CIE L*u*v* color space for adjusting
the chromatic character of colors to compensate for the
chromatic differences between the source and destination
white points. This procedure simply converts the color
specifications to <i>XcmsCIELuv</i> using the source white
point and then converts to the target specification format
using the destination’s white point. No client data is
necessary.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="52%">
<p><small><i>XcmsTekHVCWhiteShiftColors</i></small></p>
</td>
<td width="37%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>This uses the TekHVC color space for adjusting the
chromatic character of colors to compensate for the
chromatic differences between the source and destination
white points. This procedure simply converts the color
specifications to <i>XcmsTekHVC</i> using the source white
point and then converts to the target specification format
using the destination’s white point. An advantage of
this procedure over those previously described is an attempt
to minimize hue shift. No client data is
necessary.</small></p>
</td>
</table>
<p><small>From an implementation point of view, these white
point adjustment procedures convert the color specifications
to a device-independent but white-point-dependent color
space (for example, CIE L*u*v*, CIE L*a*b*, TekHVC) using
one white point and then converting those specifications to
the target color space using another white point. In other
words, the specification goes in the color space with one
white point but comes out with another white point,
resulting in a chromatic shift based on the chromatic
displacement between the initial white point and target
white point. The CIE color spaces that are assumed to be
white-point-independent are CIE u’v’Y, CIE XYZ,
and CIE xyY. When developing a custom white point adjustment
procedure that uses a device-independent color space not
initially accessible for use in the color management system,
use <i>XcmsAddColorSpace</i> to ensure that it is
added.</small></p>
<p><small>As an example, if the CCC specifies a white point
adjustment procedure and if the Client White Point and
Screen White Point differ, the <i>XcmsAllocColor</i>
function will use the white point adjustment procedure
twice:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="52%">
<p><small>Once to convert to <i>XcmsRGB</i></small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="74%">
<p><small>A second time to convert from
<i>XcmsRGB</i></small></p>
</td>
<td width="15%">
</td>
</table>
<p><small>For example, assume the specification is in
<i>XcmsCIEuvY</i> and the adjustment procedure is
<i>XcmsCIELuvWhiteShiftColors</i>. During conversion to
<i>XcmsRGB</i>, the call to <i>XcmsAllocColor</i> results in
the following series of color specification
conversions:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>From <i>XcmsCIEuvY</i> to <i>XcmsCIELuv</i> using
the Client White Point</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>From <i>XcmsCIELuv</i> to <i>XcmsCIEuvY</i> using
the Screen White Point</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>From <i>XcmsCIEuvY</i> to <i>XcmsCIEXYZ</i> (CIE
u’v’Y and XYZ are white-point-independent color
spaces)</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="54%">
<p><small>From <i>XcmsCIEXYZ</i> to
<i>XcmsRGBi</i></small></p>
</td>
<td width="35%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="48%">
<p><small>From <i>XcmsRGBi</i> to
<i>XcmsRGB</i></small></p>
</td>
<td width="41%">
</td>
</table>
<p><small>The resulting RGB specification is passed to
<i>XAllocColor</i>, and the RGB specification returned by
<i>XAllocColor</i> is converted back to <i>XcmsCIEuvY</i> by
reversing the color conversion sequence.</small></p>
<a name="6.11. Gamut Querying Functions"></a>
<h2>6.11. Gamut Querying Functions</h2>
<p><small>This section describes the gamut querying
functions that Xlib provides. These functions allow the
client to query the boundary of the screen’s color
gamut in terms of the CIE L*a*b*, CIE L*u*v*, and TekHVC
color spaces. Functions are also provided that allow you to
query the color specification of:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="86%">
<p><small>White (full-intensity red, green, and
blue)</small></p>
</td>
<td width="3%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Red (full-intensity red while green and blue are
zero)</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Green (full-intensity green while red and blue
are zero)</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Blue (full-intensity blue while red and green are
zero)</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="86%">
<p><small>Black (zero-intensity red, green, and
blue)</small></p>
</td>
<td width="3%">
</td>
</table>
<p><small>The white point associated with color
specifications passed to and returned from these gamut
querying functions is assumed to be the Screen White Point.
This is a reasonable assumption, because the client is
trying to query the screen’s color gamut.</small></p>
<p><small>The following naming convention is used for the
Max and Min functions:</small></p>
<pre><small>Xcms<i><color_space></i>QueryMax<i><dimensions>
</i>Xcms<i><color_space></i>QueryMin<i><dimensions>
</i></small></pre>
<p><small>The <dimensions> consists of a letter or
letters that identify the dimensions of the color space that
are not fixed. For example, <i>XcmsTekHVCQueryMaxC</i> is
given a fixed Hue and Value for which maximum Chroma is
found.</small></p>
<a name="6.11.1. Red, Green, and Blue Queries"></a>
<h2>6.11.1. Red, Green, and Blue Queries</h2>
<p><small>To obtain the color specification for black
(zero-intensity red, green, and blue), use
<i>XcmsQueryBlack</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsQueryBlack(<i>ccc</i>, <i>target_format</i>, <i>color_return</i>)
XcmsCCC <i>ccc</i>;
XcmsColorFormat <i>target_format</i>;
XcmsColor *<i>color_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the CCC. The CCC’s Client White
Point and white point adjustment procedures are
ignored.</small></p>
</td>
</table>
<p><small><i>target_format</i> Specifies the target color
specification format.</small></p>
<p><small><i>color_return</i> Returns the color
specification in the specified target format for
zero-intensity red, green, and blue. The white point
associated with the returned color specification is the
Screen White Point. The value returned in the pixel member
is undefined.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsQueryBlack</i> function returns the
color specification in the specified target format for
zero-intensity red, green, and blue.</small></p>
<p><small>To obtain the color specification for blue
(full-intensity blue while red and green are zero), use
<i>XcmsQueryBlue</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsQueryBlue(<i>ccc</i>, <i>target_format</i>, <i>color_return</i>)
XcmsCCC <i>ccc</i>;
XcmsColorFormat <i>target_format</i>;
XcmsColor *<i>color_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the CCC. The CCC’s Client White
Point and white point adjustment procedures are
ignored.</small></p>
</td>
</table>
<p><small><i>target_format</i> Specifies the target color
specification format.</small></p>
<p><small><i>color_return</i> Returns the color
specification in the specified target format for
full-intensity blue while red and green are zero. The white
point associated with the returned color specification is
the Screen White Point. The value returned in the pixel
member is undefined.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsQueryBlue</i> function returns the
color specification in the specified target format for
full-intensity blue while red and green are
zero.</small></p>
<p><small>To obtain the color specification for green
(full-intensity green while red and blue are zero), use
<i>XcmsQueryGreen</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsQueryGreen(<i>ccc</i>, <i>target_format</i>, <i>color_return</i>)
XcmsCCC <i>ccc</i>;
XcmsColorFormat <i>target_format</i>;
XcmsColor *<i>color_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the CCC. The CCC’s Client White
Point and white point adjustment procedures are
ignored.</small></p>
</td>
</table>
<p><small><i>target_format</i> Specifies the target color
specification format.</small></p>
<p><small><i>color_return</i> Returns the color
specification in the specified target format for
full-intensity green while red and blue are zero. The white
point associated with the returned color specification is
the Screen White Point. The value returned in the pixel
member is undefined.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsQueryGreen</i> function returns the
color specification in the specified target format for
full-intensity green while red and blue are
zero.</small></p>
<p><small>To obtain the color specification for red
(full-intensity red while green and blue are zero), use
<i>XcmsQueryRed</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsQueryRed(<i>ccc</i>, <i>target_format</i>, <i>color_return</i>)
XcmsCCC <i>ccc</i>;
XcmsColorFormat <i>target_format</i>;
XcmsColor *<i>color_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the CCC. The CCC’s Client White
Point and white point adjustment procedures are
ignored.</small></p>
</td>
</table>
<p><small><i>target_format</i> Specifies the target color
specification format.</small></p>
<p><small><i>color_return</i> Returns the color
specification in the specified target format for
full-intensity red while green and blue are zero. The white
point associated with the returned color specification is
the Screen White Point. The value returned in the pixel
member is undefined.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsQueryRed</i> function returns the
color specification in the specified target format for
full-intensity red while green and blue are
zero.</small></p>
<p><small>To obtain the color specification for white
(full-intensity red, green, and blue), use
<i>XcmsQueryWhite</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsQueryWhite(<i>ccc</i>, <i>target_format</i>, <i>color_return</i>)
XcmsCCC <i>ccc</i>;
XcmsColorFormat <i>target_format</i>;
XcmsColor *<i>color_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the CCC. The CCC’s Client White
Point and white point adjustment procedures are
ignored.</small></p>
</td>
</table>
<p><small><i>target_format</i> Specifies the target color
specification format.</small></p>
<p><small><i>color_return</i> Returns the color
specification in the specified target format for
full-intensity red, green, and blue. The white point
associated with the returned color specification is the
Screen White Point. The value returned in the pixel member
is undefined.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsQueryWhite</i> function returns the
color specification in the specified target format for
full-intensity red, green, and blue.</small></p>
<a name="6.11.2. CIELab Queries"></a>
<h2>6.11.2. CIELab Queries</h2>
<p><small>The following equations are useful in describing
the CIELab query functions:</small></p>
<pre><small><i> <img src="grohtml-14392-30.png">
<img src="grohtml-14392-31.png">
</i></small></pre>
<p><small>To obtain the CIE L*a*b* coordinates of maximum
Psychometric Chroma for a given Psychometric Hue Angle and
CIE metric lightness (L*), use
<i>XcmsCIELabQueryMaxC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsCIELabQueryMaxC(<i>ccc</i>, <i>hue_angle</i>, <i>L_star</i>, <i>color_return</i>)
XcmsCCC <i>ccc</i>;
XcmsFloat <i>hue_angle</i>;
XcmsFloat <i>L_star</i>;
XcmsColor *<i>color_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the CCC. The CCC’s Client White
Point and white point adjustment procedures are
ignored.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>hue_angle</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the hue angle (in degrees) at which to
find maximum chroma.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>L_star</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the lightness (L*) at which to find
maximum chroma.</small></p>
</td>
</table>
<p><small><i>color_return</i> Returns the CIE L*a*b*
coordinates of maximum chroma displayable by the screen for
the given hue angle and lightness. The white point
associated with the returned color specification is the
Screen White Point. The value returned in the pixel member
is undefined.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsCIELabQueryMaxC</i> function, given a
hue angle and lightness, finds the point of maximum chroma
displayable by the screen. It returns this point in CIE
L*a*b* coordinates.</small></p>
<p><small>To obtain the CIE L*a*b* coordinates of maximum
CIE metric lightness (L*) for a given Psychometric Hue Angle
and Psychometric Chroma, use
<i>XcmsCIELabQueryMaxL</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsCIELabQueryMaxL(<i>ccc</i>, <i>hue_angle</i>, <i>chroma</i>, <i>color_return</i>)
XcmsCCC <i>ccc</i>;
XcmsFloat <i>hue_angle</i>;
XcmsFloat <i>chroma</i>;
XcmsColor *<i>color_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the CCC. The CCC’s Client White
Point and white point adjustment procedures are
ignored.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>hue_angle</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the hue angle (in degrees) at which to
find maximum lightness.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>chroma</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the chroma at which to find maximum
lightness.</small></p>
</td>
</table>
<p><small><i>color_return</i> Returns the CIE L*a*b*
coordinates of maximum lightness displayable by the screen
for the given hue angle and chroma. The white point
associated with the returned color specification is the
Screen White Point. The value returned in the pixel member
is undefined.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsCIELabQueryMaxL</i> function, given a
hue angle and chroma, finds the point in CIE L*a*b* color
space of maximum lightness (L*) displayable by the screen.
It returns this point in CIE L*a*b* coordinates. An
<i>XcmsFailure</i> return value usually indicates that the
given chroma is beyond maximum for the given hue
angle.</small></p>
<p><small>To obtain the CIE L*a*b* coordinates of maximum
Psychometric Chroma for a given Psychometric Hue Angle, use
<i>XcmsCIELabQueryMaxLC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsCIELabQueryMaxLC(<i>ccc</i>, <i>hue_angle</i>, <i>color_return</i>)
XcmsCCC <i>ccc</i>;
XcmsFloat <i>hue_angle</i>;
XcmsColor *<i>color_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the CCC. The CCC’s Client White
Point and white point adjustment procedures are
ignored.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>hue_angle</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the hue angle (in degrees) at which to
find maximum chroma.</small></p>
</td>
</table>
<p><small><i>color_return</i> Returns the CIE L*a*b*
coordinates of maximum chroma displayable by the screen for
the given hue angle. The white point associated with the
returned color specification is the Screen White Point. The
value returned in the pixel member is undefined.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsCIELabQueryMaxLC</i> function, given a
hue angle, finds the point of maximum chroma displayable by
the screen. It returns this point in CIE L*a*b*
coordinates.</small></p>
<p><small>To obtain the CIE L*a*b* coordinates of minimum
CIE metric lightness (L*) for a given Psychometric Hue Angle
and Psychometric Chroma, use
<i>XcmsCIELabQueryMinL</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsCIELabQueryMinL(<i>ccc</i>, <i>hue_angle</i>, <i>chroma</i>, <i>color_return</i>)
XcmsCCC <i>ccc</i>;
XcmsFloat <i>hue_angle</i>;
XcmsFloat <i>chroma</i>;
XcmsColor *<i>color_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the CCC. The CCC’s Client White
Point and white point adjustment procedures are
ignored.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>hue_angle</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the hue angle (in degrees) at which to
find minimum lightness.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>chroma</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the chroma at which to find minimum
lightness.</small></p>
</td>
</table>
<p><small><i>color_return</i> Returns the CIE L*a*b*
coordinates of minimum lightness displayable by the screen
for the given hue angle and chroma. The white point
associated with the returned color specification is the
Screen White Point. The value returned in the pixel member
is undefined.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsCIELabQueryMinL</i> function, given a
hue angle and chroma, finds the point of minimum lightness
(L*) displayable by the screen. It returns this point in CIE
L*a*b* coordinates. An <i>XcmsFailure</i> return value
usually indicates that the given chroma is beyond maximum
for the given hue angle.</small></p>
<a name="6.11.3. CIELuv Queries"></a>
<h2>6.11.3. CIELuv Queries</h2>
<p><small>The following equations are useful in describing
the CIELuv query functions:</small></p>
<pre><small><i> <img src="grohtml-14392-33.png">
<img src="grohtml-14392-34.png">
</i></small></pre>
<p><small>To obtain the CIE L*u*v* coordinates of maximum
Psychometric Chroma for a given Psychometric Hue Angle and
CIE metric lightness (L*), use
<i>XcmsCIELuvQueryMaxC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsCIELuvQueryMaxC(<i>ccc</i>, <i>hue_angle</i>, <i>L_star</i>, <i>color_return</i>)
XcmsCCC <i>ccc</i>;
XcmsFloat <i>hue_angle</i>;
XcmsFloat <i>L_star</i>;
XcmsColor *<i>color_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the CCC. The CCC’s Client White
Point and white point adjustment procedures are
ignored.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>hue_angle</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the hue angle (in degrees) at which to
find maximum chroma.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>L_star</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the lightness (L*) at which to find
maximum chroma.</small></p>
</td>
</table>
<p><small><i>color_return</i> Returns the CIE L*u*v*
coordinates of maximum chroma displayable by the screen for
the given hue angle and lightness. The white point
associated with the returned color specification is the
Screen White Point. The value returned in the pixel member
is undefined.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsCIELuvQueryMaxC</i> function, given a
hue angle and lightness, finds the point of maximum chroma
displayable by the screen. It returns this point in CIE
L*u*v* coordinates.</small></p>
<p><small>To obtain the CIE L*u*v* coordinates of maximum
CIE metric lightness (L*) for a given Psychometric Hue Angle
and Psychometric Chroma, use
<i>XcmsCIELuvQueryMaxL</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsCIELuvQueryMaxL(<i>ccc</i>, <i>hue_angle</i>, <i>chroma</i>, <i>color_return</i>)
XcmsCCC <i>ccc</i>;
XcmsFloat <i>hue_angle</i>;
XcmsFloat <i>chroma</i>;
XcmsColor *<i>color_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the CCC. The CCC’s Client White
Point and white point adjustment procedures are
ignored.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>hue_angle</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the hue angle (in degrees) at which to
find maximum lightness.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>L_star</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the lightness (L*) at which to find
maximum lightness.</small></p>
</td>
</table>
<p><small><i>color_return</i> Returns the CIE L*u*v*
coordinates of maximum lightness displayable by the screen
for the given hue angle and chroma. The white point
associated with the returned color specification is the
Screen White Point. The value returned in the pixel member
is undefined.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsCIELuvQueryMaxL</i> function, given a
hue angle and chroma, finds the point in CIE L*u*v* color
space of maximum lightness (L*) displayable by the screen.
It returns this point in CIE L*u*v* coordinates. An
<i>XcmsFailure</i> return value usually indicates that the
given chroma is beyond maximum for the given hue
angle.</small></p>
<p><small>To obtain the CIE L*u*v* coordinates of maximum
Psychometric Chroma for a given Psychometric Hue Angle, use
<i>XcmsCIELuvQueryMaxLC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsCIELuvQueryMaxLC(<i>ccc</i>, <i>hue_angle</i>, <i>color_return</i>)
XcmsCCC <i>ccc</i>;
XcmsFloat <i>hue_angle</i>;
XcmsColor *<i>color_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the CCC. The CCC’s Client White
Point and white point adjustment procedures are
ignored.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>hue_angle</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the hue angle (in degrees) at which to
find maximum chroma.</small></p>
</td>
</table>
<p><small><i>color_return</i> Returns the CIE L*u*v*
coordinates of maximum chroma displayable by the screen for
the given hue angle. The white point associated with the
returned color specification is the Screen White Point. The
value returned in the pixel member is undefined.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsCIELuvQueryMaxLC</i> function, given a
hue angle, finds the point of maximum chroma displayable by
the screen. It returns this point in CIE L*u*v*
coordinates.</small></p>
<p><small>To obtain the CIE L*u*v* coordinates of minimum
CIE metric lightness (L*) for a given Psychometric Hue Angle
and Psychometric Chroma, use
<i>XcmsCIELuvQueryMinL</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsCIELuvQueryMinL(<i>ccc</i>, <i>hue_angle</i>, <i>chroma</i>, <i>color_return</i>)
XcmsCCC <i>ccc</i>;
XcmsFloat <i>hue_angle</i>;
XcmsFloat <i>chroma</i>;
XcmsColor *<i>color_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the CCC. The CCC’s Client White
Point and white point adjustment procedures are
ignored.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>hue_angle</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the hue angle (in degrees) at which to
find minimum lightness.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>chroma</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the chroma at which to find minimum
lightness.</small></p>
</td>
</table>
<p><small><i>color_return</i> Returns the CIE L*u*v*
coordinates of minimum lightness displayable by the screen
for the given hue angle and chroma. The white point
associated with the returned color specification is the
Screen White Point. The value returned in the pixel member
is undefined.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsCIELuvQueryMinL</i> function, given a
hue angle and chroma, finds the point of minimum lightness
(L*) displayable by the screen. It returns this point in CIE
L*u*v* coordinates. An <i>XcmsFailure</i> return value
usually indicates that the given chroma is beyond maximum
for the given hue angle.</small></p>
<a name="6.11.4. TekHVC Queries"></a>
<h2>6.11.4. TekHVC Queries</h2>
<p><small>To obtain the maximum Chroma for a given Hue and
Value, use <i>XcmsTekHVCQueryMaxC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsTekHVCQueryMaxC(<i>ccc</i>, <i>hue</i>, <i>value</i>, <i>color_return</i>)
XcmsCCC <i>ccc</i>;
XcmsFloat <i>hue</i>;
XcmsFloat <i>value</i>;
XcmsColor *<i>color_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the CCC. The CCC’s Client White
Point and white point adjustment procedures are
ignored.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>hue</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the Hue in which to find the maximum
Chroma.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>value</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the Value in which to find the maximum
Chroma.</small></p>
</td>
</table>
<p><small><i>color_return</i> Returns the maximum Chroma
along with the actual Hue and Value at which the maximum
Chroma was found. The white point associated with the
returned color specification is the Screen White Point. The
value returned in the pixel member is undefined.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsTekHVCQueryMaxC</i> function, given a
Hue and Value, determines the maximum Chroma in TekHVC color
space displayable by the screen. It returns the maximum
Chroma along with the actual Hue and Value at which the
maximum Chroma was found.</small></p>
<p><small>To obtain the maximum Value for a given Hue and
Chroma, use <i>XcmsTekHVCQueryMaxV</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsTekHVCQueryMaxV(<i>ccc</i>, <i>hue</i>, <i>chroma</i>, <i>color_return</i>)
XcmsCCC <i>ccc</i>;
XcmsFloat <i>hue</i>;
XcmsFloat <i>chroma</i>;
XcmsColor *<i>color_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the CCC. The CCC’s Client White
Point and white point adjustment procedures are
ignored.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>hue</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the Hue in which to find the maximum
Value.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>chroma</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the chroma at which to find maximum
Value.</small></p>
</td>
</table>
<p><small><i>color_return</i> Returns the maximum Value
along with the Hue and Chroma at which the maximum Value was
found. The white point associated with the returned color
specification is the Screen White Point. The value returned
in the pixel member is undefined.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsTekHVCQueryMaxV</i> function, given a
Hue and Chroma, determines the maximum Value in TekHVC color
space displayable by the screen. It returns the maximum
Value and the actual Hue and Chroma at which the maximum
Value was found.</small></p>
<p><small>To obtain the maximum Chroma and Value at which
it is reached for a specified Hue, use
<i>XcmsTekHVCQueryMaxVC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsTekHVCQueryMaxVC(<i>ccc</i>, <i>hue</i>, <i>color_return</i>)
XcmsCCC <i>ccc</i>;
XcmsFloat <i>hue</i>;
XcmsColor *<i>color_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the CCC. The CCC’s Client White
Point and white point adjustment procedures are
ignored.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>hue</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the Hue in which to find the maximum
Chroma.</small></p>
</td>
</table>
<p><small><i>color_return</i> Returns the color
specification in XcmsTekHVC for the maximum Chroma, the
Value at which that maximum Chroma is reached, and the
actual Hue at which the maximum Chroma was found. The white
point associated with the returned color specification is
the Screen White Point. The value returned in the pixel
member is undefined.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsTekHVCQueryMaxVC</i> function, given a
Hue, determines the maximum Chroma in TekHVC color space
displayable by the screen and the Value at which that
maximum Chroma is reached. It returns the maximum Chroma,
the Value at which that maximum Chroma is reached, and the
actual Hue for which the maximum Chroma was
found.</small></p>
<p><small>To obtain a specified number of TekHVC
specifications such that they contain maximum Values for a
specified Hue and the Chroma at which the maximum Values are
reached, use <i>XcmsTekHVCQueryMaxVSamples</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsTekHVCQueryMaxVSamples(<i>ccc</i>, <i>hue</i>, <i>colors_return</i>, <i>nsamples</i>)
XcmsCCC <i>ccc</i>;
XcmsFloat <i>hue</i>;
XcmsColor <i>colors_return[]</i>;
unsigned int <i>nsamples</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the CCC. The CCC’s Client White
Point and white point adjustment procedures are
ignored.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>hue</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the Hue for maximum Chroma/Value
samples.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>nsamples</i></small></p>
</td>
<td width="4%"></td>
<td width="64%">
<p><small>Specifies the number of samples.</small></p>
</td>
<td width="15%">
</td>
</table>
<p><small><i>colors_return</i> Returns nsamples of color
specifications in XcmsTekHVC such that the Chroma is the
maximum attainable for the Value and Hue. The white point
associated with the returned color specification is the
Screen White Point. The value returned in the pixel member
is undefined.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsTekHVCQueryMaxVSamples</i> returns
nsamples of maximum Value, the Chroma at which that maximum
Value is reached, and the actual Hue for which the maximum
Chroma was found. These sample points may then be used to
plot the maximum Value/Chroma boundary of the screen’s
color gamut for the specified Hue in TekHVC color
space.</small></p>
<p><small>To obtain the minimum Value for a given Hue and
Chroma, use <i>XcmsTekHVCQueryMinV</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsTekHVCQueryMinV(<i>ccc</i>, <i>hue</i>, <i>chroma</i>, <i>color_return</i>)
XcmsCCC <i>ccc</i>;
XcmsFloat <i>hue</i>;
XcmsFloat <i>chroma</i>;
XcmsColor *<i>color_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the CCC. The CCC’s Client White
Point and white point adjustment procedures are
ignored.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>hue</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the Hue in which to find the minimum
Value.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>value</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the Value in which to find the minimum
Value.</small></p>
</td>
</table>
<p><small><i>color_return</i> Returns the minimum Value and
the actual Hue and Chroma at which the minimum Value was
found. The white point associated with the returned color
specification is the Screen White Point. The value returned
in the pixel member is undefined.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsTekHVCQueryMinV</i> function, given a
Hue and Chroma, determines the minimum Value in TekHVC color
space displayable by the screen. It returns the minimum
Value and the actual Hue and Chroma at which the minimum
Value was found.</small></p>
<a name="6.12. Color Management Extensions"></a>
<h2>6.12. Color Management Extensions</h2>
<p><small>The Xlib color management facilities can be
extended in two ways:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Device-Independent Color Spaces</small></p>
</td>
<td width="27%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Device-independent color spaces that are derivable
to CIE XYZ space can be added using the
<i>XcmsAddColorSpace</i> function.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="70%">
<p><small>Color Characterization Function Set</small></p>
</td>
<td width="19%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A Color Characterization Function Set consists of
device-dependent color spaces and their functions that
convert between these color spaces and the CIE XYZ color
space, bundled together for a specific class of output
devices. A function set can be added using the
<i>XcmsAddFunctionSet</i> function.</small></p></td>
</table>
<a name="6.12.1. Color Spaces"></a>
<h2>6.12.1. Color Spaces</h2>
<p><small>The CIE XYZ color space serves as the hub for all
conversions between device-independent and device-dependent
color spaces. Therefore, the knowledge to convert an
<i>XcmsColor</i> structure to and from CIE XYZ format is
associated with each color space. For example, conversion
from CIE L*u*v* to RGB requires the knowledge to convert
from CIE L*u*v* to CIE XYZ and from CIE XYZ to RGB. This
knowledge is stored as an array of functions that, when
applied in series, will convert the <i>XcmsColor</i>
structure to or from CIE XYZ format. This color
specification conversion mechanism facilitates the addition
of color spaces.</small></p>
<p><small>Of course, when converting between only
device-independent color spaces or only device-dependent
color spaces, shortcuts are taken whenever possible. For
example, conversion from TekHVC to CIE L*u*v* is performed
by intermediate conversion to CIE u*v*Y and then to CIE
L*u*v*, thus bypassing conversion between CIE u*v*Y and CIE
XYZ.</small></p>
<a name="6.12.2. Adding Device-Independent Color Spaces"></a>
<h2>6.12.2. Adding Device-Independent Color Spaces</h2>
<p><small>To add a device-independent color space, use
<i>XcmsAddColorSpace</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsAddColorSpace(<i>color_space</i>)
XcmsColorSpace *<i>color_space</i>;
</small></pre>
<p><small><i>color_space</i> Specifies the
device-independent color space to add.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsAddColorSpace</i> function makes a
device-independent color space (actually an
<i>XcmsColorSpace</i> structure) accessible by the color
management system. Because format values for unregistered
color spaces are assigned at run time, they should be
treated as private to the client. If references to an
unregistered color space must be made outside the client
(for example, storing color specifications in a file using
the unregistered color space), then reference should be made
by color space prefix (see <i>XcmsFormatOfPrefix</i> and
<i>XcmsPrefixOfFormat</i>).</small></p>
<p><small>If the <i>XcmsColorSpace</i> structure is already
accessible in the color management system,
<i>XcmsAddColorSpace</i> returns
<i>XcmsSuccess</i>.</small></p>
<p><small>Note that added <i>XcmsColorSpaces</i> must be
retained for reference by Xlib.</small></p>
<a name="6.12.3. Querying Color Space Format and Prefix"></a>
<h2>6.12.3. Querying Color Space Format and Prefix</h2>
<p><small>To obtain the format associated with the color
space associated with a specified color string prefix, use
<i>XcmsFormatOfPrefix</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XcmsColorFormat XcmsFormatOfPrefix(<i>prefix</i>)
char *<i>prefix</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>prefix</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the string that contains the color
space prefix.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XcmsFormatOfPrefix</i> function returns
the format for the specified color space prefix (for
example, the string ‘‘CIEXYZ’’). The
prefix is case-insensitive. If the color space is not
accessible in the color management system,
<i>XcmsFormatOfPrefix</i> returns
<i>XcmsUndefinedFormat</i>.</small></p>
<p><small>To obtain the color string prefix associated with
the color space specified by a color format, use
<i>XcmsPrefixOfFormat</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char *XcmsPrefixOfFormat(<i>format</i>)
XcmsColorFormat <i>format</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>format</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the color specification
format.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XcmsPrefixOfFormat</i> function returns
the string prefix associated with the color specification
encoding specified by the format argument. Otherwise, if no
encoding is found, it returns NULL. The returned string must
be treated as read-only.</small></p>
<a name="6.12.4. Creating Additional Color Spaces"></a>
<h2>6.12.4. Creating Additional Color Spaces</h2>
<p><small>Color space specific information necessary for
color space conversion and color string parsing is stored in
an <i>XcmsColorSpace</i> structure. Therefore, a new
structure containing this information is required for each
additional color space. In the case of device-independent
color spaces, a handle to this new structure (that is, by
means of a global variable) is usually made accessible to
the client program for use with the <i>XcmsAddColorSpace</i>
function.</small></p>
<p><small>If a new <i>XcmsColorSpace</i> structure
specifies a color space not registered with the X
Consortium, they should be treated as private to the client
because format values for unregistered color spaces are
assigned at run time. If references to an unregistered color
space must be made outside the client (for example, storing
color specifications in a file using the unregistered color
space), then reference should be made by color space prefix
(see <i>XcmsFormatOfPrefix</i> and
<i>XcmsPrefixOfFormat</i>).</small></p>
<p><small>__ │</small></p>
<pre><small>typedef (*XcmsConversionProc)();
typedef XcmsConversionProc *XcmsFuncListPtr;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
</td>
<td width="50%">
<p><small>/* A NULL terminated list of function
pointers*/</small></p>
</td>
</table>
<p><small>typedef struct _XcmsColorSpace {</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>char *prefix;</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>XcmsColorFormat format;</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>XcmsParseStringProc parseString;</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>XcmsFuncListPtr to_CIEXYZ;</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>XcmsFuncListPtr from_CIEXYZ;</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>int inverse_flag;</small></p>
</td>
</table>
<p><small>} XcmsColorSpace;</small></p>
<p><small>│__</small></p>
<p><small>The prefix member specifies the prefix that
indicates a color string is in this color space’s
string format. For example, the strings
‘‘ciexyz’’ or
‘‘CIEXYZ’’ for CIE XYZ, and
‘‘rgb’’ or
‘‘RGB’’ for RGB. The prefix is case
insensitive. The format member specifies the color
specification format. Formats for unregistered color spaces
are assigned at run time. The parseString member contains a
pointer to the function that can parse a color string into
an <i>XcmsColor</i> structure. This function returns an
integer (int): nonzero if it succeeded and zero otherwise.
The to_CIEXYZ and from_CIEXYZ members contain pointers, each
to a NULL terminated list of function pointers. When the
list of functions is executed in series, it will convert the
color specified in an <i>XcmsColor</i> structure from/to the
current color space format to/from the CIE XYZ format. Each
function returns an integer (int): nonzero if it succeeded
and zero otherwise. The white point to be associated with
the colors is specified explicitly, even though white points
can be found in the CCC. The inverse_flag member, if
nonzero, specifies that for each function listed in
to_CIEXYZ, its inverse function can be found in from_CIEXYZ
such that:</small></p>
<pre><small>Given: n = number of functions in each list
for each i, such that 0 <= i < n
from_CIEXYZ[n - i - 1] is the inverse of to_CIEXYZ[i].
</small></pre>
<p><small>This allows Xlib to use the shortest conversion
path, thus bypassing CIE XYZ if possible (for example,
TekHVC to CIE L*u*v*).</small></p>
<a name="6.12.5. Parse String Callback"></a>
<h2>6.12.5. Parse String Callback</h2>
<p><small>The callback in the <i>XcmsColorSpace</i>
structure for parsing a color string for the particular
color space must adhere to the following software interface
specification:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef int (*XcmsParseStringProc)(<i>color_string</i>, <i>color_return</i>)
char *<i>color_string</i>;
XcmsColor *<i>color_return</i>;
</small></pre>
<p><small><i>color_string</i> Specifies the color string to
parse.</small></p>
<p><small><i>color_return</i> Returns the color
specification in the color space’s format.</small></p>
<p><small>│__</small></p>
<a name="6.12.6. Color Specification Conversion Callback"></a>
<h2>6.12.6. Color Specification Conversion Callback</h2>
<p><small>Callback functions in the <i>XcmsColorSpace</i>
structure for converting a color specification between
device-independent spaces must adhere to the following
software interface specification:</small></p>
<p><small>__ │</small></p>
<pre><small>Status ConversionProc(<i>ccc</i>, <i>white_point</i>, <i>colors_in_out</i>, <i>ncolors</i>)
XcmsCCC <i>ccc</i>;
XcmsColor *<i>white_point</i>;
XcmsColor *<i>colors_in_out</i>;
unsigned int <i>ncolors</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="36%">
<p><small>Specifies the CCC.</small></p>
</td>
<td width="43%">
</td>
</table>
<p><small><i>white_point</i> Specifies the white point
associated with color specifications. The pixel member
should be ignored, and the entire structure remain unchanged
upon return.</small></p>
<p><small><i>colors_in_out</i> Specifies an array of color
specifications. Pixel members should be ignored and must
remain unchanged upon return.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>ncolors</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the number of <i>XcmsColor</i>
structures in the color-specification array.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Callback functions in the <i>XcmsColorSpace</i>
structure for converting a color specification to or from a
device-dependent space must adhere to the following software
interface specification:</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>Status ConversionProc(<i>ccc</i>, <i>colors_in_out</i>, <i>ncolors</i>, <i>compression_flags_return</i>)
XcmsCCC <i>ccc</i>;
XcmsColor *<i>colors_in_out</i>;
unsigned int <i>ncolors</i>;
Bool <i>compression_flags_return</i>[];
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>ccc</i></small></p>
</td>
<td width="14%"></td>
<td width="36%">
<p><small>Specifies the CCC.</small></p>
</td>
<td width="43%">
</td>
</table>
<p><small><i>colors_in_out</i> Specifies an array of color
specifications. Pixel members should be ignored and must
remain unchanged upon return.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>ncolors</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the number of <i>XcmsColor</i>
structures in the color-specification array.</small></p>
</td>
</table>
<p><small><i>compression_flags_return</i> Returns an array
of Boolean values for indicating compression status. If a
non-NULL pointer is supplied and a color at a given index is
compressed, then <i>True</i> should be stored at the
corresponding index in this array; otherwise, the array
should not be modified.</small></p>
<p><small>│__</small></p>
<p><small>Conversion functions are available globally for
use by other color spaces. The conversion functions provided
by Xlib are:</small></p>
<p align=center><small><img src="grohtml-1439222.png"></small></p>
<a name="6.12.7. Function Sets"></a>
<h2>6.12.7. Function Sets</h2>
<p><small>Functions to convert between device-dependent
color spaces and CIE XYZ may differ for different classes of
output devices (for example, color versus gray monitors).
Therefore, the notion of a Color Characterization Function
Set has been developed. A function set consists of
device-dependent color spaces and the functions that convert
color specifications between these device-dependent color
spaces and the CIE XYZ color space appropriate for a
particular class of output devices. The function set also
contains a function that reads color characterization data
off root window properties. It is this characterization data
that will differ between devices within a class of output
devices. For details about how color characterization data
is stored in root window properties, see the section on
Device Color Characterization in the <i>Inter-Client
Communication Conventions Manual</i>. The LINEAR_RGB
function set is provided by Xlib and will support most color
monitors. Function sets may require data that differs from
those needed for the LINEAR_RGB function set. In that case,
its corresponding data may be stored on different root
window properties.</small></p>
<a name="6.12.8. Adding Function Sets"></a>
<h2>6.12.8. Adding Function Sets</h2>
<p><small>To add a function set, use
<i>XcmsAddFunctionSet</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XcmsAddFunctionSet(<i>function_set</i>)
XcmsFunctionSet *<i>function_set</i>;
</small></pre>
<p><small><i>function_set</i> Specifies the function set to
add.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XcmsAddFunctionSet</i> function adds a
function set to the color management system. If the function
set uses device-dependent <i>XcmsColorSpace</i> structures
not accessible in the color management system,
<i>XcmsAddFunctionSet</i> adds them. If an added
<i>XcmsColorSpace</i> structure is for a device-dependent
color space not registered with the X Consortium, they
should be treated as private to the client because format
values for unregistered color spaces are assigned at run
time. If references to an unregistered color space must be
made outside the client (for example, storing color
specifications in a file using the unregistered color
space), then reference should be made by color space prefix
(see <i>XcmsFormatOfPrefix</i> and
<i>XcmsPrefixOfFormat</i>).</small></p>
<p><small>Additional function sets should be added before
any calls to other Xlib routines are made. If not, the
<i>XcmsPerScrnInfo</i> member of a previously created
<i>XcmsCCC</i> does not have the opportunity to initialize
with the added function set.</small></p>
<a name="6.12.9. Creating Additional Function Sets"></a>
<h2>6.12.9. Creating Additional Function Sets</h2>
<p><small>The creation of additional function sets should
be required only when an output device does not conform to
existing function sets or when additional device-dependent
color spaces are necessary. A function set consists
primarily of a collection of device-dependent
<i>XcmsColorSpace</i> structures and a means to read and
store a screen’s color characterization data. This
data is stored in an <i>XcmsFunctionSet</i> structure. A
handle to this structure (that is, by means of global
variable) is usually made accessible to the client program
for use with <i>XcmsAddFunctionSet</i>.</small></p>
<p><small>If a function set uses new device-dependent
<i>XcmsColorSpace</i> structures, they will be transparently
processed into the color management system. Function sets
can share an <i>XcmsColorSpace</i> structure for a
device-dependent color space. In addition, multiple
<i>XcmsColorSpace</i> structures are allowed for a
device-dependent color space; however, a function set can
reference only one of them. These <i>XcmsColorSpace</i>
structures will differ in the functions to convert to and
from CIE XYZ, thus tailored for the specific function
set.</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct _XcmsFunctionSet {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XcmsColorSpace **DDColorSpaces;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XcmsScreenInitProc screenInitProc;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XcmsScreenFreeProc screenFreeProc;</small></p>
</td>
<td width="49%">
</td>
</table>
<p><small>} XcmsFunctionSet;</small></p>
<p><small>│__</small></p>
<p><small>The DDColorSpaces member is a pointer to a NULL
terminated list of pointers to <i>XcmsColorSpace</i>
structures for the device-dependent color spaces that are
supported by the function set. The screenInitProc member is
set to the callback procedure (see the following interface
specification) that initializes the <i>XcmsPerScrnInfo</i>
structure for a particular screen.</small></p>
<p><small>The screen initialization callback must adhere to
the following software interface specification:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef Status (*XcmsScreenInitProc)(<i>display</i>, <i>screen_number</i>, <i>screen_info</i>)
Display *<i>display</i>;
int <i>screen_number</i>;
XcmsPerScrnInfo *<i>screen_info</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small><i>screen_info</i> Specifies the
<i>XcmsPerScrnInfo</i> structure, which contains the per
screen information.</small></p>
<p><small>│__</small></p>
<p><small>The screen initialization callback in the
<i>XcmsFunctionSet</i> structure fetches the color
characterization data (device profile) for the specified
screen, typically off properties on the screen’s root
window. It then initializes the specified
<i>XcmsPerScrnInfo</i> structure. If successful, the
procedure fills in the <i>XcmsPerScrnInfo</i> structure as
follows:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It sets the screenData member to the address of
the created device profile data structure (contents known
only by the function set).</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="82%">
<p><small>It next sets the screenWhitePoint
member.</small></p>
</td>
<td width="7%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It next sets the functionSet member to the
address of the <i>XcmsFunctionSet</i> structure.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It then sets the state member to
<i>XcmsInitSuccess</i> and finally returns
<i>XcmsSuccess</i>.</small></p>
</td>
</table>
<p><small>If unsuccessful, the procedure sets the state
member to <i>XcmsInitFailure</i> and returns
<i>XcmsFailure</i>.</small></p>
<p><small>The <i>XcmsPerScrnInfo</i> structure
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct _XcmsPerScrnInfo {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XcmsColor screenWhitePoint;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XPointer functionSet;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XPointer screenData;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned char state;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>char pad[3];</small></p>
</td>
<td width="49%">
</td>
</table>
<p><small>} XcmsPerScrnInfo;</small></p>
<p><small>│__</small></p>
<p><small>The screenWhitePoint member specifies the white
point inherent to the screen. The functionSet member
specifies the appropriate function set. The screenData
member specifies the device profile. The state member is set
to one of the following:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>XcmsInitNone</i> indicates initialization has
not been previously attempted.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>XcmsInitFailure</i> indicates initialization
has been previously attempted but failed.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>XcmsInitSuccess</i> indicates initialization
has been previously attempted and succeeded.</small></p>
</td>
</table>
<p><small>The screen free callback must adhere to the
following software interface specification:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef void (*XcmsScreenFreeProc)(<i>screenData</i>)
XPointer <i>screenData</i>;
</small></pre>
<p><small><i>screenData</i> Specifies the data to be
freed.</small></p>
<p><small>│__</small></p>
<p><small>This function is called to free the screenData
stored in an <i>XcmsPerScrnInfo</i> structure.</small></p>
<p><small><b>6</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b>Chapter 7</b></p>
<p align=center><b>Graphics Context Functions</b></p>
<p><small>A number of resources are used when performing
graphics operations in X. Most information about performing
graphics (for example, foreground color, background color,
line style, and so on) is stored in resources called
graphics contexts (GCs). Most graphics operations (see
chapter 8) take a GC as an argument. Although in theory the
X protocol permits sharing of GCs between applications, it
is expected that applications will use their own GCs when
performing operations. Sharing of GCs is highly discouraged
because the library may cache GC state.</small></p>
<p><small>Graphics operations can be performed to either
windows or pixmaps, which collectively are called drawables.
Each drawable exists on a single screen. A GC is created for
a specific screen and drawable depth and can only be used
with drawables of matching screen and depth.</small></p>
<p><small>This chapter discusses how to:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="66%">
<p><small>Manipulate graphics context/state</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="84%">
<p><small>Use graphics context convenience
functions</small></p>
</td>
<td width="5%">
</td>
</table>
<a name="7.1. Manipulating Graphics Context/State"></a>
<h2>7.1. Manipulating Graphics Context/State</h2>
<p><small>Most attributes of graphics operations are stored
in GCs. These include line width, line style, plane mask,
foreground, background, tile, stipple, clipping region, end
style, join style, and so on. Graphics operations (for
example, drawing lines) use these values to determine the
actual drawing operation. Extensions to X may add additional
components to GCs. The contents of a GC are private to
Xlib.</small></p>
<p><small>Xlib implements a write-back cache for all
elements of a GC that are not resource IDs to allow Xlib to
implement the transparent coalescing of changes to GCs. For
example, a call to <i>XSetForeground</i> of a GC followed by
a call to <i>XSetLineAttributes</i> results in only a
single-change GC protocol request to the server. GCs are
neither expected nor encouraged to be shared between client
applications, so this write-back caching should present no
problems. Applications cannot share GCs without external
synchronization. Therefore, sharing GCs between applications
is highly discouraged.</small></p>
<p><small>To set an attribute of a GC, set the appropriate
member of the <i>XGCValues</i> structure and OR in the
corresponding value bitmask in your subsequent calls to
<i>XCreateGC</i>. The symbols for the value mask bits and
the <i>XGCValues</i> structure are:</small></p>
<p><small>__ │</small></p>
<p><small>/* GC attribute value mask bits */</small></p>
<p align=center><small><img src="grohtml-1439223.png"></small></p>
<pre><small>/* Values */
typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int function;</small></p>
</td>
<td width="40%">
<p><small>/* logical operation */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long plane_mask;/* plane mask
*/</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long foreground;/* foreground pixel
*/</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long background;/* background pixel
*/</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int line_width;</small></p>
</td>
<td width="40%">
<p><small>/* line width (in pixels) */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int line_style;</small></p>
</td>
<td width="40%">
<p><small>/* LineSolid, LineOnOffDash, LineDoubleDash
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int cap_style;</small></p>
</td>
<td width="40%">
<p><small>/* CapNotLast, CapButt, CapRound, CapProjecting
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int join_style;</small></p>
</td>
<td width="40%">
<p><small>/* JoinMiter, JoinRound, JoinBevel */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int fill_style;</small></p>
</td>
<td width="40%">
<p><small>/* FillSolid, FillTiled, FillStippled
FillOpaqueStippled*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int fill_rule;</small></p>
</td>
<td width="40%">
<p><small>/* EvenOddRule, WindingRule */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int arc_mode;</small></p>
</td>
<td width="40%">
<p><small>/* ArcChord, ArcPieSlice */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Pixmap tile;</small></p>
</td>
<td width="40%">
<p><small>/* tile pixmap for tiling operations
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Pixmap stipple;</small></p>
</td>
<td width="40%">
<p><small>/* stipple 1 plane pixmap for stippling
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int ts_x_origin;</small></p>
</td>
<td width="40%">
<p><small>/* offset for tile or stipple operations
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int ts_y_origin;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Font font;</small></p>
</td>
<td width="40%">
<p><small>/* default text font for text operations
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int subwindow_mode;</small></p>
</td>
<td width="40%">
<p><small>/* ClipByChildren, IncludeInferiors
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool graphics_exposures;</small></p>
</td>
<td width="40%">
<p><small>/* boolean, should exposures be generated
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int clip_x_origin;</small></p>
</td>
<td width="40%">
<p><small>/* origin for clipping */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int clip_y_origin;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Pixmap clip_mask;</small></p>
</td>
<td width="40%">
<p><small>/* bitmap clipping; other calls for rects
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int dash_offset;</small></p>
</td>
<td width="40%">
<p><small>/* patterned/dashed line information
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>char dashes;</small></p>
</td>
<td width="40%">
</td>
</table>
<p><small>} XGCValues;</small></p>
<p><small>│__</small></p>
<p><small>The default GC values are:</small></p>
<p align=center><small><img src="grohtml-1439224.png"></small></p>
<p><small>Note that foreground and background are not set
to any values likely to be useful in a window.</small></p>
<p><small>The function attributes of a GC are used when you
update a section of a drawable (the destination) with bits
from somewhere else (the source). The function in a GC
defines how the new destination bits are to be computed from
the source bits and the old destination bits. <i>GXcopy</i>
is typically the most useful because it will work on a color
display, but special applications may use other functions,
particularly in concert with particular planes of a color
display. The 16 GC functions, defined in
<<i>X11/X.h</i>>, are:</small></p>
<p align=center><small><img src="grohtml-1439225.png"></small></p>
<p><small>Many graphics operations depend on either pixel
values or planes in a GC. The planes attribute is of type
long, and it specifies which planes of the destination are
to be modified, one bit per plane. A monochrome display has
only one plane and will be the least significant bit of the
word. As planes are added to the display hardware, they will
occupy more significant bits in the plane mask.</small></p>
<p><small>In graphics operations, given a source and
destination pixel, the result is computed bitwise on
corresponding bits of the pixels. That is, a Boolean
operation is performed in each bit plane. The plane_mask
restricts the operation to a subset of planes. A macro
constant <i>AllPlanes</i> can be used to refer to all planes
of the screen simultaneously. The result is computed by the
following:</small></p>
<pre><small> ((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))
</small></pre>
<p><small>Range checking is not performed on the values for
foreground, background, or plane_mask. They are simply
truncated to the appropriate number of bits. The line-width
is measured in pixels and either can be greater than or
equal to one (wide line) or can be the special value zero
(thin line).</small></p>
<p><small>Wide lines are drawn centered on the path
described by the graphics request. Unless otherwise
specified by the join-style or cap-style, the bounding box
of a wide line with endpoints [x1, y1], [x2, y2] and width w
is a rectangle with vertices at the following real
coordinates:</small></p>
<pre><small> [x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)],
[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]
</small></pre>
<p><small>Here sn is the sine of the angle of the line, and
cs is the cosine of the angle of the line. A pixel is part
of the line and so is drawn if the center of the pixel is
fully inside the bounding box (which is viewed as having
infinitely thin edges). If the center of the pixel is
exactly on the bounding box, it is part of the line if and
only if the interior is immediately to its right (x
increasing direction). Pixels with centers on a horizontal
edge are a special case and are part of the line if and only
if the interior or the boundary is immediately below (y
increasing direction) and the interior or the boundary is
immediately to the right (x increasing
direction).</small></p>
<p><small>Thin lines (zero line-width) are one-pixel-wide
lines drawn using an unspecified, device-dependent
algorithm. There are only two constraints on this
algorithm.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small>1.</small></p>
</td>
<td width="6%"></td>
<td width="90%">
<p><small>If a line is drawn unclipped from [x1,y1] to
[x2,y2] and if another line is drawn unclipped from
[x1+dx,y1+dy] to [x2+dx,y2+dy], a point [x,y] is touched by
drawing the first line if and only if the point [x+dx,y+dy]
is touched by drawing the second line.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small>2.</small></p>
</td>
<td width="6%"></td>
<td width="90%">
<p><small>The effective set of points comprising a line
cannot be affected by clipping. That is, a point is touched
in a clipped line if and only if the point lies inside the
clipping region and the point would be touched by the line
when drawn unclipped.</small></p>
</td>
</table>
<p><small>A wide line drawn from [x1,y1] to [x2,y2] always
draws the same pixels as a wide line drawn from [x2,y2] to
[x1,y1], not counting cap-style and join-style. It is
recommended that this property be true for thin lines, but
this is not required. A line-width of zero may differ from a
line-width of one in which pixels are drawn. This permits
the use of many manufacturers’ line drawing hardware,
which may run many times faster than the more precisely
specified wide lines.</small></p>
<p><small>In general, drawing a thin line will be faster
than drawing a wide line of width one. However, because of
their different drawing algorithms, thin lines may not mix
well aesthetically with wide lines. If it is desirable to
obtain precise and uniform results across all displays, a
client should always use a line-width of one rather than a
line-width of zero.</small></p>
<p><small>The line-style defines which sections of a line
are drawn:</small></p>
<p align=center><small><img src="grohtml-1439226.png"></small></p>
<p><small>The cap-style defines how the endpoints of a path
are drawn:</small></p>
<p align=center><small><img src="grohtml-1439227.png"></small></p>
<p><small>The join-style defines how corners are drawn for
wide lines:</small></p>
<p align=center><small><img src="grohtml-1439228.png"></small></p>
<p><small>For a line with coincident endpoints (x1=x2,
y1=y2), when the cap-style is applied to both endpoints, the
semantics depends on the line-width and the
cap-style:</small></p>
<p align=center><small><img src="grohtml-1439229.png"></small></p>
<p><small>For a line with coincident endpoints (x1=x2,
y1=y2), when the join-style is applied at one or both
endpoints, the effect is as if the line was removed from the
overall path. However, if the total path consists of or is
reduced to a single point joined with itself, the effect is
the same as when the cap-style is applied at both
endpoints.</small></p>
<p><small>The tile/stipple represents an infinite
two-dimensional plane, with the tile/stipple replicated in
all dimensions. When that plane is superimposed on the
drawable for use in a graphics operation, the upper-left
corner of some instance of the tile/stipple is at the
coordinates within the drawable specified by the
tile/stipple origin. The tile/stipple and clip origins are
interpreted relative to the origin of whatever destination
drawable is specified in a graphics request. The tile pixmap
must have the same root and depth as the GC, or a
<i>BadMatch</i> error results. The stipple pixmap must have
depth one and must have the same root as the GC, or a
<i>BadMatch</i> error results. For stipple operations where
the fill-style is <i>FillStippled</i> but not
<i>FillOpaqueStippled</i>, the stipple pattern is tiled in a
single plane and acts as an additional clip mask to be ANDed
with the clip-mask. Although some sizes may be faster to use
than others, any size pixmap can be used for tiling or
stippling.</small></p>
<p><small>The fill-style defines the contents of the source
for line, text, and fill requests. For all text and fill
requests (for example, <i>XDrawText</i>, <i>XDrawText16</i>,
<i>XFillRectangle</i>, <i>XFillPolygon</i>, and
<i>XFillArc</i>); for line requests with line-style
<i>LineSolid</i> (for example, <i>XDrawLine</i>,
<i>XDrawSegments</i>, <i>XDrawRectangle</i>,
<i>XDrawArc</i>); and for the even dashes for line requests
with line-style <i>LineOnOffDash</i> or
<i>LineDoubleDash</i>, the following apply:</small></p>
<p align=center><small><img src="grohtml-1439230.png"></small></p>
<p><small>When drawing lines with line-style
<i>LineDoubleDash</i>, the odd dashes are controlled by the
fill-style in the following manner:</small></p>
<p align=center><small><img src="grohtml-1439231.png"></small></p>
<p><small>Storing a pixmap in a GC might or might not
result in a copy being made. If the pixmap is later used as
the destination for a graphics request, the change might or
might not be reflected in the GC. If the pixmap is used
simultaneously in a graphics request both as a destination
and as a tile or stipple, the results are
undefined.</small></p>
<p><small>For optimum performance, you should draw as much
as possible with the same GC (without changing its
components). The costs of changing GC components relative to
using different GCs depend on the display hardware and the
server implementation. It is quite likely that some amount
of GC information will be cached in display hardware and
that such hardware can only cache a small number of
GCs.</small></p>
<p><small>The dashes value is actually a simplified form of
the more general patterns that can be set with
<i>XSetDashes</i>. Specifying a value of N is equivalent to
specifying the two-element list [N, N] in <i>XSetDashes</i>.
The value must be nonzero, or a <i>BadValue</i> error
results.</small></p>
<p><small>The clip-mask restricts writes to the destination
drawable. If the clip-mask is set to a pixmap, it must have
depth one and have the same root as the GC, or a
<i>BadMatch</i> error results. If clip-mask is set to
<i>None</i>, the pixels are always drawn regardless of the
clip origin. The clip-mask also can be set by calling the
<i>XSetClipRectangles</i> or <i>XSetRegion</i> functions.
Only pixels where the clip-mask has a bit set to 1 are
drawn. Pixels are not drawn outside the area covered by the
clip-mask or where the clip-mask has a bit set to 0. The
clip-mask affects all graphics requests. The clip-mask does
not clip sources. The clip-mask origin is interpreted
relative to the origin of whatever destination drawable is
specified in a graphics request.</small></p>
<p><small>You can set the subwindow-mode to
<i>ClipByChildren</i> or <i>IncludeInferiors</i>. For
<i>ClipByChildren</i>, both source and destination windows
are additionally clipped by all viewable <i>InputOutput</i>
children. For <i>IncludeInferiors</i>, neither source nor
destination window is clipped by inferiors. This will result
in including subwindow contents in the source and drawing
through subwindow boundaries of the destination. The use of
<i>IncludeInferiors</i> on a window of one depth with mapped
inferiors of differing depth is not illegal, but the
semantics are undefined by the core protocol.</small></p>
<p><small>The fill-rule defines what pixels are inside
(drawn) for paths given in <i>XFillPolygon</i> requests and
can be set to <i>EvenOddRule</i> or <i>WindingRule</i>. For
<i>EvenOddRule</i>, a point is inside if an infinite ray
with the point as origin crosses the path an odd number of
times. For <i>WindingRule</i>, a point is inside if an
infinite ray with the point as origin crosses an unequal
number of clockwise and counterclockwise directed path
segments. A clockwise directed path segment is one that
crosses the ray from left to right as observed from the
point. A counterclockwise segment is one that crosses the
ray from right to left as observed from the point. The case
where a directed line segment is coincident with the ray is
uninteresting because you can simply choose a different ray
that is not coincident with a segment.</small></p>
<p><small>For both <i>EvenOddRule</i> and
<i>WindingRule</i>, a point is infinitely small, and the
path is an infinitely thin line. A pixel is inside if the
center point of the pixel is inside and the center point is
not on the boundary. If the center point is on the boundary,
the pixel is inside if and only if the polygon interior is
immediately to its right (x increasing direction). Pixels
with centers on a horizontal edge are a special case and are
inside if and only if the polygon interior is immediately
below (y increasing direction).</small></p>
<p><small>The arc-mode controls filling in the
<i>XFillArcs</i> function and can be set to
<i>ArcPieSlice</i> or <i>ArcChord</i>. For
<i>ArcPieSlice</i>, the arcs are pie-slice filled. For
<i>ArcChord</i>, the arcs are chord filled.</small></p>
<p><small>The graphics-exposure flag controls
<i>GraphicsExpose</i> event generation for <i>XCopyArea</i>
and <i>XCopyPlane</i> requests (and any similar requests
defined by extensions).</small></p>
<p><small>To create a new GC that is usable on a given
screen with a depth of drawable, use
<i>XCreateGC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>GC XCreateGC(<i>display</i>, <i>d</i>, <i>valuemask</i>, <i>values</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
unsigned long <i>valuemask</i>;
XGCValues *<i>values</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>valuemask</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>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.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>values</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies any values as specified by the
valuemask.</small></p>
</td>
<td width="0%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XCreateGC</i> 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
<i>BadMatch</i> error.</small></p>
<p><small><i>XCreateGC</i> can generate <i>BadAlloc</i>,
<i>BadDrawable</i>, <i>BadFont</i>, <i>BadMatch</i>,
<i>BadPixmap</i>, and <i>BadValue</i> errors.</small></p>
<p><small>To copy components from a source GC to a
destination GC, use <i>XCopyGC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XCopyGC(<i>display</i>, <i>src</i>, <i>valuemask</i>, <i>dest</i>)
Display *<i>display</i>;
GC <i>src</i>, <i>dest</i>;
unsigned long <i>valuemask</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>src</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the components of the source
GC.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>valuemask</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>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.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>dest</i></small></p>
</td>
<td width="12%"></td>
<td width="58%">
<p><small>Specifies the destination GC.</small></p>
</td>
<td width="21%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XCopyGC</i> 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 <i>BadMatch</i> error results. The valuemask
specifies which component to copy, as for
<i>XCreateGC</i>.</small></p>
<p><small><i>XCopyGC</i> can generate <i>BadAlloc</i>,
<i>BadGC</i>, and <i>BadMatch</i> errors.</small></p>
<p><small>To change the components in a given GC, use
<i>XChangeGC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XChangeGC(<i>display</i>, <i>gc</i>, <i>valuemask</i>, <i>values</i>)
Display *<i>display</i>;
GC <i>gc</i>;
unsigned long <i>valuemask</i>;
XGCValues *<i>values</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>valuemask</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>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.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>values</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies any values as specified by the
valuemask.</small></p>
</td>
<td width="0%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XChangeGC</i> 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 <i>XCreateGC</i>.
Changing the clip-mask overrides any previous
<i>XSetClipRectangles</i> request on the context. Changing
the dash-offset or dash-list overrides any previous
<i>XSetDashes</i> 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.</small></p>
<p><small><i>XChangeGC</i> can generate <i>BadAlloc</i>,
<i>BadFont</i>, <i>BadGC</i>, <i>BadMatch</i>,
<i>BadPixmap</i>, and <i>BadValue</i> errors.</small></p>
<p><small>To obtain components of a given GC, use
<i>XGetGCValues</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetGCValues(<i>display</i>, <i>gc</i>, <i>valuemask</i>, <i>values_return</i>)
Display *<i>display</i>;
GC <i>gc</i>;
unsigned long <i>valuemask</i>;
XGCValues *<i>values_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>valuemask</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies which components in the GC are to be
returned in the values_return argument. This argument is the
bitwise inclusive OR of zero or more of the valid GC
component mask bits.</small></p>
</td>
</table>
<p><small><i>values_return</i> Returns the GC values in the
specified <i>XGCValues</i> structure.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetGCValues</i> function returns the
components specified by valuemask for the specified GC. If
the valuemask contains a valid set of GC mask bits
(<i>GCFunction</i>, <i>GCPlaneMask</i>, <i>GCForeground</i>,
<i>GCBackground</i>, <i>GCLineWidth</i>, <i>GCLineStyle</i>,
<i>GCCapStyle</i>, <i>GCJoinStyle</i>, <i>GCFillStyle</i>,
<i>GCFillRule</i>, <i>GCTile</i>, <i>GCStipple</i>,
<i>GCTileStipXOrigin</i>, <i>GCTileStipYOrigin</i>,
<i>GCFont</i>, <i>GCSubwindowMode</i>,
<i>GCGraphicsExposures</i>, <i>GCClipXOrigin</i>,
<i>GCCLipYOrigin</i>, <i>GCDashOffset</i>, or
<i>GCArcMode</i>) and no error occurs, <i>XGetGCValues</i>
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
<i>GCClipMask</i> and <i>GCDashList</i> 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
<i>GCFont</i>, <i>GCTile</i>, and <i>GCStipple</i> if the
component has never been explicitly set by the
client.</small></p>
<p><small>To free a given GC, use
<i>XFreeGC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XFreeGC(<i>display</i>, <i>gc</i>)
Display *<i>display</i>;
GC <i>gc</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XFreeGC</i> function destroys the
specified GC as well as all the associated
storage.</small></p>
<p><small><i>XFreeGC</i> can generate a <i>BadGC</i>
error.</small></p>
<p><small>To obtain the <i>GContext</i> resource ID for a
given GC, use <i>XGContextFromGC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>GContext XGContextFromGC(<i>gc</i>)
GC <i>gc</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="80%">
<p><small>Specifies the GC for which you want the resource
ID.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Xlib usually defers sending changes to the
components of a GC to the server until a graphics function
is actually called with that GC. This permits batching of
component changes into a single server request. In some
circumstances, however, it may be necessary for the client
to explicitly force sending the changes to the server. An
example might be when a protocol extension uses the GC
indirectly, in such a way that the extension interface
cannot know what GC will be used. To force sending GC
component changes, use <i>XFlushGC</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>void XFlushGC(<i>display</i>, <i>gc</i>)
Display *<i>display</i>;
GC <i>gc</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<p><small>│__</small></p>
<a name="7.2. Using Graphics Context Convenience Routines"></a>
<h2>7.2. Using Graphics Context Convenience Routines</h2>
<p><small>This section discusses how to set
the:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Foreground, background, plane mask, or function
components</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="74%">
<p><small>Line attributes and dashes components</small></p>
</td>
<td width="15%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="70%">
<p><small>Fill style and fill rule components</small></p>
</td>
<td width="19%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="64%">
<p><small>Fill tile and stipple components</small></p>
</td>
<td width="25%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="28%">
<p><small>Font component</small></p>
</td>
<td width="61%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>Clip region component</small></p>
</td>
<td width="47%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Arc mode, subwindow mode, and graphics exposure
components</small></p>
</td>
</table>
<a name="7.2.1. Setting the Foreground, Background, Function, or Plane Mask"></a>
<h2>7.2.1. Setting the Foreground, Background, Function, or Plane Mask</h2>
<p><small>To set the foreground, background, plane mask,
and function components for a given GC, use
<i>XSetState</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetState(<i>display</i>, <i>gc</i>, <i>foreground</i>, <i>background</i>, <i>function</i>, <i>plane_mask</i>)
Display *<i>display</i>;
GC <i>gc</i>;
unsigned long <i>foreground</i>, <i>background</i>;
int <i>function</i>;
unsigned long <i>plane_mask</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<p><small><i>foreground</i> Specifies the foreground you
want to set for the specified GC.</small></p>
<p><small><i>background</i> Specifies the background you
want to set for the specified GC.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>function</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the function you want to set for the
specified GC.</small></p>
</td>
</table>
<p><small><i>plane_mask</i> Specifies the plane
mask.</small></p>
<p><small>│__</small></p>
<p><small><i>XSetState</i> can generate <i>BadAlloc</i>,
<i>BadGC</i>, and <i>BadValue</i> errors.</small></p>
<p><small>To set the foreground of a given GC, use
<i>XSetForeground</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetForeground(<i>display</i>, <i>gc</i>, <i>foreground</i>)
Display *<i>display</i>;
GC <i>gc</i>;
unsigned long <i>foreground</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<p><small><i>foreground</i> Specifies the foreground you
want to set for the specified GC.</small></p>
<p><small>│__</small></p>
<p><small><i>XSetForeground</i> can generate
<i>BadAlloc</i> and <i>BadGC</i> errors.</small></p>
<p><small>To set the background of a given GC, use
<i>XSetBackground</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetBackground(<i>display</i>, <i>gc</i>, <i>background</i>)
Display *<i>display</i>;
GC <i>gc</i>;
unsigned long <i>background</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<p><small><i>background</i> Specifies the background you
want to set for the specified GC.</small></p>
<p><small>│__</small></p>
<p><small><i>XSetBackground</i> can generate
<i>BadAlloc</i> and <i>BadGC</i> errors.</small></p>
<p><small>To set the display function in a given GC, use
<i>XSetFunction</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetFunction(<i>display</i>, <i>gc</i>, <i>function</i>)
Display *<i>display</i>;
GC <i>gc</i>;
int <i>function</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>function</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the function you want to set for the
specified GC.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small><i>XSetFunction</i> can generate <i>BadAlloc</i>,
<i>BadGC</i>, and <i>BadValue</i> errors.</small></p>
<p><small>To set the plane mask of a given GC, use
<i>XSetPlaneMask</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetPlaneMask(<i>display</i>, <i>gc</i>, <i>plane_mask</i>)
Display *<i>display</i>;
GC <i>gc</i>;
unsigned long <i>plane_mask</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<p><small><i>plane_mask</i> Specifies the plane
mask.</small></p>
<p><small>│__</small></p>
<p><small><i>XSetPlaneMask</i> can generate <i>BadAlloc</i>
and <i>BadGC</i> errors.</small></p>
<a name="7.2.2. Setting the Line Attributes and Dashes"></a>
<h2>7.2.2. Setting the Line Attributes and Dashes</h2>
<p><small>To set the line drawing components of a given GC,
use <i>XSetLineAttributes</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetLineAttributes(<i>display</i>, <i>gc</i>, <i>line_width</i>, <i>line_style</i>, <i>cap_style</i>, <i>join_style</i>)
Display *<i>display</i>;
GC <i>gc</i>;
unsigned int <i>line_width</i>;
int <i>line_style</i>;
int <i>cap_style</i>;
int <i>join_style</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<p><small><i>line_width</i> Specifies the line-width you
want to set for the specified GC.</small></p>
<p><small><i>line_style</i> Specifies the line-style you
want to set for the specified GC. You can pass
<i>LineSolid</i>, <i>LineOnOffDash</i>, or
<i>LineDoubleDash</i>.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>cap_style</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the line-style and cap-style you want
to set for the specified GC. You can pass <i>CapNotLast</i>,
<i>CapButt</i>, <i>CapRound</i>, or
<i>CapProjecting</i>.</small></p>
</td>
</table>
<p><small><i>join_style</i> Specifies the line join-style
you want to set for the specified GC. You can pass
<i>JoinMiter</i>, <i>JoinRound</i>, or
<i>JoinBevel</i>.</small></p>
<p><small>│__</small></p>
<p><small><i>XSetLineAttributes</i> can generate
<i>BadAlloc</i>, <i>BadGC</i>, and <i>BadValue</i>
errors.</small></p>
<p><small>To set the dash-offset and dash-list for dashed
line styles of a given GC, use
<i>XSetDashes</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetDashes(<i>display</i>, <i>gc</i>, <i>dash_offset</i>, <i>dash_list</i>, <i>n</i>)
Display *<i>display</i>;
GC <i>gc</i>;
int <i>dash_offset</i>;
char <i>dash_list</i>[];
int <i>n</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<p><small><i>dash_offset</i> Specifies the phase of the
pattern for the dashed line-style you want to set for the
specified GC.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>dash_list</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the dash-list for the dashed line-style
you want to set for the specified GC.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>n</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the number of elements in
dash_list.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetDashes</i> function sets the
dash-offset and dash-list attributes for dashed line styles
in the specified GC. There must be at least one element in
the specified dash_list, or a <i>BadValue</i> error results.
The initial and alternating elements (second, fourth, and so
on) of the dash_list are the even dashes, and the others are
the odd dashes. Each element specifies a dash length in
pixels. All of the elements must be nonzero, or a
<i>BadValue</i> error results. Specifying an odd-length list
is equivalent to specifying the same list concatenated with
itself to produce an even-length list.</small></p>
<p><small>The dash-offset defines the phase of the pattern,
specifying how many pixels into the dash-list the pattern
should actually begin in any single graphics request.
Dashing is continuous through path elements combined with a
join-style but is reset to the dash-offset between each
sequence of joined lines.</small></p>
<p><small>The unit of measure for dashes is the same for
the ordinary coordinate system. Ideally, a dash length is
measured along the slope of the line, but implementations
are only required to match this ideal for horizontal and
vertical lines. Failing the ideal semantics, it is suggested
that the length be measured along the major axis of the
line. The major axis is defined as the x axis for lines
drawn at an angle of between −45 and +45 degrees or
between 135 and 225 degrees from the x axis. For all other
lines, the major axis is the y axis.</small></p>
<p><small><i>XSetDashes</i> can generate <i>BadAlloc</i>,
<i>BadGC</i>, and <i>BadValue</i> errors.</small></p>
<a name="7.2.3. Setting the Fill Style and Fill Rule"></a>
<h2>7.2.3. Setting the Fill Style and Fill Rule</h2>
<p><small>To set the fill-style of a given GC, use
<i>XSetFillStyle</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetFillStyle(<i>display</i>, <i>gc</i>, <i>fill_style</i>)
Display *<i>display</i>;
GC <i>gc</i>;
int <i>fill_style</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<p><small><i>fill_style</i> Specifies the fill-style you
want to set for the specified GC. You can pass
<i>FillSolid</i>, <i>FillTiled</i>, <i>FillStippled</i>, or
<i>FillOpaqueStippled</i>.</small></p>
<p><small>│__</small></p>
<p><small><i>XSetFillStyle</i> can generate
<i>BadAlloc</i>, <i>BadGC</i>, and <i>BadValue</i>
errors.</small></p>
<p><small>To set the fill-rule of a given GC, use
<i>XSetFillRule</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetFillRule(<i>display</i>, <i>gc</i>, <i>fill_rule</i>)
Display *<i>display</i>;
GC <i>gc</i>;
int <i>fill_rule</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>fill_rule</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the fill-rule you want to set for the
specified GC. You can pass <i>EvenOddRule</i> or
<i>WindingRule</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small><i>XSetFillRule</i> can generate <i>BadAlloc</i>,
<i>BadGC</i>, and <i>BadValue</i> errors.</small></p>
<a name="7.2.4. Setting the Fill Tile and Stipple"></a>
<h2>7.2.4. Setting the Fill Tile and Stipple</h2>
<p><small>Some displays have hardware support for tiling or
stippling with patterns of specific sizes. Tiling and
stippling operations that restrict themselves to those
specific sizes run much faster than such operations with
arbitrary size patterns. Xlib provides functions that you
can use to determine the best size, tile, or stipple for the
display as well as to set the tile or stipple shape and the
tile or stipple origin.</small></p>
<p><small>To obtain the best size of a tile, stipple, or
cursor, use <i>XQueryBestSize</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XQueryBestSize(<i>display</i>, <i>class</i>, <i>which_screen</i>, <i>width</i>, <i>height</i>, <i>width_return</i>, <i>height_return</i>)
Display *<i>display</i>;
int <i>class</i>;
Drawable <i>which_screen</i>;
unsigned int <i>width</i>, <i>height</i>;
unsigned int *<i>width_return</i>, *<i>height_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>class</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the class that you are interested in.
You can pass <i>TileShape</i>, <i>CursorShape</i>, or
<i>StippleShape</i>.</small></p>
</td>
</table>
<p><small><i>which_screen</i> Specifies any drawable on the
screen.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="58%">
<p><small>Specify the width and height.</small></p>
</td>
<td width="21%">
</td>
</table>
<p><small><i>width_return</i></small></p>
<p><small><i>height_return</i> Return the width and height
of the object best supported by the display
hardware.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XQueryBestSize</i> function returns the
best or closest size to the specified size. For
<i>CursorShape</i>, this is the largest size that can be
fully displayed on the screen specified by which_screen. For
<i>TileShape</i>, this is the size that can be tiled
fastest. For <i>StippleShape</i>, this is the size that can
be stippled fastest. For <i>CursorShape</i>, the drawable
indicates the desired screen. For <i>TileShape</i> and
<i>StippleShape</i>, the drawable indicates the screen and
possibly the window class and depth. An <i>InputOnly</i>
window cannot be used as the drawable for <i>TileShape</i>
or <i>StippleShape</i>, or a <i>BadMatch</i> error
results.</small></p>
<p><small><i>XQueryBestSize</i> can generate
<i>BadDrawable</i>, <i>BadMatch</i>, and <i>BadValue</i>
errors.</small></p>
<p><small>To obtain the best fill tile shape, use
<i>XQueryBestTile</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XQueryBestTile(<i>display</i>, <i>which_screen</i>, <i>width</i>, <i>height</i>, <i>width_return</i>, <i>height_return</i>)
Display *<i>display</i>;
Drawable <i>which_screen</i>;
unsigned int <i>width</i>, <i>height</i>;
unsigned int *<i>width_return</i>, *<i>height_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>which_screen</i> Specifies any drawable on the
screen.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="58%">
<p><small>Specify the width and height.</small></p>
</td>
<td width="21%">
</td>
</table>
<p><small><i>width_return</i></small></p>
<p><small><i>height_return</i> Return the width and height
of the object best supported by the display
hardware.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XQueryBestTile</i> function returns the
best or closest size, that is, the size that can be tiled
fastest on the screen specified by which_screen. The
drawable indicates the screen and possibly the window class
and depth. If an <i>InputOnly</i> window is used as the
drawable, a <i>BadMatch</i> error results.</small></p>
<p><small><i>XQueryBestTile</i> can generate
<i>BadDrawable</i> and <i>BadMatch</i> errors.</small></p>
<p><small>To obtain the best stipple shape, use
<i>XQueryBestStipple</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XQueryBestStipple(<i>display</i>, <i>which_screen</i>, <i>width</i>, <i>height</i>, <i>width_return</i>, <i>height_return</i>)
Display *<i>display</i>;
Drawable <i>which_screen</i>;
unsigned int <i>width</i>, <i>height</i>;
unsigned int *<i>width_return</i>, *<i>height_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>which_screen</i> Specifies any drawable on the
screen.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="58%">
<p><small>Specify the width and height.</small></p>
</td>
<td width="21%">
</td>
</table>
<p><small><i>width_return</i></small></p>
<p><small><i>height_return</i> Return the width and height
of the object best supported by the display
hardware.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XQueryBestStipple</i> function returns the
best or closest size, that is, the size that can be stippled
fastest on the screen specified by which_screen. The
drawable indicates the screen and possibly the window class
and depth. If an <i>InputOnly</i> window is used as the
drawable, a <i>BadMatch</i> error results.</small></p>
<p><small><i>XQueryBestStipple</i> can generate
<i>BadDrawable</i> and <i>BadMatch</i> errors.</small></p>
<p><small>To set the fill tile of a given GC, use
<i>XSetTile</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetTile(<i>display</i>, <i>gc</i>, <i>tile</i>)
Display *<i>display</i>;
GC <i>gc</i>;
Pixmap <i>tile</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>tile</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the fill tile you want to set for the
specified GC.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The tile and GC must have the same depth, or a
<i>BadMatch</i> error results.</small></p>
<p><small><i>XSetTile</i> can generate <i>BadAlloc</i>,
<i>BadGC</i>, <i>BadMatch</i>, and <i>BadPixmap</i>
errors.</small></p>
<p><small>To set the stipple of a given GC, use
<i>XSetStipple</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetStipple(<i>display</i>, <i>gc</i>, <i>stipple</i>)
Display *<i>display</i>;
GC <i>gc</i>;
Pixmap <i>stipple</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>stipple</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the stipple you want to set for the
specified GC.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The stipple must have a depth of one, or a
<i>BadMatch</i> error results.</small></p>
<p><small><i>XSetStipple</i> can generate <i>BadAlloc</i>,
<i>BadGC</i>, <i>BadMatch</i>, and <i>BadPixmap</i>
errors.</small></p>
<p><small>To set the tile or stipple origin of a given GC,
use <i>XSetTSOrigin</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetTSOrigin(<i>display</i>, <i>gc</i>, <i>ts_x_origin</i>, <i>ts_y_origin</i>)
Display *<i>display</i>;
GC <i>gc</i>;
int <i>ts_x_origin</i>, <i>ts_y_origin</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<p><small><i>ts_x_origin</i></small></p>
<p><small><i>ts_y_origin</i> Specify the x and y
coordinates of the tile and stipple origin.</small></p>
<p><small>│__</small></p>
<p><small>When graphics requests call for tiling or
stippling, the parent’s origin will be interpreted
relative to whatever destination drawable is specified in
the graphics request.</small></p>
<p><small><i>XSetTSOrigin</i> can generate <i>BadAlloc</i>
and <i>BadGC</i> errors.</small></p>
<a name="7.2.5. Setting the Current Font"></a>
<h2>7.2.5. Setting the Current Font</h2>
<p><small>To set the current font of a given GC, use
<i>XSetFont</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetFont(<i>display</i>, <i>gc</i>, <i>font</i>)
Display *<i>display</i>;
GC <i>gc</i>;
Font <i>font</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>font</i></small></p>
</td>
<td width="12%"></td>
<td width="38%">
<p><small>Specifies the font.</small></p>
</td>
<td width="41%">
</td>
</table>
<p><small>│__</small></p>
<p><small><i>XSetFont</i> can generate <i>BadAlloc</i>,
<i>BadFont</i>, and <i>BadGC</i> errors.</small></p>
<a name="7.2.6. Setting the Clip Region"></a>
<h2>7.2.6. Setting the Clip Region</h2>
<p><small>Xlib provides functions that you can use to set
the clip-origin and the clip-mask or set the clip-mask to a
list of rectangles.</small></p>
<p><small>To set the clip-origin of a given GC, use
<i>XSetClipOrigin</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetClipOrigin(<i>display</i>, <i>gc</i>, <i>clip_x_origin</i>, <i>clip_y_origin</i>)
Display *<i>display</i>;
GC <i>gc</i>;
int <i>clip_x_origin</i>, <i>clip_y_origin</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<p><small><i>clip_x_origin</i></small></p>
<p><small><i>clip_y_origin</i> Specify the x and y
coordinates of the clip-mask origin.</small></p>
<p><small>│__</small></p>
<p><small>The clip-mask origin is interpreted relative to
the origin of whatever destination drawable is specified in
the graphics request.</small></p>
<p><small><i>XSetClipOrigin</i> can generate
<i>BadAlloc</i> and <i>BadGC</i> errors.</small></p>
<p><small>To set the clip-mask of a given GC to the
specified pixmap, use <i>XSetClipMask</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetClipMask(<i>display</i>, <i>gc</i>, <i>pixmap</i>)
Display *<i>display</i>;
GC <i>gc</i>;
Pixmap <i>pixmap</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>pixmap</i></small></p>
</td>
<td width="8%"></td>
<td width="58%">
<p><small>Specifies the pixmap or <i>None</i>.</small></p>
</td>
<td width="21%">
</td>
</table>
<p><small>│__</small></p>
<p><small>If the clip-mask is set to <i>None</i>, the
pixels are always drawn (regardless of the
clip-origin).</small></p>
<p><small><i>XSetClipMask</i> can generate <i>BadAlloc</i>,
<i>BadGC</i>, <i>BadMatch</i>, and <i>BadPixmap</i>
errors.</small></p>
<p><small>To set the clip-mask of a given GC to the
specified list of rectangles, use
<i>XSetClipRectangles</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetClipRectangles(<i>display</i>, <i>gc</i>, <i>clip_x_origin</i>, <i>clip_y_origin</i>, <i>rectangles</i>, <i>n</i>, <i>ordering</i>)
Display *<i>display</i>;
GC <i>gc</i>;
int <i>clip_x_origin</i>, <i>clip_y_origin</i>;
XRectangle <i>rectangles</i>[];
int <i>n</i>;
int <i>ordering</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<p><small><i>clip_x_origin</i></small></p>
<p><small><i>clip_y_origin</i> Specify the x and y
coordinates of the clip-mask origin.</small></p>
<p><small><i>rectangles</i> Specifies an array of
rectangles that define the clip-mask.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>n</i></small></p>
</td>
<td width="18%"></td>
<td width="70%">
<p><small>Specifies the number of rectangles.</small></p>
</td>
<td width="9%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>ordering</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the ordering relations on the
rectangles. You can pass <i>Unsorted</i>, <i>YSorted</i>,
<i>YXSorted</i>, or <i>YXBanded</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetClipRectangles</i> function changes
the clip-mask in the specified GC to the specified list of
rectangles and sets the clip origin. The output is clipped
to remain contained within the rectangles. The clip-origin
is interpreted relative to the origin of whatever
destination drawable is specified in a graphics request. The
rectangle coordinates are interpreted relative to the
clip-origin. The rectangles should be nonintersecting, or
the graphics results will be undefined. Note that the list
of rectangles can be empty, which effectively disables
output. This is the opposite of passing <i>None</i> as the
clip-mask in <i>XCreateGC</i>, <i>XChangeGC</i>, and
<i>XSetClipMask</i>.</small></p>
<p><small>If known by the client, ordering relations on the
rectangles can be specified with the ordering argument. This
may provide faster operation by the server. If an incorrect
ordering is specified, the X server may generate a
<i>BadMatch</i> error, but it is not required to do so. If
no error is generated, the graphics results are undefined.
<i>Unsorted</i> means the rectangles are in arbitrary order.
<i>YSorted</i> means that the rectangles are nondecreasing
in their Y origin. <i>YXSorted</i> additionally constrains
<i>YSorted</i> order in that all rectangles with an equal Y
origin are nondecreasing in their X origin. <i>YXBanded</i>
additionally constrains <i>YXSorted</i> by requiring that,
for every possible Y scanline, all rectangles that include
that scanline have an identical Y origins and Y
extents.</small></p>
<p><small><i>XSetClipRectangles</i> can generate
<i>BadAlloc</i>, <i>BadGC</i>, <i>BadMatch</i>, and
<i>BadValue</i> errors.</small></p>
<p><small>Xlib provides a set of basic functions for
performing region arithmetic. For information about these
functions, see section 16.5.</small></p>
<a name="7.2.7. Setting the Arc Mode, Subwindow Mode, and Graphics Exposure"></a>
<h2>7.2.7. Setting the Arc Mode, Subwindow Mode, and Graphics Exposure</h2>
<p><small>To set the arc mode of a given GC, use
<i>XSetArcMode</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetArcMode(<i>display</i>, <i>gc</i>, <i>arc_mode</i>)
Display *<i>display</i>;
GC <i>gc</i>;
int <i>arc_mode</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>arc_mode</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the arc mode. You can pass
<i>ArcChord</i> or <i>ArcPieSlice</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small><i>XSetArcMode</i> can generate <i>BadAlloc</i>,
<i>BadGC</i>, and <i>BadValue</i> errors.</small></p>
<p><small>To set the subwindow mode of a given GC, use
<i>XSetSubwindowMode</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetSubwindowMode(<i>display</i>, <i>gc</i>, <i>subwindow_mode</i>)
Display *<i>display</i>;
GC <i>gc</i>;
int <i>subwindow_mode</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<p><small><i>subwindow_mode</i> Specifies the subwindow
mode. You can pass <i>ClipByChildren</i> or
<i>IncludeInferiors</i>.</small></p>
<p><small>│__</small></p>
<p><small><i>XSetSubwindowMode</i> can generate
<i>BadAlloc</i>, <i>BadGC</i>, and <i>BadValue</i>
errors.</small></p>
<p><small>To set the graphics-exposures flag of a given GC,
use <i>XSetGraphicsExposures</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetGraphicsExposures(<i>display</i>, <i>gc</i>, <i>graphics_exposures</i>)
Display *<i>display</i>;
GC <i>gc</i>;
Bool <i>graphics_exposures</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<p><small><i>graphics_exposures</i> Specifies a Boolean
value that indicates whether you want <i>GraphicsExpose</i>
and <i>NoExpose</i> events to be reported when calling
<i>XCopyArea</i> and <i>XCopyPlane</i> with this
GC.</small></p>
<p><small>│__</small></p>
<p><small><i>XSetGraphicsExposures</i> can generate
<i>BadAlloc</i>, <i>BadGC</i>, and <i>BadValue</i>
errors.</small></p>
<p><small><b>7</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b>Chapter 8</b></p>
<p align=center><b>Graphics Functions</b></p>
<p><small>Once you have established a connection to a
display, you can use the Xlib graphics functions
to:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="40%">
<p><small>Clear and copy areas</small></p>
</td>
<td width="49%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Draw points, lines, rectangles, and
arcs</small></p>
</td>
<td width="9%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="20%">
<p><small>Fill areas</small></p>
</td>
<td width="69%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="32%">
<p><small>Manipulate fonts</small></p>
</td>
<td width="57%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="18%">
<p><small>Draw text</small></p>
</td>
<td width="71%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Transfer images between clients and the
server</small></p>
</td>
</table>
<p><small>If the same drawable and GC is used for each
call, Xlib batches back-to-back calls to <i>XDrawPoint</i>,
<i>XDrawLine</i>, <i>XDrawRectangle</i>, <i>XFillArc</i>,
and <i>XFillRectangle</i>. Note that this reduces the total
number of requests sent to the server.</small></p>
<a name="8.1. Clearing Areas"></a>
<h2>8.1. Clearing Areas</h2>
<p><small>Xlib provides functions that you can use to clear
an area or the entire window. Because pixmaps do not have
defined backgrounds, they cannot be filled by using the
functions described in this section. Instead, to accomplish
an analogous operation on a pixmap, you should use
<i>XFillRectangle</i>, which sets the pixmap to a known
value.</small></p>
<p><small>To clear a rectangular area of a given window,
use <i>XClearArea</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XClearArea(<i>display</i>, <i>w</i>, <i>x</i>, <i>y</i>, <i>width</i>, <i>height</i>, <i>exposures</i>)
Display *<i>display</i>;
Window <i>w</i>;
int <i>x</i>, <i>y</i>;
unsigned int <i>width</i>, <i>height</i>;
Bool <i>exposures</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which are
relative to the origin of the window and specify the
upper-left corner of the rectangle.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the width and height, which are the
dimensions of the rectangle.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>exposures</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies a Boolean value that indicates if
<i>Expose</i> events are to be generated.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XClearArea</i> 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
<i>ClipByChildren</i>. 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 <i>None</i>, the contents of
the window are not changed. In either case, if exposures is
<i>True</i>, one or more <i>Expose</i> 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 <i>InputOnly</i>, a <i>BadMatch</i> error
results.</small></p>
<p><small><i>XClearArea</i> can generate <i>BadMatch</i>,
<i>BadValue</i>, and <i>BadWindow</i> errors.</small></p>
<p><small>To clear the entire area in a given window, use
<i>XClearWindow</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XClearWindow(<i>display</i>, <i>w</i>)
Display *<i>display</i>;
Window <i>w</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XClearWindow</i> function clears the
entire area in the specified window and is equivalent to
<i>XClearArea</i> (display, w, 0, 0, 0, 0, <i>False</i>). If
the window has a defined background tile, the rectangle is
tiled with a plane-mask of all ones and <i>GXcopy</i>
function. If the window has background <i>None</i>, the
contents of the window are not changed. If you specify a
window whose class is <i>InputOnly</i>, a <i>BadMatch</i>
error results.</small></p>
<p><small><i>XClearWindow</i> can generate <i>BadMatch</i>
and <i>BadWindow</i> errors.</small></p>
<a name="8.2. Copying Areas"></a>
<h2>8.2. Copying Areas</h2>
<p><small>Xlib provides functions that you can use to copy
an area or a bit plane.</small></p>
<p><small>To copy an area between drawables of the same
root and depth, use <i>XCopyArea</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XCopyArea(<i>display</i>, <i>src</i>, <i>dest</i>, <i>gc</i>, <i>src_x</i>, <i>src_y</i>, <i>width</i>, <i>height</i>, <i> dest_x</i>, <i>dest_y</i>)
Display *<i>display</i>;
Drawable <i>src</i>, <i>dest</i>;
GC <i>gc</i>;
int <i>src_x</i>, <i>src_y</i>;
unsigned int <i>width</i>, <i>height</i>;
int <i>dest_x</i>, <i>dest_y</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>src</i></small></p>
</td>
<td width="93%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>dest</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specify the source and destination rectangles to
be combined.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>src_x</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>src_y</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which are
relative to the origin of the source rectangle and specify
its upper-left corner.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the width and height, which are the
dimensions of both the source and destination
rectangles.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>dest_x</i></small></p>
</td>
<td width="87%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>dest_y</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which are
relative to the origin of the destination rectangle and
specify its upper-left corner.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XCopyArea</i> function combines the
specified rectangle of src with the specified rectangle of
dest. The drawables must have the same root and depth, or a
<i>BadMatch</i> error results.</small></p>
<p><small>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 <i>None</i>,
corresponding regions of the destination are tiled with that
background (with plane-mask of all ones and <i>GXcopy</i>
function). Regardless of tiling or whether the destination
is a window or a pixmap, if graphics-exposures is
<i>True</i>, then <i>GraphicsExpose</i> events for all
corresponding destination regions are generated. If
graphics-exposures is <i>True</i> but no
<i>GraphicsExpose</i> events are generated, a
<i>NoExpose</i> event is generated. Note that by default
graphics-exposures is <i>True</i> in new GCs.</small></p>
<p><small>This function uses these GC components: function,
plane-mask, subwindow-mode, graphics-exposures,
clip-x-origin, clip-y-origin, and clip-mask.</small></p>
<p><small><i>XCopyArea</i> can generate <i>BadDrawable</i>,
<i>BadGC</i>, and <i>BadMatch</i> errors.</small></p>
<p><small>To copy a single bit plane of a given drawable,
use <i>XCopyPlane</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XCopyPlane(<i>display</i>, <i>src</i>, <i>dest</i>, <i>gc</i>, <i>src_x</i>, <i>src_y</i>, <i>width</i>, <i>height</i>, <i>dest_x</i>, <i>dest_y</i>, <i>plane</i>)
Display *<i>display</i>;
Drawable <i>src</i>, <i>dest</i>;
GC <i>gc</i>;
int <i>src_x</i>, <i>src_y</i>;
unsigned int <i>width</i>, <i>height</i>;
int <i>dest_x</i>, <i>dest_y</i>;
unsigned long <i>plane</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>src</i></small></p>
</td>
<td width="93%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>dest</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specify the source and destination rectangles to
be combined.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>src_x</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>src_y</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which are
relative to the origin of the source rectangle and specify
its upper-left corner.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the width and height, which are the
dimensions of both the source and destination
rectangles.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>dest_x</i></small></p>
</td>
<td width="87%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>dest_y</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which are
relative to the origin of the destination rectangle and
specify its upper-left corner.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>plane</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the bit plane. You must set exactly one
bit to 1.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XCopyPlane</i> 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
<i>BadMatch</i> error results. If plane does not have
exactly one bit set to 1 and the value of plane is not less
than <img src="grohtml-14392-45.png"> , where <i>n</i> is
the depth of src, a <i>BadValue</i> error
results.</small></p>
<p><small>Effectively, <i>XCopyPlane</i> 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 <i>CopyArea</i> 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
<i>FillOpaqueStippled</i> for filling a rectangular area of
the destination.</small></p>
<p><small>This function uses these GC components: function,
plane-mask, foreground, background, subwindow-mode,
graphics-exposures, clip-x-origin, clip-y-origin, and
clip-mask.</small></p>
<p><small><i>XCopyPlane</i> can generate
<i>BadDrawable</i>, <i>BadGC</i>, <i>BadMatch</i>, and
<i>BadValue</i> errors.</small></p>
<a name="8.3. Drawing Points, Lines, Rectangles, and Arcs"></a>
<h2>8.3. Drawing Points, Lines, Rectangles, and Arcs</h2>
<p><small>Xlib provides functions that you can use to
draw:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="66%">
<p><small>A single point or multiple points</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>A single line or multiple lines</small></p>
</td>
<td width="27%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="82%">
<p><small>A single rectangle or multiple
rectangles</small></p>
</td>
<td width="7%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="58%">
<p><small>A single arc or multiple arcs</small></p>
</td>
<td width="31%">
</td>
</table>
<p><small>Some of the functions described in the following
sections use these structures:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>short x1, y1, x2, y2;</small></p>
</td>
<td width="79%">
</td>
</table>
<p><small>} XSegment;</small></p>
<p><small>│__</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>short x, y;</small></p>
</td>
<td width="79%">
</td>
</table>
<p><small>} XPoint;</small></p>
<p><small>│__</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>short x, y;</small></p>
</td>
<td width="79%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>unsigned short width, height;</small></p>
</td>
<td width="79%">
</td>
</table>
<p><small>} XRectangle;</small></p>
<p><small>│__</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>short x, y;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned short width, height;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>short angle1, angle2; /* Degrees * 64
*/</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>} XArc;</small></p>
<p><small>│__</small></p>
<p><small>All x and y members are signed integers. The
width and height members are 16-bit unsigned integers. You
should be careful not to generate coordinates and sizes out
of the 16-bit ranges, because the protocol only has 16-bit
fields for these values.</small></p>
<a name="8.3.1. Drawing Single and Multiple Points"></a>
<h2>8.3.1. Drawing Single and Multiple Points</h2>
<p><small>To draw a single point in a given drawable, use
<i>XDrawPoint</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XDrawPoint(<i>display</i>, <i>d</i>, <i>gc</i>, <i>x</i>, <i>y</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
int <i>x</i>, <i>y</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates where you want
the point drawn.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>To draw multiple points in a given drawable, use
<i>XDrawPoints</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>XDrawPoints(<i>display</i>, <i>d</i>, <i>gc</i>, <i>points</i>, <i>npoints</i>, <i>mode</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
XPoint *<i>points</i>;
int <i>npoints</i>;
int <i>mode</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>points</i></small></p>
</td>
<td width="8%"></td>
<td width="58%">
<p><small>Specifies an array of points.</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>npoints</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the number of points in the
array.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>mode</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the coordinate mode. You can pass
<i>CoordModeOrigin</i> or
<i>CoordModePrevious</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XDrawPoint</i> function uses the
foreground pixel and function components of the GC to draw a
single point into the specified drawable; <i>XDrawPoints</i>
draws multiple points this way. <i>CoordModeOrigin</i>
treats all coordinates as relative to the origin, and
<i>CoordModePrevious</i> treats all coordinates after the
first as relative to the previous point. <i>XDrawPoints</i>
draws the points in the order listed in the
array.</small></p>
<p><small>Both functions use these GC components: function,
plane-mask, foreground, subwindow-mode, clip-x-origin,
clip-y-origin, and clip-mask.</small></p>
<p><small><i>XDrawPoint</i> can generate
<i>BadDrawable</i>, <i>BadGC</i>, and <i>BadMatch</i>
errors. <i>XDrawPoints</i> can generate <i>BadDrawable</i>,
<i>BadGC</i>, <i>BadMatch</i>, and <i>BadValue</i>
errors.</small></p>
<a name="8.3.2. Drawing Single and Multiple Lines"></a>
<h2>8.3.2. Drawing Single and Multiple Lines</h2>
<p><small>To draw a single line between two points in a
given drawable, use <i>XDrawLine</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XDrawLine(<i>display</i>, <i>d</i>, <i>gc</i>, <i>x1</i>, <i>y1</i>, <i>x2</i>, <i>y2</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
int <i>x1</i>, <i>y1</i>, <i>x2</i>, <i>y2</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>x1</i></small></p>
</td>
<td width="95%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>y1</i></small></p>
</td>
<td width="95%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>x2</i></small></p>
</td>
<td width="95%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>y2</i></small></p>
</td>
<td width="16%"></td>
<td width="80%">
<p><small>Specify the points (x1, y1) and (x2, y2) to be
connected.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>To draw multiple lines in a given drawable, use
<i>XDrawLines</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>XDrawLines(<i>display</i>, <i>d</i>, <i>gc</i>, <i>points</i>, <i>npoints</i>, <i>mode</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
XPoint *<i>points</i>;
int <i>npoints</i>;
int <i>mode</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>points</i></small></p>
</td>
<td width="8%"></td>
<td width="58%">
<p><small>Specifies an array of points.</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>npoints</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the number of points in the
array.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>mode</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the coordinate mode. You can pass
<i>CoordModeOrigin</i> or
<i>CoordModePrevious</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>To draw multiple, unconnected lines in a given
drawable, use <i>XDrawSegments</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>XDrawSegments(<i>display</i>, <i>d</i>, <i>gc</i>, <i>segments</i>, <i>nsegments</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
XSegment *<i>segments</i>;
int <i>nsegments</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>segments</i></small></p>
</td>
<td width="4%"></td>
<td width="62%">
<p><small>Specifies an array of segments.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>nsegments</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the number of segments in the
array.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XDrawLine</i> 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,
<i>XDrawLine</i> does not draw a pixel more than once. If
lines intersect, the intersecting pixels are drawn multiple
times.</small></p>
<p><small>The <i>XDrawLines</i> function uses the
components of the specified GC to draw npoints−1 lines
between each pair of points (point[i], point[i+1]) in the
array of <i>XPoint</i> 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, <i>XDrawLines</i> 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 <i>PolyLine</i> protocol request were a
single, filled shape. <i>CoordModeOrigin</i> treats all
coordinates as relative to the origin, and
<i>CoordModePrevious</i> treats all coordinates after the
first as relative to the previous point.</small></p>
<p><small>The <i>XDrawSegments</i> function draws multiple,
unconnected lines. For each segment, <i>XDrawSegments</i>
draws a line between (x1, y1) and (x2, y2). It draws the
lines in the order listed in the array of <i>XSegment</i>
structures and does not perform joining at coincident
endpoints. For any given line, <i>XDrawSegments</i> does not
draw a pixel more than once. If lines intersect, the
intersecting pixels are drawn multiple times.</small></p>
<p><small>All three functions 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. The <i>XDrawLines</i> function also uses the
join-style GC component. All three functions also use these
GC mode-dependent components: foreground, background, tile,
stipple, tile-stipple-x-origin, tile-stipple-y-origin,
dash-offset, and dash-list.</small></p>
<p><small><i>XDrawLine</i>, <i>XDrawLines</i>, and
<i>XDrawSegments</i> can generate <i>BadDrawable</i>,
<i>BadGC</i>, and <i>BadMatch</i> errors. <i>XDrawLines</i>
also can generate <i>BadValue</i> errors.</small></p>
<a name="8.3.3. Drawing Single and Multiple Rectangles"></a>
<h2>8.3.3. Drawing Single and Multiple Rectangles</h2>
<p><small>To draw the outline of a single rectangle in a
given drawable, use <i>XDrawRectangle</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XDrawRectangle(<i>display</i>, <i>d</i>, <i>gc</i>, <i>x</i>, <i>y</i>, <i>width</i>, <i>height</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
int <i>x</i>, <i>y</i>;
unsigned int <i>width</i>, <i>height</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which specify
the upper-left corner of the rectangle.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the width and height, which specify the
dimensions of the rectangle.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>To draw the outline of multiple rectangles in a
given drawable, use <i>XDrawRectangles</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>XDrawRectangles(<i>display</i>, <i>d</i>, <i>gc</i>, <i>rectangles</i>, <i>nrectangles</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
XRectangle <i>rectangles</i>[];
int <i>nrectangles</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<p><small><i>rectangles</i> Specifies an array of
rectangles.</small></p>
<p><small><i>nrectangles</i> Specifies the number of
rectangles in the array.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XDrawRectangle</i> and
<i>XDrawRectangles</i> functions draw the outlines of the
specified rectangle or rectangles as if a five-point
<i>PolyLine</i> protocol request were specified for each
rectangle:</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>[x,y] [x+width,y] [x+width,y+height] [x,y+height]
[x,y]</small></p>
</td>
</table>
<p><small>For the specified rectangle or rectangles, these
functions do not draw a pixel more than once.
<i>XDrawRectangles</i> draws the rectangles in the order
listed in the array. If rectangles intersect, the
intersecting pixels are drawn multiple times.</small></p>
<p><small>Both functions 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. They also use these GC mode-dependent
components: foreground, background, tile, stipple,
tile-stipple-x-origin, tile-stipple-y-origin, dash-offset,
and dash-list.</small></p>
<p><small><i>XDrawRectangle</i> and <i>XDrawRectangles</i>
can generate <i>BadDrawable</i>, <i>BadGC</i>, and
<i>BadMatch</i> errors.</small></p>
<a name="8.3.4. Drawing Single and Multiple Arcs"></a>
<h2>8.3.4. Drawing Single and Multiple Arcs</h2>
<p><small>To draw a single arc in a given drawable, use
<i>XDrawArc</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XDrawArc(<i>display</i>, <i>d</i>, <i>gc</i>, <i>x</i>, <i>y</i>, <i>width</i>, <i>height</i>, <i>angle1</i>, <i>angle2</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
int <i>x</i>, <i>y</i>;
unsigned int <i>width</i>, <i>height</i>;
int <i>angle1</i>, <i>angle2</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>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.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the width and height, which are the major
and minor axes of the arc.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>angle1</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the start of the arc relative to the
three-o’clock position from the center, in units of
degrees * 64.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>angle2</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the path and extent of the arc relative
to the start of the arc, in units of degrees *
64.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>To draw multiple arcs in a given drawable, use
<i>XDrawArcs</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>XDrawArcs(<i>display</i>, <i>d</i>, <i>gc</i>, <i>arcs</i>, <i>narcs</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
XArc *<i>arcs</i>;
int <i>narcs</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>arcs</i></small></p>
</td>
<td width="12%"></td>
<td width="54%">
<p><small>Specifies an array of arcs.</small></p>
</td>
<td width="25%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>narcs</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the number of arcs in the
array.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small><i>XDrawArc</i> draws a single circular or
elliptical arc, and <i>XDrawArcs</i> 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, <i>XDrawArc</i> or <i>XDrawArcs</i> truncates
it to 360 degrees.</small></p>
<p><small>For an arc specified as
<img src="grohtml-14392-47.png"> , the origin of the major
and minor axes is at <img src="grohtml-14392-48.png"> , and
the infinitely thin path describing the entire circle or
ellipse intersects the horizontal axis at
<img src="grohtml-14392-49.png"> and
<img src="grohtml-14392-50.png"> and intersects the vertical
axis at <img src="grohtml-14392-51.png"> and
<img src="grohtml-14392-52.png"> . 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.</small></p>
<p><small>For an arc specified as
<img src="grohtml-14392-53.png"> , 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:</small></p>
<pre><small> <img src="grohtml-14392-54.png">
</small></pre>
<p><small>The skewed-angle and normal-angle are expressed
in radians (rather than in degrees scaled by 64) in the
range <img src="grohtml-14392-55.png"> and where atan
returns a value in the range
<img src="grohtml-14392-56.png"> and adjust is:</small></p>
<pre><small> <img src="grohtml-14392-57.png"> for normal-angle in the range <img src="grohtml-14392-58.png">
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<p><small><img src="grohtml-14392-59.png"> for normal-angle
in the range <img src="grohtml-14392-60.png"><br>
<img src="grohtml-14392-61.png"> for normal-angle in the
range</small></p>
</table>
<p><small><img src="grohtml-14392-62.png"></small></p>
<p><small>For any given arc, <i>XDrawArc</i> and
<i>XDrawArcs</i> do 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, <i>XDrawArc</i> and
<i>XDrawArcs</i> do 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.</small></p>
<p><small>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.</small></p>
<p><small>Both functions 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. They also use these GC mode-dependent
components: foreground, background, tile, stipple,
tile-stipple-x-origin, tile-stipple-y-origin, dash-offset,
and dash-list.</small></p>
<p><small><i>XDrawArc</i> and <i>XDrawArcs</i> can generate
<i>BadDrawable</i>, <i>BadGC</i>, and <i>BadMatch</i>
errors.</small></p>
<a name="8.4. Filling Areas"></a>
<h2>8.4. Filling Areas</h2>
<p><small>Xlib provides functions that you can use to
fill:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="82%">
<p><small>A single rectangle or multiple
rectangles</small></p>
</td>
<td width="7%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="32%">
<p><small>A single polygon</small></p>
</td>
<td width="57%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="58%">
<p><small>A single arc or multiple arcs</small></p>
</td>
<td width="31%">
</td>
</table>
<a name="8.4.1. Filling Single and Multiple Rectangles"></a>
<h2>8.4.1. Filling Single and Multiple Rectangles</h2>
<p><small>To fill a single rectangular area in a given
drawable, use <i>XFillRectangle</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XFillRectangle(<i>display</i>, <i>d</i>, <i>gc</i>, <i>x</i>, <i>y</i>, <i>width</i>, <i>height</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
int <i>x</i>, <i>y</i>;
unsigned int <i>width</i>, <i>height</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which are
relative to the origin of the drawable and specify the
upper-left corner of the rectangle.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the width and height, which are the
dimensions of the rectangle to be filled.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>To fill multiple rectangular areas in a given
drawable, use <i>XFillRectangles</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>XFillRectangles(<i>display</i>, <i>d</i>, <i>gc</i>, <i>rectangles</i>, <i>nrectangles</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
XRectangle *<i>rectangles</i>;
int <i>nrectangles</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<p><small><i>rectangles</i> Specifies an array of
rectangles.</small></p>
<p><small><i>nrectangles</i> Specifies the number of
rectangles in the array.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XFillRectangle</i> and
<i>XFillRectangles</i> functions fill the specified
rectangle or rectangles as if a four-point
<i>FillPolygon</i> protocol request were specified for each
rectangle:</small></p>
<pre><small> [x,y] [x+width,y] [x+width,y+height] [x,y+height]
</small></pre>
<p><small>Each function uses the x and y coordinates, width
and height dimensions, and GC you specify.</small></p>
<p><small><i>XFillRectangles</i> fills the rectangles in
the order listed in the array. For any given rectangle,
<i>XFillRectangle</i> and <i>XFillRectangles</i> do not draw
a pixel more than once. If rectangles intersect, the
intersecting pixels are drawn multiple times.</small></p>
<p><small>Both functions use 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.</small></p>
<p><small><i>XFillRectangle</i> and <i>XFillRectangles</i>
can generate <i>BadDrawable</i>, <i>BadGC</i>, and
<i>BadMatch</i> errors.</small></p>
<a name="8.4.2. Filling a Single Polygon"></a>
<h2>8.4.2. Filling a Single Polygon</h2>
<p><small>To fill a polygon area in a given drawable, use
<i>XFillPolygon</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XFillPolygon(<i>display</i>, <i>d</i>, <i>gc</i>, <i>points</i>, <i>npoints</i>, <i>shape</i>, <i>mode</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
XPoint *<i>points</i>;
int <i>npoints</i>;
int <i>shape</i>;
int <i>mode</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>points</i></small></p>
</td>
<td width="8%"></td>
<td width="58%">
<p><small>Specifies an array of points.</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>npoints</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the number of points in the
array.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>shape</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies a shape that helps the server to
improve performance. You can pass <i>Complex</i>,
<i>Convex</i>, or <i>Nonconvex</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>mode</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the coordinate mode. You can pass
<i>CoordModeOrigin</i> or
<i>CoordModePrevious</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small><i>XFillPolygon</i> 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. <i>XFillPolygon</i> does not draw a pixel of the
region more than once. <i>CoordModeOrigin</i> treats all
coordinates as relative to the origin, and
<i>CoordModePrevious</i> treats all coordinates after the
first as relative to the previous point.</small></p>
<p><small>Depending on the specified shape, the following
occurs:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If shape is <i>Complex</i>, the path may
self-intersect. Note that contiguous coincident points in
the path are not treated as self-intersection.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If shape is <i>Convex</i>, for every pair of
points inside the polygon, the line segment connecting them
does not intersect the path. If known by the client,
specifying <i>Convex</i> can improve performance. If you
specify <i>Convex</i> for a path that is not convex, the
graphics results are undefined.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If shape is <i>Nonconvex</i>, the path does not
self-intersect, but the shape is not wholly convex. If known
by the client, specifying <i>Nonconvex</i> instead of
<i>Complex</i> may improve performance. If you specify
<i>Nonconvex</i> for a self-intersecting path, the graphics
results are undefined.</small></p>
</td>
</table>
<p><small>The fill-rule of the GC controls the filling
behavior of self-intersecting polygons.</small></p>
<p><small>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.</small></p>
<p><small><i>XFillPolygon</i> can generate
<i>BadDrawable</i>, <i>BadGC</i>, <i>BadMatch</i>, and
<i>BadValue</i> errors.</small></p>
<a name="8.4.3. Filling Single and Multiple Arcs"></a>
<h2>8.4.3. Filling Single and Multiple Arcs</h2>
<p><small>To fill a single arc in a given drawable, use
<i>XFillArc</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XFillArc(<i>display</i>, <i>d</i>, <i>gc</i>, <i> x</i>, <i>y</i>, <i>width</i>, <i>height</i>, <i>angle1</i>, <i>angle2</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
int <i>x</i>, <i>y</i>;
unsigned int <i>width</i>, <i>height</i>;
int <i>angle1</i>, <i>angle2</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>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.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the width and height, which are the major
and minor axes of the arc.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>angle1</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the start of the arc relative to the
three-o’clock position from the center, in units of
degrees * 64.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>angle2</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the path and extent of the arc relative
to the start of the arc, in units of degrees *
64.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>To fill multiple arcs in a given drawable, use
<i>XFillArcs</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>XFillArcs(<i>display</i>, <i>d</i>, <i>gc</i>, <i>arcs</i>, <i>narcs</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
XArc *<i>arcs</i>;
int <i>narcs</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>arcs</i></small></p>
</td>
<td width="12%"></td>
<td width="54%">
<p><small>Specifies an array of arcs.</small></p>
</td>
<td width="25%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>narcs</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the number of arcs in the
array.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>For each arc, <i>XFillArc</i> or <i>XFillArcs</i>
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
<i>ArcChord</i>, the single line segment joining the
endpoints of the arc is used. For <i>ArcPieSlice</i>, the
two line segments joining the endpoints of the arc with the
center point are used. <i>XFillArcs</i> fills the arcs in
the order listed in the array. For any given arc,
<i>XFillArc</i> and <i>XFillArcs</i> do not draw a pixel
more than once. If regions intersect, the intersecting
pixels are drawn multiple times.</small></p>
<p><small>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.</small></p>
<p><small><i>XFillArc</i> and <i>XFillArcs</i> can generate
<i>BadDrawable</i>, <i>BadGC</i>, and <i>BadMatch</i>
errors.</small></p>
<a name="8.5. Font Metrics"></a>
<h2>8.5. Font Metrics</h2>
<p><small>A font is a graphical description of a set of
characters that are used to increase efficiency whenever a
set of small, similar sized patterns are repeatedly
used.</small></p>
<p><small>This section discusses how to:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="38%">
<p><small>Load and free fonts</small></p>
</td>
<td width="51%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="52%">
<p><small>Obtain and free font names</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="60%">
<p><small>Compute character string sizes</small></p>
</td>
<td width="29%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="46%">
<p><small>Compute logical extents</small></p>
</td>
<td width="43%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="56%">
<p><small>Query character string sizes</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small>The X server loads fonts whenever a program
requests a new font. The server can cache fonts for quick
lookup. Fonts are global across all screens in a server.
Several levels are possible when dealing with fonts. Most
applications simply use <i>XLoadQueryFont</i> to load a font
and query the font metrics.</small></p>
<p><small>Characters in fonts are regarded as masks. Except
for image text requests, the only pixels modified are those
in which bits are set to 1 in the character. This means that
it makes sense to draw text using stipples or tiles (for
example, many menus gray-out unusable entries).</small></p>
<p><small>__ │<br>
The <i>XFontStruct</i> structure contains all of the
information for the font and consists of the font-specific
information as well as a pointer to an array of
<i>XCharStruct</i> structures for the characters contained
in the font. The <i>XFontStruct</i>, <i>XFontProp</i>, and
<i>XCharStruct</i> structures contain:</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>short lbearing;</small></p>
</td>
<td width="40%">
<p><small>/* origin to left edge of raster */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>short rbearing;</small></p>
</td>
<td width="40%">
<p><small>/* origin to right edge of raster */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>short width;</small></p>
</td>
<td width="40%">
<p><small>/* advance to next char’s origin
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>short ascent;</small></p>
</td>
<td width="40%">
<p><small>/* baseline to top edge of raster */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>short descent;</small></p>
</td>
<td width="40%">
<p><small>/* baseline to bottom edge of raster
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned short attributes;/* per char flags (not
predefined) */</small></p>
</td>
<td width="40%">
</td>
</table>
<p><small>} XCharStruct;</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>Atom</small></p>
</td>
<td width="40%">
<p><small>name;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>unsigned long card32;</small></p>
</td>
<td width="40%"></td>
<td width="39%">
</td>
</table>
<p><small>} XFontProp;</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small>typedef struct {</small></p>
</td>
<td width="50%"></td>
<td width="40%">
<p><small>/* normal 16 bit characters are two bytes
*/</small></p>
</td>
</table>
<p><small>unsigned char byte1;<br>
unsigned char byte2;<br>
} XChar2b;</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XExtData *ext_data;</small></p>
</td>
<td width="40%">
<p><small>/* hook for extension to hang data */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Font fid;</small></p>
</td>
<td width="40%">
<p><small>/* Font id for this font */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned direction;</small></p>
</td>
<td width="40%">
<p><small>/* hint about the direction font is painted
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned min_char_or_byte2;/* first character
*/</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned max_char_or_byte2;/* last character
*/</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned min_byte1;</small></p>
</td>
<td width="40%">
<p><small>/* first row that exists */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned max_byte1;</small></p>
</td>
<td width="40%">
<p><small>/* last row that exists */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool all_chars_exist;</small></p>
</td>
<td width="40%">
<p><small>/* flag if all characters have nonzero size
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned default_char;</small></p>
</td>
<td width="40%">
<p><small>/* char to print for undefined character
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int n_properties;</small></p>
</td>
<td width="40%">
<p><small>/* how many properties there are */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XFontProp *properties;</small></p>
</td>
<td width="40%">
<p><small>/* pointer to array of additional properties
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XCharStruct min_bounds;</small></p>
</td>
<td width="40%">
<p><small>/* minimum bounds over all existing char
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XCharStruct max_bounds;</small></p>
</td>
<td width="40%">
<p><small>/* maximum bounds over all existing char
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XCharStruct *per_char;</small></p>
</td>
<td width="40%">
<p><small>/* first_char to last_char information
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int ascent;</small></p>
</td>
<td width="40%">
<p><small>/* logical extent above baseline for spacing
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int descent;</small></p>
</td>
<td width="40%">
<p><small>/* logical descent below baseline for spacing
*/</small></p>
</td>
</table>
<p><small>} XFontStruct;</small></p>
<p><small>│__</small></p>
<p><small>X supports single byte/character, two
bytes/character matrix, and 16-bit character text
operations. Note that any of these forms can be used with a
font, but a single byte/character text request can only
specify a single byte (that is, the first row of a 2-byte
font). You should view 2-byte fonts as a two-dimensional
matrix of defined characters: byte1 specifies the range of
defined rows and byte2 defines the range of defined columns
of the font. Single byte/character fonts have one row
defined, and the byte2 range specified in the structure
defines a range of characters.</small></p>
<p><small>The bounding box of a character is defined by the
<i>XCharStruct</i> of that character. When characters are
absent from a font, the default_char is used. When fonts
have all characters of the same size, only the information
in the <i>XFontStruct</i> min and max bounds are
used.</small></p>
<p><small>The members of the <i>XFontStruct</i> have the
following semantics:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The direction member can be either
<i>FontLeftToRight</i> or <i>FontRightToLeft</i>. It is just
a hint as to whether most <i>XCharStruct</i> elements have a
positive (<i>FontLeftToRight</i>) or a negative
(<i>FontRightToLeft</i>) character width metric. The core
protocol defines no support for vertical text.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If the min_byte1 and max_byte1 members are both
zero, min_char_or_byte2 specifies the linear character index
corresponding to the first element of the per_char array,
and max_char_or_byte2 specifies the linear character index
of the last element.</small></p>
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>If either min_byte1 or max_byte1 are nonzero, both
min_char_or_byte2 and max_char_or_byte2 are less than 256,
and the 2-byte character index values corresponding to the
per_char array element N (counting from 0) are:</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="10%">
<p><small>byte1 = N/D + min_byte1</small></p>
</td>
<td width="69%">
</td>
<tr valign="top" align="left">
<td width="19%"></td>
<td width="10%">
<p><small>byte2 = N\D + min_char_or_byte2</small></p>
</td>
<td width="69%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>where:</small></p>
<!-- INDENTATION -->
<pre><small> D = max_char_or_byte2 − min_char_or_byte2 + 1
/ = integer division
\ = integer modulus
</small></pre>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If the per_char pointer is NULL, all glyphs
between the first and last character indexes inclusive have
the same information, as given by both min_bounds and
max_bounds.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If all_chars_exist is <i>True</i>, all characters
in the per_char array have nonzero bounding
boxes.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The default_char member specifies the character
that will be used when an undefined or nonexistent character
is printed. The default_char is a 16-bit character (not a
2-byte character). For a font using 2-byte matrix format,
the default_char has byte1 in the most-significant byte and
byte2 in the least significant byte. If the default_char
itself specifies an undefined or nonexistent character, no
printing is performed for an undefined or nonexistent
character.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The min_bounds and max_bounds members contain the
most extreme values of each individual <i>XCharStruct</i>
component over all elements of this array (and ignore
nonexistent characters). The bounding box of the font (the
smallest rectangle enclosing the shape obtained by
superimposing all of the characters at the same origin
[x,y]) has its upper-left coordinate at:</small></p>
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<pre><small> [x + min_bounds.lbearing, y − max_bounds.ascent]
</small></pre>
<!-- INDENTATION -->
<p><small>Its width is:</small></p>
<!-- INDENTATION -->
<pre><small> max_bounds.rbearing − min_bounds.lbearing
</small></pre>
<!-- INDENTATION -->
<p><small>Its height is:</small></p>
<!-- INDENTATION -->
<pre><small> max_bounds.ascent + max_bounds.descent
</small></pre>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The ascent member is the logical extent of the
font above the baseline that is used for determining line
spacing. Specific characters may extend beyond
this.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The descent member is the logical extent of the
font at or below the baseline that is used for determining
line spacing. Specific characters may extend beyond
this.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If the baseline is at Y-coordinate y, the logical
extent of the font is inclusive between the Y-coordinate
values (y − font.ascent) and (y + font.descent −
1). Typically, the minimum interline spacing between rows of
text is given by ascent + descent.</small></p>
</td>
</table>
<p><small>For a character origin at [x,y], the bounding box
of a character (that is, the smallest rectangle that
encloses the character’s shape) described in terms of
<i>XCharStruct</i> components is a rectangle with its
upper-left corner at:</small></p>
<pre><small> [x + lbearing, y − ascent]
</small></pre>
<p><small>Its width is:</small></p>
<pre><small> rbearing − lbearing
</small></pre>
<p><small>Its height is:</small></p>
<pre><small> ascent + descent
</small></pre>
<p><small>The origin for the next character is defined to
be:</small></p>
<pre><small> [x + width, y]
</small></pre>
<p><small>The lbearing member defines the extent of the
left edge of the character ink from the origin. The rbearing
member defines the extent of the right edge of the character
ink from the origin. The ascent member defines the extent of
the top edge of the character ink from the origin. The
descent member defines the extent of the bottom edge of the
character ink from the origin. The width member defines the
logical width of the character.</small></p>
<p><small>Note that the baseline (the y position of the
character origin) is logically viewed as being the scanline
just below nondescending characters. When descent is zero,
only pixels with Y-coordinates less than y are drawn, and
the origin is logically viewed as being coincident with the
left edge of a nonkerned character. When lbearing is zero,
no pixels with X-coordinate less than x are drawn. Any of
the <i>XCharStruct</i> metric members could be negative. If
the width is negative, the next character will be placed to
the left of the current origin.</small></p>
<p><small>The X protocol does not define the interpretation
of the attributes member in the <i>XCharStruct</i>
structure. A nonexistent character is represented with all
members of its <i>XCharStruct</i> set to zero.</small></p>
<p><small>A font is not guaranteed to have any properties.
The interpretation of the property value (for example, long
or unsigned long) must be derived from <i>a priori</i>
knowledge of the property. A basic set of font properties is
specified in the X Consortium standard <i>X Logical Font
Description Conventions</i>.</small></p>
<a name="8.5.1. Loading and Freeing Fonts"></a>
<h2>8.5.1. Loading and Freeing Fonts</h2>
<p><small>Xlib provides functions that you can use to load
fonts, get font information, unload fonts, and free font
information. A few font functions use a <i>GContext</i>
resource ID or a font ID interchangeably.</small></p>
<p><small>To load a given font, use
<i>XLoadFont</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Font XLoadFont(<i>display</i>, <i>name</i>)
Display *<i>display</i>;
char *<i>name</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>name</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the name of the font, which is a
null-terminated string.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XLoadFont</i> function loads the specified
font and returns its associated font ID. If the font name is
not in the Host Portable Character Encoding, the result is
implementation-dependent. Use of uppercase or lowercase does
not matter. When the characters
‘‘?’’ and
‘‘*’’ are used in a font name, a
pattern match is performed and any matching font is used. In
the pattern, the ‘‘?’’ character
will match any single character, and the
‘‘*’’ character will match any
number of characters. A structured format for font names is
specified in the X Consortium standard <i>X Logical Font
Description Conventions</i>. If <i>XLoadFont</i> was
unsuccessful at loading the specified font, a <i>BadName</i>
error results. Fonts are not associated with a particular
screen and can be stored as a component of any GC. When the
font is no longer needed, call
<i>XUnloadFont</i>.</small></p>
<p><small><i>XLoadFont</i> can generate <i>BadAlloc</i> and
<i>BadName</i> errors.</small></p>
<p><small>To return information about an available font,
use <i>XQueryFont</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XFontStruct *XQueryFont(<i>display</i>, <i>font_ID</i>)
Display *<i>display</i>;
XID <i>font_ID</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>font_ID</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the font ID or the <i>GContext</i>
ID.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XQueryFont</i> function returns a pointer
to the <i>XFontStruct</i> structure, which contains
information associated with the font. You can query a font
or the font stored in a GC. The font ID stored in the
<i>XFontStruct</i> structure will be the <i>GContext</i> ID,
and you need to be careful when using this ID in other
functions (see <i>XGContextFromGC</i>). If the font does not
exist, <i>XQueryFont</i> returns NULL. To free this data,
use <i>XFreeFontInfo</i>.</small></p>
<p><small>To perform a <i>XLoadFont</i> and
<i>XQueryFont</i> in a single operation, use
<i>XLoadQueryFont</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XFontStruct *XLoadQueryFont(<i>display</i>, <i>name</i>)
Display *<i>display</i>;
char *<i>name</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>name</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the name of the font, which is a
null-terminated string.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XLoadQueryFont</i> function provides the
most common way for accessing a font. <i>XLoadQueryFont</i>
both opens (loads) the specified font and returns a pointer
to the appropriate <i>XFontStruct</i> structure. If the font
name is not in the Host Portable Character Encoding, the
result is implementation-dependent. If the font does not
exist, <i>XLoadQueryFont</i> returns NULL.</small></p>
<p><small><i>XLoadQueryFont</i> can generate a
<i>BadAlloc</i> error.</small></p>
<p><small>To unload the font and free the storage used by
the font structure that was allocated by <i>XQueryFont</i>
or <i>XLoadQueryFont</i>, use <i>XFreeFont</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XFreeFont(<i>display</i>, <i>font_struct</i>)
Display *<i>display</i>;
XFontStruct *<i>font_struct</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>font_struct</i> Specifies the storage
associated with the font.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XFreeFont</i> function deletes the
association between the font resource ID and the specified
font and frees the <i>XFontStruct</i> structure. The font
itself will be freed when no other resource references it.
The data and the font should not be referenced
again.</small></p>
<p><small><i>XFreeFont</i> can generate a <i>BadFont</i>
error.</small></p>
<p><small>To return a given font property, use
<i>XGetFontProperty</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XGetFontProperty(<i>font_struct</i>, <i>atom</i>, <i>value_return</i>)
XFontStruct *<i>font_struct</i>;
Atom <i>atom</i>;
unsigned long *<i>value_return</i>;
</small></pre>
<p><small><i>font_struct</i> Specifies the storage
associated with the font.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>atom</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the atom for the property name you want
returned.</small></p>
</td>
</table>
<p><small><i>value_return</i> Returns the value of the font
property.</small></p>
<p><small>│__</small></p>
<p><small>Given the atom for that property, the
<i>XGetFontProperty</i> function returns the value of the
specified font property. <i>XGetFontProperty</i> also
returns <i>False</i> if the property was not defined or
<i>True</i> if it was defined. A set of predefined atoms
exists for font properties, which can be found in
<<i>X11/Xatom.h</i>>. This set contains the standard
properties associated with a font. Although it is not
guaranteed, it is likely that the predefined font properties
will be present.</small></p>
<p><small>To unload a font that was loaded by
<i>XLoadFont</i>, use <i>XUnloadFont</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XUnloadFont(<i>display</i>, <i>font</i>)
Display *<i>display</i>;
Font <i>font</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>font</i></small></p>
</td>
<td width="12%"></td>
<td width="38%">
<p><small>Specifies the font.</small></p>
</td>
<td width="41%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XUnloadFont</i> function deletes the
association between the font resource ID and the specified
font. The font itself will be freed when no other resource
references it. The font should not be referenced
again.</small></p>
<p><small><i>XUnloadFont</i> can generate a <i>BadFont</i>
error.</small></p>
<a name="8.5.2. Obtaining and Freeing Font Names and Information"></a>
<h2>8.5.2. Obtaining and Freeing Font Names and Information</h2>
<p><small>You obtain font names and information by matching
a wildcard specification when querying a font type for a
list of available sizes and so on.</small></p>
<p><small>To return a list of the available font names, use
<i>XListFonts</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char **XListFonts(<i>display</i>, <i>pattern</i>, <i>maxnames</i>, <i>actual_count_return</i>)
Display *<i>display</i>;
char *<i>pattern</i>;
int <i>maxnames</i>;
int *<i>actual_count_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>pattern</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the null-terminated pattern string that
can contain wildcard characters.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>maxnames</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the maximum number of names to be
returned.</small></p>
</td>
</table>
<p><small><i>actual_count_return</i> Returns the actual
number of font names.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XListFonts</i> function returns an array
of available font names (as controlled by the font search
path; see <i>XSetFontPath</i>) 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. Each returned string is null-terminated. 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, <i>XListFonts</i> returns NULL. The client should
call <i>XFreeFontNames</i> when finished with the result to
free the memory.</small></p>
<p><small>To free a font name array, use
<i>XFreeFontNames</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XFreeFontNames(<i>list</i>)
char *<i>list</i>[];
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>list</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the array of strings you want to
free.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XFreeFontNames</i> function frees the
array and strings returned by <i>XListFonts</i> or
<i>XListFontsWithInfo</i>.</small></p>
<p><small>To obtain the names and information about
available fonts, use <i>XListFontsWithInfo</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char **XListFontsWithInfo(<i>display</i>, <i>pattern</i>, <i>maxnames</i>, <i>count_return</i>, <i>info_return</i>)
Display *<i>display</i>;
char *<i>pattern</i>;
int <i>maxnames</i>;
int *<i>count_return</i>;
XFontStruct **<i>info_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>pattern</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the null-terminated pattern string that
can contain wildcard characters.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>maxnames</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the maximum number of names to be
returned.</small></p>
</td>
</table>
<p><small><i>count_return</i> Returns the actual number of
matched font names.</small></p>
<p><small><i>info_return</i> Returns the font
information.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XListFontsWithInfo</i> function returns a
list of font names 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
<i>XLoadQueryFont</i> 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. Each returned string
is null-terminated. 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, <i>XListFontsWithInfo</i>
returns NULL.</small></p>
<p><small>To free only the allocated name array, the client
should call <i>XFreeFontNames</i>. To free both the name
array and the font information array or to free just the
font information array, the client should call
<i>XFreeFontInfo</i>.</small></p>
<p><small>To free font structures and font names, use
<i>XFreeFontInfo</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XFreeFontInfo(<i>names</i>, <i>free_info</i>, <i>actual_count</i>)
char **<i>names</i>;
XFontStruct *<i>free_info</i>;
int <i>actual_count</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>names</i></small></p>
</td>
<td width="10%"></td>
<td width="66%">
<p><small>Specifies the list of font names.</small></p>
</td>
<td width="13%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>free_info</i></small></p>
</td>
<td width="2%"></td>
<td width="62%">
<p><small>Specifies the font information.</small></p>
</td>
<td width="17%">
</td>
</table>
<p><small><i>actual_count</i> Specifies the actual number
of font names.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XFreeFontInfo</i> function frees a font
structure or an array of font structures and optionally an
array of font names. If NULL is passed for names, no font
names are freed. If a font structure for an open font
(returned by <i>XLoadQueryFont</i>) is passed, the structure
is freed, but the font is not closed; use <i>XUnloadFont</i>
to close the font.</small></p>
<a name="8.5.3. Computing Character String Sizes"></a>
<h2>8.5.3. Computing Character String Sizes</h2>
<p><small>Xlib provides functions that you can use to
compute the width, the logical extents, and the server
information about 8-bit and 2-byte text strings. The width
is computed by adding the character widths of all the
characters. It does not matter if the font is an 8-bit or
2-byte font. These functions return the sum of the character
metrics in pixels.</small></p>
<p><small>To determine the width of an 8-bit character
string, use <i>XTextWidth</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XTextWidth(<i>font_struct</i>, <i>string</i>, <i>count</i>)
XFontStruct *<i>font_struct</i>;
char *<i>string</i>;
int <i>count</i>;
</small></pre>
<p><small><i>font_struct</i> Specifies the font used for
the width computation.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Specifies the character string.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>count</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the character count in the specified
string.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>To determine the width of a 2-byte character
string, use <i>XTextWidth16</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>int XTextWidth16(<i>font_struct</i>, <i>string</i>, <i>count</i>)
XFontStruct *<i>font_struct</i>;
XChar2b *<i>string</i>;
int <i>count</i>;
</small></pre>
<p><small><i>font_struct</i> Specifies the font used for
the width computation.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Specifies the character string.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>count</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the character count in the specified
string.</small></p>
</td>
</table>
<p><small>│__</small></p>
<a name="8.5.4. Computing Logical Extents"></a>
<h2>8.5.4. Computing Logical Extents</h2>
<p><small>To compute the bounding box of an 8-bit character
string in a given font, use <i>XTextExtents</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XTextExtents(<i>font_struct</i>, <i>string</i>, <i>nchars</i>, <i>direction_return</i>, <i>font_ascent_return</i>,
<i> font_descent_return</i>, <i>overall_return</i>)
XFontStruct *<i>font_struct</i>;
char *<i>string</i>;
int <i>nchars</i>;
int *<i>direction_return</i>;
int *<i>font_ascent_return</i>, *<i>font_descent_return</i>;
XCharStruct *<i>overall_return</i>;
</small></pre>
<p><small><i>font_struct</i> Specifies the
<i>XFontStruct</i> structure.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Specifies the character string.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>nchars</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the number of characters in the
character string.</small></p>
</td>
</table>
<p><small><i>direction_return</i> Returns the value of the
direction hint (<i>FontLeftToRight</i> or
<i>FontRightToLeft</i>).</small></p>
<p><small><i>font_ascent_return</i> Returns the font
ascent.</small></p>
<p><small><i>font_descent_return</i> Returns the font
descent.</small></p>
<p><small><i>overall_return</i> Returns the overall size in
the specified <i>XCharStruct</i> structure.</small></p>
<p><small>│__</small></p>
<p><small>To compute the bounding box of a 2-byte character
string in a given font, use
<i>XTextExtents16</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>XTextExtents16(<i>font_struct</i>, <i>string</i>, <i>nchars</i>, <i>direction_return</i>, <i>font_ascent_return</i>,
<i> font_descent_return</i>, <i>overall_return</i>)
XFontStruct *<i>font_struct</i>;
XChar2b *<i>string</i>;
int <i>nchars</i>;
int *<i>direction_return</i>;
int *<i>font_ascent_return</i>, *<i>font_descent_return</i>;
XCharStruct *<i>overall_return</i>;
</small></pre>
<p><small><i>font_struct</i> Specifies the
<i>XFontStruct</i> structure.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Specifies the character string.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>nchars</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the number of characters in the
character string.</small></p>
</td>
</table>
<p><small><i>direction_return</i> Returns the value of the
direction hint (<i>FontLeftToRight</i> or
<i>FontRightToLeft</i>).</small></p>
<p><small><i>font_ascent_return</i> Returns the font
ascent.</small></p>
<p><small><i>font_descent_return</i> Returns the font
descent.</small></p>
<p><small><i>overall_return</i> Returns the overall size in
the specified <i>XCharStruct</i> structure.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XTextExtents</i> and <i>XTextExtents16</i>
functions perform the size computation locally and, thereby,
avoid the round-trip overhead of <i>XQueryTextExtents</i>
and <i>XQueryTextExtents16</i>. Both functions return an
<i>XCharStruct</i> structure, whose members are set to the
values as follows.</small></p>
<p><small>The ascent member is set to the maximum of the
ascent metrics of all characters in the string. The descent
member is set to the maximum of the descent metrics. The
width member is set to the sum of the character-width
metrics of all characters in the string. For each character
in the string, let W be the sum of the character-width
metrics of all characters preceding it in the string. Let L
be the left-side-bearing metric of the character plus W. Let
R be the right-side-bearing metric of the character plus W.
The lbearing member is set to the minimum L of all
characters in the string. The rbearing member is set to the
maximum R.</small></p>
<p><small>For fonts defined with linear indexing rather
than 2-byte matrix indexing, each <i>XChar2b</i> structure
is interpreted as a 16-bit number with byte1 as the most
significant byte. If the font has no defined default
character, undefined characters in the string are taken to
have all zero metrics.</small></p>
<a name="8.5.5. Querying Character String Sizes"></a>
<h2>8.5.5. Querying Character String Sizes</h2>
<p><small>To query the server for the bounding box of an
8-bit character string in a given font, use
<i>XQueryTextExtents</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XQueryTextExtents(<i>display</i>, <i>font_ID</i>, <i>string</i>, <i>nchars</i>, <i>direction_return</i>, <i>font_ascent_return</i>,
<i> font_descent_return</i>, <i>overall_return</i>)
Display *<i>display</i>;
XID <i>font_ID</i>;
char *<i>string</i>;
int <i>nchars</i>;
int *<i>direction_return</i>;
int *<i>font_ascent_return</i>, *<i>font_descent_return</i>;
XCharStruct *<i>overall_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>font_ID</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies either the font ID or the
<i>GContext</i> ID that contains the font.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Specifies the character string.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>nchars</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the number of characters in the
character string.</small></p>
</td>
</table>
<p><small><i>direction_return</i> Returns the value of the
direction hint (<i>FontLeftToRight</i> or
<i>FontRightToLeft</i>).</small></p>
<p><small><i>font_ascent_return</i> Returns the font
ascent.</small></p>
<p><small><i>font_descent_return</i> Returns the font
descent.</small></p>
<p><small><i>overall_return</i> Returns the overall size in
the specified <i>XCharStruct</i> structure.</small></p>
<p><small>│__</small></p>
<p><small>To query the server for the bounding box of a
2-byte character string in a given font, use
<i>XQueryTextExtents16</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>XQueryTextExtents16(<i>display</i>, <i>font_ID</i>, <i>string</i>, <i>nchars</i>, <i>direction_return</i>, <i>font_ascent_return</i>,
<i> font_descent_return</i>, <i>overall_return</i>)
Display *<i>display</i>;
XID <i>font_ID</i>;
XChar2b *<i>string</i>;
int <i>nchars</i>;
int *<i>direction_return</i>;
int *<i>font_ascent_return</i>, *<i>font_descent_return</i>;
XCharStruct *<i>overall_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>font_ID</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies either the font ID or the
<i>GContext</i> ID that contains the font.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Specifies the character string.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>nchars</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the number of characters in the
character string.</small></p>
</td>
</table>
<p><small><i>direction_return</i> Returns the value of the
direction hint (<i>FontLeftToRight</i> or
<i>FontRightToLeft</i>).</small></p>
<p><small><i>font_ascent_return</i> Returns the font
ascent.</small></p>
<p><small><i>font_descent_return</i> Returns the font
descent.</small></p>
<p><small><i>overall_return</i> Returns the overall size in
the specified <i>XCharStruct</i> structure.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XQueryTextExtents</i> and
<i>XQueryTextExtents16</i> functions return the bounding box
of the specified 8-bit and 16-bit character string in the
specified font or the font contained in the specified GC.
These functions query the X server and, therefore, suffer
the round-trip overhead that is avoided by
<i>XTextExtents</i> and <i>XTextExtents16</i>. Both
functions return a <i>XCharStruct</i> structure, whose
members are set to the values as follows.</small></p>
<p><small>The ascent member is set to the maximum of the
ascent metrics of all characters in the string. The descent
member is set to the maximum of the descent metrics. The
width member is set to the sum of the character-width
metrics of all characters in the string. For each character
in the string, let W be the sum of the character-width
metrics of all characters preceding it in the string. Let L
be the left-side-bearing metric of the character plus W. Let
R be the right-side-bearing metric of the character plus W.
The lbearing member is set to the minimum L of all
characters in the string. The rbearing member is set to the
maximum R.</small></p>
<p><small>For fonts defined with linear indexing rather
than 2-byte matrix indexing, each <i>XChar2b</i> structure
is interpreted as a 16-bit number with byte1 as the most
significant byte. If the font has no defined default
character, undefined characters in the string are taken to
have all zero metrics.</small></p>
<p><small>Characters with all zero metrics are ignored. If
the font has no defined default_char, the undefined
characters in the string are also ignored.</small></p>
<p><small><i>XQueryTextExtents</i> and
<i>XQueryTextExtents16</i> can generate <i>BadFont</i> and
<i>BadGC</i> errors.</small></p>
<a name="8.6. Drawing Text"></a>
<h2>8.6. Drawing Text</h2>
<p><small>This section discusses how to draw:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="24%">
<p><small>Complex text</small></p>
</td>
<td width="65%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="30%">
<p><small>Text characters</small></p>
</td>
<td width="59%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>Image text characters</small></p>
</td>
<td width="47%">
</td>
</table>
<p><small>The fundamental text functions <i>XDrawText</i>
and <i>XDrawText16</i> use the following
structures:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>char *chars;</small></p>
</td>
<td width="40%">
<p><small>/* pointer to string */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int nchars;</small></p>
</td>
<td width="40%">
<p><small>/* number of characters */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int delta;</small></p>
</td>
<td width="40%">
<p><small>/* delta between strings */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Font font;</small></p>
</td>
<td width="40%">
<p><small>/* Font to print it in, None don’t change
*/</small></p>
</td>
</table>
<p><small>} XTextItem;</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XChar2b *chars;</small></p>
</td>
<td width="40%">
<p><small>/* pointer to two-byte characters */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int nchars;</small></p>
</td>
<td width="40%">
<p><small>/* number of characters */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int delta;</small></p>
</td>
<td width="40%">
<p><small>/* delta between strings */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Font font;</small></p>
</td>
<td width="40%">
<p><small>/* font to print it in, None don’t change
*/</small></p>
</td>
</table>
<p><small>} XTextItem16;</small></p>
<p><small>│__</small></p>
<p><small>If the font member is not <i>None</i>, the font
is changed before printing and also is stored in the GC. If
an error was generated during text drawing, the previous
items may have been drawn. The baseline of the characters
are drawn starting at the x and y coordinates that you pass
in the text drawing functions.</small></p>
<p><small>For example, consider the background rectangle
drawn by <i>XDrawImageString</i>. If you want the upper-left
corner of the background rectangle to be at pixel coordinate
(x,y), pass the (x,y + ascent) as the baseline origin
coordinates to the text functions. The ascent is the font
ascent, as given in the <i>XFontStruct</i> structure. If you
want the lower-left corner of the background rectangle to be
at pixel coordinate (x,y), pass the (x,y − descent +
1) as the baseline origin coordinates to the text functions.
The descent is the font descent, as given in the
<i>XFontStruct</i> structure.</small></p>
<a name="8.6.1. Drawing Complex Text"></a>
<h2>8.6.1. Drawing Complex Text</h2>
<p><small>To draw 8-bit characters in a given drawable, use
<i>XDrawText</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XDrawText(<i>display</i>, <i>d</i>, <i>gc</i>, <i>x</i>, <i>y</i>, <i>items</i>, <i>nitems</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
int <i>x</i>, <i>y</i>;
XTextItem *<i>items</i>;
int <i>nitems</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which are
relative to the origin of the specified drawable and define
the origin of the first character.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>items</i></small></p>
</td>
<td width="10%"></td>
<td width="66%">
<p><small>Specifies an array of text items.</small></p>
</td>
<td width="13%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>nitems</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the number of text items in the
array.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>To draw 2-byte characters in a given drawable,
use <i>XDrawText16</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>XDrawText16(<i>display</i>, <i>d</i>, <i>gc</i>, <i>x</i>, <i>y</i>, <i>items</i>, <i>nitems</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
int <i>x</i>, <i>y</i>;
XTextItem16 *<i>items</i>;
int <i>nitems</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which are
relative to the origin of the specified drawable and define
the origin of the first character.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>items</i></small></p>
</td>
<td width="10%"></td>
<td width="66%">
<p><small>Specifies an array of text items.</small></p>
</td>
<td width="13%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>nitems</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the number of text items in the
array.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XDrawText16</i> function is similar to
<i>XDrawText</i> except that it uses 2-byte or 16-bit
characters. Both functions allow complex spacing and font
shifts between counted strings.</small></p>
<p><small>Each text item is processed in turn. A font
member other than <i>None</i> 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 <i>BadFont</i> error, the
previous text items may have been drawn.</small></p>
<p><small>For fonts defined with linear indexing rather
than 2-byte matrix indexing, each <i>XChar2b</i> structure
is interpreted as a 16-bit number with byte1 as the most
significant byte.</small></p>
<p><small>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.</small></p>
<p><small><i>XDrawText</i> and <i>XDrawText16</i> can
generate <i>BadDrawable</i>, <i>BadFont</i>, <i>BadGC</i>,
and <i>BadMatch</i> errors.</small></p>
<a name="8.6.2. Drawing Text Characters"></a>
<h2>8.6.2. Drawing Text Characters</h2>
<p><small>To draw 8-bit characters in a given drawable, use
<i>XDrawString</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XDrawString(<i>display</i>, <i>d</i>, <i>gc</i>, <i>x</i>, <i>y</i>, <i>string</i>, <i>length</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
int <i>x</i>, <i>y</i>;
char *<i>string</i>;
int <i>length</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which are
relative to the origin of the specified drawable and define
the origin of the first character.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Specifies the character string.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>length</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the number of characters in the string
argument.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>To draw 2-byte characters in a given drawable,
use <i>XDrawString16</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>XDrawString16(<i>display</i>, <i>d</i>, <i>gc</i>, <i>x</i>, <i>y</i>, <i>string</i>, <i>length</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
int <i>x</i>, <i>y</i>;
XChar2b *<i>string</i>;
int <i>length</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which are
relative to the origin of the specified drawable and define
the origin of the first character.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Specifies the character string.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>length</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the number of characters in the string
argument.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>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
<i>XDrawString16</i>, each byte is used as a byte2 with a
byte1 of zero.</small></p>
<p><small>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.</small></p>
<p><small><i>XDrawString</i> and <i>XDrawString16</i> can
generate <i>BadDrawable</i>, <i>BadGC</i>, and
<i>BadMatch</i> errors.</small></p>
<a name="8.6.3. Drawing Image Text Characters"></a>
<h2>8.6.3. Drawing Image Text Characters</h2>
<p><small>Some applications, in particular terminal
emulators, need to print image text in which both the
foreground and background bits of each character are
painted. This prevents annoying flicker on many
displays.</small></p>
<p><small>To draw 8-bit image text characters in a given
drawable, use <i>XDrawImageString</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XDrawImageString(<i>display</i>, <i>d</i>, <i>gc</i>, <i>x</i>, <i>y</i>, <i>string</i>, <i>length</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
int <i>x</i>, <i>y</i>;
char *<i>string</i>;
int <i>length</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which are
relative to the origin of the specified drawable and define
the origin of the first character.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Specifies the character string.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>length</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the number of characters in the string
argument.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>To draw 2-byte image text characters in a given
drawable, use <i>XDrawImageString16</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>XDrawImageString16(<i>display</i>, <i>d</i>, <i>gc</i>, <i>x</i>, <i>y</i>, <i>string</i>, <i>length</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
int <i>x</i>, <i>y</i>;
XChar2b *<i>string</i>;
int <i>length</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which are
relative to the origin of the specified drawable and define
the origin of the first character.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Specifies the character string.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>length</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the number of characters in the string
argument.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XDrawImageString16</i> function is similar
to <i>XDrawImageString</i> 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.</small></p>
<p><small>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:</small></p>
<pre><small> [x, y − font-ascent]
</small></pre>
<p><small>The width is:</small></p>
<pre><small> overall-width
</small></pre>
<p><small>The height is:</small></p>
<pre><small> font-ascent + font-descent
</small></pre>
<p><small>The overall-width, font-ascent, and font-descent
are as would be returned by <i>XQueryTextExtents</i> using
gc and string. The function and fill-style defined in the GC
are ignored for these functions. The effective function is
<i>GXcopy</i>, and the effective fill-style is
<i>FillSolid</i>.</small></p>
<p><small>For fonts defined with 2-byte matrix indexing and
used with <i>XDrawImageString</i>, each byte is used as a
byte2 with a byte1 of zero.</small></p>
<p><small>Both functions use these GC components:
plane-mask, foreground, background, font, subwindow-mode,
clip-x-origin, clip-y-origin, and clip-mask.</small></p>
<p><small><i>XDrawImageString</i> and
<i>XDrawImageString16</i> can generate <i>BadDrawable</i>,
<i>BadGC</i>, and <i>BadMatch</i> errors.</small></p>
<a name="8.7. Transferring Images between Client and Server"></a>
<h2>8.7. Transferring Images between Client and Server</h2>
<p><small>Xlib provides functions that you can use to
transfer images between a client and the server. Because the
server may require diverse data formats, Xlib provides an
image object that fully describes the data in memory and
that provides for basic operations on that data. You should
reference the data through the image object rather than
referencing the data directly. However, some implementations
of the Xlib library may efficiently deal with frequently
used data formats by replacing functions in the procedure
vector with special case functions. Supported operations
include destroying the image, getting a pixel, storing a
pixel, extracting a subimage of an image, and adding a
constant to an image (see section 16.8).</small></p>
<p><small>All the image manipulation functions discussed in
this section make use of the <i>XImage</i> structure, which
describes an image as it exists in the client’s
memory.</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct _XImage {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>int width, height;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
<p><small>/* size of image */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>int xoffset;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
<p><small>/* number of pixels offset in X direction
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>int format;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
<p><small>/* XYBitmap, XYPixmap, ZPixmap */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>char *data;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
<p><small>/* pointer to image data */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>int byte_order;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
<p><small>/* data byte order, LSBFirst, MSBFirst
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>int bitmap_unit;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
<p><small>/* quant. of scanline 8, 16, 32 */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>int bitmap_bit_order;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
<p><small>/* LSBFirst, MSBFirst */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>int bitmap_pad;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
<p><small>/* 8, 16, 32 either XY or ZPixmap */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>int depth;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
<p><small>/* depth of image */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>int bytes_per_line;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
<p><small>/* accelerator to next scanline */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>int bits_per_pixel;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
<p><small>/* bits per pixel (ZPixmap) */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>unsigned long red_mask;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
<p><small>/* bits in z arrangement */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>unsigned long green_mask;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>unsigned long blue_mask;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>XPointer obdata;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
<p><small>/* hook for the object routines to hang on
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>struct funcs {</small></p>
</td>
<td width="40%"></td>
<td width="40%">
<p><small>/* image manipulation routines */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
</td>
<td width="40%">
<p><small>struct _XImage *(*create_image)();</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
</td>
<td width="40%">
<p><small>int (*destroy_image)();</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
</td>
<td width="40%">
<p><small>unsigned long (*get_pixel)();</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
</td>
<td width="40%">
<p><small>int (*put_pixel)();</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
</td>
<td width="40%">
<p><small>struct _XImage *(*sub_image)();</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
</td>
<td width="40%">
<p><small>int (*add_pixel)();</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>} f;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
</td>
</table>
<p><small>} XImage;</small></p>
<p><small>│__</small></p>
<p><small>To initialize the image manipulation routines of
an image structure, use <i>XInitImage</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XInitImage(<i>image</i>)
XImage *<i>image</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>ximage</i></small></p>
</td>
<td width="8%"></td>
<td width="40%">
<p><small>Specifies the image.</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XInitImage</i> function initializes the
internal image manipulation routines of an image structure,
based on the values of the various structure members. All
fields other than the manipulation routines must already be
initialized. If the bytes_per_line member is zero,
<i>XInitImage</i> will assume the image data is contiguous
in memory and set the bytes_per_line member to an
appropriate value based on the other members; otherwise, the
value of bytes_per_line is not changed. All of the
manipulation routines are initialized to functions that
other Xlib image manipulation functions need to operate on
the type of image specified by the rest of the
structure.</small></p>
<p><small>This function must be called for any image
constructed by the client before passing it to any other
Xlib function. Image structures created or returned by Xlib
do not need to be initialized in this fashion.</small></p>
<p><small>This function returns a nonzero status if
initialization of the structure is successful. It returns
zero if it detected some error or inconsistency in the
structure, in which case the image is not
changed.</small></p>
<p><small>To combine an image with a rectangle of a
drawable on the display, use <i>XPutImage</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XPutImage(<i>display</i>, <i>d</i>, <i>gc</i>, <i>image</i>, <i>src_x</i>, <i>src_y</i>, <i>dest_x</i>, <i>dest_y</i>, <i>width</i>, <i>height</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
XImage *<i>image</i>;
int <i>src_x</i>, <i>src_y</i>;
int <i>dest_x</i>, <i>dest_y</i>;
unsigned int <i>width</i>, <i>height</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>image</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the image you want combined with the
rectangle.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>src_x</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the offset in X from the left edge of
the image defined by the <i>XImage</i>
structure.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>src_y</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the offset in Y from the top edge of
the image defined by the <i>XImage</i>
structure.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>dest_x</i></small></p>
</td>
<td width="87%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>dest_y</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which are
relative to the origin of the drawable and are the
coordinates of the subimage.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the width and height of the subimage,
which define the dimensions of the rectangle.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XPutImage</i> function combines an image
with a rectangle of the specified drawable. The section of
the image defined by the src_x, src_y, width, and height
arguments is drawn on the specified part of the drawable. If
<i>XYBitmap</i> format is used, the depth of the image must
be one, or a <i>BadMatch</i> error results. The foreground
pixel in the GC defines the source for the one bits in the
image, and the background pixel defines the source for the
zero bits. For <i>XYPixmap</i> and <i>ZPixmap</i>, the depth
of the image must match the depth of the drawable, or a
<i>BadMatch</i> error results.</small></p>
<p><small>If the characteristics of the image (for example,
byte_order and bitmap_unit) differ from what the server
requires, <i>XPutImage</i> automatically makes the
appropriate conversions.</small></p>
<p><small>This function uses these GC components: function,
plane-mask, subwindow-mode, clip-x-origin, clip-y-origin,
and clip-mask. It also uses these GC mode-dependent
components: foreground and background.</small></p>
<p><small><i>XPutImage</i> can generate <i>BadDrawable</i>,
<i>BadGC</i>, <i>BadMatch</i>, and <i>BadValue</i>
errors.</small></p>
<p><small>To return the contents of a rectangle in a given
drawable on the display, use <i>XGetImage</i>. This function
specifically supports rudimentary screen dumps.</small></p>
<p><small>__ │</small></p>
<pre><small>XImage *XGetImage(<i>display</i>, <i>d</i>, <i>x</i>, <i>y</i>, <i>width</i>, <i>height</i>, <i>plane_mask</i>, <i>format</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
int <i>x</i>, <i>y</i>;
unsigned int <i>width</i>, <i>height</i>;
unsigned long <i>plane_mask</i>;
int <i>format</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which are
relative to the origin of the drawable and define the
upper-left corner of the rectangle.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the width and height of the subimage,
which define the dimensions of the rectangle.</small></p>
</td>
</table>
<p><small><i>plane_mask</i> Specifies the plane
mask.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>format</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the format for the image. You can pass
<i>XYPixmap</i> or <i>ZPixmap</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetImage</i> function returns a pointer
to an <i>XImage</i> structure. This structure provides you
with the contents of the specified rectangle of the drawable
in the format you specify. If the format argument is
<i>XYPixmap</i>, the image contains only the bit planes you
passed to the plane_mask argument. If the plane_mask
argument only requests a subset of the planes of the
display, the depth of the returned image will be the number
of planes requested. If the format argument is
<i>ZPixmap</i>, <i>XGetImage</i> returns as zero the bits in
all planes not specified in the plane_mask argument. The
function performs no range checking on the values in
plane_mask and ignores extraneous bits.</small></p>
<p><small><i>XGetImage</i> returns the depth of the image
to the depth member of the <i>XImage</i> structure. The
depth of the image is as specified when the drawable was
created, except when getting a subset of the planes in
<i>XYPixmap</i> format, when the depth is given by the
number of bits set to 1 in plane_mask.</small></p>
<p><small>If the drawable is a pixmap, the given rectangle
must be wholly contained within the pixmap, or a
<i>BadMatch</i> error results. If the drawable is a window,
the window must be viewable, and it must be the case that if
there were no inferiors or overlapping windows, the
specified rectangle of the window would be fully visible on
the screen and wholly contained within the outside edges of
the window, or a <i>BadMatch</i> error results. Note that
the borders of the window can be included and read with this
request. If the window has backing-store, the backing-store
contents are returned for regions of the window that are
obscured by noninferior windows. If the window does not have
backing-store, the returned contents of such obscured
regions are undefined. The returned contents of visible
regions of inferiors of a different depth than the specified
window’s depth are also undefined. The pointer cursor
image is not included in the returned contents. If a problem
occurs, <i>XGetImage</i> returns NULL.</small></p>
<p><small><i>XGetImage</i> can generate <i>BadDrawable</i>,
<i>BadMatch</i>, and <i>BadValue</i> errors.</small></p>
<p><small>To copy the contents of a rectangle on the
display to a location within a preexisting image structure,
use <i>XGetSubImage</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XImage *XGetSubImage(<i>display</i>, <i>d</i>, <i>x</i>, <i>y</i>, <i>width</i>, <i>height</i>, <i>plane_mask</i>, <i>format</i>, <i>dest_image</i>, <i>dest_x</i>,
<i> dest_y</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
int <i>x</i>, <i>y</i>;
unsigned int <i>width</i>, <i>height</i>;
unsigned long <i>plane_mask</i>;
int <i>format</i>;
XImage *<i>dest_image</i>;
int <i>dest_x</i>, <i>dest_y</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which are
relative to the origin of the drawable and define the
upper-left corner of the rectangle.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the width and height of the subimage,
which define the dimensions of the rectangle.</small></p>
</td>
</table>
<p><small><i>plane_mask</i> Specifies the plane
mask.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>format</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the format for the image. You can pass
<i>XYPixmap</i> or <i>ZPixmap</i>.</small></p>
</td>
</table>
<p><small><i>dest_image</i> Specifies the destination
image.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>dest_x</i></small></p>
</td>
<td width="87%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>dest_y</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which are
relative to the origin of the destination rectangle, specify
its upper-left corner, and determine where the subimage is
placed in the destination image.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetSubImage</i> function updates
dest_image with the specified subimage in the same manner as
<i>XGetImage</i>. If the format argument is <i>XYPixmap</i>,
the image contains only the bit planes you passed to the
plane_mask argument. If the format argument is
<i>ZPixmap</i>, <i>XGetSubImage</i> returns as zero the bits
in all planes not specified in the plane_mask argument. The
function performs no range checking on the values in
plane_mask and ignores extraneous bits. As a convenience,
<i>XGetSubImage</i> returns a pointer to the same
<i>XImage</i> structure specified by dest_image.</small></p>
<p><small>The depth of the destination <i>XImage</i>
structure must be the same as that of the drawable. If the
specified subimage does not fit at the specified location on
the destination image, the right and bottom edges are
clipped. If the drawable is a pixmap, the given rectangle
must be wholly contained within the pixmap, or a
<i>BadMatch</i> error results. If the drawable is a window,
the window must be viewable, and it must be the case that if
there were no inferiors or overlapping windows, the
specified rectangle of the window would be fully visible on
the screen and wholly contained within the outside edges of
the window, or a <i>BadMatch</i> error results. If the
window has backing-store, then the backing-store contents
are returned for regions of the window that are obscured by
noninferior windows. If the window does not have
backing-store, the returned contents of such obscured
regions are undefined. The returned contents of visible
regions of inferiors of a different depth than the specified
window’s depth are also undefined. If a problem
occurs, <i>XGetSubImage</i> returns NULL.</small></p>
<p><small><i>XGetSubImage</i> can generate
<i>BadDrawable</i>, <i>BadGC</i>, <i>BadMatch</i>, and
<i>BadValue</i> errors.</small></p>
<p><small><b>8</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b>Chapter 9</b></p>
<p align=center><b>Window and Session Manager
Functions</b></p>
<p><small>Although it is difficult to categorize functions
as exclusively for an application, a window manager, or a
session manager, the functions in this chapter are most
often used by window managers and session managers. It is
not expected that these functions will be used by most
application programs. Xlib provides management functions
to:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="58%">
<p><small>Change the parent of a window</small></p>
</td>
<td width="31%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="64%">
<p><small>Control the lifetime of a window</small></p>
</td>
<td width="25%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="52%">
<p><small>Manage installed colormaps</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="74%">
<p><small>Set and retrieve the font search path</small></p>
</td>
<td width="15%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="30%">
<p><small>Grab the server</small></p>
</td>
<td width="59%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="26%">
<p><small>Kill a client</small></p>
</td>
<td width="63%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="48%">
<p><small>Control the screen saver</small></p>
</td>
<td width="41%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="38%">
<p><small>Control host access</small></p>
</td>
<td width="51%">
</td>
</table>
<a name="9.1. Changing the Parent of a Window"></a>
<h2>9.1. Changing the Parent of a Window</h2>
<p><small>To change a window’s parent to another
window on the same screen, use <i>XReparentWindow</i>. There
is no way to move a window between screens.</small></p>
<p><small>__ │</small></p>
<pre><small>XReparentWindow(<i>display</i>, <i>w</i>, <i>parent</i>, <i>x</i>, <i>y</i>)
Display *<i>display</i>;
Window <i>w</i>;
Window <i>parent</i>;
int <i>x</i>, <i>y</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>parent</i></small></p>
</td>
<td width="8%"></td>
<td width="56%">
<p><small>Specifies the parent window.</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates of the position
in the new parent window.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>If the specified window is mapped,
<i>XReparentWindow</i> automatically performs an
<i>UnmapWindow</i> request on it, removes it from its
current position in the hierarchy, and inserts it as the
child of the specified parent. The window is placed in the
stacking order on top with respect to sibling
windows.</small></p>
<p><small>After reparenting the specified window,
<i>XReparentWindow</i> causes the X server to generate a
<i>ReparentNotify</i> event. The override_redirect member
returned in this event is set to the window’s
corresponding attribute. Window manager clients usually
should ignore this window if this member is set to
<i>True</i>. Finally, if the specified window was originally
mapped, the X server automatically performs a
<i>MapWindow</i> request on it.</small></p>
<p><small>The X server performs normal exposure processing
on formerly obscured windows. The X server might not
generate <i>Expose</i> events for regions from the initial
<i>UnmapWindow</i> request that are immediately obscured by
the final <i>MapWindow</i> request. A <i>BadMatch</i> error
results if:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The new parent window is not on the same screen
as the old parent window.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The new parent window is the specified window or
an inferior of the specified window.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The new parent is <i>InputOnly</i>, and the
window is not.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The specified window has a <i>ParentRelative</i>
background, and the new parent window is not the same depth
as the specified window.</small></p>
</td>
</table>
<p><small><i>XReparentWindow</i> can generate
<i>BadMatch</i> and <i>BadWindow</i> errors.</small></p>
<a name="9.2. Controlling the Lifetime of a Window"></a>
<h2>9.2. Controlling the Lifetime of a Window</h2>
<p><small>The save-set of a client is a list of other
clients’ windows that, if they are inferiors of one of
the client’s windows at connection close, should not
be destroyed and should be remapped if they are unmapped.
For further information about close-connection processing,
see section 2.6. To allow an application’s window to
survive when a window manager that has reparented a window
fails, Xlib provides the save-set functions that you can use
to control the longevity of subwindows that are normally
destroyed when the parent is destroyed. For example, a
window manager that wants to add decoration to a window by
adding a frame might reparent an application’s window.
When the frame is destroyed, the application’s window
should not be destroyed but be returned to its previous
place in the window hierarchy.</small></p>
<p><small>The X server automatically removes windows from
the save-set when they are destroyed.</small></p>
<p><small>To add or remove a window from the client’s
save-set, use <i>XChangeSaveSet</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XChangeSaveSet(<i>display</i>, <i>w</i>, <i>change_mode</i>)
Display *<i>display</i>;
Window <i>w</i>;
int <i>change_mode</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the window that you want to add to or
delete from the client’s save-set.</small></p>
</td>
</table>
<p><small><i>change_mode</i> Specifies the mode. You can
pass <i>SetModeInsert</i> or
<i>SetModeDelete</i>.</small></p>
<p><small>│__</small></p>
<p><small>Depending on the specified mode,
<i>XChangeSaveSet</i> 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 <i>BadMatch</i> error results.</small></p>
<p><small><i>XChangeSaveSet</i> can generate
<i>BadMatch</i>, <i>BadValue</i>, and <i>BadWindow</i>
errors.</small></p>
<p><small>To add a window to the client’s save-set,
use <i>XAddToSaveSet</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XAddToSaveSet(<i>display</i>, <i>w</i>)
Display *<i>display</i>;
Window <i>w</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the window that you want to add to the
client’s save-set.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XAddToSaveSet</i> function adds the
specified window to the client’s save-set. The
specified window must have been created by some other
client, or a <i>BadMatch</i> error results.</small></p>
<p><small><i>XAddToSaveSet</i> can generate <i>BadMatch</i>
and <i>BadWindow</i> errors.</small></p>
<p><small>To remove a window from the client’s
save-set, use <i>XRemoveFromSaveSet</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XRemoveFromSaveSet(<i>display</i>, <i>w</i>)
Display *<i>display</i>;
Window <i>w</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the window that you want to delete from
the client’s save-set.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XRemoveFromSaveSet</i> function removes
the specified window from the client’s save-set. The
specified window must have been created by some other
client, or a <i>BadMatch</i> error results.</small></p>
<p><small><i>XRemoveFromSaveSet</i> can generate
<i>BadMatch</i> and <i>BadWindow</i> errors.</small></p>
<a name="9.3. Managing Installed Colormaps"></a>
<h2>9.3. Managing Installed Colormaps</h2>
<p><small>The X server maintains a list of installed
colormaps. Windows using these colormaps are guaranteed to
display with correct colors; windows using other colormaps
may or may not display with correct colors. Xlib provides
functions that you can use to install a colormap, uninstall
a colormap, and obtain a list of installed
colormaps.</small></p>
<p><small>At any time, there is a subset of the installed
maps that is viewed as an ordered list and is called the
required list. The length of the required list is at most M,
where M is the minimum number of installed colormaps
specified for the screen in the connection setup. The
required list is maintained as follows. When a colormap is
specified to <i>XInstallColormap</i>, it is added to the
head of the list; the list is truncated at the tail, if
necessary, to keep its length to at most M. When a colormap
is specified to <i>XUninstallColormap</i> and it is in the
required list, it is removed from the list. A colormap is
not added to the required list when it is implicitly
installed by the X server, and the X server cannot
implicitly uninstall a colormap that is in the required
list.</small></p>
<p><small>To install a colormap, use
<i>XInstallColormap</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XInstallColormap(<i>display</i>, <i>colormap</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XInstallColormap</i> function installs the
specified colormap for its associated screen. All windows
associated with this colormap immediately display with true
colors. You associated the windows with this colormap when
you created them by calling <i>XCreateWindow</i>,
<i>XCreateSimpleWindow</i>, <i>XChangeWindowAttributes</i>,
or <i>XSetWindowColormap</i>.</small></p>
<p><small>If the specified colormap is not already an
installed colormap, the X server generates a
<i>ColormapNotify</i> event on each window that has that
colormap. In addition, for every other colormap that is
installed as a result of a call to <i>XInstallColormap</i>,
the X server generates a <i>ColormapNotify</i> event on each
window that has that colormap.</small></p>
<p><small><i>XInstallColormap</i> can generate a
<i>BadColor</i> error.</small></p>
<p><small>To uninstall a colormap, use
<i>XUninstallColormap</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XUninstallColormap(<i>display</i>, <i>colormap</i>)
Display *<i>display</i>;
Colormap <i>colormap</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XUninstallColormap</i> function removes
the specified colormap from the required list for its
screen. As a result, the specified colormap might be
uninstalled, and the X server might implicitly install or
uninstall additional colormaps. Which colormaps get
installed or uninstalled is server dependent except that the
required list must remain installed.</small></p>
<p><small>If the specified colormap becomes uninstalled,
the X server generates a <i>ColormapNotify</i> event on each
window that has that colormap. In addition, for every other
colormap that is installed or uninstalled as a result of a
call to <i>XUninstallColormap</i>, the X server generates a
<i>ColormapNotify</i> event on each window that has that
colormap.</small></p>
<p><small><i>XUninstallColormap</i> can generate a
<i>BadColor</i> error.</small></p>
<p><small>To obtain a list of the currently installed
colormaps for a given screen, use
<i>XListInstalledColormaps</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Colormap *XListInstalledColormaps(<i>display</i>, <i>w</i>, <i>num_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
int *<i>num_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the window that determines the
screen.</small></p>
</td>
</table>
<p><small><i>num_return</i> Returns the number of currently
installed colormaps.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XListInstalledColormaps</i> function
returns a list of the currently installed colormaps for the
screen of the specified window. The order of the colormaps
in the list is not significant and is no explicit indication
of the required list. When the allocated list is no longer
needed, free it by using <i>XFree</i>.</small></p>
<p><small><i>XListInstalledColormaps</i> can generate a
<i>BadWindow</i> error.</small></p>
<a name="9.4. Setting and Retrieving the Font Search Path"></a>
<h2>9.4. Setting and Retrieving the Font Search Path</h2>
<p><small>The set of fonts available from a server depends
on a font search path. Xlib provides functions to set and
retrieve the search path for a server.</small></p>
<p><small>To set the font search path, use
<i>XSetFontPath</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetFontPath(<i>display</i>, <i>directories</i>, <i>ndirs</i>)
Display *<i>display</i>;
char **<i>directories</i>;
int <i>ndirs</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>directories</i> Specifies the directory path
used to look for a font. Setting the path to the empty list
restores the default path defined for the X
server.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>ndirs</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the number of directories in the
path.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetFontPath</i> function defines the
directory search path for font lookup. There is only one
search path per X server, not one per client. The encoding
and interpretation of the strings are
implementation-dependent, but typically they specify
directories or font servers to be searched in the order
listed. An X server is permitted to cache font information
internally; for example, it might cache an entire font from
a file and not check on subsequent opens of that font to see
if the underlying font file has changed. However, when the
font path is changed, the X server is guaranteed to flush
all cached information about fonts for which there currently
are no explicit resource IDs allocated. The meaning of an
error from this request is
implementation-dependent.</small></p>
<p><small><i>XSetFontPath</i> can generate a
<i>BadValue</i> error.</small></p>
<p><small>To get the current font search path, use
<i>XGetFontPath</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char **XGetFontPath(<i>display</i>, <i>npaths_return</i>)
Display *<i>display</i>;
int *<i>npaths_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>npaths_return</i> Returns the number of
strings in the font path array.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetFontPath</i> 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.
When it is no longer needed, the data in the font path
should be freed by using <i>XFreeFontPath</i>.</small></p>
<p><small>To free data returned by <i>XGetFontPath</i>, use
<i>XFreeFontPath</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XFreeFontPath(<i>list</i>)
char **<i>list</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>list</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the array of strings you want to
free.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XFreeFontPath</i> function frees the data
allocated by <i>XGetFontPath</i>.</small></p>
<a name="9.5. Grabbing the Server"></a>
<h2>9.5. Grabbing the Server</h2>
<p><small>Xlib provides functions that you can use to grab
and ungrab the server. These functions can be used to
control processing of output on other connections by the
window system server. While the server is grabbed, no
processing of requests or close downs on any other
connection will occur. A client closing its connection
automatically ungrabs the server. Although grabbing the
server is highly discouraged, it is sometimes
necessary.</small></p>
<p><small>To grab the server, use
<i>XGrabServer</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XGrabServer(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGrabServer</i> function disables
processing of requests and close downs on all other
connections than the one this request arrived on. You should
not grab the X server any more than is absolutely
necessary.</small></p>
<p><small>To ungrab the server, use
<i>XUngrabServer</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XUngrabServer(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XUngrabServer</i> function restarts
processing of requests and close downs on other connections.
You should avoid grabbing the X server as much as
possible.</small></p>
<a name="9.6. Killing Clients"></a>
<h2>9.6. Killing Clients</h2>
<p><small>Xlib provides a function to cause the connection
to a client to be closed and its resources to be destroyed.
To destroy a client, use <i>XKillClient</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XKillClient(<i>display</i>, <i>resource</i>)
Display *<i>display</i>;
XID <i>resource</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>resource</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies any resource associated with the client
that you want to destroy or <i>AllTemporary</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XKillClient</i> function forces a close
down of the client that created the resource if a valid
resource is specified. If the client has already terminated
in either <i>RetainPermanent</i> or <i>RetainTemporary</i>
mode, all of the client’s resources are destroyed. If
<i>AllTemporary</i> is specified, the resources of all
clients that have terminated in <i>RetainTemporary</i> are
destroyed (see section 2.5). This permits implementation of
window manager facilities that aid debugging. A client can
set its close-down mode to <i>RetainTemporary</i>. If the
client then crashes, its windows would not be destroyed. The
programmer can then inspect the application’s window
tree and use the window manager to destroy the zombie
windows.</small></p>
<p><small><i>XKillClient</i> can generate a <i>BadValue</i>
error.</small></p>
<a name="9.7. Controlling the Screen Saver"></a>
<h2>9.7. Controlling the Screen Saver</h2>
<p><small>Xlib provides functions that you can use to set
or reset the mode of the screen saver, to force or activate
the screen saver, or to obtain the current screen saver
values.</small></p>
<p><small>To set the screen saver mode, use
<i>XSetScreenSaver</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetScreenSaver(<i>display</i>, <i>timeout</i>, <i>interval</i>, <i>prefer_blanking</i>, <i>allow_exposures</i>)
Display *<i>display</i>;
int <i>timeout</i>, <i>interval</i>;
int <i>prefer_blanking</i>;
int <i>allow_exposures</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>timeout</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the timeout, in seconds, until the
screen saver turns on.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>interval</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the interval, in seconds, between
screen saver alterations.</small></p>
</td>
</table>
<p><small><i>prefer_blanking</i> Specifies how to enable
screen blanking. You can pass <i>DontPreferBlanking</i>,
<i>PreferBlanking</i>, or
<i>DefaultBlanking</i>.</small></p>
<p><small><i>allow_exposures</i> Specifies the screen save
control values. You can pass <i>DontAllowExposures</i>,
<i>AllowExposures</i>, or
<i>DefaultExposures</i>.</small></p>
<p><small>│__</small></p>
<p><small>Timeout and interval are specified in seconds. A
timeout of 0 disables the screen saver (but an activated
screen saver is not deactivated), and a timeout of −1
restores the default. Other negative values generate a
<i>BadValue</i> error. If the timeout value is nonzero,
<i>XSetScreenSaver</i> enables the screen saver. An interval
of 0 disables the random-pattern motion. If no input from
devices (keyboard, mouse, and so on) is generated for the
specified number of timeout seconds once the screen saver is
enabled, the screen saver is activated.</small></p>
<p><small>For each screen, if blanking is preferred and the
hardware supports video blanking, the screen simply goes
blank. Otherwise, if either exposures are allowed or the
screen can be regenerated without sending <i>Expose</i>
events to clients, the screen is tiled with the root window
background tile randomly re-origined each interval seconds.
Otherwise, the screens’ state do not change, and the
screen saver is not activated. The screen saver is
deactivated, and all screen states are restored at the next
keyboard or pointer input or at the next call to
<i>XForceScreenSaver</i> with mode
<i>ScreenSaverReset</i>.</small></p>
<p><small>If the server-dependent screen saver method
supports periodic change, the interval argument serves as a
hint about how long the change period should be, and zero
hints that no periodic change should be made. Examples of
ways to change the screen include scrambling the colormap
periodically, moving an icon image around the screen
periodically, or tiling the screen with the root window
background tile, randomly re-origined
periodically.</small></p>
<p><small><i>XSetScreenSaver</i> can generate a
<i>BadValue</i> error.</small></p>
<p><small>To force the screen saver on or off, use
<i>XForceScreenSaver</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XForceScreenSaver(<i>display</i>, <i>mode</i>)
Display *<i>display</i>;
int <i>mode</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>mode</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the mode that is to be applied. You can
pass <i>ScreenSaverActive</i> or
<i>ScreenSaverReset</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>If the specified mode is <i>ScreenSaverActive</i>
and the screen saver currently is deactivated,
<i>XForceScreenSaver</i> activates the screen saver even if
the screen saver had been disabled with a timeout of zero.
If the specified mode is <i>ScreenSaverReset</i> and the
screen saver currently is enabled, <i>XForceScreenSaver</i>
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).</small></p>
<p><small><i>XForceScreenSaver</i> can generate a
<i>BadValue</i> error.</small></p>
<p><small>To activate the screen saver, use
<i>XActivateScreenSaver</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XActivateScreenSaver(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>To reset the screen saver, use
<i>XResetScreenSaver</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>XResetScreenSaver(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>To get the current screen saver values, use
<i>XGetScreenSaver</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>XGetScreenSaver(<i>display</i>, <i>timeout_return</i>, <i>interval_return</i>, <i>prefer_blanking_return</i>,
<i> allow_exposures_return</i>)
Display *<i>display</i>;
int *<i>timeout_return</i>, *<i>interval_return</i>;
int *<i>prefer_blanking_return</i>;
int *<i>allow_exposures_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>timeout_return</i> Returns the timeout, in
seconds, until the screen saver turns on.</small></p>
<p><small><i>interval_return</i> Returns the interval
between screen saver invocations.</small></p>
<p><small><i>prefer_blanking_return</i> Returns the current
screen blanking preference (<i>DontPreferBlanking</i>,
<i>PreferBlanking</i>, or
<i>DefaultBlanking</i>).</small></p>
<p><small><i>allow_exposures_return</i> Returns the current
screen save control value (<i>DontAllowExposures</i>,
<i>AllowExposures</i>, or
<i>DefaultExposures</i>).</small></p>
<p><small>│__</small></p>
<a name="9.8. Controlling Host Access"></a>
<h2>9.8. Controlling Host Access</h2>
<p><small>This section discusses how to:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Add, get, or remove hosts from the access control
list</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="66%">
<p><small>Change, enable, or disable access</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>X does not provide any protection on a per-window
basis. If you find out the resource ID of a resource, you
can manipulate it. To provide some minimal level of
protection, however, connections are permitted only from
machines you trust. This is adequate on single-user
workstations but obviously breaks down on timesharing
machines. Although provisions exist in the X protocol for
proper connection authentication, the lack of a standard
authentication server leaves host-level access control as
the only common mechanism.</small></p>
<p><small>The initial set of hosts allowed to open
connections typically consists of:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="82%">
<p><small>The host the window system is running
on.</small></p>
</td>
<td width="7%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>On POSIX-conformant systems, each host listed in
the <i>/etc/X?.hosts</i> file. The ? indicates the number of
the display. This file should consist of host names
separated by newlines. DECnet nodes must terminate in :: to
distinguish them from Internet hosts.</small></p>
</td>
</table>
<p><small>If a host is not in the access control list when
the access control mechanism is enabled and if the host
attempts to establish a connection, the server refuses the
connection. To change the access list, the client must
reside on the same host as the server and/or must have been
granted permission in the initial authorization at
connection setup.</small></p>
<p><small>Servers also can implement other access control
policies in addition to or in place of this host access
facility. For further information about other access control
implementations, see ‘‘X Window System
Protocol.’’</small></p>
<a name="9.8.1. Adding, Getting, or Removing Hosts"></a>
<h2>9.8.1. Adding, Getting, or Removing Hosts</h2>
<p><small>Xlib provides functions that you can use to add,
get, or remove hosts from the access control list. All the
host access control functions use the <i>XHostAddress</i>
structure, which contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int family;</small></p>
</td>
<td width="40%">
<p><small>/* for example FamilyInternet */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int length;</small></p>
</td>
<td width="40%">
<p><small>/* length of address, in bytes */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>char *address;</small></p>
</td>
<td width="40%">
<p><small>/* pointer to where to find the address
*/</small></p>
</td>
</table>
<p><small>} XHostAddress;</small></p>
<p><small>│__</small></p>
<p><small>The family member specifies which protocol
address family to use (for example, TCP/IP or DECnet) and
can be <i>FamilyInternet</i>, <i>FamilyInternet6</i>,
<i>FamilyServerInterpreted</i>, <i>FamilyDECnet</i>, or
<i>FamilyChaos</i>. The length member specifies the length
of the address in bytes. The address member specifies a
pointer to the address.</small></p>
<p><small>For TCP/IP, the address should be in network byte
order. For IP version 4 addresses, the family should be
FamilyInternet and the length should be 4 bytes. For IP
version 6 addresses, the family should be FamilyInternet6
and the length should be 16 bytes.</small></p>
<p><small>For the DECnet family, the server performs no
automatic swapping on the address bytes. A Phase IV address
is 2 bytes long. The first byte contains the least
significant 8 bits of the node number. The second byte
contains the most significant 2 bits of the node number in
the least significant 2 bits of the byte and the area in the
most significant 6 bits of the byte.</small></p>
<p><small>For the ServerInterpreted family, the length is
ignored and the address member is a pointer to a
<i>XServerInterpretedAddress</i> structure, which
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int typelength;</small></p>
</td>
<td width="40%">
<p><small>/* length of type string, in bytes */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int valuelength;/* length of value string, in
bytes */</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>char *type;</small></p>
</td>
<td width="40%">
<p><small>/* pointer to where to find the type string
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>char *value;</small></p>
</td>
<td width="40%">
<p><small>/* pointer to where to find the address
*/</small></p>
</td>
</table>
<p><small>} XServerInterpretedAddress;</small></p>
<p><small>│__</small></p>
<p><small>The type and value members point to strings
representing the type and value of the server interpreted
entry. These strings may not be NULL-terminated so care
should be used when accessing them. The typelength and
valuelength members specify the length in byte of the type
and value strings.</small></p>
<p><small>To add a single host, use
<i>XAddHost</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XAddHost(<i>display</i>, <i>host</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<p><small>XHostAddress *<i>host</i>;</small></p>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>host</i></small></p>
</td>
<td width="12%"></td>
<td width="78%">
<p><small>Specifies the host that is to be
added.</small></p>
</td>
<td width="1%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XAddHost</i> function adds the specified
host to the access control list for that display. The server
must be on the same host as the client issuing the command,
or a <i>BadAccess</i> error results.</small></p>
<p><small><i>XAddHost</i> can generate <i>BadAccess</i> and
<i>BadValue</i> errors.</small></p>
<p><small>To add multiple hosts at one time, use
<i>XAddHosts</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XAddHosts(<i>display</i>, <i>hosts</i>, <i>num_hosts</i>)
Display *<i>display</i>;
XHostAddress *<i>hosts</i>;
int <i>num_hosts</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>hosts</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies each host that is to be
added.</small></p>
</td>
<td width="0%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>num_hosts</i></small></p>
</td>
<td width="2%"></td>
<td width="60%">
<p><small>Specifies the number of hosts.</small></p>
</td>
<td width="19%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XAddHosts</i> function adds each specified
host to the access control list for that display. The server
must be on the same host as the client issuing the command,
or a <i>BadAccess</i> error results.</small></p>
<p><small><i>XAddHosts</i> can generate <i>BadAccess</i>
and <i>BadValue</i> errors.</small></p>
<p><small>To obtain a host list, use
<i>XListHosts</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XHostAddress *XListHosts(<i>display</i>, <i>nhosts_return</i>, <i>state_return</i>)
Display *<i>display</i>;
int *<i>nhosts_return</i>;
Bool *<i>state_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>nhosts_return</i> Returns the number of hosts
currently in the access control list.</small></p>
<p><small><i>state_return</i> Returns the state of the
access control.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XListHosts</i> function returns the
current access control list as well as whether the use of
the list at connection setup was enabled or disabled.
<i>XListHosts</i> allows a program to find out what machines
can make connections. It also returns a pointer to a list of
host structures that were allocated by the function. When no
longer needed, this memory should be freed by calling
<i>XFree</i>.</small></p>
<p><small>To remove a single host, use
<i>XRemoveHost</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XRemoveHost(<i>display</i>, <i>host</i>)
Display *<i>display</i>;
XHostAddress *<i>host</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>host</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the host that is to be
removed.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XRemoveHost</i> function removes the
specified host from the access control list for that
display. The server must be on the same host as the client
process, or a <i>BadAccess</i> error results. If you remove
your machine from the access list, you can no longer connect
to that server, and this operation cannot be reversed unless
you reset the server.</small></p>
<p><small><i>XRemoveHost</i> can generate <i>BadAccess</i>
and <i>BadValue</i> errors.</small></p>
<p><small>To remove multiple hosts at one time, use
<i>XRemoveHosts</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XRemoveHosts(<i>display</i>, <i>hosts</i>, <i>num_hosts</i>)
Display *<i>display</i>;
XHostAddress *<i>hosts</i>;
int <i>num_hosts</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>hosts</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies each host that is to be
removed.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>num_hosts</i></small></p>
</td>
<td width="2%"></td>
<td width="60%">
<p><small>Specifies the number of hosts.</small></p>
</td>
<td width="19%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XRemoveHosts</i> function removes each
specified host from the access control list for that
display. The X server must be on the same host as the client
process, or a <i>BadAccess</i> error results. If you remove
your machine from the access list, you can no longer connect
to that server, and this operation cannot be reversed unless
you reset the server.</small></p>
<p><small><i>XRemoveHosts</i> can generate <i>BadAccess</i>
and <i>BadValue</i> errors.</small></p>
<a name="9.8.2. Changing, Enabling, or Disabling Access Control"></a>
<h2>9.8.2. Changing, Enabling, or Disabling Access Control</h2>
<p><small>Xlib provides functions that you can use to
enable, disable, or change access control.</small></p>
<p><small>For these functions to execute successfully, the
client application must reside on the same host as the X
server and/or have been given permission in the initial
authorization at connection setup.</small></p>
<p><small>To change access control, use
<i>XSetAccessControl</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetAccessControl(<i>display</i>, <i>mode</i>)
Display *<i>display</i>;
int <i>mode</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>mode</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the mode. You can pass
<i>EnableAccess</i> or <i>DisableAccess</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetAccessControl</i> function either
enables or disables the use of the access control list at
each connection setup.</small></p>
<p><small><i>XSetAccessControl</i> can generate
<i>BadAccess</i> and <i>BadValue</i> errors.</small></p>
<p><small>To enable access control, use
<i>XEnableAccessControl</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XEnableAccessControl(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XEnableAccessControl</i> function enables
the use of the access control list at each connection
setup.</small></p>
<p><small><i>XEnableAccessControl</i> can generate a
<i>BadAccess</i> error.</small></p>
<p><small>To disable access control, use
<i>XDisableAccessControl</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XDisableAccessControl(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XDisableAccessControl</i> function
disables the use of the access control list at each
connection setup.</small></p>
<p><small><i>XDisableAccessControl</i> can generate a
<i>BadAccess</i> error.</small></p>
<p><small><b>9</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b>Chapter 10</b></p>
<p align=center><b>Events</b></p>
<p><small>A client application communicates with the X
server through the connection you establish with the
<i>XOpenDisplay</i> function. A client application sends
requests to the X server over this connection. These
requests are made by the Xlib functions that are called in
the client application. Many Xlib functions cause the X
server to generate events, and the user’s typing or
moving the pointer can generate events asynchronously. The X
server returns events to the client on the same
connection.</small></p>
<p><small>This chapter discusses the following topics
associated with events:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="22%">
<p><small>Event types</small></p>
</td>
<td width="67%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="32%">
<p><small>Event structures</small></p>
</td>
<td width="57%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="22%">
<p><small>Event masks</small></p>
</td>
<td width="67%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="32%">
<p><small>Event processing</small></p>
</td>
<td width="57%">
</td>
</table>
<p><small>Functions for handling events are dealt with in
the next chapter.</small></p>
<a name="10.1. Event Types"></a>
<h2>10.1. Event Types</h2>
<p><small>An event is data generated asynchronously by the
X server as a result of some device activity or as side
effects of a request sent by an Xlib function.
Device-related events propagate from the source window to
ancestor windows until some client application has selected
that event type or until the event is explicitly discarded.
The X server generally sends an event to a client
application only if the client has specifically asked to be
informed of that event type, typically by setting the
event-mask attribute of the window. The mask can also be set
when you create a window or by changing the window’s
event-mask. You can also mask out events that would
propagate to ancestor windows by manipulating the
do-not-propagate mask of the window’s attributes.
However, <i>MappingNotify</i> events are always sent to all
clients.</small></p>
<p><small>An event type describes a specific event
generated by the X server. For each event type, a
corresponding constant name is defined in
<<i>X11/X.h</i>>, which is used when referring to an
event type. The following table lists the event category and
its associated event type or types. The processing
associated with these events is discussed in section
10.5.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="39%"></td>
<td width="4%">
<p align=center><small><img src="grohtml-1439233.png"></small></p>
<a name="10.2. Event Structures"></a>
<h2>10.2. Event Structures</h2>
<p><small>For each event type, a corresponding structure is
declared in <<i>X11/Xlib.h</i>>. All the event
structures have the following common members:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
</td>
</table>
<p><small>} XAnyEvent;</small></p>
<p><small>│__</small></p>
<p><small>The type member is set to the event type constant
name that uniquely identifies it. For example, when the X
server reports a <i>GraphicsExpose</i> event to a client
application, it sends an <i>XGraphicsExposeEvent</i>
structure with the type member set to <i>GraphicsExpose</i>.
The display member is set to a pointer to the display the
event was read on. The send_event member is set to
<i>True</i> if the event came from a <i>SendEvent</i>
protocol request. The serial member is set from the serial
number reported in the protocol but expanded from the 16-bit
least-significant bits to a full 32-bit value. The window
member is set to the window that is most useful to toolkit
dispatchers.</small></p>
<p><small>The X server can send events at any time in the
input stream. Xlib stores any events received while waiting
for a reply in an event queue for later use. Xlib also
provides functions that allow you to check events in the
event queue (see section 11.3).</small></p>
<p><small>In addition to the individual structures declared
for each event type, the <i>XEvent</i> structure is a union
of the individual structures declared for each event type.
Depending on the type, you should access members of each
event by using the <i>XEvent</i> union.</small></p>
<p><small>__ │</small></p>
<pre><small>typedef union _XEvent {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* must not be changed */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XAnyEvent xany;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XKeyEvent xkey;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XButtonEvent xbutton;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XMotionEvent xmotion;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XCrossingEvent xcrossing;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XFocusChangeEvent xfocus;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XExposeEvent xexpose;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XGraphicsExposeEvent xgraphicsexpose;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XNoExposeEvent xnoexpose;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XVisibilityEvent xvisibility;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XCreateWindowEvent xcreatewindow;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XDestroyWindowEvent xdestroywindow;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XUnmapEvent xunmap;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XMapEvent xmap;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XMapRequestEvent xmaprequest;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XReparentEvent xreparent;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XConfigureEvent xconfigure;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XGravityEvent xgravity;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XResizeRequestEvent xresizerequest;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XConfigureRequestEvent
xconfigurerequest;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XCirculateEvent xcirculate;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XCirculateRequestEvent
xcirculaterequest;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XPropertyEvent xproperty;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XSelectionClearEvent xselectionclear;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XSelectionRequestEvent
xselectionrequest;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XSelectionEvent xselection;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XColormapEvent xcolormap;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XClientMessageEvent xclient;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XMappingEvent xmapping;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XErrorEvent xerror;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XKeymapEvent xkeymap;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>long pad[24];</small></p>
</td>
<td width="40%">
</td>
</table>
<p><small>} XEvent;</small></p>
<p><small>│__</small></p>
<p><small>An <i>XEvent</i> structure’s first entry
always is the type member, which is set to the event type.
The second member always is the serial number of the
protocol request that generated the event. The third member
always is send_event, which is a <i>Bool</i> that indicates
if the event was sent by a different client. The fourth
member always is a display, which is the display that the
event was read from. Except for keymap events, the fifth
member always is a window, which has been carefully selected
to be useful to toolkit dispatchers. To avoid breaking
toolkits, the order of these first five entries is not to
change. Most events also contain a time member, which is the
time at which an event occurred. In addition, a pointer to
the generic event must be cast before it is used to access
any other information in the structure.</small></p>
<a name="10.3. Event Masks"></a>
<h2>10.3. Event Masks</h2>
<p><small>Clients select event reporting of most events
relative to a window. To do this, pass an event mask to an
Xlib event-handling function that takes an event_mask
argument. The bits of the event mask are defined in
<<i>X11/X.h</i>>. Each bit in the event mask maps to
an event mask name, which describes the event or events you
want the X server to return to a client
application.</small></p>
<p><small>Unless the client has specifically asked for
them, most events are not reported to clients when they are
generated. Unless the client suppresses them by setting
graphics-exposures in the GC to <i>False</i>,
<i>GraphicsExpose</i> and <i>NoExpose</i> are reported by
default as a result of <i>XCopyPlane</i> and
<i>XCopyArea</i>. <i>SelectionClear</i>,
<i>SelectionRequest</i>, <i>SelectionNotify</i>, or
<i>ClientMessage</i> cannot be masked. Selection-related
events are only sent to clients cooperating with selections
(see section 4.5). When the keyboard or pointer mapping is
changed, <i>MappingNotify</i> is always sent to
clients.</small></p>
<p><small>The following table lists the event mask
constants you can pass to the event_mask argument and the
circumstances in which you would want to specify the event
mask:</small></p>
<p align=center><small><img src="grohtml-1439234.png"></small></p>
<a name="10.4. Event Processing Overview"></a>
<h2>10.4. Event Processing Overview</h2>
<p><small>The event reported to a client application during
event processing depends on which event masks you provide as
the event-mask attribute for a window. For some event masks,
there is a one-to-one correspondence between the event mask
constant and the event type constant. For example, if you
pass the event mask <i>ButtonPressMask</i>, the X server
sends back only <i>ButtonPress</i> events. Most events
contain a time member, which is the time at which an event
occurred.</small></p>
<p><small>In other cases, one event mask constant can map
to several event type constants. For example, if you pass
the event mask <i>SubstructureNotifyMask</i>, the X server
can send back <i>CirculateNotify</i>,
<i>ConfigureNotify</i>, <i>CreateNotify</i>,
<i>DestroyNotify</i>, <i>GravityNotify</i>,
<i>MapNotify</i>, <i>ReparentNotify</i>, or
<i>UnmapNotify</i> events.</small></p>
<p><small>In another case, two event masks can map to one
event type. For example, if you pass either
<i>PointerMotionMask</i> or <i>ButtonMotionMask</i>, the X
server sends back a <i>MotionNotify</i> event.</small></p>
<p><small>The following table lists the event mask, its
associated event type or types, and the structure name
associated with the event type. Some of these structures
actually are typedefs to a generic structure that is shared
between two event types. Note that N.A. appears in columns
for which the information is not applicable.</small></p>
<p align=center><small><img src="grohtml-1439235.png"></small></p>
<p><small>The sections that follow describe the processing
that occurs when you select the different event masks. The
sections are organized according to these processing
categories:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="54%">
<p><small>Keyboard and pointer events</small></p>
</td>
<td width="35%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="44%">
<p><small>Window crossing events</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="36%">
<p><small>Input focus events</small></p>
</td>
<td width="53%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="64%">
<p><small>Keymap state notification events</small></p>
</td>
<td width="25%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="30%">
<p><small>Exposure events</small></p>
</td>
<td width="59%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="64%">
<p><small>Window state notification events</small></p>
</td>
<td width="25%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="48%">
<p><small>Structure control events</small></p>
</td>
<td width="41%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="68%">
<p><small>Colormap state notification events</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="54%">
<p><small>Client communication events</small></p>
</td>
<td width="35%">
</td>
</table>
<a name="10.5. Keyboard and Pointer Events"></a>
<h2>10.5. Keyboard and Pointer Events</h2>
<p><small>This section discusses:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>Pointer button events</small></p>
</td>
<td width="47%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="54%">
<p><small>Keyboard and pointer events</small></p>
</td>
<td width="35%">
</td>
</table>
<a name="10.5.1. Pointer Button Events"></a>
<h2>10.5.1. Pointer Button Events</h2>
<p><small>The following describes the event processing that
occurs when a pointer button press is processed with the
pointer in some window w and when no active pointer grab is
in progress.</small></p>
<p><small>The X server searches the ancestors of w from the
root down, looking for a passive grab to activate. If no
matching passive grab on the button exists, the X server
automatically starts an active grab for the client receiving
the event and sets the last-pointer-grab time to the current
server time. The effect is essentially equivalent to an
<i>XGrabButton</i> with these client passed
arguments:</small></p>
<p align=center><small><img src="grohtml-1439236.png"></small></p>
<p><small>The active grab is automatically terminated when
the logical state of the pointer has all buttons released.
Clients can modify the active grab by calling
<i>XUngrabPointer</i> and
<i>XChangeActivePointerGrab</i>.</small></p>
<a name="10.5.2. Keyboard and Pointer Events"></a>
<h2>10.5.2. Keyboard and Pointer Events</h2>
<p><small>This section discusses the processing that occurs
for the keyboard events <i>KeyPress</i> and
<i>KeyRelease</i> and the pointer events <i>ButtonPress</i>,
<i>ButtonRelease</i>, and <i>MotionNotify</i>. For
information about the keyboard event-handling utilities, see
chapter 11.</small></p>
<p><small>The X server reports <i>KeyPress</i> or
<i>KeyRelease</i> events to clients wanting information
about keys that logically change state. Note that these
events are generated for all keys, even those mapped to
modifier bits. The X server reports <i>ButtonPress</i> or
<i>ButtonRelease</i> events to clients wanting information
about buttons that logically change state.</small></p>
<p><small>The X server reports <i>MotionNotify</i> events
to clients wanting information about when the pointer
logically moves. The X server generates this event whenever
the pointer is moved and the pointer motion begins and ends
in the window. The granularity of <i>MotionNotify</i> events
is not guaranteed, but a client that selects this event type
is guaranteed to receive at least one event when the pointer
moves and then rests.</small></p>
<p><small>The generation of the logical changes lags the
physical changes if device event processing is
frozen.</small></p>
<p><small>To receive <i>KeyPress</i>, <i>KeyRelease</i>,
<i>ButtonPress</i>, and <i>ButtonRelease</i> events, set
<i>KeyPressMask</i>, <i>KeyReleaseMask</i>,
<i>ButtonPressMask</i>, and <i>ButtonReleaseMask</i> bits in
the event-mask attribute of the window.</small></p>
<p><small>To receive <i>MotionNotify</i> events, set one or
more of the following event masks bits in the event-mask
attribute of the window.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="74%">
<p><small><i>Button1MotionMask</i> −
<i>Button5MotionMask</i></small></p>
</td>
<td width="15%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The client application receives
<i>MotionNotify</i> events only when one or more of the
specified buttons is pressed.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="32%">
<p><small><i>ButtonMotionMask</i></small></p>
</td>
<td width="57%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The client application receives
<i>MotionNotify</i> events only when at least one button is
pressed.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="34%">
<p><small><i>PointerMotionMask</i></small></p>
</td>
<td width="55%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The client application receives
<i>MotionNotify</i> events independent of the state of the
pointer buttons.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small><i>PointerMotionHintMask</i></small></p>
</td>
<td width="47%">
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>If <i>PointerMotionHintMask</i> is selected in
combination with one or more of the above masks, the X
server is free to send only one <i>MotionNotify</i> event
(with the is_hint member of the <i>XPointerMovedEvent</i>
structure set to <i>NotifyHint</i>) to the client for the
event window, until either the key or button state changes,
the pointer leaves the event window, or the client calls
<i>XQueryPointer</i> or <i>XGetMotionEvents</i>. The server
still may send <i>MotionNotify</i> events without is_hint
set to <i>NotifyHint</i>.</small></p>
</td>
</table>
<p><small>The source of the event is the viewable window
that the pointer is in. The window used by the X server to
report these events depends on the window’s position
in the window hierarchy and whether any intervening window
prohibits the generation of these events. Starting with the
source window, the X server searches up the window hierarchy
until it locates the first window specified by a client as
having an interest in these events. If one of the
intervening windows has its do-not-propagate-mask set to
prohibit generation of the event type, the events of those
types will be suppressed. Clients can modify the actual
window used for reporting by performing active grabs and, in
the case of keyboard events, by using the focus
window.</small></p>
<p><small>The structures for these event types
contain:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* ButtonPress or ButtonRelease */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
<p><small>/* ‘‘event’’ window it is
reported relative to */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window root;</small></p>
</td>
<td width="40%">
<p><small>/* root window that the event occurred on
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window subwindow;</small></p>
</td>
<td width="40%">
<p><small>/* child window */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Time time;</small></p>
</td>
<td width="40%">
<p><small>/* milliseconds */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int x, y;</small></p>
</td>
<td width="40%">
<p><small>/* pointer x, y coordinates in event window
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int x_root, y_root;</small></p>
</td>
<td width="40%">
<p><small>/* coordinates relative to root */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned int state;</small></p>
</td>
<td width="40%">
<p><small>/* key or button mask */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned int button;</small></p>
</td>
<td width="40%">
<p><small>/* detail */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool same_screen;</small></p>
</td>
<td width="40%">
<p><small>/* same screen flag */</small></p>
</td>
</table>
<p><small>} XButtonEvent;<br>
typedef XButtonEvent XButtonPressedEvent;<br>
typedef XButtonEvent XButtonReleasedEvent;</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* KeyPress or KeyRelease */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
<p><small>/* ‘‘event’’ window it is
reported relative to */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window root;</small></p>
</td>
<td width="40%">
<p><small>/* root window that the event occurred on
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window subwindow;</small></p>
</td>
<td width="40%">
<p><small>/* child window */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Time time;</small></p>
</td>
<td width="40%">
<p><small>/* milliseconds */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int x, y;</small></p>
</td>
<td width="40%">
<p><small>/* pointer x, y coordinates in event window
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int x_root, y_root;</small></p>
</td>
<td width="40%">
<p><small>/* coordinates relative to root */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned int state;</small></p>
</td>
<td width="40%">
<p><small>/* key or button mask */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned int keycode;</small></p>
</td>
<td width="40%">
<p><small>/* detail */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool same_screen;</small></p>
</td>
<td width="40%">
<p><small>/* same screen flag */</small></p>
</td>
</table>
<p><small>} XKeyEvent;<br>
typedef XKeyEvent XKeyPressedEvent;<br>
typedef XKeyEvent XKeyReleasedEvent;</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* MotionNotify */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
<p><small>/* ‘‘event’’ window
reported relative to */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window root;</small></p>
</td>
<td width="40%">
<p><small>/* root window that the event occurred on
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window subwindow;</small></p>
</td>
<td width="40%">
<p><small>/* child window */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Time time;</small></p>
</td>
<td width="40%">
<p><small>/* milliseconds */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int x, y;</small></p>
</td>
<td width="40%">
<p><small>/* pointer x, y coordinates in event window
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int x_root, y_root;</small></p>
</td>
<td width="40%">
<p><small>/* coordinates relative to root */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned int state;</small></p>
</td>
<td width="40%">
<p><small>/* key or button mask */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>char is_hint;</small></p>
</td>
<td width="40%">
<p><small>/* detail */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool same_screen;</small></p>
</td>
<td width="40%">
<p><small>/* same screen flag */</small></p>
</td>
</table>
<p><small>} XMotionEvent;<br>
typedef XMotionEvent XPointerMovedEvent;</small></p>
<p><small>│__</small></p>
<p><small>These structures have the following common
members: window, root, subwindow, time, x, y, x_root,
y_root, state, and same_screen. The window member is set to
the window on which the event was generated and is referred
to as the event window. As long as the conditions previously
discussed are met, this is the window used by the X server
to report the event. The root member is set to the source
window’s root window. The x_root and y_root members
are set to the pointer’s coordinates relative to the
root window’s origin at the time of the
event.</small></p>
<p><small>The same_screen member is set to indicate whether
the event window is on the same screen as the root window
and can be either <i>True</i> or <i>False</i>. If
<i>True</i>, the event and root windows are on the same
screen. If <i>False</i>, the event and root windows are not
on the same screen.</small></p>
<p><small>If the source window is an inferior of the event
window, the subwindow member of the structure is set to the
child of the event window that is the source window or the
child of the event window that is an ancestor of the source
window. Otherwise, the X server sets the subwindow member to
<i>None</i>. The time member is set to the time when the
event was generated and is expressed in
milliseconds.</small></p>
<p><small>If the event window is on the same screen as the
root window, the x and y members are set to the coordinates
relative to the event window’s origin. Otherwise,
these members are set to zero.</small></p>
<p><small>The state member is set to indicate the logical
state of the pointer buttons and modifier keys just prior to
the event, which is the bitwise inclusive OR of one or more
of the button or modifier key masks: <i>Button1Mask</i>,
<i>Button2Mask</i>, <i>Button3Mask</i>, <i>Button4Mask</i>,
<i>Button5Mask</i>, <i>ShiftMask</i>, <i>LockMask</i>,
<i>ControlMask</i>, <i>Mod1Mask</i>, <i>Mod2Mask</i>,
<i>Mod3Mask</i>, <i>Mod4Mask</i>, and
<i>Mod5Mask</i>.</small></p>
<p><small>Each of these structures also has a member that
indicates the detail. For the <i>XKeyPressedEvent</i> and
<i>XKeyReleasedEvent</i> structures, this member is called a
keycode. It is set to a number that represents a physical
key on the keyboard. The keycode is an arbitrary
representation for any key on the keyboard (see sections
12.7 and 16.1).</small></p>
<p><small>For the <i>XButtonPressedEvent</i> and
<i>XButtonReleasedEvent</i> structures, this member is
called button. It represents the pointer button that changed
state and can be the <i>Button1</i>, <i>Button2</i>,
<i>Button3</i>, <i>Button4</i>, or <i>Button5</i> value. For
the <i>XPointerMovedEvent</i> structure, this member is
called is_hint. It can be set to <i>NotifyNormal</i> or
<i>NotifyHint</i>.</small></p>
<p><small>Some of the symbols mentioned in this section
have fixed values, as follows:</small></p>
<p align=center><small><img src="grohtml-1439237.png"></small></p>
<a name="10.6. Window Entry/Exit Events"></a>
<h2>10.6. Window Entry/Exit Events</h2>
<p><small>This section describes the processing that occurs
for the window crossing events <i>EnterNotify</i> and
<i>LeaveNotify</i>. If a pointer motion or a window
hierarchy change causes the pointer to be in a different
window than before, the X server reports <i>EnterNotify</i>
or <i>LeaveNotify</i> events to clients who have selected
for these events. All <i>EnterNotify</i> and
<i>LeaveNotify</i> events caused by a hierarchy change are
generated after any hierarchy event (<i>UnmapNotify</i>,
<i>MapNotify</i>, <i>ConfigureNotify</i>,
<i>GravityNotify</i>, <i>CirculateNotify</i>) caused by that
change; however, the X protocol does not constrain the
ordering of <i>EnterNotify</i> and <i>LeaveNotify</i> events
with respect to <i>FocusOut</i>, <i>VisibilityNotify</i>,
and <i>Expose</i> events.</small></p>
<p><small>This contrasts with <i>MotionNotify</i> events,
which are also generated when the pointer moves but only
when the pointer motion begins and ends in a single window.
An <i>EnterNotify</i> or <i>LeaveNotify</i> event also can
be generated when some client application calls
<i>XGrabPointer</i> and <i>XUngrabPointer</i>.</small></p>
<p><small>To receive <i>EnterNotify</i> or
<i>LeaveNotify</i> events, set the <i>EnterWindowMask</i> or
<i>LeaveWindowMask</i> bits of the event-mask attribute of
the window.</small></p>
<p><small>The structure for these event types
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* EnterNotify or LeaveNotify */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
<p><small>/* ‘‘event’’ window
reported relative to */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window root;</small></p>
</td>
<td width="40%">
<p><small>/* root window that the event occurred on
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window subwindow;</small></p>
</td>
<td width="40%">
<p><small>/* child window */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Time time;</small></p>
</td>
<td width="40%">
<p><small>/* milliseconds */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int x, y;</small></p>
</td>
<td width="40%">
<p><small>/* pointer x, y coordinates in event window
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int x_root, y_root;</small></p>
</td>
<td width="40%">
<p><small>/* coordinates relative to root */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int mode;</small></p>
</td>
<td width="40%">
<p><small>/* NotifyNormal, NotifyGrab, NotifyUngrab
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int detail;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
</td>
<td width="40%">
<p><small>/*</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
</td>
<td width="40%">
<p><small>* NotifyAncestor, NotifyVirtual,
NotifyInferior,</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
</td>
<td width="40%">
<p><small>*
NotifyNonlinear,NotifyNonlinearVirtual</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
</td>
<td width="40%">
<p><small>*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool same_screen;</small></p>
</td>
<td width="40%">
<p><small>/* same screen flag */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool focus;</small></p>
</td>
<td width="40%">
<p><small>/* boolean focus */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned int state;</small></p>
</td>
<td width="40%">
<p><small>/* key or button mask */</small></p>
</td>
</table>
<p><small>} XCrossingEvent;<br>
typedef XCrossingEvent XEnterWindowEvent;<br>
typedef XCrossingEvent XLeaveWindowEvent;</small></p>
<p><small>│__</small></p>
<p><small>The window member is set to the window on which
the <i>EnterNotify</i> or <i>LeaveNotify</i> event was
generated and is referred to as the event window. This is
the window used by the X server to report the event, and is
relative to the root window on which the event occurred. The
root member is set to the root window of the screen on which
the event occurred.</small></p>
<p><small>For a <i>LeaveNotify</i> event, if a child of the
event window contains the initial position of the pointer,
the subwindow component is set to that child. Otherwise, the
X server sets the subwindow member to <i>None</i>. For an
<i>EnterNotify</i> event, if a child of the event window
contains the final pointer position, the subwindow component
is set to that child or <i>None</i>.</small></p>
<p><small>The time member is set to the time when the event
was generated and is expressed in milliseconds. The x and y
members are set to the coordinates of the pointer position
in the event window. This position is always the
pointer’s final position, not its initial position. If
the event window is on the same screen as the root window, x
and y are the pointer coordinates relative to the event
window’s origin. Otherwise, x and y are set to zero.
The x_root and y_root members are set to the pointer’s
coordinates relative to the root window’s origin at
the time of the event.</small></p>
<p><small>The same_screen member is set to indicate whether
the event window is on the same screen as the root window
and can be either <i>True</i> or <i>False</i>. If
<i>True</i>, the event and root windows are on the same
screen. If <i>False</i>, the event and root windows are not
on the same screen.</small></p>
<p><small>The focus member is set to indicate whether the
event window is the focus window or an inferior of the focus
window. The X server can set this member to either
<i>True</i> or <i>False</i>. If <i>True</i>, the event
window is the focus window or an inferior of the focus
window. If <i>False</i>, the event window is not the focus
window or an inferior of the focus window.</small></p>
<p><small>The state member is set to indicate the state of
the pointer buttons and modifier keys just prior to the
event. The X server can set this member to the bitwise
inclusive OR of one or more of the button or modifier key
masks: <i>Button1Mask</i>, <i>Button2Mask</i>,
<i>Button3Mask</i>, <i>Button4Mask</i>, <i>Button5Mask</i>,
<i>ShiftMask</i>, <i>LockMask</i>, <i>ControlMask</i>,
<i>Mod1Mask</i>, <i>Mod2Mask</i>, <i>Mod3Mask</i>,
<i>Mod4Mask</i>, <i>Mod5Mask</i>.</small></p>
<p><small>The mode member is set to indicate whether the
events are normal events, pseudo-motion events when a grab
activates, or pseudo-motion events when a grab deactivates.
The X server can set this member to <i>NotifyNormal</i>,
<i>NotifyGrab</i>, or <i>NotifyUngrab</i>.</small></p>
<p><small>The detail member is set to indicate the notify
detail and can be <i>NotifyAncestor</i>,
<i>NotifyVirtual</i>, <i>NotifyInferior</i>,
<i>NotifyNonlinear</i>, or
<i>NotifyNonlinearVirtual</i>.</small></p>
<a name="10.6.1. Normal Entry/Exit Events"></a>
<h2>10.6.1. Normal Entry/Exit Events</h2>
<p><small><i>EnterNotify</i> and <i>LeaveNotify</i> events
are generated when the pointer moves from one window to
another window. Normal events are identified by
<i>XEnterWindowEvent</i> or <i>XLeaveWindowEvent</i>
structures whose mode member is set to
<i>NotifyNormal</i>.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When the pointer moves from window A to window B
and A is an inferior of B, the X server does the
following:</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>LeaveNotify</i> event on window
A, with the detail member of the <i>XLeaveWindowEvent</i>
structure set to <i>NotifyAncestor</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>LeaveNotify</i> event on each
window between window A and window B, exclusive, with the
detail member of each <i>XLeaveWindowEvent</i> structure set
to <i>NotifyVirtual</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates an <i>EnterNotify</i> event on
window B, with the detail member of the
<i>XEnterWindowEvent</i> structure set to
<i>NotifyInferior</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When the pointer moves from window A to window B
and B is an inferior of A, the X server does the
following:</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>LeaveNotify</i> event on window
A, with the detail member of the <i>XLeaveWindowEvent</i>
structure set to <i>NotifyInferior</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates an <i>EnterNotify</i> event on each
window between window A and window B, exclusive, with the
detail member of each <i>XEnterWindowEvent</i> structure set
to <i>NotifyVirtual</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates an <i>EnterNotify</i> event on
window B, with the detail member of the
<i>XEnterWindowEvent</i> structure set to
<i>NotifyAncestor</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When the pointer moves from window A to window B
and window C is their least common ancestor, the X server
does the following:</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>LeaveNotify</i> event on window
A, with the detail member of the <i>XLeaveWindowEvent</i>
structure set to <i>NotifyNonlinear</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>LeaveNotify</i> event on each
window between window A and window C, exclusive, with the
detail member of each <i>XLeaveWindowEvent</i> structure set
to <i>NotifyNonlinearVirtual</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates an <i>EnterNotify</i> event on each
window between window C and window B, exclusive, with the
detail member of each <i>XEnterWindowEvent</i> structure set
to <i>NotifyNonlinearVirtual</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates an <i>EnterNotify</i> event on
window B, with the detail member of the
<i>XEnterWindowEvent</i> structure set to
<i>NotifyNonlinear</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When the pointer moves from window A to window B
on different screens, the X server does the
following:</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>LeaveNotify</i> event on window
A, with the detail member of the <i>XLeaveWindowEvent</i>
structure set to <i>NotifyNonlinear</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>If window A is not a root window, it generates a
<i>LeaveNotify</i> event on each window above window A up to
and including its root, with the detail member of each
<i>XLeaveWindowEvent</i> structure set to
<i>NotifyNonlinearVirtual</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>If window B is not a root window, it generates an
<i>EnterNotify</i> event on each window from window
B’s root down to but not including window B, with the
detail member of each <i>XEnterWindowEvent</i> structure set
to <i>NotifyNonlinearVirtual</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates an <i>EnterNotify</i> event on
window B, with the detail member of the
<i>XEnterWindowEvent</i> structure set to
<i>NotifyNonlinear</i>.</small></p>
</td>
</table>
<a name="10.6.2. Grab and Ungrab Entry/Exit Events"></a>
<h2>10.6.2. Grab and Ungrab Entry/Exit Events</h2>
<p><small>Pseudo-motion mode <i>EnterNotify</i> and
<i>LeaveNotify</i> events are generated when a pointer grab
activates or deactivates. Events in which the pointer grab
activates are identified by <i>XEnterWindowEvent</i> or
<i>XLeaveWindowEvent</i> structures whose mode member is set
to <i>NotifyGrab</i>. Events in which the pointer grab
deactivates are identified by <i>XEnterWindowEvent</i> or
<i>XLeaveWindowEvent</i> structures whose mode member is set
to <i>NotifyUngrab</i> (see
<i>XGrabPointer</i>).</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When a pointer grab activates after any initial
warp into a confine_to window and before generating any
actual <i>ButtonPress</i> event that activates the grab, G
is the grab_window for the grab, and P is the window the
pointer is in, the X server does the following:</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates <i>EnterNotify</i> and
<i>LeaveNotify</i> events (see section 10.6.1) with the mode
members of the <i>XEnterWindowEvent</i> and
<i>XLeaveWindowEvent</i> structures set to
<i>NotifyGrab</i>. These events are generated as if the
pointer were to suddenly warp from its current position in P
to some position in G. However, the pointer does not warp,
and the X server uses the pointer position as both the
initial and final positions for the events.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When a pointer grab deactivates after generating
any actual <i>ButtonRelease</i> event that deactivates the
grab, G is the grab_window for the grab, and P is the window
the pointer is in, the X server does the
following:</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates <i>EnterNotify</i> and
<i>LeaveNotify</i> events (see section 10.6.1) with the mode
members of the <i>XEnterWindowEvent</i> and
<i>XLeaveWindowEvent</i> structures set to
<i>NotifyUngrab</i>. These events are generated as if the
pointer were to suddenly warp from some position in G to its
current position in P. However, the pointer does not warp,
and the X server uses the current pointer position as both
the initial and final positions for the events.</small></p>
</td>
</table>
<a name="10.7. Input Focus Events"></a>
<h2>10.7. Input Focus Events</h2>
<p><small>This section describes the processing that occurs
for the input focus events <i>FocusIn</i> and
<i>FocusOut</i>. The X server can report <i>FocusIn</i> or
<i>FocusOut</i> events to clients wanting information about
when the input focus changes. The keyboard is always
attached to some window (typically, the root window or a
top-level window), which is called the focus window. The
focus window and the position of the pointer determine the
window that receives keyboard input. Clients may need to
know when the input focus changes to control highlighting of
areas on the screen.</small></p>
<p><small>To receive <i>FocusIn</i> or <i>FocusOut</i>
events, set the <i>FocusChangeMask</i> bit in the event-mask
attribute of the window.</small></p>
<p><small>The structure for these event types
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* FocusIn or FocusOut */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
<p><small>/* window of event */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int mode;</small></p>
</td>
<td width="40%">
<p><small>/* NotifyNormal, NotifyGrab, NotifyUngrab
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int detail;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
</td>
<td width="40%">
<p><small>/*</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
</td>
<td width="40%">
<p><small>* NotifyAncestor, NotifyVirtual,
NotifyInferior,</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
</td>
<td width="40%">
<p><small>* NotifyNonlinear,NotifyNonlinearVirtual,
NotifyPointer,</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
</td>
<td width="40%">
<p><small>* NotifyPointerRoot, NotifyDetailNone</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
</td>
<td width="40%">
<p><small>*/</small></p>
</td>
</table>
<p><small>} XFocusChangeEvent;<br>
typedef XFocusChangeEvent XFocusInEvent;<br>
typedef XFocusChangeEvent XFocusOutEvent;</small></p>
<p><small>│__</small></p>
<p><small>The window member is set to the window on which
the <i>FocusIn</i> or <i>FocusOut</i> event was generated.
This is the window used by the X server to report the event.
The mode member is set to indicate whether the focus events
are normal focus events, focus events while grabbed, focus
events when a grab activates, or focus events when a grab
deactivates. The X server can set the mode member to
<i>NotifyNormal</i>, <i>NotifyWhileGrabbed</i>,
<i>NotifyGrab</i>, or <i>NotifyUngrab</i>.</small></p>
<p><small>All <i>FocusOut</i> events caused by a window
unmap are generated after any <i>UnmapNotify</i> event;
however, the X protocol does not constrain the ordering of
<i>FocusOut</i> events with respect to generated
<i>EnterNotify</i>, <i>LeaveNotify</i>,
<i>VisibilityNotify</i>, and <i>Expose</i>
events.</small></p>
<p><small>Depending on the event mode, the detail member is
set to indicate the notify detail and can be
<i>NotifyAncestor</i>, <i>NotifyVirtual</i>,
<i>NotifyInferior</i>, <i>NotifyNonlinear</i>,
<i>NotifyNonlinearVirtual</i>, <i>NotifyPointer</i>,
<i>NotifyPointerRoot</i>, or
<i>NotifyDetailNone</i>.</small></p>
<a name="10.7.1. Normal Focus Events and Focus Events While Grabbed"></a>
<h2>10.7.1. Normal Focus Events and Focus Events While Grabbed</h2>
<p><small>Normal focus events are identified by
<i>XFocusInEvent</i> or <i>XFocusOutEvent</i> structures
whose mode member is set to <i>NotifyNormal</i>. Focus
events while grabbed are identified by <i>XFocusInEvent</i>
or <i>XFocusOutEvent</i> structures whose mode member is set
to <i>NotifyWhileGrabbed</i>. The X server processes normal
focus and focus events while grabbed according to the
following:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When the focus moves from window A to window B, A
is an inferior of B, and the pointer is in window P, the X
server does the following:</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>FocusOut</i> event on window A,
with the detail member of the <i>XFocusOutEvent</i>
structure set to <i>NotifyAncestor</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>FocusOut</i> event on each
window between window A and window B, exclusive, with the
detail member of each <i>XFocusOutEvent</i> structure set to
<i>NotifyVirtual</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>FocusIn</i> event on window B,
with the detail member of the <i>XFocusOutEvent</i>
structure set to <i>NotifyInferior</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>If window P is an inferior of window B but window
P is not window A or an inferior or ancestor of window A, it
generates a <i>FocusIn</i> event on each window below window
B, down to and including window P, with the detail member of
each <i>XFocusInEvent</i> structure set to
<i>NotifyPointer</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When the focus moves from window A to window B, B
is an inferior of A, and the pointer is in window P, the X
server does the following:</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>If window P is an inferior of window A but P is
not an inferior of window B or an ancestor of B, it
generates a <i>FocusOut</i> event on each window from window
P up to but not including window A, with the detail member
of each <i>XFocusOutEvent</i> structure set to
<i>NotifyPointer</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>FocusOut</i> event on window A,
with the detail member of the <i>XFocusOutEvent</i>
structure set to <i>NotifyInferior</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>FocusIn</i> event on each
window between window A and window B, exclusive, with the
detail member of each <i>XFocusInEvent</i> structure set to
<i>NotifyVirtual</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>FocusIn</i> event on window B,
with the detail member of the <i>XFocusInEvent</i> structure
set to <i>NotifyAncestor</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When the focus moves from window A to window B,
window C is their least common ancestor, and the pointer is
in window P, the X server does the following:</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>If window P is an inferior of window A, it
generates a <i>FocusOut</i> event on each window from window
P up to but not including window A, with the detail member
of the <i>XFocusOutEvent</i> structure set to
<i>NotifyPointer</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>FocusOut</i> event on window A,
with the detail member of the <i>XFocusOutEvent</i>
structure set to <i>NotifyNonlinear</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>FocusOut</i> event on each
window between window A and window C, exclusive, with the
detail member of each <i>XFocusOutEvent</i> structure set to
<i>NotifyNonlinearVirtual</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>FocusIn</i> event on each
window between C and B, exclusive, with the detail member of
each <i>XFocusInEvent</i> structure set to
<i>NotifyNonlinearVirtual</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>FocusIn</i> event on window B,
with the detail member of the <i>XFocusInEvent</i> structure
set to <i>NotifyNonlinear</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>If window P is an inferior of window B, it
generates a <i>FocusIn</i> event on each window below window
B down to and including window P, with the detail member of
the <i>XFocusInEvent</i> structure set to
<i>NotifyPointer</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When the focus moves from window A to window B on
different screens and the pointer is in window P, the X
server does the following:</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>If window P is an inferior of window A, it
generates a <i>FocusOut</i> event on each window from window
P up to but not including window A, with the detail member
of each <i>XFocusOutEvent</i> structure set to
<i>NotifyPointer</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>FocusOut</i> event on window A,
with the detail member of the <i>XFocusOutEvent</i>
structure set to <i>NotifyNonlinear</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>If window A is not a root window, it generates a
<i>FocusOut</i> event on each window above window A up to
and including its root, with the detail member of each
<i>XFocusOutEvent</i> structure set to
<i>NotifyNonlinearVirtual</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>If window B is not a root window, it generates a
<i>FocusIn</i> event on each window from window B’s
root down to but not including window B, with the detail
member of each <i>XFocusInEvent</i> structure set to
<i>NotifyNonlinearVirtual</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>FocusIn</i> event on window B,
with the detail member of each <i>XFocusInEvent</i>
structure set to <i>NotifyNonlinear</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>If window P is an inferior of window B, it
generates a <i>FocusIn</i> event on each window below window
B down to and including window P, with the detail member of
each <i>XFocusInEvent</i> structure set to
<i>NotifyPointer</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When the focus moves from window A to
<i>PointerRoot</i> (events sent to the window under the
pointer) or <i>None</i> (discard), and the pointer is in
window P, the X server does the following:</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>If window P is an inferior of window A, it
generates a <i>FocusOut</i> event on each window from window
P up to but not including window A, with the detail member
of each <i>XFocusOutEvent</i> structure set to
<i>NotifyPointer</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>FocusOut</i> event on window A,
with the detail member of the <i>XFocusOutEvent</i>
structure set to <i>NotifyNonlinear</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>If window A is not a root window, it generates a
<i>FocusOut</i> event on each window above window A up to
and including its root, with the detail member of each
<i>XFocusOutEvent</i> structure set to
<i>NotifyNonlinearVirtual</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>FocusIn</i> event on the root
window of all screens, with the detail member of each
<i>XFocusInEvent</i> structure set to
<i>NotifyPointerRoot</i> (or
<i>NotifyDetailNone</i>).</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>If the new focus is <i>PointerRoot</i>, it
generates a <i>FocusIn</i> event on each window from window
P’s root down to and including window P, with the
detail member of each <i>XFocusInEvent</i> structure set to
<i>NotifyPointer</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When the focus moves from <i>PointerRoot</i>
(events sent to the window under the pointer) or <i>None</i>
to window A, and the pointer is in window P, the X server
does the following:</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>If the old focus is <i>PointerRoot</i>, it
generates a <i>FocusOut</i> event on each window from window
P up to and including window P’s root, with the detail
member of each <i>XFocusOutEvent</i> structure set to
<i>NotifyPointer</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>FocusOut</i> event on all root
windows, with the detail member of each
<i>XFocusOutEvent</i> structure set to
<i>NotifyPointerRoot</i> (or
<i>NotifyDetailNone</i>).</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>If window A is not a root window, it generates a
<i>FocusIn</i> event on each window from window A’s
root down to but not including window A, with the detail
member of each <i>XFocusInEvent</i> structure set to
<i>NotifyNonlinearVirtual</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>FocusIn</i> event on window A,
with the detail member of the <i>XFocusInEvent</i> structure
set to <i>NotifyNonlinear</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>If window P is an inferior of window A, it
generates a <i>FocusIn</i> event on each window below window
A down to and including window P, with the detail member of
each <i>XFocusInEvent</i> structure set to
<i>NotifyPointer</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When the focus moves from <i>PointerRoot</i>
(events sent to the window under the pointer) to <i>None</i>
(or vice versa), and the pointer is in window P, the X
server does the following:</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>If the old focus is <i>PointerRoot</i>, it
generates a <i>FocusOut</i> event on each window from window
P up to and including window P’s root, with the detail
member of each <i>XFocusOutEvent</i> structure set to
<i>NotifyPointer</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>FocusOut</i> event on all root
windows, with the detail member of each
<i>XFocusOutEvent</i> structure set to either
<i>NotifyPointerRoot</i> or
<i>NotifyDetailNone</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates a <i>FocusIn</i> event on all root
windows, with the detail member of each <i>XFocusInEvent</i>
structure set to <i>NotifyDetailNone</i> or
<i>NotifyPointerRoot</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>If the new focus is <i>PointerRoot</i>, it
generates a <i>FocusIn</i> event on each window from window
P’s root down to and including window P, with the
detail member of each <i>XFocusInEvent</i> structure set to
<i>NotifyPointer</i>.</small></p>
</td>
</table>
<a name="10.7.2. Focus Events Generated by Grabs"></a>
<h2>10.7.2. Focus Events Generated by Grabs</h2>
<p><small>Focus events in which the keyboard grab activates
are identified by <i>XFocusInEvent</i> or
<i>XFocusOutEvent</i> structures whose mode member is set to
<i>NotifyGrab</i>. Focus events in which the keyboard grab
deactivates are identified by <i>XFocusInEvent</i> or
<i>XFocusOutEvent</i> structures whose mode member is set to
<i>NotifyUngrab</i> (see <i>XGrabKeyboard</i>).</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When a keyboard grab activates before generating
any actual <i>KeyPress</i> event that activates the grab, G
is the grab_window, and F is the current focus, the X server
does the following:</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates <i>FocusIn</i> and <i>FocusOut</i>
events, with the mode members of the <i>XFocusInEvent</i>
and <i>XFocusOutEvent</i> structures set to
<i>NotifyGrab</i>. These events are generated as if the
focus were to change from F to G.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When a keyboard grab deactivates after generating
any actual <i>KeyRelease</i> event that deactivates the
grab, G is the grab_window, and F is the current focus, the
X server does the following:</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>−</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>It generates <i>FocusIn</i> and <i>FocusOut</i>
events, with the mode members of the <i>XFocusInEvent</i>
and <i>XFocusOutEvent</i> structures set to
<i>NotifyUngrab</i>. These events are generated as if the
focus were to change from G to F.</small></p>
</td>
</table>
<a name="10.8. Key Map State Notification Events"></a>
<h2>10.8. Key Map State Notification Events</h2>
<p><small>The X server can report <i>KeymapNotify</i>
events to clients that want information about changes in
their keyboard state.</small></p>
<p><small>To receive <i>KeymapNotify</i> events, set the
<i>KeymapStateMask</i> bit in the event-mask attribute of
the window. The X server generates this event immediately
after every <i>EnterNotify</i> and <i>FocusIn</i>
event.</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>/* generated on EnterWindow and FocusIn when KeymapState selected */
typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* KeymapNotify */</small></p>
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="10%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="10%"></td>
<td width="50%">
<p><small>char key_vector[32];</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="10%">
<p><small>} XKeymapEvent;</small></p>
</td>
<td width="50%"></td>
<td width="40%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The window member is not used but is present to
aid some toolkits. The key_vector member is set to the bit
vector of the keyboard. Each bit set to 1 indicates that the
corresponding key is currently pressed. The vector is
represented as 32 bytes. Byte N (from 0) contains the bits
for keys 8N to 8N + 7 with the least significant bit in the
byte representing key 8N.</small></p>
<a name="10.9. Exposure Events"></a>
<h2>10.9. Exposure Events</h2>
<p><small>The X protocol does not guarantee to preserve the
contents of window regions when the windows are obscured or
reconfigured. Some implementations may preserve the contents
of windows. Other implementations are free to destroy the
contents of windows when exposed. X expects client
applications to assume the responsibility for restoring the
contents of an exposed window region. (An exposed window
region describes a formerly obscured window whose region
becomes visible.) Therefore, the X server sends
<i>Expose</i> events describing the window and the region of
the window that has been exposed. A naive client application
usually redraws the entire window. A more sophisticated
client application redraws only the exposed
region.</small></p>
<a name="10.9.1. Expose Events"></a>
<h2>10.9.1. Expose Events</h2>
<p><small>The X server can report <i>Expose</i> events to
clients wanting information about when the contents of
window regions have been lost. The circumstances in which
the X server generates <i>Expose</i> events are not as
definite as those for other events. However, the X server
never generates <i>Expose</i> events on windows whose class
you specified as <i>InputOnly</i>. The X server can generate
<i>Expose</i> events when no valid contents are available
for regions of a window and either the regions are visible,
the regions are viewable and the server is (perhaps newly)
maintaining backing store on the window, or the window is
not viewable but the server is (perhaps newly) honoring the
window’s backing-store attribute of <i>Always</i> or
<i>WhenMapped</i>. The regions decompose into an (arbitrary)
set of rectangles, and an <i>Expose</i> event is generated
for each rectangle. For any given window, the X server
guarantees to report contiguously all of the regions exposed
by some action that causes <i>Expose</i> events, such as
raising a window.</small></p>
<p><small>To receive <i>Expose</i> events, set the
<i>ExposureMask</i> bit in the event-mask attribute of the
window.</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* Expose */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int x, y;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int width, height;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int count;</small></p>
</td>
<td width="40%">
<p><small>/* if nonzero, at least this many more
*/</small></p>
</td>
</table>
<p><small>} XExposeEvent;</small></p>
<p><small>│__</small></p>
<p><small>The window member is set to the exposed (damaged)
window. The x and y members are set to the coordinates
relative to the window’s origin and indicate the
upper-left corner of the rectangle. The width and height
members are set to the size (extent) of the rectangle. The
count member is set to the number of <i>Expose</i> events
that are to follow. If count is zero, no more <i>Expose</i>
events follow for this window. However, if count is nonzero,
at least that number of <i>Expose</i> events (and possibly
more) follow for this window. Simple applications that do
not want to optimize redisplay by distinguishing between
subareas of its window can just ignore all <i>Expose</i>
events with nonzero counts and perform full redisplays on
events with zero counts.</small></p>
<a name="10.9.2. GraphicsExpose and NoExpose Events"></a>
<h2>10.9.2. GraphicsExpose and NoExpose Events</h2>
<p><small>The X server can report <i>GraphicsExpose</i>
events to clients wanting information about when a
destination region could not be computed during certain
graphics requests: <i>XCopyArea</i> or <i>XCopyPlane</i>.
The X server generates this event whenever a destination
region could not be computed because of an obscured or
out-of-bounds source region. In addition, the X server
guarantees to report contiguously all of the regions exposed
by some graphics request (for example, copying an area of a
drawable to a destination drawable).</small></p>
<p><small>The X server generates a <i>NoExpose</i> event
whenever a graphics request that might produce a
<i>GraphicsExpose</i> event does not produce any. In other
words, the client is really asking for a
<i>GraphicsExpose</i> event but instead receives a
<i>NoExpose</i> event.</small></p>
<p><small>To receive <i>GraphicsExpose</i> or
<i>NoExpose</i> events, you must first set the
graphics-exposure attribute of the graphics context to
<i>True</i>. You also can set the graphics-expose attribute
when creating a graphics context using <i>XCreateGC</i> or
by calling <i>XSetGraphicsExposures</i>.</small></p>
<p><small>The structures for these event types
contain:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* GraphicsExpose */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Drawable drawable;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int x, y;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int width, height;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int count;</small></p>
</td>
<td width="40%">
<p><small>/* if nonzero, at least this many more
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int major_code;</small></p>
</td>
<td width="40%">
<p><small>/* core is CopyArea or CopyPlane */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int minor_code;</small></p>
</td>
<td width="40%">
<p><small>/* not defined in the core */</small></p>
</td>
</table>
<p><small>} XGraphicsExposeEvent;</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* NoExpose */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Drawable drawable;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int major_code;</small></p>
</td>
<td width="40%">
<p><small>/* core is CopyArea or CopyPlane */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int minor_code;</small></p>
</td>
<td width="40%">
<p><small>/* not defined in the core */</small></p>
</td>
</table>
<p><small>} XNoExposeEvent;</small></p>
<p><small>│__</small></p>
<p><small>Both structures have these common members:
drawable, major_code, and minor_code. The drawable member is
set to the drawable of the destination region on which the
graphics request was to be performed. The major_code member
is set to the graphics request initiated by the client and
can be either <i>X_CopyArea</i> or <i>X_CopyPlane</i>. If it
is <i>X_CopyArea</i>, a call to <i>XCopyArea</i> initiated
the request. If it is <i>X_CopyPlane</i>, a call to
<i>XCopyPlane</i> initiated the request. These constants are
defined in <<i>X11/Xproto.h</i>>. The minor_code
member, like the major_code member, indicates which graphics
request was initiated by the client. However, the minor_code
member is not defined by the core X protocol and will be
zero in these cases, although it may be used by an
extension.</small></p>
<p><small>The <i>XGraphicsExposeEvent</i> structure has
these additional members: x, y, width, height, and count.
The x and y members are set to the coordinates relative to
the drawable’s origin and indicate the upper-left
corner of the rectangle. The width and height members are
set to the size (extent) of the rectangle. The count member
is set to the number of <i>GraphicsExpose</i> events to
follow. If count is zero, no more <i>GraphicsExpose</i>
events follow for this window. However, if count is nonzero,
at least that number of <i>GraphicsExpose</i> events (and
possibly more) are to follow for this window.</small></p>
<a name="10.10. Window State Change Events"></a>
<h2>10.10. Window State Change Events</h2>
<p><small>The following sections discuss:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="44%">
<p><small><i>CirculateNotify</i> events</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="44%">
<p><small><i>ConfigureNotify</i> events</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="38%">
<p><small><i>CreateNotify</i> events</small></p>
</td>
<td width="51%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="40%">
<p><small><i>DestroyNotify</i> events</small></p>
</td>
<td width="49%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="40%">
<p><small><i>GravityNotify</i> events</small></p>
</td>
<td width="49%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="32%">
<p><small><i>MapNotify</i> events</small></p>
</td>
<td width="57%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="40%">
<p><small><i>MappingNotify</i> events</small></p>
</td>
<td width="49%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small><i>ReparentNotify</i> events</small></p>
</td>
<td width="47%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="36%">
<p><small><i>UnmapNotify</i> events</small></p>
</td>
<td width="53%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="46%">
<p><small><i>VisibilityNotify</i> events</small></p>
</td>
<td width="43%">
</td>
</table>
<a name="10.10.1. CirculateNotify Events"></a>
<h2>10.10.1. CirculateNotify Events</h2>
<p><small>The X server can report <i>CirculateNotify</i>
events to clients wanting information about when a window
changes its position in the stack. The X server generates
this event type whenever a window is actually restacked as a
result of a client application calling
<i>XCirculateSubwindows</i>, <i>XCirculateSubwindowsUp</i>,
or <i>XCirculateSubwindowsDown</i>.</small></p>
<p><small>To receive <i>CirculateNotify</i> events, set the
<i>StructureNotifyMask</i> bit in the event-mask attribute
of the window or the <i>SubstructureNotifyMask</i> bit in
the event-mask attribute of the parent window (in which
case, circulating any child generates an event).</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* CirculateNotify */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window event;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int place;</small></p>
</td>
<td width="40%">
<p><small>/* PlaceOnTop, PlaceOnBottom */</small></p>
</td>
</table>
<p><small>} XCirculateEvent;</small></p>
<p><small>│__</small></p>
<p><small>The event member is set either to the restacked
window or to its parent, depending on whether
<i>StructureNotify</i> or <i>SubstructureNotify</i> was
selected. The window member is set to the window that was
restacked. The place member is set to the window’s
position after the restack occurs and is either
<i>PlaceOnTop</i> or <i>PlaceOnBottom</i>. If it is
<i>PlaceOnTop</i>, the window is now on top of all siblings.
If it is <i>PlaceOnBottom</i>, the window is now below all
siblings.</small></p>
<a name="10.10.2. ConfigureNotify Events"></a>
<h2>10.10.2. ConfigureNotify Events</h2>
<p><small>The X server can report <i>ConfigureNotify</i>
events to clients wanting information about actual changes
to a window’s state, such as size, position, border,
and stacking order. The X server generates this event type
whenever one of the following configure window requests made
by a client application actually completes:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>A window’s size, position, border, and/or
stacking order is reconfigured by calling
<i>XConfigureWindow</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The window’s position in the stacking order
is changed by calling <i>XLowerWindow</i>,
<i>XRaiseWindow</i>, or <i>XRestackWindows</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="82%">
<p><small>A window is moved by calling
<i>XMoveWindow</i>.</small></p>
</td>
<td width="7%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>A window’s size is changed by calling
<i>XResizeWindow</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>A window’s size and location is changed by
calling <i>XMoveResizeWindow</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>A window is mapped and its position in the
stacking order is changed by calling
<i>XMapRaised</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>A window’s border width is changed by
calling <i>XSetWindowBorderWidth</i>.</small></p>
</td>
<td width="0%">
</td>
</table>
<p><small>To receive <i>ConfigureNotify</i> events, set the
<i>StructureNotifyMask</i> bit in the event-mask attribute
of the window or the <i>SubstructureNotifyMask</i> bit in
the event-mask attribute of the parent window (in which
case, configuring any child generates an event).</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* ConfigureNotify */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window event;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int x, y;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int width, height;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int border_width;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window above;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool override_redirect;</small></p>
</td>
<td width="40%">
</td>
</table>
<p><small>} XConfigureEvent;</small></p>
<p><small>│__</small></p>
<p><small>The event member is set either to the
reconfigured window or to its parent, depending on whether
<i>StructureNotify</i> or <i>SubstructureNotify</i> was
selected. The window member is set to the window whose size,
position, border, and/or stacking order was
changed.</small></p>
<p><small>The x and y members are set to the coordinates
relative to the parent window’s origin and indicate
the position of the upper-left outside corner of the window.
The width and height members are set to the inside size of
the window, not including the border. The border_width
member is set to the width of the window’s border, in
pixels.</small></p>
<p><small>The above member is set to the sibling window and
is used for stacking operations. If the X server sets this
member to <i>None</i>, the window whose state was changed is
on the bottom of the stack with respect to sibling windows.
However, if this member is set to a sibling window, the
window whose state was changed is placed on top of this
sibling window.</small></p>
<p><small>The override_redirect member is set to the
override-redirect attribute of the window. Window manager
clients normally should ignore this window if the
override_redirect member is <i>True</i>.</small></p>
<a name="10.10.3. CreateNotify Events"></a>
<h2>10.10.3. CreateNotify Events</h2>
<p><small>The X server can report <i>CreateNotify</i>
events to clients wanting information about creation of
windows. The X server generates this event whenever a client
application creates a window by calling <i>XCreateWindow</i>
or <i>XCreateSimpleWindow</i>.</small></p>
<p><small>To receive <i>CreateNotify</i> events, set the
<i>SubstructureNotifyMask</i> bit in the event-mask
attribute of the window. Creating any children then
generates an event.</small></p>
<p><small>The structure for the event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* CreateNotify */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window parent;</small></p>
</td>
<td width="40%">
<p><small>/* parent of the window */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
<p><small>/* window id of window created */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int x, y;</small></p>
</td>
<td width="40%">
<p><small>/* window location */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int width, height;</small></p>
</td>
<td width="40%">
<p><small>/* size of window */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int border_width;</small></p>
</td>
<td width="40%">
<p><small>/* border width */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool override_redirect;</small></p>
</td>
<td width="40%">
<p><small>/* creation should be overridden */</small></p>
</td>
</table>
<p><small>} XCreateWindowEvent;</small></p>
<p><small>│__</small></p>
<p><small>The parent member is set to the created
window’s parent. The window member specifies the
created window. The x and y members are set to the created
window’s coordinates relative to the parent
window’s origin and indicate the position of the
upper-left outside corner of the created window. The width
and height members are set to the inside size of the created
window (not including the border) and are always nonzero.
The border_width member is set to the width of the created
window’s border, in pixels. The override_redirect
member is set to the override-redirect attribute of the
window. Window manager clients normally should ignore this
window if the override_redirect member is
<i>True</i>.</small></p>
<a name="10.10.4. DestroyNotify Events"></a>
<h2>10.10.4. DestroyNotify Events</h2>
<p><small>The X server can report <i>DestroyNotify</i>
events to clients wanting information about which windows
are destroyed. The X server generates this event whenever a
client application destroys a window by calling
<i>XDestroyWindow</i> or
<i>XDestroySubwindows</i>.</small></p>
<p><small>The ordering of the <i>DestroyNotify</i> events
is such that for any given window, <i>DestroyNotify</i> is
generated on all inferiors of the window before being
generated on the window itself. The X protocol does not
constrain the ordering among siblings and across
subhierarchies.</small></p>
<p><small>To receive <i>DestroyNotify</i> events, set the
<i>StructureNotifyMask</i> bit in the event-mask attribute
of the window or the <i>SubstructureNotifyMask</i> bit in
the event-mask attribute of the parent window (in which
case, destroying any child generates an event).</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* DestroyNotify */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window event;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
</td>
</table>
<p><small>} XDestroyWindowEvent;</small></p>
<p><small>│__</small></p>
<p><small>The event member is set either to the destroyed
window or to its parent, depending on whether
<i>StructureNotify</i> or <i>SubstructureNotify</i> was
selected. The window member is set to the window that is
destroyed.</small></p>
<a name="10.10.5. GravityNotify Events"></a>
<h2>10.10.5. GravityNotify Events</h2>
<p><small>The X server can report <i>GravityNotify</i>
events to clients wanting information about when a window is
moved because of a change in the size of its parent. The X
server generates this event whenever a client application
actually moves a child window as a result of resizing its
parent by calling <i>XConfigureWindow</i>,
<i>XMoveResizeWindow</i>, or
<i>XResizeWindow</i>.</small></p>
<p><small>To receive <i>GravityNotify</i> events, set the
<i>StructureNotifyMask</i> bit in the event-mask attribute
of the window or the <i>SubstructureNotifyMask</i> bit in
the event-mask attribute of the parent window (in which
case, any child that is moved because its parent has been
resized generates an event).</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* GravityNotify */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window event;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int x, y;</small></p>
</td>
<td width="40%">
</td>
</table>
<p><small>} XGravityEvent;</small></p>
<p><small>│__</small></p>
<p><small>The event member is set either to the window that
was moved or to its parent, depending on whether
<i>StructureNotify</i> or <i>SubstructureNotify</i> was
selected. The window member is set to the child window that
was moved. The x and y members are set to the coordinates
relative to the new parent window’s origin and
indicate the position of the upper-left outside corner of
the window.</small></p>
<a name="10.10.6. MapNotify Events"></a>
<h2>10.10.6. MapNotify Events</h2>
<p><small>The X server can report <i>MapNotify</i> events
to clients wanting information about which windows are
mapped. The X server generates this event type whenever a
client application changes the window’s state from
unmapped to mapped by calling <i>XMapWindow</i>,
<i>XMapRaised</i>, <i>XMapSubwindows</i>,
<i>XReparentWindow</i>, or as a result of save-set
processing.</small></p>
<p><small>To receive <i>MapNotify</i> events, set the
<i>StructureNotifyMask</i> bit in the event-mask attribute
of the window or the <i>SubstructureNotifyMask</i> bit in
the event-mask attribute of the parent window (in which
case, mapping any child generates an event).</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* MapNotify */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window event;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool override_redirect;</small></p>
</td>
<td width="40%">
<p><small>/* boolean, is override set... */</small></p>
</td>
</table>
<p><small>} XMapEvent;</small></p>
<p><small>│__</small></p>
<p><small>The event member is set either to the window that
was mapped or to its parent, depending on whether
<i>StructureNotify</i> or <i>SubstructureNotify</i> was
selected. The window member is set to the window that was
mapped. The override_redirect member is set to the
override-redirect attribute of the window. Window manager
clients normally should ignore this window if the
override-redirect attribute is <i>True</i>, because these
events usually are generated from pop-ups, which override
structure control.</small></p>
<a name="10.10.7. MappingNotify Events"></a>
<h2>10.10.7. MappingNotify Events</h2>
<p><small>The X server reports <i>MappingNotify</i> events
to all clients. There is no mechanism to express disinterest
in this event. The X server generates this event type
whenever a client application successfully
calls:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>XSetModifierMapping</i> to indicate which
KeyCodes are to be used as modifiers</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>XChangeKeyboardMapping</i> to change the
keyboard mapping</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>XSetPointerMapping</i> to set the pointer
mapping</small></p>
</td>
<td width="0%">
</td>
</table>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* MappingNotify */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
<p><small>/* unused */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int request;</small></p>
</td>
<td width="40%">
<p><small>/* one of MappingModifier,
MappingKeyboard,</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
</td>
<td width="40%">
<p><small>MappingPointer */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int first_keycode;</small></p>
</td>
<td width="40%">
<p><small>/* first keycode */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int count;</small></p>
</td>
<td width="40%">
<p><small>/* defines range of change w.
first_keycode*/</small></p>
</td>
</table>
<p><small>} XMappingEvent;</small></p>
<p><small>│__</small></p>
<p><small>The request member is set to indicate the kind of
mapping change that occurred and can be
<i>MappingModifier</i>, <i>MappingKeyboard</i>, or
<i>MappingPointer</i>. If it is <i>MappingModifier</i>, the
modifier mapping was changed. If it is
<i>MappingKeyboard</i>, the keyboard mapping was changed. If
it is <i>MappingPointer</i>, the pointer button mapping was
changed. The first_keycode and count members are set only if
the request member was set to <i>MappingKeyboard</i>. The
number in first_keycode represents the first number in the
range of the altered mapping, and count represents the
number of keycodes altered.</small></p>
<p><small>To update the client application’s
knowledge of the keyboard, you should call
<i>XRefreshKeyboardMapping</i>.</small></p>
<a name="10.10.8. ReparentNotify Events"></a>
<h2>10.10.8. ReparentNotify Events</h2>
<p><small>The X server can report <i>ReparentNotify</i>
events to clients wanting information about changing a
window’s parent. The X server generates this event
whenever a client application calls <i>XReparentWindow</i>
and the window is actually reparented.</small></p>
<p><small>To receive <i>ReparentNotify</i> events, set the
<i>StructureNotifyMask</i> bit in the event-mask attribute
of the window or the <i>SubstructureNotifyMask</i> bit in
the event-mask attribute of either the old or the new parent
window (in which case, reparenting any child generates an
event).</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* ReparentNotify */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window event;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window parent;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int x, y;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool override_redirect;</small></p>
</td>
<td width="40%">
</td>
</table>
<p><small>} XReparentEvent;</small></p>
<p><small>│__</small></p>
<p><small>The event member is set either to the reparented
window or to the old or the new parent, depending on whether
<i>StructureNotify</i> or <i>SubstructureNotify</i> was
selected. The window member is set to the window that was
reparented. The parent member is set to the new parent
window. The x and y members are set to the reparented
window’s coordinates relative to the new parent
window’s origin and define the upper-left outer corner
of the reparented window. The override_redirect member is
set to the override-redirect attribute of the window
specified by the window member. Window manager clients
normally should ignore this window if the override_redirect
member is <i>True</i>.</small></p>
<a name="10.10.9. UnmapNotify Events"></a>
<h2>10.10.9. UnmapNotify Events</h2>
<p><small>The X server can report <i>UnmapNotify</i> events
to clients wanting information about which windows are
unmapped. The X server generates this event type whenever a
client application changes the window’s state from
mapped to unmapped.</small></p>
<p><small>To receive <i>UnmapNotify</i> events, set the
<i>StructureNotifyMask</i> bit in the event-mask attribute
of the window or the <i>SubstructureNotifyMask</i> bit in
the event-mask attribute of the parent window (in which
case, unmapping any child window generates an
event).</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* UnmapNotify */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window event;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool from_configure;</small></p>
</td>
<td width="40%">
</td>
</table>
<p><small>} XUnmapEvent;</small></p>
<p><small>│__</small></p>
<p><small>The event member is set either to the unmapped
window or to its parent, depending on whether
<i>StructureNotify</i> or <i>SubstructureNotify</i> was
selected. This is the window used by the X server to report
the event. The window member is set to the window that was
unmapped. The from_configure member is set to <i>True</i> if
the event was generated as a result of a resizing of the
window’s parent when the window itself had a
win_gravity of <i>UnmapGravity</i>.</small></p>
<a name="10.10.10. VisibilityNotify Events"></a>
<h2>10.10.10. VisibilityNotify Events</h2>
<p><small>The X server can report <i>VisibilityNotify</i>
events to clients wanting any change in the visibility of
the specified window. A region of a window is visible if
someone looking at the screen can actually see it. The X
server generates this event whenever the visibility changes
state. However, this event is never generated for windows
whose class is <i>InputOnly</i>.</small></p>
<p><small>All <i>VisibilityNotify</i> events caused by a
hierarchy change are generated after any hierarchy event
(<i>UnmapNotify</i>, <i>MapNotify</i>,
<i>ConfigureNotify</i>, <i>GravityNotify</i>,
<i>CirculateNotify</i>) caused by that change. Any
<i>VisibilityNotify</i> event on a given window is generated
before any <i>Expose</i> events on that window, but it is
not required that all <i>VisibilityNotify</i> events on all
windows be generated before all <i>Expose</i> events on all
windows. The X protocol does not constrain the ordering of
<i>VisibilityNotify</i> events with respect to
<i>FocusOut</i>, <i>EnterNotify</i>, and <i>LeaveNotify</i>
events.</small></p>
<p><small>To receive <i>VisibilityNotify</i> events, set
the <i>VisibilityChangeMask</i> bit in the event-mask
attribute of the window.</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* VisibilityNotify */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int state;</small></p>
</td>
<td width="40%">
</td>
</table>
<p><small>} XVisibilityEvent;</small></p>
<p><small>│__</small></p>
<p><small>The window member is set to the window whose
visibility state changes. The state member is set to the
state of the window’s visibility and can be
<i>VisibilityUnobscured</i>,
<i>VisibilityPartiallyObscured</i>, or
<i>VisibilityFullyObscured</i>. The X server ignores all of
a window’s subwindows when determining the visibility
state of the window and processes <i>VisibilityNotify</i>
events according to the following:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When the window changes state from partially
obscured, fully obscured, or not viewable to viewable and
completely unobscured, the X server generates the event with
the state member of the <i>XVisibilityEvent</i> structure
set to <i>VisibilityUnobscured</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When the window changes state from viewable and
completely unobscured or not viewable to viewable and
partially obscured, the X server generates the event with
the state member of the <i>XVisibilityEvent</i> structure
set to <i>VisibilityPartiallyObscured</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When the window changes state from viewable and
completely unobscured, viewable and partially obscured, or
not viewable to viewable and fully obscured, the X server
generates the event with the state member of the
<i>XVisibilityEvent</i> structure set to
<i>VisibilityFullyObscured</i>.</small></p>
</td>
</table>
<a name="10.11. Structure Control Events"></a>
<h2>10.11. Structure Control Events</h2>
<p><small>This section discusses:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="46%">
<p><small><i>CirculateRequest</i> events</small></p>
</td>
<td width="43%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="46%">
<p><small><i>ConfigureRequest</i> events</small></p>
</td>
<td width="43%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="34%">
<p><small><i>MapRequest</i> events</small></p>
</td>
<td width="55%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="40%">
<p><small><i>ResizeRequest</i> events</small></p>
</td>
<td width="49%">
</td>
</table>
<a name="10.11.1. CirculateRequest Events"></a>
<h2>10.11.1. CirculateRequest Events</h2>
<p><small>The X server can report <i>CirculateRequest</i>
events to clients wanting information about when another
client initiates a circulate window request on a specified
window. The X server generates this event type whenever a
client initiates a circulate window request on a window and
a subwindow actually needs to be restacked. The client
initiates a circulate window request on the window by
calling <i>XCirculateSubwindows</i>,
<i>XCirculateSubwindowsUp</i>, or
<i>XCirculateSubwindowsDown</i>.</small></p>
<p><small>To receive <i>CirculateRequest</i> events, set
the <i>SubstructureRedirectMask</i> in the event-mask
attribute of the window. Then, in the future, the circulate
window request for the specified window is not executed, and
thus, any subwindow’s position in the stack is not
changed. For example, suppose a client application calls
<i>XCirculateSubwindowsUp</i> to raise a subwindow to the
top of the stack. If you had selected
<i>SubstructureRedirectMask</i> on the window, the X server
reports to you a <i>CirculateRequest</i> event and does not
raise the subwindow to the top of the stack.</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* CirculateRequest */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window parent;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int place;</small></p>
</td>
<td width="40%">
<p><small>/* PlaceOnTop, PlaceOnBottom */</small></p>
</td>
</table>
<p><small>} XCirculateRequestEvent;</small></p>
<p><small>│__</small></p>
<p><small>The parent member is set to the parent window.
The window member is set to the subwindow to be restacked.
The place member is set to what the new position in the
stacking order should be and is either <i>PlaceOnTop</i> or
<i>PlaceOnBottom</i>. If it is <i>PlaceOnTop</i>, the
subwindow should be on top of all siblings. If it is
<i>PlaceOnBottom</i>, the subwindow should be below all
siblings.</small></p>
<a name="10.11.2. ConfigureRequest Events"></a>
<h2>10.11.2. ConfigureRequest Events</h2>
<p><small>The X server can report <i>ConfigureRequest</i>
events to clients wanting information about when a different
client initiates a configure window request on any child of
a specified window. The configure window request attempts to
reconfigure a window’s size, position, border, and
stacking order. The X server generates this event whenever a
different client initiates a configure window request on a
window by calling <i>XConfigureWindow</i>,
<i>XLowerWindow</i>, <i>XRaiseWindow</i>, <i>XMapRaised</i>,
<i>XMoveResizeWindow</i>, <i>XMoveWindow</i>,
<i>XResizeWindow</i>, <i>XRestackWindows</i>, or
<i>XSetWindowBorderWidth</i>.</small></p>
<p><small>To receive <i>ConfigureRequest</i> events, set
the <i>SubstructureRedirectMask</i> bit in the event-mask
attribute of the window. <i>ConfigureRequest</i> events are
generated when a <i>ConfigureWindow</i> protocol request is
issued on a child window by another client. For example,
suppose a client application calls <i>XLowerWindow</i> to
lower a window. If you had selected
<i>SubstructureRedirectMask</i> on the parent window and if
the override-redirect attribute of the window is set to
<i>False</i>, the X server reports a <i>ConfigureRequest</i>
event to you and does not lower the specified
window.</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* ConfigureRequest */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window parent;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int x, y;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int width, height;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int border_width;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window above;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int detail;</small></p>
</td>
<td width="40%">
<p><small>/* Above, Below, TopIf, BottomIf, Opposite
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long value_mask;</small></p>
</td>
<td width="40%">
</td>
</table>
<p><small>} XConfigureRequestEvent;</small></p>
<p><small>│__</small></p>
<p><small>The parent member is set to the parent window.
The window member is set to the window whose size, position,
border width, and/or stacking order is to be reconfigured.
The value_mask member indicates which components were
specified in the <i>ConfigureWindow</i> protocol request.
The corresponding values are reported as given in the
request. The remaining values are filled in from the current
geometry of the window, except in the case of above
(sibling) and detail (stack-mode), which are reported as
<i>None</i> and <i>Above</i>, respectively, if they are not
given in the request.</small></p>
<a name="10.11.3. MapRequest Events"></a>
<h2>10.11.3. MapRequest Events</h2>
<p><small>The X server can report <i>MapRequest</i> events
to clients wanting information about a different
client’s desire to map windows. A window is considered
mapped when a map window request completes. The X server
generates this event whenever a different client initiates a
map window request on an unmapped window whose
override_redirect member is set to <i>False</i>. Clients
initiate map window requests by calling <i>XMapWindow</i>,
<i>XMapRaised</i>, or <i>XMapSubwindows</i>.</small></p>
<p><small>To receive <i>MapRequest</i> events, set the
<i>SubstructureRedirectMask</i> bit in the event-mask
attribute of the window. This means another client’s
attempts to map a child window by calling one of the map
window request functions is intercepted, and you are sent a
<i>MapRequest</i> instead. For example, suppose a client
application calls <i>XMapWindow</i> to map a window. If you
(usually a window manager) had selected
<i>SubstructureRedirectMask</i> on the parent window and if
the override-redirect attribute of the window is set to
<i>False</i>, the X server reports a <i>MapRequest</i> event
to you and does not map the specified window. Thus, this
event gives your window manager client the ability to
control the placement of subwindows.</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* MapRequest */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window parent;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
</td>
</table>
<p><small>} XMapRequestEvent;</small></p>
<p><small>│__</small></p>
<p><small>The parent member is set to the parent window.
The window member is set to the window to be
mapped.</small></p>
<a name="10.11.4. ResizeRequest Events"></a>
<h2>10.11.4. ResizeRequest Events</h2>
<p><small>The X server can report <i>ResizeRequest</i>
events to clients wanting information about another
client’s attempts to change the size of a window. The
X server generates this event whenever some other client
attempts to change the size of the specified window by
calling <i>XConfigureWindow</i>, <i>XResizeWindow</i>, or
<i>XMoveResizeWindow</i>.</small></p>
<p><small>To receive <i>ResizeRequest</i> events, set the
<i>ResizeRedirect</i> bit in the event-mask attribute of the
window. Any attempts to change the size by other clients are
then redirected.</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* ResizeRequest */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int width, height;</small></p>
</td>
<td width="40%">
</td>
</table>
<p><small>} XResizeRequestEvent;</small></p>
<p><small>│__</small></p>
<p><small>The window member is set to the window whose size
another client attempted to change. The width and height
members are set to the inside size of the window, excluding
the border.</small></p>
<a name="10.12. Colormap State Change Events"></a>
<h2>10.12. Colormap State Change Events</h2>
<p><small>The X server can report <i>ColormapNotify</i>
events to clients wanting information about when the
colormap changes and when a colormap is installed or
uninstalled. The X server generates this event type whenever
a client application:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Changes the colormap member of the
<i>XSetWindowAttributes</i> structure by calling
<i>XChangeWindowAttributes</i>, <i>XFreeColormap</i>, or
<i>XSetWindowColormap</i></small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Installs or uninstalls the colormap by calling
<i>XInstallColormap</i> or
<i>XUninstallColormap</i></small></p>
</td>
</table>
<p><small>To receive <i>ColormapNotify</i> events, set the
<i>ColormapChangeMask</i> bit in the event-mask attribute of
the window.</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* ColormapNotify */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Colormap colormap;</small></p>
</td>
<td width="40%">
<p><small>/* colormap or None */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool new;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int state;</small></p>
</td>
<td width="40%">
<p><small>/* ColormapInstalled, ColormapUninstalled
*/</small></p>
</td>
</table>
<p><small>} XColormapEvent;</small></p>
<p><small>│__</small></p>
<p><small>The window member is set to the window whose
associated colormap is changed, installed, or uninstalled.
For a colormap that is changed, installed, or uninstalled,
the colormap member is set to the colormap associated with
the window. For a colormap that is changed by a call to
<i>XFreeColormap</i>, the colormap member is set to
<i>None</i>. The new member is set to indicate whether the
colormap for the specified window was changed or installed
or uninstalled and can be <i>True</i> or <i>False</i>. If it
is <i>True</i>, the colormap was changed. If it is
<i>False</i>, the colormap was installed or uninstalled. The
state member is always set to indicate whether the colormap
is installed or uninstalled and can be
<i>ColormapInstalled</i> or
<i>ColormapUninstalled</i>.</small></p>
<a name="10.13. Client Communication Events"></a>
<h2>10.13. Client Communication Events</h2>
<p><small>This section discusses:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="40%">
<p><small><i>ClientMessage</i> events</small></p>
</td>
<td width="49%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small><i>PropertyNotify</i> events</small></p>
</td>
<td width="47%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small><i>SelectionClear</i> events</small></p>
</td>
<td width="47%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="44%">
<p><small><i>SelectionNotify</i> events</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="46%">
<p><small><i>SelectionRequest</i> events</small></p>
</td>
<td width="43%">
</td>
</table>
<a name="10.13.1. ClientMessage Events"></a>
<h2>10.13.1. ClientMessage Events</h2>
<p><small>The X server generates <i>ClientMessage</i>
events only when a client calls the function
<i>XSendEvent</i>.</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>int type;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
<p><small>/* ClientMessage */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>Display *display;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>Window window;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>Atom message_type;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>int format;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>union {</small></p>
</td>
<td width="40%"></td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
</td>
<td width="40%">
<p><small>char b[20];</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
</td>
<td width="40%">
<p><small>short s[10];</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
</td>
<td width="40%">
<p><small>long l[5];</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>} data;</small></p>
</td>
<td width="40%"></td>
<td width="40%">
</td>
</table>
<p><small>} XClientMessageEvent;</small></p>
<p><small>│__</small></p>
<p><small>The message_type member is set to an atom that
indicates how the data should be interpreted by the
receiving client. The format member is set to 8, 16, or 32
and specifies whether the data should be viewed as a list of
bytes, shorts, or longs. The data member is a union that
contains the members b, s, and l. The b, s, and l members
represent data of twenty 8-bit values, ten 16-bit values,
and five 32-bit values. Particular message types might not
make use of all these values. The X server places no
interpretation on the values in the window, message_type, or
data members.</small></p>
<a name="10.13.2. PropertyNotify Events"></a>
<h2>10.13.2. PropertyNotify Events</h2>
<p><small>The X server can report <i>PropertyNotify</i>
events to clients wanting information about property changes
for a specified window.</small></p>
<p><small>To receive <i>PropertyNotify</i> events, set the
<i>PropertyChangeMask</i> bit in the event-mask attribute of
the window.</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* PropertyNotify */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Atom atom;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Time time;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int state;</small></p>
</td>
<td width="40%">
<p><small>/* PropertyNewValue or PropertyDelete
*/</small></p>
</td>
</table>
<p><small>} XPropertyEvent;</small></p>
<p><small>│__</small></p>
<p><small>The window member is set to the window whose
associated property was changed. The atom member is set to
the property’s atom and indicates which property was
changed or desired. The time member is set to the server
time when the property was changed. The state member is set
to indicate whether the property was changed to a new value
or deleted and can be <i>PropertyNewValue</i> or
<i>PropertyDelete</i>. The state member is set to
<i>PropertyNewValue</i> when a property of the window is
changed using <i>XChangeProperty</i> or
<i>XRotateWindowProperties</i> (even when adding zero-length
data using <i>XChangeProperty</i>) and when replacing all or
part of a property with identical data using
<i>XChangeProperty</i> or <i>XRotateWindowProperties</i>.
The state member is set to <i>PropertyDelete</i> when a
property of the window is deleted using
<i>XDeleteProperty</i> or, if the delete argument is
<i>True</i>, <i>XGetWindowProperty</i>.</small></p>
<a name="10.13.3. SelectionClear Events"></a>
<h2>10.13.3. SelectionClear Events</h2>
<p><small>The X server reports <i>SelectionClear</i> events
to the client losing ownership of a selection. The X server
generates this event type when another client asserts
ownership of the selection by calling
<i>XSetSelectionOwner</i>.</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* SelectionClear */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window window;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Atom selection;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Time time;</small></p>
</td>
<td width="40%">
</td>
</table>
<p><small>} XSelectionClearEvent;</small></p>
<p><small>│__</small></p>
<p><small>The selection member is set to the selection
atom. The time member is set to the last change time
recorded for the selection. The window member is the window
that was specified by the current owner (the owner losing
the selection) in its <i>XSetSelectionOwner</i>
call.</small></p>
<a name="10.13.4. SelectionRequest Events"></a>
<h2>10.13.4. SelectionRequest Events</h2>
<p><small>The X server reports <i>SelectionRequest</i>
events to the owner of a selection. The X server generates
this event whenever a client requests a selection conversion
by calling <i>XConvertSelection</i> for the owned
selection.</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* SelectionRequest */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window owner;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window requestor;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Atom selection;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Atom target;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Atom property;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Time time;</small></p>
</td>
<td width="40%">
</td>
</table>
<p><small>} XSelectionRequestEvent;</small></p>
<p><small>│__</small></p>
<p><small>The owner member is set to the window that was
specified by the current owner in its
<i>XSetSelectionOwner</i> call. The requestor member is set
to the window requesting the selection. The selection member
is set to the atom that names the selection. For example,
PRIMARY is used to indicate the primary selection. The
target member is set to the atom that indicates the type the
selection is desired in. The property member can be a
property name or <i>None</i>. The time member is set to the
timestamp or <i>CurrentTime</i> value from the
<i>ConvertSelection</i> request.</small></p>
<p><small>The owner should convert the selection based on
the specified target type and send a <i>SelectionNotify</i>
event back to the requestor. A complete specification for
using selections is given in the X Consortium standard
<i>Inter-Client Communication Conventions
Manual</i>.</small></p>
<a name="10.13.5. SelectionNotify Events"></a>
<h2>10.13.5. SelectionNotify Events</h2>
<p><small>This event is generated by the X server in
response to a <i>ConvertSelection</i> protocol request when
there is no owner for the selection. When there is an owner,
it should be generated by the owner of the selection by
using <i>XSendEvent</i>. The owner of a selection should
send this event to a requestor when a selection has been
converted and stored as a property or when a selection
conversion could not be performed (which is indicated by
setting the property member to <i>None</i>).</small></p>
<p><small>If <i>None</i> is specified as the property in
the <i>ConvertSelection</i> protocol request, the owner
should choose a property name, store the result as that
property on the requestor window, and then send a
<i>SelectionNotify</i> giving that actual property
name.</small></p>
<p><small>The structure for this event type
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int type;</small></p>
</td>
<td width="40%">
<p><small>/* SelectionNotify */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long serial;</small></p>
</td>
<td width="40%">
<p><small>/* # of last request processed by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Bool send_event;</small></p>
</td>
<td width="40%">
<p><small>/* true if this came from a SendEvent request
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *display;</small></p>
</td>
<td width="40%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Window requestor;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Atom selection;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Atom target;</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Atom property;</small></p>
</td>
<td width="40%">
<p><small>/* atom or None */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Time time;</small></p>
</td>
<td width="40%">
</td>
</table>
<p><small>} XSelectionEvent;</small></p>
<p><small>│__</small></p>
<p><small>The requestor member is set to the window
associated with the requestor of the selection. The
selection member is set to the atom that indicates the
selection. For example, PRIMARY is used for the primary
selection. The target member is set to the atom that
indicates the converted type. For example, PIXMAP is used
for a pixmap. The property member is set to the atom that
indicates which property the result was stored on. If the
conversion failed, the property member is set to
<i>None</i>. The time member is set to the time the
conversion took place and can be a timestamp or
<i>CurrentTime</i>.</small></p>
<p><small><b>10</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b>Chapter 11</b></p>
<p align=center><b>Event Handling Functions</b></p>
<p><small>This chapter discusses the Xlib functions you can
use to:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="26%">
<p><small>Select events</small></p>
</td>
<td width="63%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="88%">
<p><small>Handle the output buffer and the event
queue</small></p>
</td>
<td width="1%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="68%">
<p><small>Select events from the event queue</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="38%">
<p><small>Send and get events</small></p>
</td>
<td width="51%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="44%">
<p><small>Handle protocol errors</small></p>
</td>
<td width="45%">
</td>
</table>
<p align=center><small>Note</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>Some toolkits use their own event-handling
functions and do not allow you to interchange these
event-handling functions with those in Xlib. For further
information, see the documentation supplied with the
toolkit.</small></p>
</td>
</table>
<p><small>Most applications simply are event loops: they
wait for an event, decide what to do with it, execute some
amount of code that results in changes to the display, and
then wait for the next event.</small></p>
<a name="11.1. Selecting Events"></a>
<h2>11.1. Selecting Events</h2>
<p><small>There are two ways to select the events you want
reported to your client application. One way is to set the
event_mask member of the <i>XSetWindowAttributes</i>
structure when you call <i>XCreateWindow</i> and
<i>XChangeWindowAttributes</i>. Another way is to use
<i>XSelectInput</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSelectInput(<i>display</i>, <i>w</i>, <i>event_mask</i>)
Display *<i>display</i>;
Window <i>w</i>;
long <i>event_mask</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the window whose events you are
interested in.</small></p>
</td>
</table>
<p><small><i>event_mask</i> Specifies the event
mask.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XSelectInput</i> function requests that
the X server report the events associated with the specified
event mask. Initially, X will not report any of these
events. Events are reported relative to a window. If a
window is not interested in a device event, it usually
propagates to the closest ancestor that is interested,
unless the do_not_propagate mask prohibits it.</small></p>
<p><small>Setting the event-mask attribute of a window
overrides any previous call for the same window but not for
other clients. Multiple clients can select for the same
events on the same window with the following
restrictions:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Multiple clients can select events on the same
window because their event masks are disjoint. When the X
server generates an event, it reports it to all interested
clients.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Only one client at a time can select
<i>CirculateRequest</i>, <i>ConfigureRequest</i>, or
<i>MapRequest</i> events, which are associated with the
event mask <i>SubstructureRedirectMask</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Only one client at a time can select a
<i>ResizeRequest</i> event, which is associated with the
event mask <i>ResizeRedirectMask</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Only one client at a time can select a
<i>ButtonPress</i> event, which is associated with the event
mask <i>ButtonPressMask</i>.</small></p>
</td>
</table>
<p><small>The server reports the event to all interested
clients.</small></p>
<p><small><i>XSelectInput</i> can generate a
<i>BadWindow</i> error.</small></p>
<a name="11.2. Handling the Output Buffer"></a>
<h2>11.2. Handling the Output Buffer</h2>
<p><small>The output buffer is an area used by Xlib to
store requests. The functions described in this section
flush the output buffer if the function would block or not
return an event. That is, all requests residing in the
output buffer that have not yet been sent are transmitted to
the X server. These functions differ in the additional tasks
they might perform.</small></p>
<p><small>To flush the output buffer, use
<i>XFlush</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XFlush(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XFlush</i> 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 <i>XPending</i>, <i>XNextEvent</i>, and
<i>XWindowEvent</i>. Events generated by the server may be
enqueued into the library’s event queue.</small></p>
<p><small>To flush the output buffer and then wait until
all requests have been processed, use
<i>XSync</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSync(<i>display</i>, <i>discard</i>)
Display *<i>display</i>;
Bool <i>discard</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>discard</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies a Boolean value that indicates whether
<i>XSync</i> discards all events on the event
queue.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSync</i> function flushes the output
buffer and then waits until all requests have been received
and processed by the X server. Any errors generated must be
handled by the error handler. For each protocol error
received by Xlib, <i>XSync</i> calls the client
application’s error handling routine (see section
11.8.2). Any events generated by the server are enqueued
into the library’s event queue.</small></p>
<p><small>Finally, if you passed <i>False</i>, <i>XSync</i>
does not discard the events in the queue. If you passed
<i>True</i>, <i>XSync</i> discards all events in the queue,
including those events that were on the queue before
<i>XSync</i> was called. Client applications seldom need to
call <i>XSync</i>.</small></p>
<a name="11.3. Event Queue Management"></a>
<h2>11.3. Event Queue Management</h2>
<p><small>Xlib maintains an event queue. However, the
operating system also may be buffering data in its network
connection that is not yet read into the event
queue.</small></p>
<p><small>To check the number of events in the event queue,
use <i>XEventsQueued</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XEventsQueued(<i>display</i>, <i>mode</i>)
Display *<i>display</i>;
int <i>mode</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>mode</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the mode. You can pass
<i>QueuedAlready</i>, <i>QueuedAfterFlush</i>, or
<i>QueuedAfterReading</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>If mode is <i>QueuedAlready</i>,
<i>XEventsQueued</i> returns the number of events already in
the event queue (and never performs a system call). If mode
is <i>QueuedAfterFlush</i>, <i>XEventsQueued</i> returns the
number of events already in the queue if the number is
nonzero. If there are no events in the queue,
<i>XEventsQueued</i> flushes the output buffer, attempts to
read more events out of the application’s connection,
and returns the number read. If mode is
<i>QueuedAfterReading</i>, <i>XEventsQueued</i> returns the
number of events already in the queue if the number is
nonzero. If there are no events in the queue,
<i>XEventsQueued</i> attempts to read more events out of the
application’s connection without flushing the output
buffer and returns the number read.</small></p>
<p><small><i>XEventsQueued</i> always returns immediately
without I/O if there are events already in the queue.
<i>XEventsQueued</i> with mode <i>QueuedAfterFlush</i> is
identical in behavior to <i>XPending</i>.
<i>XEventsQueued</i> with mode <i>QueuedAlready</i> is
identical to the <i>XQLength</i> function.</small></p>
<p><small>To return the number of events that are pending,
use <i>XPending</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XPending(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XPending</i> function returns the number
of events that have been received from the X server but have
not been removed from the event queue. <i>XPending</i> is
identical to <i>XEventsQueued</i> with the mode
<i>QueuedAfterFlush</i> specified.</small></p>
<a name="11.4. Manipulating the Event Queue"></a>
<h2>11.4. Manipulating the Event Queue</h2>
<p><small>Xlib provides functions that let you manipulate
the event queue. This section discusses how to:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Obtain events, in order, and remove them from the
queue</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Peek at events in the queue without removing
them</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Obtain events that match the event mask or the
arbitrary predicate procedures that you provide</small></p>
</td>
</table>
<a name="11.4.1. Returning the Next Event"></a>
<h2>11.4.1. Returning the Next Event</h2>
<p><small>To get the next event and remove it from the
queue, use <i>XNextEvent</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XNextEvent(<i>display</i>, <i>event_return</i>)
Display *<i>display</i>;
XEvent *<i>event_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>event_return</i> Returns the next event in the
queue.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XNextEvent</i> function copies the first
event from the event queue into the specified <i>XEvent</i>
structure and then removes it from the queue. If the event
queue is empty, <i>XNextEvent</i> flushes the output buffer
and blocks until an event is received.</small></p>
<p><small>To peek at the event queue, use
<i>XPeekEvent</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XPeekEvent(<i>display</i>, <i>event_return</i>)
Display *<i>display</i>;
XEvent *<i>event_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>event_return</i> Returns a copy of the matched
event’s associated structure.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XPeekEvent</i> function returns the first
event from the event queue, but it does not remove the event
from the queue. If the queue is empty, <i>XPeekEvent</i>
flushes the output buffer and blocks until an event is
received. It then copies the event into the client-supplied
<i>XEvent</i> structure without removing it from the event
queue.</small></p>
<a name="11.4.2. Selecting Events Using a Predicate Procedure"></a>
<h2>11.4.2. Selecting Events Using a Predicate Procedure</h2>
<p><small>Each of the functions discussed in this section
requires you to pass a predicate procedure that determines
if an event matches what you want. Your predicate procedure
must decide if the event is useful without calling any Xlib
functions. If the predicate directly or indirectly causes
the state of the event queue to change, the result is not
defined. If Xlib has been initialized for threads, the
predicate is called with the display locked and the result
of a call by the predicate to any Xlib function that locks
the display is not defined unless the caller has first
called <i>XLockDisplay</i>.</small></p>
<p><small>The predicate procedure and its associated
arguments are:</small></p>
<p><small>__ │</small></p>
<pre><small>Bool (*<i>predicate</i>)(<i>display</i>, <i>event</i>, <i>arg</i>)
Display *<i>display</i>;
XEvent *<i>event</i>;
XPointer <i>arg</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>event</i></small></p>
</td>
<td width="10%"></td>
<td width="62%">
<p><small>Specifies the <i>XEvent</i>
structure.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>arg</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the argument passed in from the
<i>XIfEvent</i>, <i>XCheckIfEvent</i>, or
<i>XPeekIfEvent</i> function.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The predicate procedure is called once for each
event in the queue until it finds a match. After finding a
match, the predicate procedure must return <i>True</i>. If
it did not find a match, it must return
<i>False</i>.</small></p>
<p><small>To check the event queue for a matching event
and, if found, remove the event from the queue, use
<i>XIfEvent</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XIfEvent(<i>display</i>, <i>event_return</i>, <i>predicate</i>, <i>arg</i>)
Display *<i>display</i>;
XEvent *<i>event_return</i>;
Bool (*<i>predicate</i>)();
XPointer <i>arg</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>event_return</i> Returns the matched
event’s associated structure.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>predicate</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the procedure that is to be called to
determine if the next event in the queue matches what you
want.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>arg</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the user-supplied argument that will be
passed to the predicate procedure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XIfEvent</i> function completes only when
the specified predicate procedure returns <i>True</i> for an
event, which indicates an event in the queue matches.
<i>XIfEvent</i> flushes the output buffer if it blocks
waiting for additional events. <i>XIfEvent</i> removes the
matching event from the queue and copies the structure into
the client-supplied <i>XEvent</i> structure.</small></p>
<p><small>To check the event queue for a matching event
without blocking, use <i>XCheckIfEvent</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XCheckIfEvent(<i>display</i>, <i>event_return</i>, <i>predicate</i>, <i>arg</i>)
Display *<i>display</i>;
XEvent *<i>event_return</i>;
Bool (*<i>predicate</i>)();
XPointer <i>arg</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>event_return</i> Returns a copy of the matched
event’s associated structure.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>predicate</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the procedure that is to be called to
determine if the next event in the queue matches what you
want.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>arg</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the user-supplied argument that will be
passed to the predicate procedure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>When the predicate procedure finds a match,
<i>XCheckIfEvent</i> copies the matched event into the
client-supplied <i>XEvent</i> structure and returns
<i>True</i>. (This event is removed from the queue.) If the
predicate procedure finds no match, <i>XCheckIfEvent</i>
returns <i>False</i>, and the output buffer will have been
flushed. All earlier events stored in the queue are not
discarded.</small></p>
<p><small>To check the event queue for a matching event
without removing the event from the queue, use
<i>XPeekIfEvent</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XPeekIfEvent(<i>display</i>, <i>event_return</i>, <i>predicate</i>, <i>arg</i>)
Display *<i>display</i>;
XEvent *<i>event_return</i>;
Bool (*<i>predicate</i>)();
XPointer <i>arg</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>event_return</i> Returns a copy of the matched
event’s associated structure.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>predicate</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the procedure that is to be called to
determine if the next event in the queue matches what you
want.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>arg</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the user-supplied argument that will be
passed to the predicate procedure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XPeekIfEvent</i> function returns only
when the specified predicate procedure returns <i>True</i>
for an event. After the predicate procedure finds a match,
<i>XPeekIfEvent</i> copies the matched event into the
client-supplied <i>XEvent</i> structure without removing the
event from the queue. <i>XPeekIfEvent</i> flushes the output
buffer if it blocks waiting for additional
events.</small></p>
<a name="11.4.3. Selecting Events Using a Window or Event Mask"></a>
<h2>11.4.3. Selecting Events Using a Window or Event Mask</h2>
<p><small>The functions discussed in this section let you
select events by window or event types, allowing you to
process events out of order.</small></p>
<p><small>To remove the next event that matches both a
window and an event mask, use
<i>XWindowEvent</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XWindowEvent(<i>display</i>, <i>w</i>, <i>event_mask</i>, <i>event_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
long <i>event_mask</i>;
XEvent *<i>event_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the window whose events you are
interested in.</small></p>
</td>
</table>
<p><small><i>event_mask</i> Specifies the event
mask.</small></p>
<p><small><i>event_return</i> Returns the matched
event’s associated structure.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XWindowEvent</i> function searches the
event queue for an event that matches both the specified
window and event mask. When it finds a match,
<i>XWindowEvent</i> removes that event from the queue and
copies it into the specified <i>XEvent</i> structure. The
other events stored in the queue are not discarded. If a
matching event is not in the queue, <i>XWindowEvent</i>
flushes the output buffer and blocks until one is
received.</small></p>
<p><small>To remove the next event that matches both a
window and an event mask (if any), use
<i>XCheckWindowEvent</i>. This function is similar to
<i>XWindowEvent</i> except that it never blocks and it
returns a <i>Bool</i> indicating if the event was
returned.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XCheckWindowEvent(<i>display</i>, <i>w</i>, <i>event_mask</i>, <i>event_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
long <i>event_mask</i>;
XEvent *<i>event_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the window whose events you are
interested in.</small></p>
</td>
</table>
<p><small><i>event_mask</i> Specifies the event
mask.</small></p>
<p><small><i>event_return</i> Returns the matched
event’s associated structure.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XCheckWindowEvent</i> 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,
<i>XCheckWindowEvent</i> removes that event, copies it into
the specified <i>XEvent</i> structure, and returns
<i>True</i>. The other events stored in the queue are not
discarded. If the event you requested is not available,
<i>XCheckWindowEvent</i> returns <i>False</i>, and the
output buffer will have been flushed.</small></p>
<p><small>To remove the next event that matches an event
mask, use <i>XMaskEvent</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XMaskEvent(<i>display</i>, <i>event_mask</i>, <i>event_return</i>)
Display *<i>display</i>;
long <i>event_mask</i>;
XEvent *<i>event_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>event_mask</i> Specifies the event
mask.</small></p>
<p><small><i>event_return</i> Returns the matched
event’s associated structure.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XMaskEvent</i> function searches the event
queue for the events associated with the specified mask.
When it finds a match, <i>XMaskEvent</i> removes that event
and copies it into the specified <i>XEvent</i> structure.
The other events stored in the queue are not discarded. If
the event you requested is not in the queue,
<i>XMaskEvent</i> flushes the output buffer and blocks until
one is received.</small></p>
<p><small>To return and remove the next event that matches
an event mask (if any), use <i>XCheckMaskEvent</i>. This
function is similar to <i>XMaskEvent</i> except that it
never blocks and it returns a <i>Bool</i> indicating if the
event was returned.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XCheckMaskEvent(<i>display</i>, <i>event_mask</i>, <i>event_return</i>)
Display *<i>display</i>;
long <i>event_mask</i>;
XEvent *<i>event_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>event_mask</i> Specifies the event
mask.</small></p>
<p><small><i>event_return</i> Returns the matched
event’s associated structure.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XCheckMaskEvent</i> 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, <i>XCheckMaskEvent</i> removes
that event, copies it into the specified <i>XEvent</i>
structure, and returns <i>True</i>. The other events stored
in the queue are not discarded. If the event you requested
is not available, <i>XCheckMaskEvent</i> returns
<i>False</i>, and the output buffer will have been
flushed.</small></p>
<p><small>To return and remove the next event in the queue
that matches an event type, use
<i>XCheckTypedEvent</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XCheckTypedEvent(<i>display</i>, <i>event_type</i>, <i>event_return</i>)
Display *<i>display</i>;
int <i>event_type</i>;
XEvent *<i>event_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>event_type</i> Specifies the event type to be
compared.</small></p>
<p><small><i>event_return</i> Returns the matched
event’s associated structure.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XCheckTypedEvent</i> 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, <i>XCheckTypedEvent</i> removes
that event, copies it into the specified <i>XEvent</i>
structure, and returns <i>True</i>. The other events in the
queue are not discarded. If the event is not available,
<i>XCheckTypedEvent</i> returns <i>False</i>, and the output
buffer will have been flushed.</small></p>
<p><small>To return and remove the next event in the queue
that matches an event type and a window, use
<i>XCheckTypedWindowEvent</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XCheckTypedWindowEvent(<i>display</i>, <i>w</i>, <i>event_type</i>, <i>event_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
int <i>event_type</i>;
XEvent *<i>event_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>event_type</i> Specifies the event type to be
compared.</small></p>
<p><small><i>event_return</i> Returns the matched
event’s associated structure.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XCheckTypedWindowEvent</i> 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,
<i>XCheckTypedWindowEvent</i> removes the event from the
queue, copies it into the specified <i>XEvent</i> structure,
and returns <i>True</i>. The other events in the queue are
not discarded. If the event is not available,
<i>XCheckTypedWindowEvent</i> returns <i>False</i>, and the
output buffer will have been flushed.</small></p>
<a name="11.5. Putting an Event Back into the Queue"></a>
<h2>11.5. Putting an Event Back into the Queue</h2>
<p><small>To push an event back into the event queue, use
<i>XPutBackEvent</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XPutBackEvent(<i>display</i>, <i>event</i>)
Display *<i>display</i>;
XEvent *<i>event</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>event</i></small></p>
</td>
<td width="10%"></td>
<td width="40%">
<p><small>Specifies the event.</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XPutBackEvent</i> function pushes an event
back onto the head of the display’s event queue by
copying the event into the queue. This can be useful if you
read an event and then decide that you would rather deal
with it later. There is no limit to the number of times in
succession that you can call
<i>XPutBackEvent</i>.</small></p>
<a name="11.6. Sending Events to Other Applications"></a>
<h2>11.6. Sending Events to Other Applications</h2>
<p><small>To send an event to a specified window, use
<i>XSendEvent</i>. This function is often used in selection
processing. For example, the owner of a selection should use
<i>XSendEvent</i> to send a <i>SelectionNotify</i> event to
a requestor when a selection has been converted and stored
as a property.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XSendEvent(<i>display</i>, <i>w</i>, <i>propagate</i>, <i>event_mask</i>, <i>event_send</i>)
Display *<i>display</i>;
Window <i>w</i>;
Bool <i>propagate</i>;
long <i>event_mask</i>;
XEvent *<i>event_send</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the window the event is to be sent to,
or <i>PointerWindow</i>, or <i>InputFocus</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>propagate</i></small></p>
</td>
<td width="2%"></td>
<td width="52%">
<p><small>Specifies a Boolean value.</small></p>
</td>
<td width="27%">
</td>
</table>
<p><small><i>event_mask</i> Specifies the event
mask.</small></p>
<p><small><i>event_send</i> Specifies the event that is to
be sent.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XSendEvent</i> function identifies the
destination window, determines which clients should receive
the specified events, and ignores any active grabs. This
function requires you to pass an event mask. For a
discussion of the valid event mask names, see section 10.3.
This function uses the w argument to identify the
destination window as follows:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If w is <i>PointerWindow</i>, the destination
window is the window that contains the pointer.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If w is <i>InputFocus</i> and if the focus window
contains the pointer, the destination window is the window
that contains the pointer; otherwise, the destination window
is the focus window.</small></p>
</td>
</table>
<p><small>To determine which clients should receive the
specified events, <i>XSendEvent</i> uses the propagate
argument as follows:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If event_mask is the empty set, the event is sent
to the client that created the destination window. If that
client no longer exists, no event is sent.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If propagate is <i>False</i>, the event is sent
to every client selecting on destination any of the event
types in the event_mask argument.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If propagate is <i>True</i> and no clients have
selected on destination any of the event types in
event-mask, the destination is replaced with the closest
ancestor of destination for which some client has selected a
type in event-mask and for which no intervening window has
that type in its do-not-propagate-mask. If no such window
exists or if the window is an ancestor of the focus window
and <i>InputFocus</i> was originally specified as the
destination, the event is not sent to any clients.
Otherwise, the event is reported to every client selecting
on the final destination any of the types specified in
event_mask.</small></p>
</td>
</table>
<p><small>The event in the <i>XEvent</i> structure must be
one of the core events or one of the events defined by an
extension (or a <i>BadValue</i> error results) so that the X
server can correctly byte-swap the contents as necessary.
The contents of the event are otherwise unaltered and
unchecked by the X server except to force send_event to
<i>True</i> in the forwarded event and to set the serial
number in the event correctly; therefore these fields and
the display field are ignored by
<i>XSendEvent</i>.</small></p>
<p><small><i>XSendEvent</i> returns zero if the conversion
to wire protocol format failed and returns nonzero
otherwise.</small></p>
<p><small><i>XSendEvent</i> can generate <i>BadValue</i>
and <i>BadWindow</i> errors.</small></p>
<a name="11.7. Getting Pointer Motion History"></a>
<h2>11.7. Getting Pointer Motion History</h2>
<p><small>Some X server implementations will maintain a
more complete history of pointer motion than is reported by
event notification. The pointer position at each pointer
hardware interrupt may be stored in a buffer for later
retrieval. This buffer is called the motion history buffer.
For example, a few applications, such as paint programs,
want to have a precise history of where the pointer
traveled. However, this historical information is highly
excessive for most applications.</small></p>
<p><small>To determine the approximate maximum number of
elements in the motion buffer, use
<i>XDisplayMotionBufferSize</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>unsigned long XDisplayMotionBufferSize(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The server may retain the recent history of the
pointer motion and do so to a finer granularity than is
reported by <i>MotionNotify</i> events. The
<i>XGetMotionEvents</i> function makes this history
available.</small></p>
<p><small>To get the motion history for a specified window
and time, use <i>XGetMotionEvents</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XTimeCoord *XGetMotionEvents(<i>display</i>, <i>w</i>, <i>start</i>, <i>stop</i>, <i>nevents_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<p><small>Time <i>start</i>, <i>stop</i>;</small></p>
</table>
<p><small>int *<i>nevents_return</i>;</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>start</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>stop</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specify the time interval in which the events are
returned from the motion history buffer. You can pass a
timestamp or <i>CurrentTime</i>.</small></p>
</td>
</table>
<p><small><i>nevents_return</i> Returns the number of
events from the motion history buffer.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetMotionEvents</i> function returns all
events in the motion history buffer that fall between the
specified start and stop times, inclusive, and that have
coordinates that lie within the specified window (including
its borders) at its present placement. If the server does
not support motion history, if the start time is later than
the stop time, or if the start time is in the future, no
events are returned; <i>XGetMotionEvents</i> returns NULL.
If the stop time is in the future, it is equivalent to
specifying <i>CurrentTime</i>. The return type for this
function is a structure defined as follows:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>Time time;</small></p>
</td>
<td width="79%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>short x, y;</small></p>
</td>
<td width="79%">
</td>
</table>
<p><small>} XTimeCoord;</small></p>
<p><small>│__</small></p>
<p><small>The time member is set to the time, in
milliseconds. The x and y members are set to the coordinates
of the pointer and are reported relative to the origin of
the specified window. To free the data returned from this
call, use <i>XFree</i>.</small></p>
<p><small><i>XGetMotionEvents</i> can generate a
<i>BadWindow</i> error.</small></p>
<a name="11.8. Handling Protocol Errors"></a>
<h2>11.8. Handling Protocol Errors</h2>
<p><small>Xlib provides functions that you can use to
enable or disable synchronization and to use the default
error handlers.</small></p>
<a name="11.8.1. Enabling or Disabling Synchronization"></a>
<h2>11.8.1. Enabling or Disabling Synchronization</h2>
<p><small>When debugging X applications, it often is very
convenient to require Xlib to behave synchronously so that
errors are reported as they occur. The following function
lets you disable or enable synchronous behavior. Note that
graphics may occur 30 or more times more slowly when
synchronization is enabled. On POSIX-conformant systems,
there is also a global variable <i>_Xdebug</i> that, if set
to nonzero before starting a program under a debugger, will
force synchronous library behavior.</small></p>
<p><small>After completing their work, all Xlib functions
that generate protocol requests call what is known as an
after function. <i>XSetAfterFunction</i> sets which function
is to be called.</small></p>
<p><small>__ │</small></p>
<pre><small>int (*XSetAfterFunction(<i>display</i>, <i>procedure</i>))()
Display *<i>display</i>;
int (*<i>procedure</i>)();
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>procedure</i></small></p>
</td>
<td width="2%"></td>
<td width="74%">
<p><small>Specifies the procedure to be called.</small></p>
</td>
<td width="5%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The specified procedure is called with only a
display pointer. <i>XSetAfterFunction</i> returns the
previous after function.</small></p>
<p><small>To enable or disable synchronization, use
<i>XSynchronize</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int (*XSynchronize(<i>display</i>, <i>onoff</i>))()
Display *<i>display</i>;
Bool <i>onoff</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>onoff</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies a Boolean value that indicates whether
to enable or disable synchronization.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSynchronize</i> function returns the
previous after function. If onoff is <i>True</i>,
<i>XSynchronize</i> turns on synchronous behavior. If onoff
is <i>False</i>, <i>XSynchronize</i> turns off synchronous
behavior.</small></p>
<a name="11.8.2. Using the Default Error Handlers"></a>
<h2>11.8.2. Using the Default Error Handlers</h2>
<p><small>There are two default error handlers in Xlib: one
to handle typically fatal conditions (for example, the
connection to a display server dying because a machine
crashed) and one to handle protocol errors from the X
server. These error handlers can be changed to user-supplied
routines if you prefer your own error handling and can be
changed as often as you like. If either function is passed a
NULL pointer, it will reinvoke the default handler. The
action of the default handlers is to print an explanatory
message and exit.</small></p>
<p><small>To set the error handler, use
<i>XSetErrorHandler</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int (*XSetErrorHandler(<i>handler</i>))()
int (*<i>handler</i>)(Display *, XErrorEvent *)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>handler</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the program’s supplied error
handler.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Xlib generally calls the program’s supplied
error handler whenever an error is received. It is not
called on <i>BadName</i> errors from <i>OpenFont</i>,
<i>LookupColor</i>, or <i>AllocNamedColor</i> protocol
requests or on <i>BadFont</i> errors from a <i>QueryFont</i>
protocol request. These errors generally are reflected back
to the program through the procedural interface. Because
this condition is not assumed to be fatal, it is acceptable
for your error handler to return; the returned value is
ignored. However, the error handler should not call any
functions (directly or indirectly) on the display that will
generate protocol requests or that will look for input
events. The previous error handler is returned.</small></p>
<p><small>The <i>XErrorEvent</i> structure
contains:</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int type;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>Display *display;</small></p>
</td>
<td width="50%">
<p><small>/* Display the event was read from */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned long serial;/* serial number of failed
request */</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned char error_code;/* error code of failed
request */</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned char request_code;/* Major op-code of
failed request */</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned char minor_code;/* Minor op-code of
failed request */</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XID resourceid;</small></p>
</td>
<td width="50%">
<p><small>/* resource id */</small></p>
</td>
</table>
<p><small>} XErrorEvent;</small></p>
<p><small>The serial member is the number of requests,
starting from one, sent over the network connection since it
was opened. It is the number that was the value of
<i>NextRequest</i> immediately before the failing call was
made. The request_code member is a protocol request of the
procedure that failed, as defined in
<<i>X11/Xproto.h</i>>. The following error codes can
be returned by the functions described in this
chapter:</small></p>
<p align=center><small><img src="grohtml-1439238.png"></small></p>
<p align=center><small>Note</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The <i>BadAtom</i>, <i>BadColor</i>,
<i>BadCursor</i>, <i>BadDrawable</i>, <i>BadFont</i>,
<i>BadGC</i>, <i>BadPixmap</i>, and <i>BadWindow</i> errors
are also used when the argument type is extended by a set of
fixed alternatives.</small></p>
</td>
</table>
<p><small>To obtain textual descriptions of the specified
error code, use <i>XGetErrorText</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XGetErrorText(<i>display</i>, <i>code</i>, <i>buffer_return</i>, <i>length</i>)
Display *<i>display</i>;
int <i>code</i>;
char *<i>buffer_return</i>;
int <i>length</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>code</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the error code for which you want to
obtain a description.</small></p>
</td>
</table>
<p><small><i>buffer_return</i> Returns the error
description.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>length</i></small></p>
</td>
<td width="8%"></td>
<td width="66%">
<p><small>Specifies the size of the buffer.</small></p>
</td>
<td width="13%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetErrorText</i> function copies a
null-terminated string describing the specified error code
into the specified buffer. 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.</small></p>
<p><small>To obtain error messages from the error database,
use <i>XGetErrorDatabaseText</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XGetErrorDatabaseText(<i>display</i>, <i>name</i>, <i>message</i>, <i>default_string</i>, <i>buffer_return</i>, <i>length</i>)
Display *<i>display</i>;
char *<i>name</i>, *<i>message</i>;
char *<i>default_string</i>;
char *<i>buffer_return</i>;
int <i>length</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>name</i></small></p>
</td>
<td width="12%"></td>
<td width="76%">
<p><small>Specifies the name of the
application.</small></p>
</td>
<td width="3%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>message</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the type of the error
message.</small></p>
</td>
<td width="0%">
</td>
</table>
<p><small><i>default_string</i> Specifies the default error
message if none is found in the database.</small></p>
<p><small><i>buffer_return</i> Returns the error
description.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>length</i></small></p>
</td>
<td width="8%"></td>
<td width="66%">
<p><small>Specifies the size of the buffer.</small></p>
</td>
<td width="13%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetErrorDatabaseText</i> function returns
a null-terminated 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.</small></p>
<p><small>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.</small></p>
<p><small>XProtoError</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>The protocol error number is used as a string for
the message argument.</small></p>
</td>
</table>
<p><small>XlibMessage</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>These are the message strings that are used
internally by the library.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small>XRequest</small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>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
<i>InitExtension</i>) 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.</small></p>
</td>
</table>
<p><small>To report an error to the user when the requested
display does not exist, use <i>XDisplayName</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char *XDisplayName(<i>string</i>)
char *<i>string</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Specifies the character string.</small></p>
</td>
<td width="17%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XDisplayName</i> function returns the name
of the display that <i>XOpenDisplay</i> would attempt to
use. If a NULL string is specified, <i>XDisplayName</i>
looks in the environment for the display and returns the
display name that <i>XOpenDisplay</i> 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.</small></p>
<p><small>To handle fatal I/O errors, use
<i>XSetIOErrorHandler</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int (*XSetIOErrorHandler(<i>handler</i>))()
int (*<i>handler</i>)(Display *);
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>handler</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the program’s supplied error
handler.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetIOErrorHandler</i> sets the fatal I/O
error handler. Xlib calls the program’s supplied error
handler if any sort of system call error occurs (for
example, the connection to the server was lost). This is
assumed to be a fatal condition, and the called routine
should not return. If the I/O error handler does return, the
client process exits.</small></p>
<p><small>Note that the previous error handler is
returned.</small></p>
<p><small><b>11</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b>Chapter 12</b></p>
<p align=center><b>Input Device Functions</b></p>
<p><small>You can use the Xlib input device functions
to:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Grab the pointer and individual buttons on the
pointer</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Grab the keyboard and individual keys on the
keyboard</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="46%">
<p><small>Resume event processing</small></p>
</td>
<td width="43%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="32%">
<p><small>Move the pointer</small></p>
</td>
<td width="57%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="38%">
<p><small>Set the input focus</small></p>
</td>
<td width="51%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="88%">
<p><small>Manipulate the keyboard and pointer
settings</small></p>
</td>
<td width="1%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="64%">
<p><small>Manipulate the keyboard encoding</small></p>
</td>
<td width="25%">
</td>
</table>
<a name="12.1. Pointer Grabbing"></a>
<h2>12.1. Pointer Grabbing</h2>
<p><small>Xlib provides functions that you can use to
control input from the pointer, which usually is a mouse.
Usually, as soon as keyboard and mouse events occur, the X
server delivers them to the appropriate client, which is
determined by the window and input focus. The X server
provides sufficient control over event delivery to allow
window managers to support mouse ahead and various other
styles of user interface. Many of these user interfaces
depend on synchronous delivery of events. The delivery of
pointer and keyboard events can be controlled
independently.</small></p>
<p><small>When mouse buttons or keyboard keys are grabbed,
events will be sent to the grabbing client rather than the
normal client who would have received the event. If the
keyboard or pointer is in asynchronous mode, further mouse
and keyboard events will continue to be processed. If the
keyboard or pointer is in synchronous mode, no further
events are processed until the grabbing client allows them
(see <i>XAllowEvents</i>). The keyboard or pointer is
considered frozen during this interval. The event that
triggered the grab can also be replayed.</small></p>
<p><small>Note that the logical state of a device (as seen
by client applications) may lag the physical state if device
event processing is frozen.</small></p>
<p><small>There are two kinds of grabs: active and passive.
An active grab occurs when a single client grabs the
keyboard and/or pointer explicitly (see <i>XGrabPointer</i>
and <i>XGrabKeyboard</i>). A passive grab occurs when
clients grab a particular keyboard key or pointer button in
a window, and the grab will activate when the key or button
is actually pressed. Passive grabs are convenient for
implementing reliable pop-up menus. For example, you can
guarantee that the pop-up is mapped before the up pointer
button event occurs by grabbing a button requesting
synchronous behavior. The down event will trigger the grab
and freeze further processing of pointer events until you
have the chance to map the pop-up window. You can then allow
further event processing. The up event will then be
correctly processed relative to the pop-up
window.</small></p>
<p><small>For many operations, there are functions that
take a time argument. The X server includes a timestamp in
various events. One special time, called <i>CurrentTime</i>,
represents the current server time. The X server maintains
the time when the input focus was last changed, when the
keyboard was last grabbed, when the pointer was last
grabbed, or when a selection was last changed. Your
application may be slow reacting to an event. You often need
some way to specify that your request should not occur if
another application has in the meanwhile taken control of
the keyboard, pointer, or selection. By providing the
timestamp from the event in the request, you can arrange
that the operation not take effect if someone else has
performed an operation in the meanwhile.</small></p>
<p><small>A timestamp is a time value, expressed in
milliseconds. It typically is the time since the last server
reset. Timestamp values wrap around (after about 49.7 days).
The server, given its current time is represented by
timestamp T, always interprets timestamps from clients by
treating half of the timestamp space as being later in time
than T. One timestamp value, named <i>CurrentTime</i>, is
never generated by the server. This value is reserved for
use in requests to represent the current server
time.</small></p>
<p><small>For many functions in this section, you pass
pointer event mask bits. The valid pointer event mask bits
are: <i>ButtonPressMask</i>, <i>ButtonReleaseMask</i>,
<i>EnterWindowMask</i>, <i>LeaveWindowMask</i>,
<i>PointerMotionMask</i>, <i>PointerMotionHintMask</i>,
<i>Button1MotionMask</i>, <i>Button2MotionMask</i>,
<i>Button3MotionMask</i>, <i>Button4MotionMask</i>,
<i>Button5MotionMask</i>, <i>ButtonMotionMask</i>, and
<i>KeyMapStateMask</i>. For other functions in this section,
you pass keymask bits. The valid keymask bits are:
<i>ShiftMask</i>, <i>LockMask</i>, <i>ControlMask</i>,
<i>Mod1Mask</i>, <i>Mod2Mask</i>, <i>Mod3Mask</i>,
<i>Mod4Mask</i>, and <i>Mod5Mask</i>.</small></p>
<p><small>To grab the pointer, use
<i>XGrabPointer</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XGrabPointer(<i>display</i>, <i>grab_window</i>, <i>owner_events</i>, <i>event_mask</i>, <i>pointer_mode</i>,
<i> keyboard_mode</i>, <i>confine_to</i>, <i>cursor</i>, <i>time</i>)
Display *<i>display</i>;
Window <i>grab_window</i>;
Bool <i>owner_events</i>;
unsigned int <i>event_mask</i>;
int <i>pointer_mode</i>, <i>keyboard_mode</i>;
Window <i>confine_to</i>;
Cursor <i>cursor</i>;
Time <i>time</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>grab_window</i> Specifies the grab
window.</small></p>
<p><small><i>owner_events</i> 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.</small></p>
<p><small><i>event_mask</i> Specifies which pointer events
are reported to the client. The mask is the bitwise
inclusive OR of the valid pointer event mask
bits.</small></p>
<p><small><i>pointer_mode</i> Specifies further processing
of pointer events. You can pass <i>GrabModeSync</i> or
<i>GrabModeAsync</i>.</small></p>
<p><small><i>keyboard_mode</i> Specifies further processing
of keyboard events. You can pass <i>GrabModeSync</i> or
<i>GrabModeAsync</i>.</small></p>
<p><small><i>confine_to</i> Specifies the window to confine
the pointer in or <i>None</i>.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>cursor</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the cursor that is to be displayed
during the grab or <i>None</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>time</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the time. You can pass either a
timestamp or <i>CurrentTime</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGrabPointer</i> function actively grabs
control of the pointer and returns <i>GrabSuccess</i> if the
grab was successful. Further pointer events are reported
only to the grabbing client. <i>XGrabPointer</i> overrides
any active pointer grab by this client. If owner_events is
<i>False</i>, all generated pointer events are reported with
respect to grab_window and are reported only if selected by
event_mask. If owner_events is <i>True</i> 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.</small></p>
<p><small>If the pointer_mode is <i>GrabModeAsync</i>,
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
<i>GrabModeSync</i>, 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 <i>XAllowEvents</i> 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.</small></p>
<p><small>If the keyboard_mode is <i>GrabModeAsync</i>,
keyboard event processing is unaffected by activation of the
grab. If the keyboard_mode is <i>GrabModeSync</i>, 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 <i>XAllowEvents</i>
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.</small></p>
<p><small>If a cursor is specified, it is displayed
regardless of what window the pointer is in. If <i>None</i>
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.</small></p>
<p><small>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.</small></p>
<p><small>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.</small></p>
<p><small><i>XGrabPointer</i> generates <i>EnterNotify</i>
and <i>LeaveNotify</i> events.</small></p>
<p><small>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, <i>XGrabPointer</i> fails
and returns <i>GrabNotViewable</i>. If the pointer is
actively grabbed by some other client, it fails and returns
<i>AlreadyGrabbed</i>. If the pointer is frozen by an active
grab of another client, it fails and returns
<i>GrabFrozen</i>. If the specified time is earlier than the
last-pointer-grab time or later than the current X server
time, it fails and returns <i>GrabInvalidTime</i>.
Otherwise, the last-pointer-grab time is set to the
specified time (<i>CurrentTime</i> is replaced by the
current X server time).</small></p>
<p><small><i>XGrabPointer</i> can generate
<i>BadCursor</i>, <i>BadValue</i>, and <i>BadWindow</i>
errors.</small></p>
<p><small>To ungrab the pointer, use
<i>XUngrabPointer</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XUngrabPointer(<i>display</i>, <i>time</i>)
Display *<i>display</i>;
Time <i>time</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>time</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the time. You can pass either a
timestamp or <i>CurrentTime</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XUngrabPointer</i> function releases the
pointer and any queued events if this client has actively
grabbed the pointer from <i>XGrabPointer</i>,
<i>XGrabButton</i>, or from a normal button press.
<i>XUngrabPointer</i> does not release the pointer if the
specified time is earlier than the last-pointer-grab time or
is later than the current X server time. It also generates
<i>EnterNotify</i> and <i>LeaveNotify</i> events. The X
server performs an <i>UngrabPointer</i> request
automatically if the event window or confine_to window for
an active pointer grab becomes not viewable or if window
reconfiguration causes the confine_to window to lie
completely outside the boundaries of the root
window.</small></p>
<p><small>To change an active pointer grab, use
<i>XChangeActivePointerGrab</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XChangeActivePointerGrab(<i>display</i>, <i>event_mask</i>, <i>cursor</i>, <i>time</i>)
Display *<i>display</i>;
unsigned int <i>event_mask</i>;
Cursor <i>cursor</i>;
Time <i>time</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>event_mask</i> Specifies which pointer events
are reported to the client. The mask is the bitwise
inclusive OR of the valid pointer event mask
bits.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>cursor</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the cursor that is to be displayed or
<i>None</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>time</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the time. You can pass either a
timestamp or <i>CurrentTime</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XChangeActivePointerGrab</i> 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 an <i>XGrabButton</i>. The
interpretation of event_mask and cursor is the same as
described in <i>XGrabPointer</i>.</small></p>
<p><small><i>XChangeActivePointerGrab</i> can generate
<i>BadCursor</i> and <i>BadValue</i> errors.</small></p>
<p><small>To grab a pointer button, use
<i>XGrabButton</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XGrabButton(<i>display</i>, <i>button</i>, <i>modifiers</i>, <i>grab_window</i>, <i>owner_events</i>, <i>event_mask</i>,
<i> pointer_mode</i>, <i>keyboard_mode</i>, <i>confine_to</i>, <i>cursor</i>)
Display *<i>display</i>;
unsigned int <i>button</i>;
unsigned int <i>modifiers</i>;
Window <i>grab_window</i>;
Bool <i>owner_events</i>;
unsigned int <i>event_mask</i>;
int <i>pointer_mode</i>, <i>keyboard_mode</i>;
Window <i>confine_to</i>;
Cursor <i>cursor</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>button</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the pointer button that is to be
grabbed or <i>AnyButton</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>modifiers</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the set of keymasks or
<i>AnyModifier</i>. The mask is the bitwise inclusive OR of
the valid keymask bits.</small></p>
</td>
</table>
<p><small><i>grab_window</i> Specifies the grab
window.</small></p>
<p><small><i>owner_events</i> 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.</small></p>
<p><small><i>event_mask</i> Specifies which pointer events
are reported to the client. The mask is the bitwise
inclusive OR of the valid pointer event mask
bits.</small></p>
<p><small><i>pointer_mode</i> Specifies further processing
of pointer events. You can pass <i>GrabModeSync</i> or
<i>GrabModeAsync</i>.</small></p>
<p><small><i>keyboard_mode</i> Specifies further processing
of keyboard events. You can pass <i>GrabModeSync</i> or
<i>GrabModeAsync</i>.</small></p>
<p><small><i>confine_to</i> Specifies the window to confine
the pointer in or <i>None</i>.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>cursor</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the cursor that is to be displayed or
<i>None</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGrabButton</i> function establishes a
passive grab. In the future, the pointer is actively grabbed
(as for <i>XGrabPointer</i>), the last-pointer-grab time is
set to the time at which the button was pressed (as
transmitted in the <i>ButtonPress</i> event), and the
<i>ButtonPress</i> event is reported if all of the following
conditions are true:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>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.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="74%">
<p><small>The grab_window contains the pointer.</small></p>
</td>
<td width="15%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="86%">
<p><small>The confine_to window (if any) is
viewable.</small></p>
</td>
<td width="3%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>A passive grab on the same button/key combination
does not exist on any ancestor of grab_window.</small></p>
</td>
</table>
<p><small>The interpretation of the remaining arguments is
as for <i>XGrabPointer</i>. 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).</small></p>
<p><small>Note that the logical state of a device (as seen
by client applications) may lag the physical state if device
event processing is frozen.</small></p>
<p><small>This request overrides all previous grabs by the
same client on the same button/key combinations on the same
window. A modifiers of <i>AnyModifier</i> 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 <i>AnyButton</i> 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.</small></p>
<p><small>If some other client has already issued an
<i>XGrabButton</i> with the same button/key combination on
the same window, a <i>BadAccess</i> error results. When
using <i>AnyModifier</i> or <i>AnyButton</i>, the request
fails completely, and a <i>BadAccess</i> error results (no
grabs are established) if there is a conflicting grab for
any combination. <i>XGrabButton</i> has no effect on an
active grab.</small></p>
<p><small><i>XGrabButton</i> can generate <i>BadCursor</i>,
<i>BadValue</i>, and <i>BadWindow</i> errors.</small></p>
<p><small>To ungrab a pointer button, use
<i>XUngrabButton</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XUngrabButton(<i>display</i>, <i>button</i>, <i>modifiers</i>, <i>grab_window</i>)
Display *<i>display</i>;
unsigned int <i>button</i>;
unsigned int <i>modifiers</i>;
Window <i>grab_window</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>button</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the pointer button that is to be
released or <i>AnyButton</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>modifiers</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the set of keymasks or
<i>AnyModifier</i>. The mask is the bitwise inclusive OR of
the valid keymask bits.</small></p>
</td>
</table>
<p><small><i>grab_window</i> Specifies the grab
window.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XUngrabButton</i> function releases the
passive button/key combination on the specified window if it
was grabbed by this client. A modifiers of
<i>AnyModifier</i> is equivalent to issuing the ungrab
request for all possible modifier combinations, including
the combination of no modifiers. A button of
<i>AnyButton</i> is equivalent to issuing the request for
all possible buttons. <i>XUngrabButton</i> has no effect on
an active grab.</small></p>
<p><small><i>XUngrabButton</i> can generate <i>BadValue</i>
and <i>BadWindow</i> errors.</small></p>
<a name="12.2. Keyboard Grabbing"></a>
<h2>12.2. Keyboard Grabbing</h2>
<p><small>Xlib provides functions that you can use to grab
or ungrab the keyboard as well as allow events.</small></p>
<p><small>For many functions in this section, you pass
keymask bits. The valid keymask bits are: <i>ShiftMask</i>,
<i>LockMask</i>, <i>ControlMask</i>, <i>Mod1Mask</i>,
<i>Mod2Mask</i>, <i>Mod3Mask</i>, <i>Mod4Mask</i>, and
<i>Mod5Mask</i>.</small></p>
<p><small>To grab the keyboard, use
<i>XGrabKeyboard</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XGrabKeyboard(<i>display</i>, <i>grab_window</i>, <i>owner_events</i>, <i>pointer_mode</i>, <i>keyboard_mode</i>, <i>time</i>)
Display *<i>display</i>;
Window <i>grab_window</i>;
Bool <i>owner_events</i>;
int <i>pointer_mode</i>, <i>keyboard_mode</i>;
Time <i>time</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>grab_window</i> Specifies the grab
window.</small></p>
<p><small><i>owner_events</i> Specifies a Boolean value
that indicates whether the keyboard events are to be
reported as usual.</small></p>
<p><small><i>pointer_mode</i> Specifies further processing
of pointer events. You can pass <i>GrabModeSync</i> or
<i>GrabModeAsync</i>.</small></p>
<p><small><i>keyboard_mode</i> Specifies further processing
of keyboard events. You can pass <i>GrabModeSync</i> or
<i>GrabModeAsync</i>.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>time</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the time. You can pass either a
timestamp or <i>CurrentTime</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGrabKeyboard</i> function actively grabs
control of the keyboard and generates <i>FocusIn</i> and
<i>FocusOut</i> events. Further key events are reported only
to the grabbing client. <i>XGrabKeyboard</i> overrides any
active keyboard grab by this client. If owner_events is
<i>False</i>, all generated key events are reported with
respect to grab_window. If owner_events is <i>True</i> 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
<i>KeyPress</i> and <i>KeyRelease</i> events are always
reported, independent of any event selection made by the
client.</small></p>
<p><small>If the keyboard_mode argument is
<i>GrabModeAsync</i>, 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 <i>GrabModeSync</i>, 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
<i>XAllowEvents</i> 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.</small></p>
<p><small>If pointer_mode is <i>GrabModeAsync</i>, pointer
event processing is unaffected by activation of the grab. If
pointer_mode is <i>GrabModeSync</i>, 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 <i>XAllowEvents</i>
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.</small></p>
<p><small>If the keyboard is actively grabbed by some other
client, <i>XGrabKeyboard</i> fails and returns
<i>AlreadyGrabbed</i>. If grab_window is not viewable, it
fails and returns <i>GrabNotViewable</i>. If the keyboard is
frozen by an active grab of another client, it fails and
returns <i>GrabFrozen</i>. If the specified time is earlier
than the last-keyboard-grab time or later than the current X
server time, it fails and returns <i>GrabInvalidTime</i>.
Otherwise, the last-keyboard-grab time is set to the
specified time (<i>CurrentTime</i> is replaced by the
current X server time).</small></p>
<p><small><i>XGrabKeyboard</i> can generate <i>BadValue</i>
and <i>BadWindow</i> errors.</small></p>
<p><small>To ungrab the keyboard, use
<i>XUngrabKeyboard</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XUngrabKeyboard(<i>display</i>, <i>time</i>)
Display *<i>display</i>;
Time <i>time</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>time</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the time. You can pass either a
timestamp or <i>CurrentTime</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XUngrabKeyboard</i> function releases the
keyboard and any queued events if this client has it
actively grabbed from either <i>XGrabKeyboard</i> or
<i>XGrabKey</i>. <i>XUngrabKeyboard</i> does not release the
keyboard and any queued events if the specified time is
earlier than the last-keyboard-grab time or is later than
the current X server time. It also generates <i>FocusIn</i>
and <i>FocusOut</i> events. The X server automatically
performs an <i>UngrabKeyboard</i> request if the event
window for an active keyboard grab becomes not
viewable.</small></p>
<p><small>To passively grab a single key of the keyboard,
use <i>XGrabKey</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XGrabKey(<i>display</i>, <i>keycode</i>, <i>modifiers</i>, <i>grab_window</i>, <i>owner_events</i>, <i>pointer_mode</i>,
<i> keyboard_mode</i>)
Display *<i>display</i>;
int <i>keycode</i>;
unsigned int <i>modifiers</i>;
Window <i>grab_window</i>;
Bool <i>owner_events</i>;
int <i>pointer_mode</i>, <i>keyboard_mode</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>keycode</i></small></p>
</td>
<td width="6%"></td>
<td width="64%">
<p><small>Specifies the KeyCode or
<i>AnyKey</i>.</small></p>
</td>
<td width="15%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>modifiers</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the set of keymasks or
<i>AnyModifier</i>. The mask is the bitwise inclusive OR of
the valid keymask bits.</small></p>
</td>
</table>
<p><small><i>grab_window</i> Specifies the grab
window.</small></p>
<p><small><i>owner_events</i> Specifies a Boolean value
that indicates whether the keyboard events are to be
reported as usual.</small></p>
<p><small><i>pointer_mode</i> Specifies further processing
of pointer events. You can pass <i>GrabModeSync</i> or
<i>GrabModeAsync</i>.</small></p>
<p><small><i>keyboard_mode</i> Specifies further processing
of keyboard events. You can pass <i>GrabModeSync</i> or
<i>GrabModeAsync</i>.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGrabKey</i> function establishes a
passive grab on the keyboard. In the future, the keyboard is
actively grabbed (as for <i>XGrabKeyboard</i>), the
last-keyboard-grab time is set to the time at which the key
was pressed (as transmitted in the <i>KeyPress</i> event),
and the <i>KeyPress</i> event is reported if all of the
following conditions are true:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>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.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>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.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>A passive grab on the same key combination does
not exist on any ancestor of grab_window.</small></p>
</td>
</table>
<p><small>The interpretation of the remaining arguments is
as for <i>XGrabKeyboard</i>. 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).</small></p>
<p><small>Note that the logical state of a device (as seen
by client applications) may lag the physical state if device
event processing is frozen.</small></p>
<p><small>A modifiers argument of <i>AnyModifier</i> 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 <i>AnyKey</i> 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 <i>BadValue</i> error results.</small></p>
<p><small>If some other client has issued a <i>XGrabKey</i>
with the same key combination on the same window, a
<i>BadAccess</i> error results. When using
<i>AnyModifier</i> or <i>AnyKey</i>, the request fails
completely, and a <i>BadAccess</i> error results (no grabs
are established) if there is a conflicting grab for any
combination.</small></p>
<p><small><i>XGrabKey</i> can generate <i>BadAccess</i>,
<i>BadValue</i>, and <i>BadWindow</i> errors.</small></p>
<p><small>To ungrab a key, use
<i>XUngrabKey</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XUngrabKey(<i>display</i>, <i>keycode</i>, <i>modifiers</i>, <i>grab_window</i>)
Display *<i>display</i>;
int <i>keycode</i>;
unsigned int <i>modifiers</i>;
Window <i>grab_window</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>keycode</i></small></p>
</td>
<td width="6%"></td>
<td width="64%">
<p><small>Specifies the KeyCode or
<i>AnyKey</i>.</small></p>
</td>
<td width="15%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>modifiers</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the set of keymasks or
<i>AnyModifier</i>. The mask is the bitwise inclusive OR of
the valid keymask bits.</small></p>
</td>
</table>
<p><small><i>grab_window</i> Specifies the grab
window.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XUngrabKey</i> function releases the key
combination on the specified window if it was grabbed by
this client. It has no effect on an active grab. A modifiers
of <i>AnyModifier</i> is equivalent to issuing the request
for all possible modifier combinations (including the
combination of no modifiers). A keycode argument of
<i>AnyKey</i> is equivalent to issuing the request for all
possible key codes.</small></p>
<p><small><i>XUngrabKey</i> can generate <i>BadValue</i>
and <i>BadWindow</i> errors.</small></p>
<a name="12.3. Resuming Event Processing"></a>
<h2>12.3. Resuming Event Processing</h2>
<p><small>The previous sections discussed grab mechanisms
with which processing of events by the server can be
temporarily suspended. This section describes the mechanism
for resuming event processing.</small></p>
<p><small>To allow further events to be processed when the
device has been frozen, use <i>XAllowEvents</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XAllowEvents(<i>display</i>, <i>event_mode</i>, <i>time</i>)
Display *<i>display</i>;
int <i>event_mode</i>;
Time <i>time</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>event_mode</i> Specifies the event mode. You
can pass <i>AsyncPointer</i>, <i>SyncPointer</i>,
<i>AsyncKeyboard</i>, <i>SyncKeyboard</i>,
<i>ReplayPointer</i>, <i>ReplayKeyboard</i>,
<i>AsyncBoth</i>, or <i>SyncBoth</i>.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>time</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the time. You can pass either a
timestamp or <i>CurrentTime</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XAllowEvents</i> 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:</small></p>
<p align=center><small><img src="grohtml-1439239.png"></small></p>
<p><small><i>AsyncPointer</i>, <i>SyncPointer</i>, and
<i>ReplayPointer</i> have no effect on the processing of
keyboard events. <i>AsyncKeyboard</i>, <i>SyncKeyboard</i>,
and <i>ReplayKeyboard</i> 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 <i>AllowEvents</i> releases both.</small></p>
<p><small><i>XAllowEvents</i> can generate a
<i>BadValue</i> error.</small></p>
<a name="12.4. Moving the Pointer"></a>
<h2>12.4. Moving the Pointer</h2>
<p><small>Although movement of the pointer normally should
be left to the control of the end user, sometimes it is
necessary to move the pointer to a new position under
program control.</small></p>
<p><small>To move the pointer to an arbitrary point in a
window, use <i>XWarpPointer</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XWarpPointer(<i>display</i>, <i>src_w</i>, <i>dest_w</i>, <i>src_x</i>, <i>src_y</i>, <i>src_width</i>, <i>src_height</i>, <i>dest_x</i>,
<i> dest_y</i>)
Display *<i>display</i>;
Window <i>src_w</i>, <i>dest_w</i>;
int <i>src_x</i>, <i>src_y</i>;
unsigned int <i>src_width</i>, <i>src_height</i>;
int <i>dest_x</i>, <i>dest_y</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>src_w</i></small></p>
</td>
<td width="10%"></td>
<td width="72%">
<p><small>Specifies the source window or
<i>None</i>.</small></p>
</td>
<td width="7%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>dest_w</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the destination window or
<i>None</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>src_x</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>src_y</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>src_width</i></small></p>
</td>
<td width="81%">
</td>
</table>
<p><small><i>src_height</i> Specify a rectangle in the
source window.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>dest_x</i></small></p>
</td>
<td width="87%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>dest_y</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates within the
destination window.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>If dest_w is <i>None</i>, <i>XWarpPointer</i>
moves the pointer by the offsets (dest_x, dest_y) relative
to the current position of the pointer. If dest_w is a
window, <i>XWarpPointer</i> moves the pointer to the offsets
(dest_x, dest_y) relative to the origin of dest_w. However,
if src_w is a window, the move only takes place if the
window src_w contains the pointer and if the specified
rectangle of src_w contains the pointer.</small></p>
<p><small>The src_x and src_y coordinates are relative to
the origin of src_w. If src_height is zero, it is replaced
with the current height of src_w minus src_y. If src_width
is zero, it is replaced with the current width of src_w
minus src_x.</small></p>
<p><small>There is seldom any reason for calling this
function. The pointer should normally be left to the user.
If you do use this function, however, it generates events
just as if the user had instantaneously moved the pointer
from one position to another. Note that you cannot use
<i>XWarpPointer</i> to move the pointer outside the
confine_to window of an active pointer grab. An attempt to
do so will only move the pointer as far as the closest edge
of the confine_to window.</small></p>
<p><small><i>XWarpPointer</i> can generate a
<i>BadWindow</i> error.</small></p>
<a name="12.5. Controlling Input Focus"></a>
<h2>12.5. Controlling Input Focus</h2>
<p><small>Xlib provides functions that you can use to set
and get the input focus. The input focus is a shared
resource, and cooperation among clients is required for
correct interaction. See the <i>Inter-Client Communication
Conventions Manual</i> for input focus policy.</small></p>
<p><small>To set the input focus, use
<i>XSetInputFocus</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetInputFocus(<i>display</i>, <i>focus</i>, <i>revert_to</i>, <i>time</i>)
Display *<i>display</i>;
Window <i>focus</i>;
int <i>revert_to</i>;
Time <i>time</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>focus</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the window, <i>PointerRoot</i>, or
<i>None</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>revert_to</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies where the input focus reverts to if the
window becomes not viewable. You can pass
<i>RevertToParent</i>, <i>RevertToPointerRoot</i>, or
<i>RevertToNone</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>time</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the time. You can pass either a
timestamp or <i>CurrentTime</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetInputFocus</i> function changes the
input focus and the last-focus-change time. It has no effect
if the specified time is earlier than the current
last-focus-change time or is later than the current X server
time. Otherwise, the last-focus-change time is set to the
specified time (<i>CurrentTime</i> is replaced by the
current X server time). <i>XSetInputFocus</i> causes the X
server to generate <i>FocusIn</i> and <i>FocusOut</i>
events.</small></p>
<p><small>Depending on the focus argument, the following
occurs:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If focus is <i>None</i>, all keyboard events are
discarded until a new focus window is set, and the revert_to
argument is ignored.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If focus is a window, it becomes the
keyboard’s focus window. If a generated keyboard event
would normally be reported to this window or one of its
inferiors, the event is reported as usual. Otherwise, the
event is reported relative to the focus window.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If focus is <i>PointerRoot</i>, the focus window
is dynamically taken to be the root window of whatever
screen the pointer is on at each keyboard event. In this
case, the revert_to argument is ignored.</small></p>
</td>
</table>
<p><small>The specified focus window must be viewable at
the time <i>XSetInputFocus</i> is called, or a
<i>BadMatch</i> error results. If the focus window later
becomes not viewable, the X server evaluates the revert_to
argument to determine the new focus window as
follows:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If revert_to is <i>RevertToParent</i>, the focus
reverts to the parent (or the closest viewable ancestor),
and the new revert_to value is taken to be
<i>RevertToNone</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If revert_to is <i>RevertToPointerRoot</i> or
<i>RevertToNone</i>, the focus reverts to <i>PointerRoot</i>
or <i>None</i>, respectively. When the focus reverts, the X
server generates <i>FocusIn</i> and <i>FocusOut</i> events,
but the last-focus-change time is not affected.</small></p>
</td>
</table>
<p><small><i>XSetInputFocus</i> can generate
<i>BadMatch</i>, <i>BadValue</i>, and <i>BadWindow</i>
errors.</small></p>
<p><small>To obtain the current input focus, use
<i>XGetInputFocus</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XGetInputFocus(<i>display</i>, <i>focus_return</i>, <i>revert_to_return</i>)
Display *<i>display</i>;
Window *<i>focus_return</i>;
int *<i>revert_to_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>focus_return</i> Returns the focus window,
<i>PointerRoot</i>, or <i>None</i>.</small></p>
<p><small><i>revert_to_return</i> Returns the current focus
state (<i>RevertToParent</i>, <i>RevertToPointerRoot</i>, or
<i>RevertToNone</i>).</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetInputFocus</i> function returns the
focus window and the current focus state.</small></p>
<a name="12.6. Manipulating the Keyboard and Pointer Settings"></a>
<h2>12.6. Manipulating the Keyboard and Pointer Settings</h2>
<p><small>Xlib provides functions that you can use to
change the keyboard control, obtain a list of the
auto-repeat keys, turn keyboard auto-repeat on or off, ring
the bell, set or obtain the pointer button or keyboard
mapping, and obtain a bit vector for the
keyboard.</small></p>
<p><small>This section discusses the user-preference
options of bell, key click, pointer behavior, and so on. The
default values for many of these options are server
dependent. Not all implementations will actually be able to
control all of these parameters.</small></p>
<p><small>The <i>XChangeKeyboardControl</i> function
changes control of a keyboard and operates on a
<i>XKeyboardControl</i> structure:</small></p>
<p><small>__ │</small></p>
<p><small>/* Mask bits for ChangeKeyboardControl
*/</small></p>
<p align=center><small><img src="grohtml-1439240.png"></small></p>
<pre><small>/* Values */
typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int key_click_percent;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int bell_percent;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int bell_pitch;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int bell_duration;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int led;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int led_mode;</small></p>
</td>
<td width="50%">
<p><small>/* LedModeOn, LedModeOff */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int key;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int auto_repeat_mode;/* AutoRepeatModeOff,
AutoRepeatModeOn,</small></p>
</td>
<td width="50%">
</td>
</table>
<p><small>AutoRepeatModeDefault */<br>
} XKeyboardControl;</small></p>
<p><small>│__</small></p>
<p><small>The key_click_percent member sets the volume for
key clicks between 0 (off) and 100 (loud) inclusive, if
possible. A setting of −1 restores the default. Other
negative values generate a <i>BadValue</i>
error.</small></p>
<p><small>The bell_percent sets the base volume for the
bell between 0 (off) and 100 (loud) inclusive, if possible.
A setting of −1 restores the default. Other negative
values generate a <i>BadValue</i> error. The bell_pitch
member sets the pitch (specified in Hz) of the bell, if
possible. A setting of −1 restores the default. Other
negative values generate a <i>BadValue</i> error. The
bell_duration member sets the duration of the bell specified
in milliseconds, if possible. A setting of −1 restores
the default. Other negative values generate a
<i>BadValue</i> error.</small></p>
<p><small>If both the led_mode and led members are
specified, the state of that LED is changed, if possible.
The led_mode member can be set to <i>LedModeOn</i> or
<i>LedModeOff</i>. If only led_mode is specified, the state
of all LEDs are changed, if possible. At most 32 LEDs
numbered from one are supported. No standard interpretation
of LEDs is defined. If led is specified without led_mode, a
<i>BadMatch</i> error results.</small></p>
<p><small>If both the auto_repeat_mode and key members are
specified, the auto_repeat_mode of that key is changed
(according to <i>AutoRepeatModeOn</i>,
<i>AutoRepeatModeOff</i>, or <i>AutoRepeatModeDefault</i>),
if possible. If only auto_repeat_mode is specified, the
global auto_repeat_mode for the entire keyboard is changed,
if possible, and does not affect the per-key settings. If a
key is specified without an auto_repeat_mode, a
<i>BadMatch</i> error results. Each key has an individual
mode of whether or not it should auto-repeat and a default
setting for the mode. In addition, there is a global mode of
whether auto-repeat should be enabled or not and a default
setting for that mode. When global mode is
<i>AutoRepeatModeOn</i>, keys should obey their individual
auto-repeat modes. When global mode is
<i>AutoRepeatModeOff</i>, no keys should auto-repeat. An
auto-repeating key generates alternating <i>KeyPress</i> and
<i>KeyRelease</i> events. When a key is used as a modifier,
it is desirable for the key not to auto-repeat, regardless
of its auto-repeat setting.</small></p>
<p><small>A bell generator connected with the console but
not directly on a keyboard is treated as if it were part of
the keyboard. The order in which controls are verified and
altered is server-dependent. If an error is generated, a
subset of the controls may have been altered.</small></p>
<p><small>__ │</small></p>
<pre><small>XChangeKeyboardControl(<i>display</i>, <i>value_mask</i>, <i>values</i>)
Display *<i>display</i>;
unsigned long <i>value_mask</i>;
XKeyboardControl *<i>values</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>value_mask</i> Specifies which controls to
change. This mask is the bitwise inclusive OR of the valid
control mask bits.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>values</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies one value for each bit set to 1 in the
mask.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XChangeKeyboardControl</i> function
controls the keyboard characteristics defined by the
<i>XKeyboardControl</i> structure. The value_mask argument
specifies which values are to be changed.</small></p>
<p><small><i>XChangeKeyboardControl</i> can generate
<i>BadMatch</i> and <i>BadValue</i> errors.</small></p>
<p><small>To obtain the current control values for the
keyboard, use <i>XGetKeyboardControl</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XGetKeyboardControl(<i>display</i>, <i>values_return</i>)
Display *<i>display</i>;
XKeyboardState *<i>values_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>values_return</i> Returns the current keyboard
controls in the specified <i>XKeyboardState</i>
structure.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetKeyboardControl</i> function returns
the current control values for the keyboard to the
<i>XKeyboardState</i> structure.</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>int key_click_percent;</small></p>
</td>
<td width="79%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>int bell_percent;</small></p>
</td>
<td width="79%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>unsigned int bell_pitch,
bell_duration;</small></p>
</td>
<td width="79%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>unsigned long led_mask;</small></p>
</td>
<td width="79%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>int global_auto_repeat;</small></p>
</td>
<td width="79%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>char auto_repeats[32];</small></p>
</td>
<td width="79%">
</td>
</table>
<p><small>} XKeyboardState;</small></p>
<p><small>│__</small></p>
<p><small>For the LEDs, the least significant bit of
led_mask corresponds to LED one, and each bit set to 1 in
led_mask indicates an LED that is lit. The
global_auto_repeat member can be set to
<i>AutoRepeatModeOn</i> or <i>AutoRepeatModeOff</i>. The
auto_repeats member is a bit vector. Each bit set to 1
indicates that auto-repeat is enabled for the corresponding
key. The vector is represented as 32 bytes. Byte N (from 0)
contains the bits for keys 8N to 8N + 7 with the least
significant bit in the byte representing key 8N.</small></p>
<p><small>To turn on keyboard auto-repeat, use
<i>XAutoRepeatOn</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XAutoRepeatOn(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XAutoRepeatOn</i> function turns on
auto-repeat for the keyboard on the specified
display.</small></p>
<p><small>To turn off keyboard auto-repeat, use
<i>XAutoRepeatOff</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XAutoRepeatOff(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XAutoRepeatOff</i> function turns off
auto-repeat for the keyboard on the specified
display.</small></p>
<p><small>To ring the bell, use <i>XBell</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XBell(<i>display</i>, <i>percent</i>)
Display *<i>display</i>;
int <i>percent</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>percent</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the volume for the bell, which can
range from −100 to 100 inclusive.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XBell</i> function rings the bell on the
keyboard on the specified display, if possible. The
specified volume is relative to the base volume for the
keyboard. If the value for the percent argument is not in
the range −100 to 100 inclusive, a <i>BadValue</i>
error results. The volume at which the bell rings when the
percent argument is nonnegative is:</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>base − [(base * percent) / 100] +
percent</small></p>
</td>
</table>
<p><small>The volume at which the bell rings when the
percent argument is negative is:</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>base + [(base * percent) / 100]</small></p>
</td>
</table>
<p><small>To change the base volume of the bell, use
<i>XChangeKeyboardControl</i>.</small></p>
<p><small><i>XBell</i> can generate a <i>BadValue</i>
error.</small></p>
<p><small>To obtain a bit vector that describes the state
of the keyboard, use <i>XQueryKeymap</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XQueryKeymap(<i>display</i>, <i>keys_return</i>)
Display *<i>display</i>;
char <i>keys_return</i>[32];
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>keys_return</i> Returns an array of bytes that
identifies which keys are pressed down. Each bit represents
one key of the keyboard.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XQueryKeymap</i> function returns a bit
vector for the logical state of the keyboard, where each bit
set to 1 indicates that the corresponding key is currently
pressed down. The vector is represented as 32 bytes. Byte N
(from 0) contains the bits for keys 8N to 8N + 7 with the
least significant bit in the byte representing key
8N.</small></p>
<p><small>Note that the logical state of a device (as seen
by client applications) may lag the physical state if device
event processing is frozen.</small></p>
<p><small>To set the mapping of the pointer buttons, use
<i>XSetPointerMapping</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XSetPointerMapping(<i>display</i>, <i>map</i>, <i>nmap</i>)
Display *<i>display</i>;
unsigned char <i>map</i>[];
int <i>nmap</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>map</i></small></p>
</td>
<td width="14%"></td>
<td width="54%">
<p><small>Specifies the mapping list.</small></p>
</td>
<td width="25%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>nmap</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the number of items in the mapping
list.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetPointerMapping</i> function sets the
mapping of the pointer. If it succeeds, the X server
generates a <i>MappingNotify</i> event, and
<i>XSetPointerMapping</i> returns <i>MappingSuccess</i>.
Element map[i] defines the logical button number for the
physical button i+1. The length of the list must be the same
as <i>XGetPointerMapping</i> would return, or a
<i>BadValue</i> error results. A zero element disables a
button, and elements are not restricted in value by the
number of physical buttons. However, no two elements can
have the same nonzero value, or a <i>BadValue</i> error
results. If any of the buttons to be altered are logically
in the down state, <i>XSetPointerMapping</i> returns
<i>MappingBusy</i>, and the mapping is not
changed.</small></p>
<p><small><i>XSetPointerMapping</i> can generate a
<i>BadValue</i> error.</small></p>
<p><small>To get the pointer mapping, use
<i>XGetPointerMapping</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XGetPointerMapping(<i>display</i>, <i>map_return</i>, <i>nmap</i>)
Display *<i>display</i>;
unsigned char <i>map_return</i>[];
int <i>nmap</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>map_return</i> Returns the mapping
list.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>nmap</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the number of items in the mapping
list.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetPointerMapping</i> function returns
the current mapping of the pointer. Pointer buttons are
numbered starting from one. <i>XGetPointerMapping</i>
returns the number of physical buttons actually on the
pointer. The nominal mapping for a pointer is map[i]=i+1.
The nmap argument specifies the length of the array where
the pointer mapping is returned, and only the first nmap
elements are returned in map_return.</small></p>
<p><small>To control the pointer’s interactive feel,
use <i>XChangePointerControl</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XChangePointerControl(<i>display</i>, <i>do_accel</i>, <i>do_threshold</i>, <i>accel_numerator</i>,
<i> accel_denominator</i>, <i>threshold</i>)
Display *<i>display</i>;
Bool <i>do_accel</i>, <i>do_threshold</i>;
int <i>accel_numerator</i>, <i>accel_denominator</i>;
int <i>threshold</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>do_accel</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies a Boolean value that controls whether
the values for the accel_numerator or accel_denominator are
used.</small></p>
</td>
</table>
<p><small><i>do_threshold</i> Specifies a Boolean value
that controls whether the value for the threshold is
used.</small></p>
<p><small><i>accel_numerator</i> Specifies the numerator
for the acceleration multiplier.</small></p>
<p><small><i>accel_denominator</i> Specifies the
denominator for the acceleration multiplier.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>threshold</i></small></p>
</td>
<td width="2%"></td>
<td width="74%">
<p><small>Specifies the acceleration threshold.</small></p>
</td>
<td width="5%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XChangePointerControl</i> 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 <i>True</i> for
the pointer values to be set, or the parameters are
unchanged. Negative values (other than −1) generate a
<i>BadValue</i> error, as does a zero value for the
accel_denominator argument.</small></p>
<p><small><i>XChangePointerControl</i> can generate a
<i>BadValue</i> error.</small></p>
<p><small>To get the current pointer parameters, use
<i>XGetPointerControl</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XGetPointerControl(<i>display</i>, <i>accel_numerator_return</i>, <i>accel_denominator_return</i>,
<i> threshold_return</i>)
Display *<i>display</i>;
int *<i>accel_numerator_return</i>, *<i>accel_denominator_return</i>;
int *<i>threshold_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>accel_numerator_return</i> Returns the
numerator for the acceleration multiplier.</small></p>
<p><small><i>accel_denominator_return</i> Returns the
denominator for the acceleration multiplier.</small></p>
<p><small><i>threshold_return</i> Returns the acceleration
threshold.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetPointerControl</i> function returns
the pointer’s current acceleration multiplier and
acceleration threshold.</small></p>
<a name="12.7. Manipulating the Keyboard Encoding"></a>
<h2>12.7. Manipulating the Keyboard Encoding</h2>
<p><small>A KeyCode represents a physical (or logical) key.
KeyCodes lie in the inclusive range [8,255]. A KeyCode value
carries no intrinsic information, although server
implementors may attempt to encode geometry (for example,
matrix) information in some fashion so that it can be
interpreted in a server-dependent fashion. The mapping
between keys and KeyCodes cannot be changed.</small></p>
<p><small>A KeySym is an encoding of a symbol on the cap of
a key. The set of defined KeySyms includes the ISO Latin
character sets (1−4), Katakana, Arabic, Cyrillic,
Greek, Technical, Special, Publishing, APL, Hebrew, Thai,
Korean and a miscellany of keys found on keyboards (Return,
Help, Tab, and so on). To the extent possible, these sets
are derived from international standards. In areas where no
standards exist, some of these sets are derived from Digital
Equipment Corporation standards. The list of defined symbols
can be found in <<i>X11/keysymdef.h</i>>.
Unfortunately, some C preprocessors have limits on the
number of defined symbols. If you must use KeySyms not in
the Latin 1−4, Greek, and miscellaneous classes, you
may have to define a symbol for those sets. Most
applications usually only include
<<i>X11/keysym.h</i>>, which defines symbols for ISO
Latin 1−4, Greek, and miscellaneous.</small></p>
<p><small>A list of KeySyms is associated with each
KeyCode. The list is intended to convey the set of symbols
on the corresponding key. If the list (ignoring trailing
<i>NoSymbol</i> entries) is a single KeySym
‘‘<i>K</i>’’, then the list is
treated as if it were the list ‘‘<i>K</i>
NoSymbol <i>K</i> NoSymbol’’. If the list
(ignoring trailing <i>NoSymbol</i> entries) is a pair of
KeySyms ‘‘<i>K1 K2</i>’’, then the
list is treated as if it were the list ‘‘<i>K1
K2 K1 K2</i>’’. If the list (ignoring trailing
<i>NoSymbol</i> entries) is a triple of KeySyms
‘‘<i>K1 K2 K3</i>’’, then the list
is treated as if it were the list ‘‘<i>K1 K2
K3</i> NoSymbol’’. When an explicit
‘‘void’’ element is desired in the
list, the value <i>VoidSymbol</i> can be used.</small></p>
<p><small>The first four elements of the list are split
into two groups of KeySyms. Group 1 contains the first and
second KeySyms; Group 2 contains the third and fourth
KeySyms. Within each group, if the second element of the
group is <i>NoSymbol</i>, then the group should be treated
as if the second element were the same as the first element,
except when the first element is an alphabetic KeySym
‘‘<i>K</i>’’ for which both
lowercase and uppercase forms are defined. In that case, the
group should be treated as if the first element were the
lowercase form of ‘‘<i>K</i>’’ and
the second element were the uppercase form of
‘‘<i>K</i>’’.</small></p>
<p><small>The standard rules for obtaining a KeySym from a
<i>KeyPress</i> event make use of only the Group 1 and Group
2 KeySyms; no interpretation of other KeySyms in the list is
given. Which group to use is determined by the modifier
state. Switching between groups is controlled by the KeySym
named MODE SWITCH, by attaching that KeySym to some KeyCode
and attaching that KeyCode to any one of the modifiers
<i>Mod1</i> through <i>Mod5</i>. This modifier is called the
<i>group modifier</i>. For any KeyCode, Group 1 is used when
the group modifier is off, and Group 2 is used when the
group modifier is on.</small></p>
<p><small>The <i>Lock</i> modifier is interpreted as
CapsLock when the KeySym named XK_Caps_Lock is attached to
some KeyCode and that KeyCode is attached to the <i>Lock</i>
modifier. The <i>Lock</i> modifier is interpreted as
ShiftLock when the KeySym named XK_Shift_Lock is attached to
some KeyCode and that KeyCode is attached to the <i>Lock</i>
modifier. If the <i>Lock</i> modifier could be interpreted
as both CapsLock and ShiftLock, the CapsLock interpretation
is used.</small></p>
<p><small>The operation of keypad keys is controlled by the
KeySym named XK_Num_Lock, by attaching that KeySym to some
KeyCode and attaching that KeyCode to any one of the
modifiers <i>Mod1</i> through <i>Mod5</i>. This modifier is
called the <i>numlock modifier</i>. The standard KeySyms
with the prefix ‘‘XK_KP_’’ in their
name are called keypad KeySyms; these are KeySyms with
numeric value in the hexadecimal range 0xFF80 to 0xFFBD
inclusive. In addition, vendor-specific KeySyms in the
hexadecimal range 0x11000000 to 0x1100FFFF are also keypad
KeySyms.</small></p>
<p><small>Within a group, the choice of KeySym is
determined by applying the first rule that is satisfied from
the following list:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The numlock modifier is on and the second KeySym
is a keypad KeySym. In this case, if the <i>Shift</i>
modifier is on, or if the <i>Lock</i> modifier is on and is
interpreted as ShiftLock, then the first KeySym is used,
otherwise the second KeySym is used.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The <i>Shift</i> and <i>Lock</i> modifiers are
both off. In this case, the first KeySym is
used.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The <i>Shift</i> modifier is off, and the
<i>Lock</i> modifier is on and is interpreted as CapsLock.
In this case, the first KeySym is used, but if that KeySym
is lowercase alphabetic, then the corresponding uppercase
KeySym is used instead.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The <i>Shift</i> modifier is on, and the
<i>Lock</i> modifier is on and is interpreted as CapsLock.
In this case, the second KeySym is used, but if that KeySym
is lowercase alphabetic, then the corresponding uppercase
KeySym is used instead.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The <i>Shift</i> modifier is on, or the
<i>Lock</i> modifier is on and is interpreted as ShiftLock,
or both. In this case, the second KeySym is
used.</small></p>
</td>
</table>
<p><small>No spatial geometry of the symbols on the key is
defined by their order in the KeySym list, although a
geometry might be defined on a server-specific basis. The X
server does not use the mapping between KeyCodes and
KeySyms. Rather, it merely stores it for reading and writing
by clients.</small></p>
<p><small>To obtain the legal KeyCodes for a display, use
<i>XDisplayKeycodes</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XDisplayKeycodes(<i>display</i>, <i>min_keycodes_return</i>, <i>max_keycodes_return</i>)
Display *<i>display</i>;
int *<i>min_keycodes_return</i>, *<i>max_keycodes_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>min_keycodes_return</i> Returns the minimum
number of KeyCodes.</small></p>
<p><small><i>max_keycodes_return</i> Returns the maximum
number of KeyCodes.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XDisplayKeycodes</i> function returns the
min-keycodes and max-keycodes supported by the specified
display. The minimum number of KeyCodes returned is never
less than 8, and the maximum number of KeyCodes returned is
never greater than 255. Not all KeyCodes in this range are
required to have corresponding keys.</small></p>
<p><small>To obtain the symbols for the specified KeyCodes,
use <i>XGetKeyboardMapping</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>KeySym *XGetKeyboardMapping(<i>display</i>, <i>first_keycode</i>, <i>keycode_count</i>,
<i> keysyms_per_keycode_return</i>)
Display *<i>display</i>;
KeyCode <i>first_keycode</i>;
int <i>keycode_count</i>;
int *<i>keysyms_per_keycode_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>first_keycode</i> Specifies the first KeyCode
that is to be returned.</small></p>
<p><small><i>keycode_count</i> Specifies the number of
KeyCodes that are to be returned.</small></p>
<p><small><i>keysyms_per_keycode_return</i> Returns the
number of KeySyms per KeyCode.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetKeyboardMapping</i> function returns
the symbols for the specified number of KeyCodes starting
with first_keycode. The value specified in first_keycode
must be greater than or equal to min_keycode as returned by
<i>XDisplayKeycodes</i>, or a <i>BadValue</i> error results.
In addition, the following expression must be less than or
equal to max_keycode as returned by
<i>XDisplayKeycodes</i>:</small></p>
<pre><small> first_keycode + keycode_count − 1
</small></pre>
<p><small>If this is not the case, a <i>BadValue</i> error
results. The number of elements in the KeySyms list
is:</small></p>
<pre><small> keycode_count * keysyms_per_keycode_return
</small></pre>
<p><small>KeySym number N, counting from zero, for KeyCode
K has the following index in the list, counting from
zero:</small></p>
<pre><small> (K − first_code) * keysyms_per_code_return + N
</small></pre>
<p><small>The X server arbitrarily chooses the
keysyms_per_keycode_return value to be large enough to
report all requested symbols. A special KeySym value of
<i>NoSymbol</i> is used to fill in unused elements for
individual KeyCodes. To free the storage returned by
<i>XGetKeyboardMapping</i>, use <i>XFree</i>.</small></p>
<p><small><i>XGetKeyboardMapping</i> can generate a
<i>BadValue</i> error.</small></p>
<p><small>To change the keyboard mapping, use
<i>XChangeKeyboardMapping</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XChangeKeyboardMapping(<i>display</i>, <i>first_keycode</i>, <i>keysyms_per_keycode</i>, <i>keysyms</i>, <i>num_codes</i>)
Display *<i>display</i>;
int <i>first_keycode</i>;
int <i>keysyms_per_keycode</i>;
KeySym *<i>keysyms</i>;
int <i>num_codes</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>first_keycode</i> Specifies the first KeyCode
that is to be changed.</small></p>
<p><small><i>keysyms_per_keycode</i> Specifies the number
of KeySyms per KeyCode.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>keysyms</i></small></p>
</td>
<td width="6%"></td>
<td width="60%">
<p><small>Specifies an array of KeySyms.</small></p>
</td>
<td width="19%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>num_codes</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the number of KeyCodes that are to be
changed.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XChangeKeyboardMapping</i> 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:</small></p>
<pre><small> num_codes * keysyms_per_keycode
</small></pre>
<p><small>The specified first_keycode must be greater than
or equal to min_keycode returned by <i>XDisplayKeycodes</i>,
or a <i>BadValue</i> error results. In addition, the
following expression must be less than or equal to
max_keycode as returned by <i>XDisplayKeycodes</i>, or a
<i>BadValue</i> error results:</small></p>
<pre><small> first_keycode + num_codes − 1
</small></pre>
<p><small>KeySym number N, counting from zero, for KeyCode
K has the following index in keysyms, counting from
zero:</small></p>
<pre><small> (K − first_keycode) * keysyms_per_keycode + N
</small></pre>
<p><small>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 <i>NoSymbol</i>
should be used to fill in unused elements for individual
KeyCodes. It is legal for <i>NoSymbol</i> to appear in
nontrailing positions of the effective list for a KeyCode.
<i>XChangeKeyboardMapping</i> generates a
<i>MappingNotify</i> event.</small></p>
<p><small>There is no requirement that the X server
interpret this mapping. It is merely stored for reading and
writing by clients.</small></p>
<p><small><i>XChangeKeyboardMapping</i> can generate
<i>BadAlloc</i> and <i>BadValue</i> errors.</small></p>
<p><small>The next six functions make use of the
<i>XModifierKeymap</i> data structure, which
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int max_keypermod;</small></p>
</td>
<td width="50%">
<p><small>/* This server’s max number of keys per
modifier */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>KeyCode *modifiermap;/* An 8 by max_keypermod
array of the modifiers */</small></p>
</td>
<td width="50%">
</td>
</table>
<p><small>} XModifierKeymap;</small></p>
<p><small>│__</small></p>
<p><small>To create an <i>XModifierKeymap</i> structure,
use <i>XNewModifiermap</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XModifierKeymap *XNewModifiermap(<i>max_keys_per_mod</i>)
int <i>max_keys_per_mod</i>;
</small></pre>
<p><small><i>max_keys_per_mod</i> Specifies the number of
KeyCode entries preallocated to the modifiers in the
map.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XNewModifiermap</i> function returns a
pointer to <i>XModifierKeymap</i> structure for later
use.</small></p>
<p><small>To add a new entry to an <i>XModifierKeymap</i>
structure, use <i>XInsertModifiermapEntry</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XModifierKeymap *XInsertModifiermapEntry(<i>modmap</i>, <i>keycode_entry</i>, <i>modifier</i>)
XModifierKeymap *<i>modmap</i>;
KeyCode <i>keycode_entry</i>;
int <i>modifier</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>modmap</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the <i>XModifierKeymap</i>
structure.</small></p>
</td>
<td width="0%">
</td>
</table>
<p><small><i>keycode_entry</i> Specifies the
KeyCode.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>modifier</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the modifier.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XInsertModifiermapEntry</i> function adds
the specified KeyCode to the set that controls the specified
modifier and returns the resulting <i>XModifierKeymap</i>
structure (expanded as needed).</small></p>
<p><small>To delete an entry from an <i>XModifierKeymap</i>
structure, use <i>XDeleteModifiermapEntry</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XModifierKeymap *XDeleteModifiermapEntry(<i>modmap</i>, <i>keycode_entry</i>, <i>modifier</i>)
XModifierKeymap *<i>modmap</i>;
KeyCode <i>keycode_entry</i>;
int <i>modifier</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>modmap</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the <i>XModifierKeymap</i>
structure.</small></p>
</td>
<td width="0%">
</td>
</table>
<p><small><i>keycode_entry</i> Specifies the
KeyCode.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>modifier</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the modifier.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XDeleteModifiermapEntry</i> function
deletes the specified KeyCode from the set that controls the
specified modifier and returns a pointer to the resulting
<i>XModifierKeymap</i> structure.</small></p>
<p><small>To destroy an <i>XModifierKeymap</i> structure,
use <i>XFreeModifiermap</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XFreeModifiermap(<i>modmap</i>)
XModifierKeymap *<i>modmap</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>modmap</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the <i>XModifierKeymap</i>
structure.</small></p>
</td>
<td width="0%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XFreeModifiermap</i> function frees the
specified <i>XModifierKeymap</i> structure.</small></p>
<p><small>To set the KeyCodes to be used as modifiers, use
<i>XSetModifierMapping</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XSetModifierMapping(<i>display</i>, <i>modmap</i>)
Display *<i>display</i>;
XModifierKeymap *<i>modmap</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>modmap</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the <i>XModifierKeymap</i>
structure.</small></p>
</td>
<td width="0%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetModifierMapping</i> function specifies
the KeyCodes of the keys (if any) that are to be used as
modifiers. If it succeeds, the X server generates a
<i>MappingNotify</i> event, and <i>XSetModifierMapping</i>
returns <i>MappingSuccess</i>. X permits at most 8 modifier
keys. If more than 8 are specified in the
<i>XModifierKeymap</i> structure, a <i>BadLength</i> error
results.</small></p>
<p><small>The modifiermap member of the
<i>XModifierKeymap</i> structure contains 8 sets of
max_keypermod KeyCodes, one for each modifier in the order
<i>Shift</i>, <i>Lock</i>, <i>Control</i>, <i>Mod1</i>,
<i>Mod2</i>, <i>Mod3</i>, <i>Mod4</i>, and <i>Mod5</i>. Only
nonzero KeyCodes have meaning in each set, and zero KeyCodes
are ignored. In addition, all of the nonzero KeyCodes must
be in the range specified by min_keycode and max_keycode in
the <i>Display</i> structure, or a <i>BadValue</i> error
results.</small></p>
<p><small>An X server can impose restrictions on how
modifiers can be changed, for example, if certain keys do
not generate up transitions in hardware, if auto-repeat
cannot be disabled on certain keys, or if multiple modifier
keys are not supported. If some such restriction is
violated, the status reply is <i>MappingFailed</i>, and none
of the modifiers are changed. If the new KeyCodes specified
for a modifier differ from those currently defined and any
(current or new) keys for that modifier are in the logically
down state, <i>XSetModifierMapping</i> returns
<i>MappingBusy</i>, and none of the modifiers is
changed.</small></p>
<p><small><i>XSetModifierMapping</i> can generate
<i>BadAlloc</i> and <i>BadValue</i> errors.</small></p>
<p><small>To obtain the KeyCodes used as modifiers, use
<i>XGetModifierMapping</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XModifierKeymap *XGetModifierMapping(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetModifierMapping</i> function returns a
pointer to a newly created <i>XModifierKeymap</i> structure
that contains the keys being used as modifiers. The
structure should be freed after use by calling
<i>XFreeModifiermap</i>. If only zero values appear in the
set for any modifier, that modifier is disabled.</small></p>
<p><small><b>12</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b>Chapter 13</b></p>
<p align=center><b>Locales and Internationalized Text
Functions</b></p>
<p><small>An internationalized application is one that is
adaptable to the requirements of different native languages,
local customs, and character string encodings. The process
of adapting the operation to a particular native language,
local custom, or string encoding is called
<i>localization</i>. A goal of internationalization is to
permit localization without program source modifications or
recompilation.</small></p>
<p><small>As one of the localization mechanisms, Xlib
provides an X Input Method (<i>XIM</i>) functional interface
for internationalized text input and an X Output Method
(<i>XOM</i>) functional interface for internationalized text
output.</small></p>
<p><small>Internationalization in X is based on the concept
of a <i>locale</i>. A locale defines the localized behavior
of a program at run time. Locales affect Xlib in
its:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="88%">
<p><small>Encoding and processing of input method
text</small></p>
</td>
<td width="1%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="74%">
<p><small>Encoding of resource files and values</small></p>
</td>
<td width="15%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="72%">
<p><small>Encoding and imaging of text strings</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="86%">
<p><small>Encoding and decoding for inter-client text
communication</small></p>
</td>
<td width="3%">
</td>
</table>
<p><small>Characters from various languages are represented
in a computer using an encoding. Different languages have
different encodings, and there are even different encodings
for the same characters in the same language.</small></p>
<p><small>This chapter defines support for localized text
imaging and text input and describes the locale mechanism
that controls all locale-dependent Xlib functions. Sets of
functions are provided for multibyte (char *) text as well
as wide character (wchar_t) text in the form supported by
the host C language environment. The multibyte and wide
character functions are equivalent except for the form of
the text argument.</small></p>
<p><small>The Xlib internationalization functions are not
meant to provide support for multilingual applications
(mixing multiple languages within a single piece of text),
but they make it possible to implement applications that
work in limited fashion with more than one language in
independent contexts.</small></p>
<p><small>The remainder of this chapter
discusses:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="38%">
<p><small>X locale management</small></p>
</td>
<td width="51%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="64%">
<p><small>Locale and modifier dependencies</small></p>
</td>
<td width="25%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="46%">
<p><small>Variable argument lists</small></p>
</td>
<td width="43%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="28%">
<p><small>Output methods</small></p>
</td>
<td width="61%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="26%">
<p><small>Input methods</small></p>
</td>
<td width="63%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="32%">
<p><small>String constants</small></p>
</td>
<td width="57%">
</td>
</table>
<a name="13.1. X Locale Management"></a>
<h2>13.1. X Locale Management</h2>
<p><small>X supports one or more of the locales defined by
the host environment. On implementations that conform to the
ANSI C library, the locale announcement method is
<i>setlocale</i>. This function configures the locale
operation of both the host C library and Xlib. The operation
of Xlib is governed by the LC_CTYPE category; this is called
the <i>current locale</i>. An implementation is permitted to
provide implementation-dependent mechanisms for announcing
the locale in addition to <i>setlocale</i>.</small></p>
<p><small>On implementations that do not conform to the
ANSI C library, the locale announcement method is Xlib
implementation-dependent.</small></p>
<p><small>The mechanism by which the semantic operation of
Xlib is defined for a specific locale is
implementation-dependent.</small></p>
<p><small>X is not required to support all the locales
supported by the host. To determine if the current locale is
supported by X, use <i>XSupportsLocale</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XSupportsLocale()
</small></pre>
<p><small>│__</small></p>
<p><small>The <i>XSupportsLocale</i> function returns
<i>True</i> if Xlib functions are capable of operating under
the current locale. If it returns <i>False</i>, Xlib
locale-dependent functions for which the
<i>XLocaleNotSupported</i> return status is defined will
return <i>XLocaleNotSupported</i>. Other Xlib
locale-dependent routines will operate in the
‘‘C’’ locale.</small></p>
<p><small>The client is responsible for selecting its
locale and X modifiers. Clients should provide a means for
the user to override the clients’ locale selection at
client invocation. Most single-display X clients operate in
a single locale for both X and the host processing
environment. They will configure the locale by calling three
functions: the host locale configuration function,
<i>XSupportsLocale</i>, and
<i>XSetLocaleModifiers</i>.</small></p>
<p><small>The semantics of certain categories of X
internationalization capabilities can be configured by
setting modifiers. Modifiers are named by
implementation-dependent and locale-specific strings. The
only standard use for this capability at present is
selecting one of several styles of keyboard input
method.</small></p>
<p><small>To configure Xlib locale modifiers for the
current locale, use <i>XSetLocaleModifiers</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char *XSetLocaleModifiers(<i>modifier_list</i>)
char *<i>modifier_list</i>;
</small></pre>
<p><small><i>modifier_list</i> Specifies the
modifiers.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XSetLocaleModifiers</i> function sets the
X modifiers for the current locale setting. The
modifier_list argument is a null-terminated string of the
form
‘‘{@<i>category</i>=<i>value</i>}’’,
that is, having zero or more concatenated
‘‘@<i>category</i>=<i>value</i>’’
entries, where <i>category</i> is a category name and
<i>value</i> is the (possibly empty) setting for that
category. The values are encoded in the current locale.
Category names are restricted to the POSIX Portable Filename
Character Set.</small></p>
<p><small>The local host X locale modifiers announcer (on
POSIX-compliant systems, the XMODIFIERS environment
variable) is appended to the modifier_list to provide
default values on the local host. If a given category
appears more than once in the list, the first setting in the
list is used. If a given category is not included in the
full modifier list, the category is set to an
implementation-dependent default for the current locale. An
empty value for a category explicitly specifies the
implementation-dependent default.</small></p>
<p><small>If the function is successful, it returns a
pointer to a string. The contents of the string are such
that a subsequent call with that string (in the same locale)
will restore the modifiers to the same settings. If
modifier_list is a NULL pointer, <i>XSetLocaleModifiers</i>
also returns a pointer to such a string, and the current
locale modifiers are not changed.</small></p>
<p><small>If invalid values are given for one or more
modifier categories supported by the locale, a NULL pointer
is returned, and none of the current modifiers are
changed.</small></p>
<p><small>At program startup, the modifiers that are in
effect are unspecified until the first successful call to
set them. Whenever the locale is changed, the modifiers that
are in effect become unspecified until the next successful
call to set them. Clients should always call
<i>XSetLocaleModifiers</i> with a non-NULL modifier_list
after setting the locale before they call any
locale-dependent Xlib routine.</small></p>
<p><small>The only standard modifier category currently
defined is ‘‘im’’, which identifies
the desired input method. The values for input method are
not standardized. A single locale may use multiple input
methods, switching input method under user control. The
modifier may specify the initial input method in effect or
an ordered list of input methods. Multiple input methods may
be specified in a single im value string in an
implementation-dependent manner.</small></p>
<p><small>The returned modifiers string is owned by Xlib
and should not be modified or freed by the client. It may be
freed by Xlib after the current locale or modifiers are
changed. Until freed, it will not be modified by
Xlib.</small></p>
<p><small>The recommended procedure for clients
initializing their locale and modifiers is to obtain locale
and modifier announcers separately from one of the following
prioritized sources:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>A command line option</small></p>
</td>
<td width="47%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="20%">
<p><small>A resource</small></p>
</td>
<td width="69%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>The empty string ("")</small></p>
</td>
<td width="47%">
</td>
</table>
<p><small>The first of these that is defined should be
used. Note that when a locale command line option or locale
resource is defined, the effect should be to set all
categories to the specified locale, overriding any
category-specific settings in the local host
environment.</small></p>
<a name="13.2. Locale and Modifier Dependencies"></a>
<h2>13.2. Locale and Modifier Dependencies</h2>
<p><small>The internationalized Xlib functions operate in
the current locale configured by the host environment and X
locale modifiers set by <i>XSetLocaleModifiers</i> or in the
locale and modifiers configured at the time some object
supplied to the function was created. For each
locale-dependent function, the following table describes the
locale (and modifiers) dependency:</small></p>
<p align=center><small><img src="grohtml-1439241.png"></small></p>
<p><small>Clients may assume that a locale-encoded text
string returned by an X function can be passed to a C
library routine, or vice versa, if the locale is the same at
the two calls.</small></p>
<p><small>All text strings processed by internationalized
Xlib functions are assumed to begin in the initial state of
the encoding of the locale, if the encoding is
state-dependent.</small></p>
<p><small>All Xlib functions behave as if they do not
change the current locale or X modifier setting. (This means
that if they do change locale or call
<i>XSetLocaleModifiers</i> with a non-NULL argument, they
must save and restore the current state on entry and exit.)
Also, Xlib functions on implementations that conform to the
ANSI C library do not alter the global state associated with
the ANSI C functions <i>mblen</i>, <i>mbtowc</i>,
<i>wctomb</i>, and <i>strtok</i>.</small></p>
<a name="13.3. Variable Argument Lists"></a>
<h2>13.3. Variable Argument Lists</h2>
<p><small>Various functions in this chapter have arguments
that conform to the ANSI C variable argument list calling
convention. Each function denoted with an argument of the
form ‘‘...’’ takes a variable-length
list of name and value pairs, where each name is a string
and each value is of type <i>XPointer</i>. A name argument
that is NULL identifies the end of the list.</small></p>
<p><small>A variable-length argument list may contain a
nested list. If the name <i>XNVaNestedList</i> is specified
in place of an argument name, then the following value is
interpreted as an <i>XVaNestedList</i> value that specifies
a list of values logically inserted into the original list
at the point of declaration. A NULL identifies the end of a
nested list.</small></p>
<p><small>To allocate a nested variable argument list
dynamically, use <i>XVaCreateNestedList</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>typedef void * XVaNestedList;
XVaNestedList XVaCreateNestedList(<i>dummy</i>, ...)
int <i>dummy</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>dummy</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies an unused argument (required by ANSI
C).</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="88%">
<p><small>Specifies the variable length argument
list.</small></p>
</td>
<td width="11%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XVaCreateNestedList</i> function allocates
memory and copies its arguments into a single list pointer,
which may be used as a value for arguments requiring a list
value. Any entries are copied as specified. Data passed by
reference is not copied; the caller must ensure data remains
valid for the lifetime of the nested list. The list should
be freed using <i>XFree</i> when it is no longer
needed.</small></p>
<a name="13.4. Output Methods"></a>
<h2>13.4. Output Methods</h2>
<p><small>This section provides discussions of the
following X Output Method (XOM) topics:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="44%">
<p><small>Output method overview</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="46%">
<p><small>Output method functions</small></p>
</td>
<td width="43%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="40%">
<p><small>Output method values</small></p>
</td>
<td width="49%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="48%">
<p><small>Output context functions</small></p>
</td>
<td width="41%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>Output context values</small></p>
</td>
<td width="47%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Creating and freeing a font set</small></p>
</td>
<td width="27%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="52%">
<p><small>Obtaining font set metrics</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="56%">
<p><small>Drawing text using font sets</small></p>
</td>
<td width="33%">
</td>
</table>
<a name="13.4.1. Output Method Overview"></a>
<h2>13.4.1. Output Method Overview</h2>
<p><small>Locale-dependent text may include one or more
text components, each of which may require different fonts
and character set encodings. In some languages, each
component might have a different drawing direction, and some
components might contain context-dependent characters that
change shape based on relationships with neighboring
characters.</small></p>
<p><small>When drawing such locale-dependent text, some
locale-specific knowledge is required; for example, what
fonts are required to draw the text, how the text can be
separated into components, and which fonts are selected to
draw each component. Further, when bidirectional text must
be drawn, the internal representation order of the text must
be changed into the visual representation order to be
drawn.</small></p>
<p><small>An X Output Method provides a functional
interface so that clients do not have to deal directly with
such locale-dependent details. Output methods provide the
following capabilities:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Creating a set of fonts required to draw
locale-dependent text.</small></p>
</td>
<td width="9%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Drawing locale-dependent text with a font set
without the caller needing to be aware of locale
dependencies.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Obtaining the escapement and extents in pixels of
locale-dependent text.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Determining if bidirectional or context-dependent
drawing is required in a specific locale with a specific
font set.</small></p>
</td>
</table>
<p><small>Two different abstractions are used in the
representation of the output method for clients.</small></p>
<p><small>The abstraction used to communicate with an
output method is an opaque data structure represented by the
<i>XOM</i> data type. The abstraction for representing the
state of a particular output thread is called an <i>output
context</i>. The Xlib representation of an output context is
an <i>XOC</i>, which is compatible with <i>XFontSet</i> in
terms of its functional interface, but is a broader, more
generalized abstraction.</small></p>
<a name="13.4.2. Output Method Functions"></a>
<h2>13.4.2. Output Method Functions</h2>
<p><small>To open an output method, use
<i>XOpenOM</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XOM XOpenOM(<i>display</i>, <i>db</i>, <i>res_name</i>, <i>res_class</i>)
Display *<i>display</i>;
XrmDatabase <i>db</i>;
char *<i>res_name</i>;
char *<i>res_class</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>db</i></small></p>
</td>
<td width="16%"></td>
<td width="80%">
<p><small>Specifies a pointer to the resource
database.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>res_name</i></small></p>
</td>
<td width="4%"></td>
<td width="78%">
<p><small>Specifies the full resource name of the
application.</small></p>
</td>
<td width="1%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>res_class</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the full class name of the
application.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XOpenOM</i> function opens an output
method matching the current locale and modifiers
specification. The current locale and modifiers are bound to
the output method when <i>XOpenOM</i> is called. The locale
associated with an output method cannot be
changed.</small></p>
<p><small>The specific output method to which this call
will be routed is identified on the basis of the current
locale and modifiers. <i>XOpenOM</i> will identify a default
output method corresponding to the current locale. That
default can be modified using <i>XSetLocaleModifiers</i> to
set the output method modifier.</small></p>
<p><small>The db argument is the resource database to be
used by the output method for looking up resources that are
private to the output method. It is not intended that this
database be used to look up values that can be set as OC
values in an output context. If db is NULL, no database is
passed to the output method.</small></p>
<p><small>The res_name and res_class arguments specify the
resource name and class of the application. They are
intended to be used as prefixes by the output method when
looking up resources that are common to all output contexts
that may be created for this output method. The characters
used for resource names and classes must be in the X
Portable Character Set. The resources looked up are not
fully specified if res_name or res_class is
NULL.</small></p>
<p><small>The res_name and res_class arguments are not
assumed to exist beyond the call to <i>XOpenOM</i>. The
specified resource database is assumed to exist for the
lifetime of the output method.</small></p>
<p><small><i>XOpenOM</i> returns NULL if no output method
could be opened.</small></p>
<p><small>To close an output method, use
<i>XCloseOM</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XCloseOM(<i>om</i>)
XOM <i>om</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>om</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the output method.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XCloseOM</i> function closes the specified
output method.</small></p>
<p><small>To set output method attributes, use
<i>XSetOMValues</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char * XSetOMValues(<i>om</i>, ...)
XOM <i>om</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>om</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the output method.</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="1" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="100%">
<p><small>Specifies the variable-length argument list to
set XOM values.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetOMValues</i> function presents a
variable argument list programming interface for setting
properties or features of the specified output method. This
function returns NULL if it succeeds; otherwise, it returns
the name of the first argument that could not be
obtained.</small></p>
<p><small>No standard arguments are currently defined by
Xlib.</small></p>
<p><small>To query an output method, use
<i>XGetOMValues</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char * XGetOMValues(<i>om</i>, ...)
XOM <i>om</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>om</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the output method.</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="1" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="100%">
<p><small>Specifies the variable-length argument list to
get XOM values.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetOMValues</i> function presents a
variable argument list programming interface for querying
properties or features of the specified output method. This
function returns NULL if it succeeds; otherwise, it returns
the name of the first argument that could not be
obtained.</small></p>
<p><small>To obtain the display associated with an output
method, use <i>XDisplayOfOM</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Display * XDisplayOfOM(<i>om</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XOM <i>om</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>om</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the output method.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XDisplayOfOM</i> function returns the
display associated with the specified output
method.</small></p>
<p><small>To get the locale associated with an output
method, use <i>XLocaleOfOM</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char * XLocaleOfOM(<i>om</i>)
XOM <i>om</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>om</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the output method.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XLocaleOfOM</i> returns the locale
associated with the specified output method.</small></p>
<a name="13.4.3. X Output Method Values"></a>
<h2>13.4.3. X Output Method Values</h2>
<p><small>The following table describes how XOM values are
interpreted by an output method. The first column lists the
XOM values. The second column indicates how each of the XOM
values are treated by a particular output style.</small></p>
<p><small>The following key applies to this
table.</small></p>
<p align=center><small><img src="grohtml-1439242.png"></small></p>
<p align=center><small><img src="grohtml-1439243.png"></small></p>
<a name="13.4.3.1. Required Char Set"></a>
<h2>13.4.3.1. Required Char Set</h2>
<p><small>The <i>XNRequiredCharSet</i> argument returns the
list of charsets that are required for loading the fonts
needed for the locale. The value of the argument is a
pointer to a structure of type
<i>XOMCharSetList</i>.</small></p>
<p><small>The <i>XOMCharSetList</i> structure is defined as
follows:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int charset_count;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>char **charset_list;</small></p>
</td>
<td width="49%">
</td>
</table>
<p><small>} XOMCharSetList;</small></p>
<p><small>│__</small></p>
<p><small>The charset_list member is a list of one or more
null-terminated charset names, and the charset_count member
is the number of charset names.</small></p>
<p><small>The required charset list is owned by Xlib and
should not be modified or freed by the client. It will be
freed by a call to <i>XCloseOM</i> with the associated
<i>XOM</i>. Until freed, its contents will not be modified
by Xlib.</small></p>
<a name="13.4.3.2. Query Orientation"></a>
<h2>13.4.3.2. Query Orientation</h2>
<p><small>The <i>XNQueryOrientation</i> argument returns
the global orientation of text when drawn. Other than
<i>XOMOrientation_LTR_TTB</i>, the set of orientations
supported is locale-dependent. The value of the argument is
a pointer to a structure of type <i>XOMOrientation</i>.
Clients are responsible for freeing the
<i>XOMOrientation</i> structure by using <i>XFree</i>; this
also frees the contents of the structure.</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int num_orientation;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XOrientation *orientation;/* Input Text
description */</small></p>
</td>
<td width="49%">
</td>
</table>
<p><small>} XOMOrientation;</small></p>
<p><small>typedef enum {</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>XOMOrientation_LTR_TTB,</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>XOMOrientation_RTL_TTB,</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>XOMOrientation_TTB_LTR,</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>XOMOrientation_TTB_RTL,</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>XOMOrientation_Context</small></p>
</td>
</table>
<p><small>} XOrientation;</small></p>
<p><small>│__</small></p>
<p><small>The possible value for XOrientation may
be:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>XOMOrientation_LTR_TTB</i> left-to-right,
top-to-bottom global orientation</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>XOMOrientation_RTL_TTB</i> right-to-left,
top-to-bottom global orientation</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>XOMOrientation_TTB_LTR</i> top-to-bottom,
left-to-right global orientation</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>XOMOrientation_TTB_RTL</i> top-to-bottom,
right-to-left global orientation</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>XOMOrientation_Context</i> contextual global
orientation</small></p>
</td>
</table>
<a name="13.4.3.3. Directional Dependent Drawing"></a>
<h2>13.4.3.3. Directional Dependent Drawing</h2>
<p><small>The <i>XNDirectionalDependentDrawing</i> argument
indicates whether the text rendering functions implement
implicit handling of directional text. If this value is
<i>True</i>, the output method has knowledge of directional
dependencies and reorders text as necessary when rendering
text. If this value is <i>False</i>, the output method does
not implement any directional text handling, and all
character directions are assumed to be
left-to-right.</small></p>
<p><small>Regardless of the rendering order of characters,
the origins of all characters are on the primary draw
direction side of the drawing origin.</small></p>
<p><small>This OM value presents functionality identical to
the <i>XDirectionalDependentDrawing</i>
function.</small></p>
<a name="13.4.3.4. Context Dependent Drawing"></a>
<h2>13.4.3.4. Context Dependent Drawing</h2>
<p><small>The <i>XNContextualDrawing</i> argument indicates
whether the text rendering functions implement implicit
context-dependent drawing. If this value is <i>True</i>, the
output method has knowledge of context dependencies and
performs character shape editing, combining glyphs to
present a single character as necessary. The actual shape
editing is dependent on the locale implementation and the
font set used.</small></p>
<p><small>This OM value presents functionality identical to
the <i>XContextualDrawing</i> function.</small></p>
<a name="13.4.4. Output Context Functions"></a>
<h2>13.4.4. Output Context Functions</h2>
<p><small>An output context is an abstraction that contains
both the data required by an output method and the
information required to display that data. There can be
multiple output contexts for one output method. The
programming interfaces for creating, reading, or modifying
an output context use a variable argument list. The name
elements of the argument lists are referred to as XOC
values. It is intended that output methods be controlled by
these XOC values. As new XOC values are created, they should
be registered with the X Consortium. An <i>XOC</i> can be
used anywhere an <i>XFontSet</i> can be used, and vice
versa; <i>XFontSet</i> is retained for compatibility with
previous releases. The concepts of output methods and output
contexts include broader, more generalized abstraction than
font set, supporting complex and more intelligent text
display, and dealing not only with multiple fonts but also
with context dependencies. However, <i>XFontSet</i> is
widely used in several interfaces, so <i>XOC</i> is defined
as an upward compatible type of <i>XFontSet</i>.</small></p>
<p><small>To create an output context, use
<i>XCreateOC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XOC XCreateOC(<i>om</i>, ...)
XOM <i>om</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>om</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the output method.</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="1" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="100%">
<p><small>Specifies the variable-length argument list to
set XOC values.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XCreateOC</i> function creates an output
context within the specified output method.</small></p>
<p><small>The base font names argument is mandatory at
creation time, and the output context will not be created
unless it is provided. All other output context values can
be set later.</small></p>
<p><small><i>XCreateOC</i> returns NULL if no output
context could be created. NULL can be returned for any of
the following reasons:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="64%">
<p><small>A required argument was not set.</small></p>
</td>
<td width="25%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="58%">
<p><small>A read-only argument was set.</small></p>
</td>
<td width="31%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="70%">
<p><small>An argument name is not recognized.</small></p>
</td>
<td width="19%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The output method encountered an output method
implementation-dependent error.</small></p>
</td>
</table>
<p><small><i>XCreateOC</i> can generate a <i>BadAtom</i>
error.</small></p>
<p><small>To destroy an output context, use
<i>XDestroyOC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XDestroyOC(<i>oc</i>)
XOC <i>oc</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>oc</i></small></p>
</td>
<td width="16%"></td>
<td width="58%">
<p><small>Specifies the output context.</small></p>
</td>
<td width="21%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XDestroyOC</i> function destroys the
specified output context.</small></p>
<p><small>To get the output method associated with an
output context, use <i>XOMOfOC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XOM XOMOfOC(<i>oc</i>)
XOC <i>oc</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>oc</i></small></p>
</td>
<td width="16%"></td>
<td width="58%">
<p><small>Specifies the output context.</small></p>
</td>
<td width="21%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XOMOfOC</i> function returns the output
method associated with the specified output
context.</small></p>
<p><small>Xlib provides two functions for setting and
reading output context values, respectively,
<i>XSetOCValues</i> and <i>XGetOCValues</i>. Both functions
have a variable-length argument list. In that argument list,
any XOC value’s name must be denoted with a character
string using the X Portable Character Set.</small></p>
<p><small>To set XOC values, use
<i>XSetOCValues</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char * XSetOCValues(<i>oc</i>, ...)
XOC <i>oc</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>oc</i></small></p>
</td>
<td width="16%"></td>
<td width="58%">
<p><small>Specifies the output context.</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="1" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="100%">
<p><small>Specifies the variable-length argument list to
set XOC values.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetOCValues</i> function returns NULL if
no error occurred; otherwise, it returns the name of the
first argument that could not be set. An argument might not
be set for any of the following reasons:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="52%">
<p><small>The argument is read-only.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="72%">
<p><small>The argument name is not recognized.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="82%">
<p><small>An implementation-dependent error
occurs.</small></p>
</td>
<td width="7%">
</td>
</table>
<p><small>Each value to be set must be an appropriate
datum, matching the data type imposed by the semantics of
the argument.</small></p>
<p><small><i>XSetOCValues</i> can generate a <i>BadAtom</i>
error.</small></p>
<p><small>To obtain XOC values, use
<i>XGetOCValues</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char * XGetOCValues(<i>oc</i>, ...)
XOC <i>oc</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>oc</i></small></p>
</td>
<td width="16%"></td>
<td width="58%">
<p><small>Specifies the output context.</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="1" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="100%">
<p><small>Specifies the variable-length argument list to
get XOC values.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetOCValues</i> function returns NULL if
no error occurred; otherwise, it returns the name of the
first argument that could not be obtained. An argument might
not be obtained for any of the following
reasons:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="72%">
<p><small>The argument name is not recognized.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="82%">
<p><small>An implementation-dependent error
occurs.</small></p>
</td>
<td width="7%">
</td>
</table>
<p><small>Each argument value following a name must point
to a location where the value is to be stored.</small></p>
<a name="13.4.5. Output Context Values"></a>
<h2>13.4.5. Output Context Values</h2>
<p><small>The following table describes how XOC values are
interpreted by an output method. The first column lists the
XOC values. The second column indicates the alternative
interfaces that function identically and are provided for
compatibility with previous releases. The third column
indicates how each of the XOC values is treated.</small></p>
<p><small>The following keys apply to this
table.</small></p>
<p align=center><small><img src="grohtml-1439244.png"></small></p>
<p align=center><small><img src="grohtml-1439245.png"></small></p>
<a name="13.4.5.1. Base Font Name"></a>
<h2>13.4.5.1. Base Font Name</h2>
<p><small>The <i>XNBaseFontName</i> argument is a list of
base font names that Xlib uses to load the fonts needed for
the locale. The base font names are a comma-separated list.
The string is null-terminated and is assumed to be in the
Host Portable Character Encoding; otherwise, the result is
implementation-dependent. White space immediately on either
side of a separating comma is ignored.</small></p>
<p><small>Use of XLFD font names permits Xlib to obtain the
fonts needed for a variety of locales from a single
locale-independent base font name. The single base font name
should name a family of fonts whose members are encoded in
the various charsets needed by the locales of
interest.</small></p>
<p><small>An XLFD base font name can explicitly name a
charset needed for the locale. This allows the user to
specify an exact font for use with a charset required by a
locale, fully controlling the font selection.</small></p>
<p><small>If a base font name is not an XLFD name, Xlib
will attempt to obtain an XLFD name from the font properties
for the font. If Xlib is successful, the <i>XGetOCValues</i>
function will return this XLFD name instead of the
client-supplied name.</small></p>
<p><small>This argument must be set at creation time and
cannot be changed. If no fonts exist for any of the required
charsets, or if the locale definition in Xlib requires that
a font exist for a particular charset and a font is not
found for that charset, <i>XCreateOC</i> returns
NULL.</small></p>
<p><small>When querying for the <i>XNBaseFontName</i> XOC
value, <i>XGetOCValues</i> returns a null-terminated string
identifying the base font names that Xlib used to load the
fonts needed for the locale. This string is owned by Xlib
and should not be modified or freed by the client. The
string will be freed by a call to <i>XDestroyOC</i> with the
associated <i>XOC</i>. Until freed, the string contents will
not be modified by Xlib.</small></p>
<a name="13.4.5.2. Missing CharSet"></a>
<h2>13.4.5.2. Missing CharSet</h2>
<p><small>The <i>XNMissingCharSet</i> argument returns the
list of required charsets that are missing from the font
set. The value of the argument is a pointer to a structure
of type <i>XOMCharSetList</i>.</small></p>
<p><small>If fonts exist for all of the charsets required
by the current locale, charset_list is set to NULL and
charset_count is set to zero. If no fonts exist for one or
more of the required charsets, charset_list is set to a list
of one or more null-terminated charset names for which no
fonts exist, and charset_count is set to the number of
missing charsets. The charsets are from the list of the
required charsets for the encoding of the locale and do not
include any charsets to which Xlib may be able to remap a
required charset.</small></p>
<p><small>The missing charset list is owned by Xlib and
should not be modified or freed by the client. It will be
freed by a call to <i>XDestroyOC</i> with the associated
<i>XOC</i>. Until freed, its contents will not be modified
by Xlib.</small></p>
<a name="13.4.5.3. Default String"></a>
<h2>13.4.5.3. Default String</h2>
<p><small>When a drawing or measuring function is called
with an <i>XOC</i> that has missing charsets, some
characters in the locale will not be drawable. The
<i>XNDefaultString</i> argument returns a pointer to a
string that represents the glyphs that are drawn with this
<i>XOC</i> when the charsets of the available fonts do not
include all glyphs required to draw a character. The string
does not necessarily consist of valid characters in the
current locale and is not necessarily drawn with the fonts
loaded for the font set, but the client can draw or measure
the default glyphs by including this string in a string
being drawn or measured with the <i>XOC</i>.</small></p>
<p><small>If the <i>XNDefaultString</i> argument returned
the empty string (""), no glyphs are drawn and the
escapement is zero. The returned string is null-terminated.
It is owned by Xlib and should not be modified or freed by
the client. It will be freed by a call to <i>XDestroyOC</i>
with the associated <i>XOC</i>. Until freed, its contents
will not be modified by Xlib.</small></p>
<a name="13.4.5.4. Orientation"></a>
<h2>13.4.5.4. Orientation</h2>
<p><small>The <i>XNOrientation</i> argument specifies the
current orientation of text when drawn. The value of this
argument is one of the values returned by the
<i>XGetOMValues</i> function with the
<i>XNQueryOrientation</i> argument specified in the
<i>XOrientation</i> list. The value of the argument is of
type <i>XOrientation</i>. When <i>XNOrientation</i> is
queried, the value specifies the current orientation. When
<i>XNOrientation</i> is set, a value is used to set the
current orientation.</small></p>
<p><small>When <i>XOMOrientation_Context</i> is set, the
text orientation of the text is determined according to an
implementation-defined method (for example, ISO 6429 control
sequences), and the initial text orientation for
locale-dependent Xlib functions is assumed to be
<i>XOMOrientation_LTR_TTB</i>.</small></p>
<p><small>The <i>XNOrientation</i> value does not change
the prime drawing direction for Xlib drawing
functions.</small></p>
<a name="13.4.5.5. Resource Name and Class"></a>
<h2>13.4.5.5. Resource Name and Class</h2>
<p><small>The <i>XNResourceName</i> and
<i>XNResourceClass</i> arguments are strings that specify
the full name and class used by the client to obtain
resources for the display of the output context. These
values should be used as prefixes for name and class when
looking up resources that may vary according to the output
context. If these values are not set, the resources will not
be fully specified.</small></p>
<p><small>It is not intended that values that can be set as
XOM values be set as resources.</small></p>
<p><small>When querying for the <i>XNResourceName</i> or
<i>XNResourceClass</i> XOC value, <i>XGetOCValues</i>
returns a null-terminated string. This string is owned by
Xlib and should not be modified or freed by the client. The
string will be freed by a call to <i>XDestroyOC</i> with the
associated <i>XOC</i> or when the associated value is
changed via <i>XSetOCValues</i>. Until freed, the string
contents will not be modified by Xlib.</small></p>
<a name="13.4.5.6. Font Info"></a>
<h2>13.4.5.6. Font Info</h2>
<p><small>The <i>XNFontInfo</i> argument specifies a list
of one or more <i>XFontStruct</i> structures and font names
for the fonts used for drawing by the given output context.
The value of the argument is a pointer to a structure of
type <i>XOMFontInfo</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int num_font;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XFontStruct **font_struct_list;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>char **font_name_list;</small></p>
</td>
<td width="49%">
</td>
</table>
<p><small>} XOMFontInfo;</small></p>
<p><small>│__</small></p>
<p><small>A list of pointers to the <i>XFontStruct</i>
structures is returned to font_struct_list. A list of
pointers to null-terminated, fully-specified font name
strings in the locale of the output context is returned to
font_name_list. The font_name_list order corresponds to the
font_struct_list order. The number of <i>XFontStruct</i>
structures and font names is returned to
num_font.</small></p>
<p><small>Because it is not guaranteed that a given
character will be imaged using a single font glyph, there is
no provision for mapping a character or default string to
the font properties, font ID, or direction hint for the font
for the character. The client may access the
<i>XFontStruct</i> list to obtain these values for all the
fonts currently in use.</small></p>
<p><small>Xlib does not guarantee that fonts are loaded
from the server at the creation of an <i>XOC</i>. Xlib may
choose to cache font data, loading it only as needed to draw
text or compute text dimensions. Therefore, existence of the
per_char metrics in the <i>XFontStruct</i> structures in the
<i>XFontStructSet</i> is undefined. Also, note that all
properties in the <i>XFontStruct</i> structures are in the
STRING encoding.</small></p>
<p><small>The client must not free the <i>XOMFontInfo</i>
struct itself; it will be freed when the <i>XOC</i> is
closed.</small></p>
<a name="13.4.5.7. OM Automatic"></a>
<h2>13.4.5.7. OM Automatic</h2>
<p><small>The <i>XNOMAutomatic</i> argument returns whether
the associated output context was created by
<i>XCreateFontSet</i> or not. Because the
<i>XFreeFontSet</i> function not only destroys the output
context but also closes the implicit output method
associated with it, <i>XFreeFontSet</i> should be used with
any output context created by <i>XCreateFontSet</i>.
However, it is possible that a client does not know how the
output context was created. Before a client destroys the
output context, it can query whether <i>XNOMAutomatic</i> is
set to determine whether <i>XFreeFontSet</i> or
<i>XDestroyOC</i> should be used to destroy the output
context.</small></p>
<a name="13.4.6. Creating and Freeing a Font Set"></a>
<h2>13.4.6. Creating and Freeing a Font Set</h2>
<p><small>Xlib international text drawing is done using a
set of one or more fonts, as needed for the locale of the
text. Fonts are loaded according to a list of base font
names supplied by the client and the charsets required by
the locale. The <i>XFontSet</i> is an opaque type
representing the state of a particular output thread and is
equivalent to the type <i>XOC</i>.</small></p>
<p><small>The <i>XCreateFontSet</i> function is a
convenience function for creating an output context using
only default values. The returned <i>XFontSet</i> has an
implicitly created <i>XOM</i>. This <i>XOM</i> has an OM
value <i>XNOMAutomatic</i> automatically set to <i>True</i>
so that the output context self indicates whether it was
created by <i>XCreateOC</i> or
<i>XCreateFontSet</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XFontSet XCreateFontSet(<i>display</i>, <i>base_font_name_list</i>, <i>missing_charset_list_return</i>,
<i> missing_charset_count_return</i>, <i>def_string_return</i>)
Display *<i>display</i>;
char *<i>base_font_name_list</i>;
char ***<i>missing_charset_list_return</i>;
int *<i>missing_charset_count_return</i>;
char **<i>def_string_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>base_font_name_list</i> Specifies the base
font names.</small></p>
<p><small><i>missing_charset_list_return</i> Returns the
missing charsets.</small></p>
<p><small><i>missing_charset_count_return</i> Returns the
number of missing charsets.</small></p>
<p><small><i>def_string_return</i> Returns the string drawn
for missing charsets.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XCreateFontSet</i> function creates a font
set for the specified display. The font set is bound to the
current locale when <i>XCreateFontSet</i> is called. The
font set may be used in subsequent calls to obtain font and
character information and to image text in the locale of the
font set.</small></p>
<p><small>The base_font_name_list argument is a list of
base font names that Xlib uses to load the fonts needed for
the locale. The base font names are a comma-separated list.
The string is null-terminated and is assumed to be in the
Host Portable Character Encoding; otherwise, the result is
implementation-dependent. White space immediately on either
side of a separating comma is ignored.</small></p>
<p><small>Use of XLFD font names permits Xlib to obtain the
fonts needed for a variety of locales from a single
locale-independent base font name. The single base font name
should name a family of fonts whose members are encoded in
the various charsets needed by the locales of
interest.</small></p>
<p><small>An XLFD base font name can explicitly name a
charset needed for the locale. This allows the user to
specify an exact font for use with a charset required by a
locale, fully controlling the font selection.</small></p>
<p><small>If a base font name is not an XLFD name, Xlib
will attempt to obtain an XLFD name from the font properties
for the font. If this action is successful in obtaining an
XLFD name, the <i>XBaseFontNameListOfFontSet</i> function
will return this XLFD name instead of the client-supplied
name.</small></p>
<p><small>Xlib uses the following algorithm to select the
fonts that will be used to display text with the
<i>XFontSet</i>.</small></p>
<p><small>For each font charset required by the locale, the
base font name list is searched for the first appearance of
one of the following cases that names a set of fonts that
exist at the server:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The first XLFD-conforming base font name that
specifies the required charset or a superset of the required
charset in its <i>CharSetRegistry</i> and
<i>CharSetEncoding</i> fields. The implementation may use a
base font name whose specified charset is a superset of the
required charset, for example, an ISO8859-1 font for an
ASCII charset.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The first set of one or more XLFD-conforming base
font names that specify one or more charsets that can be
remapped to support the required charset. The Xlib
implementation may recognize various mappings from a
required charset to one or more other charsets and use the
fonts for those charsets. For example, JIS Roman is ASCII
with tilde and backslash replaced by yen and overbar; Xlib
may load an ISO8859-1 font to support this character set if
a JIS Roman font is not available.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The first XLFD-conforming font name or the first
non-XLFD font name for which an XLFD font name can be
obtained, combined with the required charset (replacing the
<i>CharSetRegistry</i> and <i>CharSetEncoding</i> fields in
the XLFD font name). As in case 1, the implementation may
use a charset that is a superset of the required
charset.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The first font name that can be mapped in some
implementation-dependent manner to one or more fonts that
support imaging text in the charset.</small></p>
</td>
</table>
<p><small>For example, assume that a locale required the
charsets:</small></p>
<pre><small>ISO8859-1
JISX0208.1983
JISX0201.1976
GB2312-1980.0
</small></pre>
<p><small>The user could supply a base_font_name_list that
explicitly specifies the charsets, ensuring that specific
fonts are used if they exist. For example:</small></p>
<pre><small>"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\
-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\
-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\
-Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1"
</small></pre>
<p><small>Alternatively, the user could supply a
base_font_name_list that omits the charsets, letting Xlib
select font charsets required for the locale. For
example:</small></p>
<pre><small>"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\
-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\
-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\
-Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"
</small></pre>
<p><small>Alternatively, the user could simply supply a
single base font name that allows Xlib to select from all
available fonts that meet certain minimum XLFD property
requirements. For example:</small></p>
<pre><small>"-*-*-*-R-Normal--*-180-100-100-*-*"
</small></pre>
<p><small>If <i>XCreateFontSet</i> is unable to create the
font set, either because there is insufficient memory or
because the current locale is not supported,
<i>XCreateFontSet</i> returns NULL,
missing_charset_list_return is set to NULL, and
missing_charset_count_return is set to zero. If fonts exist
for all of the charsets required by the current locale,
<i>XCreateFontSet</i> returns a valid <i>XFontSet</i>,
missing_charset_list_return is set to NULL, and
missing_charset_count_return is set to zero.</small></p>
<p><small>If no font exists for one or more of the required
charsets, <i>XCreateFontSet</i> sets
missing_charset_list_return to a list of one or more
null-terminated charset names for which no font exists and
sets missing_charset_count_return to the number of missing
fonts. The charsets are from the list of the required
charsets for the encoding of the locale and do not include
any charsets to which Xlib may be able to remap a required
charset.</small></p>
<p><small>If no font exists for any of the required
charsets or if the locale definition in Xlib requires that a
font exist for a particular charset and a font is not found
for that charset, <i>XCreateFontSet</i> returns NULL.
Otherwise, <i>XCreateFontSet</i> returns a valid
<i>XFontSet</i> to font_set.</small></p>
<p><small>When an Xmb/wc drawing or measuring function is
called with an <i>XFontSet</i> that has missing charsets,
some characters in the locale will not be drawable. If
def_string_return is non-NULL, <i>XCreateFontSet</i> returns
a pointer to a string that represents the glyphs that are
drawn with this <i>XFontSet</i> when the charsets of the
available fonts do not include all font glyphs required to
draw a codepoint. The string does not necessarily consist of
valid characters in the current locale and is not
necessarily drawn with the fonts loaded for the font set,
but the client can draw and measure the default glyphs by
including this string in a string being drawn or measured
with the <i>XFontSet</i>.</small></p>
<p><small>If the string returned to def_string_return is
the empty string (""), no glyphs are drawn, and
the escapement is zero. The returned string is
null-terminated. It is owned by Xlib and should not be
modified or freed by the client. It will be freed by a call
to <i>XFreeFontSet</i> with the associated <i>XFontSet</i>.
Until freed, its contents will not be modified by
Xlib.</small></p>
<p><small>The client is responsible for constructing an
error message from the missing charset and default string
information and may choose to continue operation in the case
that some fonts did not exist.</small></p>
<p><small>The returned <i>XFontSet</i> and missing charset
list should be freed with <i>XFreeFontSet</i> and
<i>XFreeStringList</i>, respectively. The client-supplied
base_font_name_list may be freed by the client after calling
<i>XCreateFontSet</i>.</small></p>
<p><small>To obtain a list of <i>XFontStruct</i> structures
and full font names given an <i>XFontSet</i>, use
<i>XFontsOfFontSet</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XFontsOfFontSet(<i>font_set</i>, <i>font_struct_list_return</i>, <i>font_name_list_return</i>)
XFontSet <i>font_set</i>;
XFontStruct ***<i>font_struct_list_return</i>;
char ***<i>font_name_list_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>font_set</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the font set.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small><i>font_struct_list_return</i> Returns the list
of font structs.</small></p>
<p><small><i>font_name_list_return</i> Returns the list of
font names.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XFontsOfFontSet</i> function returns a
list of one or more <i>XFontStructs</i> and font names for
the fonts used by the Xmb and Xwc layers for the given font
set. A list of pointers to the <i>XFontStruct</i> structures
is returned to font_struct_list_return. A list of pointers
to null-terminated, fully specified font name strings in the
locale of the font set is returned to font_name_list_return.
The font_name_list order corresponds to the font_struct_list
order. The number of <i>XFontStruct</i> structures and font
names is returned as the value of the function.</small></p>
<p><small>Because it is not guaranteed that a given
character will be imaged using a single font glyph, there is
no provision for mapping a character or default string to
the font properties, font ID, or direction hint for the font
for the character. The client may access the
<i>XFontStruct</i> list to obtain these values for all the
fonts currently in use.</small></p>
<p><small>Xlib does not guarantee that fonts are loaded
from the server at the creation of an <i>XFontSet</i>. Xlib
may choose to cache font data, loading it only as needed to
draw text or compute text dimensions. Therefore, existence
of the per_char metrics in the <i>XFontStruct</i> structures
in the <i>XFontStructSet</i> is undefined. Also, note that
all properties in the <i>XFontStruct</i> structures are in
the STRING encoding.</small></p>
<p><small>The <i>XFontStruct</i> and font name lists are
owned by Xlib and should not be modified or freed by the
client. They will be freed by a call to <i>XFreeFontSet</i>
with the associated <i>XFontSet</i>. Until freed, their
contents will not be modified by Xlib.</small></p>
<p><small>To obtain the base font name list and the
selected font name list given an <i>XFontSet</i>, use
<i>XBaseFontNameListOfFontSet</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char *XBaseFontNameListOfFontSet(<i>font_set</i>)
XFontSet <i>font_set</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>font_set</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the font set.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XBaseFontNameListOfFontSet</i> function
returns the original base font name list supplied by the
client when the <i>XFontSet</i> was created. A
null-terminated string containing a list of comma-separated
font names is returned as the value of the function. White
space may appear immediately on either side of separating
commas.</small></p>
<p><small>If <i>XCreateFontSet</i> obtained an XLFD name
from the font properties for the font specified by a
non-XLFD base name, the <i>XBaseFontNameListOfFontSet</i>
function will return the XLFD name instead of the non-XLFD
base name.</small></p>
<p><small>The base font name list is owned by Xlib and
should not be modified or freed by the client. It will be
freed by a call to <i>XFreeFontSet</i> with the associated
<i>XFontSet</i>. Until freed, its contents will not be
modified by Xlib.</small></p>
<p><small>To obtain the locale name given an
<i>XFontSet</i>, use <i>XLocaleOfFontSet</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char *XLocaleOfFontSet(<i>font_set</i>)
XFontSet <i>font_set</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>font_set</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the font set.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XLocaleOfFontSet</i> function returns the
name of the locale bound to the specified <i>XFontSet</i>,
as a null-terminated string.</small></p>
<p><small>The returned locale name string is owned by Xlib
and should not be modified or freed by the client. It may be
freed by a call to <i>XFreeFontSet</i> with the associated
<i>XFontSet</i>. Until freed, it will not be modified by
Xlib.</small></p>
<p><small>The <i>XFreeFontSet</i> function is a convenience
function for freeing an output context. <i>XFreeFontSet</i>
also frees its associated <i>XOM</i> if the output context
was created by <i>XCreateFontSet</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XFreeFontSet(<i>display</i>, <i>font_set</i>)
Display *<i>display</i>;
XFontSet <i>font_set</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>font_set</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the font set.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XFreeFontSet</i> function frees the
specified font set. The associated base font name list, font
name list, <i>XFontStruct</i> list, and
<i>XFontSetExtents</i>, if any, are freed.</small></p>
<a name="13.4.7. Obtaining Font Set Metrics"></a>
<h2>13.4.7. Obtaining Font Set Metrics</h2>
<p><small>Metrics for the internationalized text drawing
functions are defined in terms of a primary draw direction,
which is the default direction in which the character origin
advances for each succeeding character in the string. The
Xlib interface is currently defined to support only a
left-to-right primary draw direction. The drawing origin is
the position passed to the drawing function when the text is
drawn. The baseline is a line drawn through the drawing
origin parallel to the primary draw direction. Character ink
is the pixels painted in the foreground color and does not
include interline or intercharacter spacing or image text
background pixels.</small></p>
<p><small>The drawing functions are allowed to implement
implicit text directionality control, reversing the order in
which characters are rendered along the primary draw
direction in response to locale-specific lexical analysis of
the string.</small></p>
<p><small>Regardless of the character rendering order, the
origins of all characters are on the primary draw direction
side of the drawing origin. The screen location of a
particular character image may be determined with
<i>XmbTextPerCharExtents</i> or
<i>XwcTextPerCharExtents</i>.</small></p>
<p><small>The drawing functions are allowed to implement
context-dependent rendering, where the glyphs drawn for a
string are not simply a concatenation of the glyphs that
represent each individual character. A string of two
characters drawn with <i>XmbDrawString</i> may render
differently than if the two characters were drawn with
separate calls to <i>XmbDrawString</i>. If the client
appends or inserts a character in a previously drawn string,
the client may need to redraw some adjacent characters to
obtain proper rendering.</small></p>
<p><small>To find out about direction-dependent rendering,
use <i>XDirectionalDependentDrawing</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XDirectionalDependentDrawing(<i>font_set</i>)
XFontSet <i>font_set</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>font_set</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the font set.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XDirectionalDependentDrawing</i> function
returns <i>True</i> if the drawing functions implement
implicit text directionality; otherwise, it returns
<i>False</i>.</small></p>
<p><small>To find out about context-dependent rendering,
use <i>XContextualDrawing</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XContextualDrawing(<i>font_set</i>)
XFontSet <i>font_set</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>font_set</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the font set.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XContextualDrawing</i> function returns
<i>True</i> if text drawn with the font set might include
context-dependent drawing; otherwise, it returns
<i>False</i>.</small></p>
<p><small>To find out about context-dependent or
direction-dependent rendering, use
<i>XContextDependentDrawing</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XContextDependentDrawing(<i>font_set</i>)
XFontSet <i>font_set</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>font_set</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the font set.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XContextDependentDrawing</i> function
returns <i>True</i> if the drawing functions implement
implicit text directionality or if text drawn with the
font_set might include context-dependent drawing; otherwise,
it returns <i>False</i>.</small></p>
<p><small>The drawing functions do not interpret newline,
tab, or other control characters. The behavior when
nonprinting characters other than space are drawn is
implementation-dependent. It is the client’s
responsibility to interpret control characters in a text
stream.</small></p>
<p><small>The maximum character extents for the fonts that
are used by the text drawing layers can be accessed by the
<i>XFontSetExtents</i> structure:</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XRectangle max_ink_extent;/* over all drawable
characters */</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XRectangle max_logical_extent;/* over all
drawable characters */</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>} XFontSetExtents;</small></p>
<p><small>The <i>XRectangle</i> structures used to return
font set metrics are the usual Xlib screen-oriented
rectangles with x, y giving the upper left corner, and width
and height always positive.</small></p>
<p><small>The max_ink_extent member gives the maximum
extent, over all drawable characters, of the rectangles that
bound the character glyph image drawn in the foreground
color, relative to a constant origin. See
<i>XmbTextExtents</i> and <i>XwcTextExtents</i> for detailed
semantics.</small></p>
<p><small>The max_logical_extent member gives the maximum
extent, over all drawable characters, of the rectangles that
specify minimum spacing to other graphical features,
relative to a constant origin. Other graphical features
drawn by the client, for example, a border surrounding the
text, should not intersect this rectangle. The
max_logical_extent member should be used to compute minimum
interline spacing and the minimum area that must be allowed
in a text field to draw a given number of arbitrary
characters.</small></p>
<p><small>Due to context-dependent rendering, appending a
given character to a string may change the string’s
extent by an amount other than that character’s
individual extent.</small></p>
<p><small>The rectangles for a given character in a string
can be obtained from <i>XmbPerCharExtents</i> or
<i>XwcPerCharExtents</i>.</small></p>
<p><small>To obtain the maximum extents structure given an
<i>XFontSet</i>, use <i>XExtentsOfFontSet</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XFontSetExtents *XExtentsOfFontSet(<i>font_set</i>)
XFontSet <i>font_set</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>font_set</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the font set.</small></p>
</td>
<td width="33%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XExtentsOfFontSet</i> function returns an
<i>XFontSetExtents</i> structure for the fonts used by the
Xmb and Xwc layers for the given font set.</small></p>
<p><small>The <i>XFontSetExtents</i> structure is owned by
Xlib and should not be modified or freed by the client. It
will be freed by a call to <i>XFreeFontSet</i> with the
associated <i>XFontSet</i>. Until freed, its contents will
not be modified by Xlib.</small></p>
<p><small>To obtain the escapement in pixels of the
specified text as a value, use <i>XmbTextEscapement</i> or
<i>XwcTextEscapement</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XmbTextEscapement(<i>font_set</i>, <i>string</i>, <i>num_bytes</i>)
XFontSet <i>font_set</i>;
char *<i>string</i>;
int <i>num_bytes</i>;
</small></pre>
<pre><small>int XwcTextEscapement(<i>font_set</i>, <i>string</i>, <i>num_wchars</i>)
XFontSet <i>font_set</i>;
wchar_t *<i>string</i>;
int <i>num_wchars</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>font_set</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the font set.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Specifies the character string.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>num_bytes</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the number of bytes in the string
argument.</small></p>
</td>
</table>
<p><small><i>num_wchars</i> Specifies the number of
characters in the string argument.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XmbTextEscapement</i> and
<i>XwcTextEscapement</i> functions return the escapement in
pixels of the specified string as a value, using the fonts
loaded for the specified font set. The escapement is the
distance in pixels in the primary draw direction from the
drawing origin to the origin of the next character to be
drawn, assuming that the rendering of the next character is
not dependent on the supplied string.</small></p>
<p><small>Regardless of the character rendering order, the
escapement is always positive.</small></p>
<p><small>To obtain the overall_ink_return and
overall_logical_return arguments, the overall bounding box
of the string’s image, and a logical bounding box, use
<i>XmbTextExtents</i> or <i>XwcTextExtents</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XmbTextExtents(<i>font_set</i>, <i>string</i>, <i>num_bytes</i>, <i>overall_ink_return</i>, <i>overall_logical_return</i>)
XFontSet <i>font_set</i>;
char *<i>string</i>;
int <i>num_bytes</i>;
XRectangle *<i>overall_ink_return</i>;
XRectangle *<i>overall_logical_return</i>;
</small></pre>
<pre><small>int XwcTextExtents(<i>font_set</i>, <i>string</i>, <i>num_wchars</i>,
<i>overall_ink_return</i>, <i>overall_logical_return</i>)
XFontSet <i>font_set</i>;
wchar_t *<i>string</i>;
int <i>num_wchars</i>;
XRectangle *<i>overall_ink_return</i>;
XRectangle *<i>overall_logical_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>font_set</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the font set.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Specifies the character string.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>num_bytes</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the number of bytes in the string
argument.</small></p>
</td>
</table>
<p><small><i>num_wchars</i> Specifies the number of
characters in the string argument.</small></p>
<p><small><i>overall_ink_return</i> Returns the overall ink
dimensions.</small></p>
<p><small><i>overall_logical_return</i> Returns the overall
logical dimensions.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XmbTextExtents</i> and
<i>XwcTextExtents</i> functions set the components of the
specified overall_ink_return and overall_logical_return
arguments to the overall bounding box of the string’s
image and a logical bounding box for spacing purposes,
respectively. They return the value returned by
<i>XmbTextEscapement</i> or <i>XwcTextEscapement</i>. These
metrics are relative to the drawing origin of the string,
using the fonts loaded for the specified font
set.</small></p>
<p><small>If the overall_ink_return argument is non-NULL,
it is set to the bounding box of the string’s
character ink. The overall_ink_return for a nondescending,
horizontally drawn Latin character is conventionally
entirely above the baseline; that is,
overall_ink_return.height <= −overall_ink_return.y.
The overall_ink_return for a nonkerned character is entirely
at, and to the right of, the origin; that is,
overall_ink_return.x >= 0. A character consisting of a
single pixel at the origin would set overall_ink_return
fields y = 0, x = 0, width = 1, and height = 1.</small></p>
<p><small>If the overall_logical_return argument is
non-NULL, it is set to the bounding box that provides
minimum spacing to other graphical features for the string.
Other graphical features, for example, a border surrounding
the text, should not intersect this rectangle.</small></p>
<p><small>When the <i>XFontSet</i> has missing charsets,
metrics for each unavailable character are taken from the
default string returned by <i>XCreateFontSet</i> so that the
metrics represent the text as it will actually be drawn. The
behavior for an invalid codepoint is undefined.</small></p>
<p><small>To determine the effective drawing origin for a
character in a drawn string, the client should call
<i>XmbTextPerCharExtents</i> on the entire string, then on
the character, and subtract the x values of the returned
rectangles for the character. This is useful to redraw
portions of a line of text or to justify words, but for
context-dependent rendering, the client should not assume
that it can redraw the character by itself and get the same
rendering.</small></p>
<p><small>To obtain per-character information for a text
string, use <i>XmbTextPerCharExtents</i> or
<i>XwcTextPerCharExtents</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XmbTextPerCharExtents(<i>font_set</i>, <i>string</i>, <i>num_bytes</i>, <i>ink_array_return</i>,
<i> logical_array_return</i>, <i>array_size</i>, <i>num_chars_return</i>, <i>overall_ink_return</i>, <i>overall_logical_return</i>)
XFontSet <i>font_set</i>;
char *<i>string</i>;
int <i>num_bytes</i>;
XRectangle *<i>ink_array_return</i>;
XRectangle *<i>logical_array_return</i>;
int <i>array_size</i>;
int *<i>num_chars_return</i>;
XRectangle *<i>overall_ink_return</i>;
XRectangle *<i>overall_logical_return</i>;
</small></pre>
<pre><small>Status XwcTextPerCharExtents(<i>font_set</i>, <i>string</i>, <i>num_wchars</i>, <i>ink_array_return</i>,
<i> logical_array_return</i>, <i>array_size</i>, <i>num_chars_return</i>, <i>overall_ink_return</i>, <i>overall_ink_return</i>)
XFontSet <i>font_set</i>;
wchar_t *<i>string</i>;
int <i>num_wchars</i>;
XRectangle *<i>ink_array_return</i>;
XRectangle *<i>logical_array_return</i>;
int <i>array_size</i>;
int *<i>num_chars_return</i>;
XRectangle *<i>overall_ink_return</i>;
XRectangle *<i>overall_logical_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>font_set</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the font set.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Specifies the character string.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>num_bytes</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the number of bytes in the string
argument.</small></p>
</td>
</table>
<p><small><i>num_wchars</i> Specifies the number of
characters in the string argument.</small></p>
<p><small><i>ink_array_return</i> Returns the ink
dimensions for each character.</small></p>
<p><small><i>logical_array_return</i> Returns the logical
dimensions for each character.</small></p>
<p><small><i>array_size</i> Specifies the size of
ink_array_return and logical_array_return. The caller must
pass in arrays of this size.</small></p>
<p><small><i>num_chars_return</i> Returns the number of
characters in the string argument.</small></p>
<p><small><i>overall_ink_return</i> Returns the overall ink
extents of the entire string.</small></p>
<p><small><i>overall_logical_return</i> Returns the overall
logical extents of the entire string.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XmbTextPerCharExtents</i> and
<i>XwcTextPerCharExtents</i> functions return the text
dimensions of each character of the specified text, using
the fonts loaded for the specified font set. Each successive
element of ink_array_return and logical_array_return is set
to the successive character’s drawn metrics, relative
to the drawing origin of the string and one rectangle for
each character in the supplied text string. The number of
elements of ink_array_return and logical_array_return that
have been set is returned to num_chars_return.</small></p>
<p><small>Each element of ink_array_return is set to the
bounding box of the corresponding character’s drawn
foreground color. Each element of logical_array_return is
set to the bounding box that provides minimum spacing to
other graphical features for the corresponding character.
Other graphical features should not intersect any of the
logical_array_return rectangles.</small></p>
<p><small>Note that an <i>XRectangle</i> represents the
effective drawing dimensions of the character, regardless of
the number of font glyphs that are used to draw the
character or the direction in which the character is drawn.
If multiple characters map to a single character glyph, the
dimensions of all the <i>XRectangles</i> of those characters
are the same.</small></p>
<p><small>When the <i>XFontSet</i> has missing charsets,
metrics for each unavailable character are taken from the
default string returned by <i>XCreateFontSet</i> so that the
metrics represent the text as it will actually be drawn. The
behavior for an invalid codepoint is undefined.</small></p>
<p><small>If the array_size is too small for the number of
characters in the supplied text, the functions return zero
and num_chars_return is set to the number of rectangles
required. Otherwise, the functions return a nonzero
value.</small></p>
<p><small>If the overall_ink_return or
overall_logical_return argument is non-NULL,
<i>XmbTextPerCharExtents</i> and
<i>XwcTextPerCharExtents</i> return the maximum extent of
the string’s metrics to overall_ink_return or
overall_logical_return, as returned by <i>XmbTextExtents</i>
or <i>XwcTextExtents</i>.</small></p>
<a name="13.4.8. Drawing Text Using Font Sets"></a>
<h2>13.4.8. Drawing Text Using Font Sets</h2>
<p><small>The functions defined in this section draw text
at a specified location in a drawable. They are similar to
the functions <i>XDrawText</i>, <i>XDrawString</i>, and
<i>XDrawImageString</i> except that they work with font sets
instead of single fonts and interpret the text based on the
locale of the font set instead of treating the bytes of the
string as direct font indexes. See section 8.6 for details
of the use of Graphics Contexts (GCs) and possible protocol
errors. If a <i>BadFont</i> error is generated, characters
prior to the offending character may have been
drawn.</small></p>
<p><small>The text is drawn using the fonts loaded for the
specified font set; the font in the GC is ignored and may be
modified by the functions. No validation that all fonts
conform to some width rule is performed.</small></p>
<p><small>The text functions <i>XmbDrawText</i> and
<i>XwcDrawText</i> use the following structures:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>char *chars;</small></p>
</td>
<td width="50%">
<p><small>/* pointer to string */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int nchars;</small></p>
</td>
<td width="50%">
<p><small>/* number of bytes */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int delta;</small></p>
</td>
<td width="50%">
<p><small>/* pixel delta between strings */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XFontSet font_set;</small></p>
</td>
<td width="50%">
<p><small>/* fonts, None means don’t change
*/</small></p>
</td>
</table>
<p><small>} XmbTextItem;</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>wchar_t *chars;</small></p>
</td>
<td width="50%">
<p><small>/* pointer to wide char string */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int nchars;</small></p>
</td>
<td width="50%">
<p><small>/* number of wide characters */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int delta;</small></p>
</td>
<td width="50%">
<p><small>/* pixel delta between strings */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XFontSet font_set;</small></p>
</td>
<td width="50%">
<p><small>/* fonts, None means don’t change
*/</small></p>
</td>
</table>
<p><small>} XwcTextItem;</small></p>
<p><small>│__</small></p>
<p><small>To draw text using multiple font sets in a given
drawable, use <i>XmbDrawText</i> or
<i>XwcDrawText</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XmbDrawText(<i>display</i>, <i>d</i>, <i>gc</i>, <i>x</i>, <i>y</i>, <i>items</i>, <i>nitems</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
int <i>x</i>, <i>y</i>;
XmbTextItem *<i>items</i>;
int <i>nitems</i>;
</small></pre>
<pre><small>void XwcDrawText(<i>display</i>, <i>d</i>, <i>gc</i>, <i>x</i>, <i>y</i>, <i>items</i>, <i>nitems</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
GC <i>gc</i>;
int <i>x</i>, <i>y</i>;
XwcTextItem *<i>items</i>;
int <i>nitems</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="64%">
<p><small>Specify the x and y coordinates.</small></p>
</td>
<td width="15%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>items</i></small></p>
</td>
<td width="10%"></td>
<td width="66%">
<p><small>Specifies an array of text items.</small></p>
</td>
<td width="13%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>nitems</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the number of text items in the
array.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XmbDrawText</i> and <i>XwcDrawText</i>
functions allow complex spacing and font set shifts between
text strings. Each text item is processed in turn, with the
origin of a text element advanced in the primary draw
direction by the escapement of the previous text item. A
text item delta specifies an additional escapement of the
text item drawing origin in the primary draw direction. A
font_set member other than <i>None</i> in an item causes the
font set to be used for this and subsequent text items in
the text_items list. Leading text items with a font_set
member set to <i>None</i> will not be drawn.</small></p>
<p><small><i>XmbDrawText</i> and <i>XwcDrawText</i> do not
perform any context-dependent rendering between text
segments. Clients may compute the drawing metrics by passing
each text segment to <i>XmbTextExtents</i> and
<i>XwcTextExtents</i> or <i>XmbTextPerCharExtents</i> and
<i>XwcTextPerCharExtents</i>. When the <i>XFontSet</i> has
missing charsets, each unavailable character is drawn with
the default string returned by <i>XCreateFontSet</i>. The
behavior for an invalid codepoint is undefined.</small></p>
<p><small>To draw text using a single font set in a given
drawable, use <i>XmbDrawString</i> or
<i>XwcDrawString</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XmbDrawString(<i>display</i>, <i>d</i>, <i>font_set</i>, <i>gc</i>, <i>x</i>, <i>y</i>, <i>string</i>, <i>num_bytes</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
XFontSet <i>font_set</i>;
GC <i>gc</i>;
int <i>x</i>, <i>y</i>;
char *<i>string</i>;
int <i>num_bytes</i>;
</small></pre>
<pre><small>void XwcDrawString(<i>display</i>, <i>d</i>, <i>font_set</i>, <i>gc</i>, <i>x</i>, <i>y</i>, <i>string</i>, <i>num_wchars</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
XFontSet <i>font_set</i>;
GC <i>gc</i>;
int <i>x</i>, <i>y</i>;
wchar_t *<i>string</i>;
int <i>num_wchars</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>font_set</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the font set.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="64%">
<p><small>Specify the x and y coordinates.</small></p>
</td>
<td width="15%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Specifies the character string.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>num_bytes</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the number of bytes in the string
argument.</small></p>
</td>
</table>
<p><small><i>num_wchars</i> Specifies the number of
characters in the string argument.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XmbDrawString</i> and <i>XwcDrawString</i>
functions draw the specified text with the foreground pixel.
When the <i>XFontSet</i> has missing charsets, each
unavailable character is drawn with the default string
returned by <i>XCreateFontSet</i>. The behavior for an
invalid codepoint is undefined.</small></p>
<p><small>To draw image text using a single font set in a
given drawable, use <i>XmbDrawImageString</i> or
<i>XwcDrawImageString</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XmbDrawImageString(<i>display</i>, <i>d</i>, <i>font_set</i>, <i>gc</i>, <i>x</i>, <i>y</i>, <i>string</i>, <i>num_bytes</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
XFontSet <i>font_set</i>;
GC <i>gc</i>;
int <i>x</i>, <i>y</i>;
char *<i>string</i>;
int <i>num_bytes</i>;
</small></pre>
<pre><small>void XwcDrawImageString(<i>display</i>, <i>d</i>, <i>font_set</i>, <i>gc</i>, <i>x</i>, <i>y</i>, <i>string</i>, <i>num_wchars</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
XFontSet <i>font_set</i>;
GC <i>gc</i>;
int <i>x</i>, <i>y</i>;
wchar_t *<i>string</i>;
int <i>num_wchars</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>font_set</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the font set.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="64%">
<p><small>Specify the x and y coordinates.</small></p>
</td>
<td width="15%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Specifies the character string.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>num_bytes</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the number of bytes in the string
argument.</small></p>
</td>
</table>
<p><small><i>num_wchars</i> Specifies the number of
characters in the string argument.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XmbDrawImageString</i> and
<i>XwcDrawImageString</i> functions fill a destination
rectangle with the background pixel defined in the GC and
then paint the text with the foreground pixel. The filled
rectangle is the rectangle returned to
overall_logical_return by <i>XmbTextExtents</i> or
<i>XwcTextExtents</i> for the same text and
<i>XFontSet</i>.</small></p>
<p><small>When the <i>XFontSet</i> has missing charsets,
each unavailable character is drawn with the default string
returned by <i>XCreateFontSet</i>. The behavior for an
invalid codepoint is undefined.</small></p>
<a name="13.5. Input Methods"></a>
<h2>13.5. Input Methods</h2>
<p><small>This section provides discussions of the
following X Input Method (XIM) topics:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>Input method overview</small></p>
</td>
<td width="47%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="46%">
<p><small>Input method management</small></p>
</td>
<td width="43%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="44%">
<p><small>Input method functions</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="38%">
<p><small>Input method values</small></p>
</td>
<td width="51%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="46%">
<p><small>Input context functions</small></p>
</td>
<td width="43%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="40%">
<p><small>Input context values</small></p>
</td>
<td width="49%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Input method callback semantics</small></p>
</td>
<td width="27%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="30%">
<p><small>Event filtering</small></p>
</td>
<td width="59%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="44%">
<p><small>Getting keyboard input</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="48%">
<p><small>Input method conventions</small></p>
</td>
<td width="41%">
</td>
</table>
<a name="13.5.1. Input Method Overview"></a>
<h2>13.5.1. Input Method Overview</h2>
<p><small>This section provides definitions for terms and
concepts used for internationalized text input and a brief
overview of the intended use of the mechanisms provided by
Xlib.</small></p>
<p><small>A large number of languages in the world use
alphabets consisting of a small set of symbols (letters) to
form words. To enter text into a computer in an alphabetic
language, a user usually has a keyboard on which there exist
key symbols corresponding to the alphabet. Sometimes, a few
characters of an alphabetic language are missing on the
keyboard. Many computer users who speak a
Latin-alphabet-based language only have an English-based
keyboard. They need to hit a combination of keystrokes to
enter a character that does not exist directly on the
keyboard. A number of algorithms have been developed for
entering such characters. These are known as European input
methods, compose input methods, or dead-key input
methods.</small></p>
<p><small>Japanese is an example of a language with a
phonetic symbol set, where each symbol represents a specific
sound. There are two phonetic symbol sets in Japanese:
Katakana and Hiragana. In general, Katakana is used for
words that are of foreign origin, and Hiragana is used for
writing native Japanese words. Collectively, the two systems
are called Kana. Each set consists of 48
characters.</small></p>
<p><small>Korean also has a phonetic symbol set, called
Hangul. Each of the 24 basic phonetic symbols (14 consonants
and 10 vowels) represents a specific sound. A syllable is
composed of two or three parts: the initial consonants, the
vowels, and the optional last consonants. With Hangul,
syllables can be treated as the basic units on which text
processing is done. For example, a delete operation may work
on a phonetic symbol or a syllable. Korean code sets include
several thousands of these syllables. A user types the
phonetic symbols that make up the syllables of the words to
be entered. The display may change as each phonetic symbol
is entered. For example, when the second phonetic symbol of
a syllable is entered, the first phonetic symbol may change
its shape and size. Likewise, when the third phonetic symbol
is entered, the first two phonetic symbols may change their
shape and size.</small></p>
<p><small>Not all languages rely solely on alphabetic or
phonetic systems. Some languages, including Japanese and
Korean, employ an ideographic writing system. In an
ideographic system, rather than taking a small set of
symbols and combining them in different ways to create
words, each word consists of one unique symbol (or,
occasionally, several symbols). The number of symbols can be
very large: approximately 50,000 have been identified in
Hanzi, the Chinese ideographic system.</small></p>
<p><small>Two major aspects of ideographic systems impact
their use with computers. First, the standard computer
character sets in Japan, China, and Korea include roughly
8,000 characters, while sets in Taiwan have between 15,000
and 30,000 characters. This makes it necessary to use more
than one byte to represent a character. Second, it obviously
is impractical to have a keyboard that includes all of a
given language’s ideographic symbols. Therefore, a
mechanism is required for entering characters so that a
keyboard with a reasonable number of keys can be used. Those
input methods are usually based on phonetics, but there also
exist methods based on the graphical properties of
characters.</small></p>
<p><small>In Japan, both Kana and the ideographic system
Kanji are used. In Korea, Hangul and sometimes the
ideographic system Hanja are used. Now consider entering
ideographs in Japan, Korea, China, and Taiwan.</small></p>
<p><small>In Japan, either Kana or English characters are
typed and then a region is selected (sometimes
automatically) for conversion to Kanji. Several Kanji
characters may have the same phonetic representation. If
that is the case with the string entered, a menu of
characters is presented and the user must choose the
appropriate one. If no choice is necessary or a preference
has been established, the input method does the substitution
directly. When Latin characters are converted to Kana or
Kanji, it is called a romaji conversion.</small></p>
<p><small>In Korea, it is usually acceptable to keep Korean
text in Hangul form, but some people may choose to write
Hanja-originated words in Hanja rather than in Hangul. To
change Hangul to Hanja, the user selects a region for
conversion and then follows the same basic method as that
described for Japanese.</small></p>
<p><small>Probably because there are well-accepted phonetic
writing systems for Japanese and Korean, computer input
methods in these countries for entering ideographs are
fairly standard. Keyboard keys have both English characters
and phonetic symbols engraved on them, and the user can
switch between the two sets.</small></p>
<p><small>The situation is different for Chinese. While
there is a phonetic system called Pinyin promoted by
authorities, there is no consensus for entering Chinese
text. Some vendors use a phonetic decomposition (Pinyin or
another), others use ideographic decomposition of Chinese
words, with various implementations and keyboard layouts.
There are about 16 known methods, none of which is a clear
standard.</small></p>
<p><small>Also, there are actually two ideographic sets
used: Traditional Chinese (the original written Chinese) and
Simplified Chinese. Several years ago, the People’s
Republic of China launched a campaign to simplify some
ideographic characters and eliminate redundancies
altogether. Under the plan, characters would be streamlined
every five years. Characters have been revised several times
now, resulting in the smaller, simpler set that makes up
Simplified Chinese.</small></p>
<a name="13.5.1.1. Input Method Architecture"></a>
<h2>13.5.1.1. Input Method Architecture</h2>
<p><small>As shown in the previous section, there are many
different input methods in use today, each varying with
language, culture, and history. A common feature of many
input methods is that the user may type multiple keystrokes
to compose a single character (or set of characters). The
process of composing characters from keystrokes is called
<i>preediting</i>. It may require complex algorithms and
large dictionaries involving substantial computer
resources.</small></p>
<p><small>Input methods may require one or more areas in
which to show the feedback of the actual keystrokes, to
propose disambiguation to the user, to list dictionaries,
and so on. The input method areas of concern are as
follows:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The <i>status</i> area is a logical extension of
the LEDs that exist on the physical keyboard. It is a window
that is intended to present the internal state of the input
method that is critical to the user. The status area may
consist of text data and bitmaps or some
combination.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The <i>preedit</i> area displays the intermediate
text for those languages that are composing prior to the
client handling the data.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The <i>auxiliary</i> area is used for pop-up
menus and customizing dialogs that may be required for an
input method. There may be multiple auxiliary areas for an
input method. Auxiliary areas are managed by the input
method independent of the client. Auxiliary areas are
assumed to be separate dialogs, which are maintained by the
input method.</small></p>
</td>
</table>
<p><small>There are various user interaction styles used
for preediting. The ones supported by Xlib are as
follows:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>For <i>on-the-spot</i> input methods, preediting
data will be displayed directly in the application window.
Application data is moved to allow preedit data to appear at
the point of insertion.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>Over-the-spot</i> preediting means that the
data is displayed in a preedit window that is placed over
the point of insertion.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>Off-the-spot</i> preediting means that the
preedit window is inside the application window but not at
the point of insertion. Often, this type of window is placed
at the bottom of the application window.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small><i>Root-window</i> preediting refers to input
methods that use a preedit window that is the child of
<i>RootWindow</i>.</small></p>
</td>
</table>
<p><small>It would require a lot of computing resources if
portable applications had to include input methods for all
the languages in the world. To avoid this, a goal of the
Xlib design is to allow an application to communicate with
an input method placed in a separate process. Such a process
is called an <i>input server</i>. The server to which the
application should connect is dependent on the environment
when the application is started up, that is, the user
language and the actual encoding to be used for it. The
input method connection is said to be
<i>locale-dependent</i>. It is also user-dependent. For a
given language, the user can choose, to some extent, the
user interface style of input method (if choice is possible
among several).</small></p>
<p><small>Using an input server implies communication
overhead, but applications can be migrated without
relinking. Input methods can be implemented either as a stub
communicating to an input server or as a local
library.</small></p>
<p><small>An input method may be based on a
<i>front-end</i> or a <i>back-end</i> architecture. In a
front-end architecture, there are two separate connections
to the X server: keystrokes go directly from the X server to
the input method on one connection and other events to the
regular client connection. The input method is then acting
as a filter and sends composed strings to the client. A
front-end architecture requires synchronization between the
two connections to avoid lost key events or locking
issues.</small></p>
<p><small>In a back-end architecture, a single X server
connection is used. A dispatching mechanism must decide on
this channel to delegate appropriate keystrokes to the input
method. For instance, it may retain a Help keystroke for its
own purpose. In the case where the input method is a
separate process (that is, a server), there must be a
special communication protocol between the back-end client
and the input server.</small></p>
<p><small>A front-end architecture introduces
synchronization issues and a filtering mechanism for
noncharacter keystrokes (Function keys, Help, and so on). A
back-end architecture sometimes implies more communication
overhead and more process switching. If all three processes
(X server, input server, client) are running on a single
workstation, there are two process switches for each
keystroke in a back-end architecture, but there is only one
in a front-end architecture.</small></p>
<p><small>The abstraction used by a client to communicate
with an input method is an opaque data structure represented
by the <i>XIM</i> data type. This data structure is returned
by the <i>XOpenIM</i> function, which opens an input method
on a given display. Subsequent operations on this data
structure encapsulate all communication between client and
input method. There is no need for an X client to use any
networking library or natural language package to use an
input method.</small></p>
<p><small>A single input server may be used for one or more
languages, supporting one or more encoding schemes. But the
strings returned from an input method will always be encoded
in the (single) locale associated with the <i>XIM</i>
object.</small></p>
<a name="13.5.1.2. Input Contexts"></a>
<h2>13.5.1.2. Input Contexts</h2>
<p><small>Xlib provides the ability to manage a
multi-threaded state for text input. A client may be using
multiple windows, each window with multiple text entry
areas, and the user possibly switching among them at any
time. The abstraction for representing the state of a
particular input thread is called an <i>input context</i>.
The Xlib representation of an input context is an
<i>XIC</i>.</small></p>
<p><small>An input context is the abstraction retaining the
state, properties, and semantics of communication between a
client and an input method. An input context is a
combination of an input method, a locale specifying the
encoding of the character strings to be returned, a client
window, internal state information, and various layout or
appearance characteristics. The input context concept
somewhat matches for input the graphics context abstraction
defined for graphics output.</small></p>
<p><small>One input context belongs to exactly one input
method. Different input contexts may be associated with the
same input method, possibly with the same client window. An
<i>XIC</i> is created with the <i>XCreateIC</i> function,
providing an <i>XIM</i> argument and affiliating the input
context to the input method for its lifetime. When an input
method is closed with <i>XCloseIM</i>, all of its affiliated
input contexts should not be used any more (and should
preferably be destroyed before closing the input
method).</small></p>
<p><small>Considering the example of a client window with
multiple text entry areas, the application programmer could,
for example, choose to implement as follows:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>As many input contexts are created as text entry
areas, and the client will get the input accumulated on each
context each time it looks up in that context.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>A single context is created for a top-level
window in the application. If such a window contains several
text entry areas, each time the user moves to another text
entry area, the client has to indicate changes in the
context.</small></p>
</td>
</table>
<p><small>A range of choices can be made by application
designers to use either a single or multiple input contexts,
according to the needs of their application.</small></p>
<a name="13.5.1.3. Getting Keyboard Input"></a>
<h2>13.5.1.3. Getting Keyboard Input</h2>
<p><small>To obtain characters from an input method, a
client must call the function <i>XmbLookupString</i> or
<i>XwcLookupString</i> with an input context created from
that input method. Both a locale and display are bound to an
input method when it is opened, and an input context
inherits this locale and display. Any strings returned by
<i>XmbLookupString</i> or <i>XwcLookupString</i> will be
encoded in that locale.</small></p>
<a name="13.5.1.4. Focus Management"></a>
<h2>13.5.1.4. Focus Management</h2>
<p><small>For each text entry area in which the
<i>XmbLookupString</i> or <i>XwcLookupString</i> functions
are used, there will be an associated input
context.</small></p>
<p><small>When the application focus moves to a text entry
area, the application must set the input context focus to
the input context associated with that area. The input
context focus is set by calling <i>XSetICFocus</i> with the
appropriate input context.</small></p>
<p><small>Also, when the application focus moves out of a
text entry area, the application should unset the focus for
the associated input context by calling
<i>XUnsetICFocus</i>. As an optimization, if
<i>XSetICFocus</i> is called successively on two different
input contexts, setting the focus on the second will
automatically unset the focus on the first.</small></p>
<p><small>To set and unset the input context focus
correctly, it is necessary to track application-level focus
changes. Such focus changes do not necessarily correspond to
X server focus changes.</small></p>
<p><small>If a single input context is being used to do
input for multiple text entry areas, it will also be
necessary to set the focus window of the input context
whenever the focus window changes (see section
13.5.6.3).</small></p>
<a name="13.5.1.5. Geometry Management"></a>
<h2>13.5.1.5. Geometry Management</h2>
<p><small>In most input method architectures (on-the-spot
being the notable exception), the input method will perform
the display of its own data. To provide better visual
locality, it is often desirable to have the input method
areas embedded within a client. To do this, the client may
need to allocate space for an input method. Xlib provides
support that allows the size and position of input method
areas to be provided by a client. The input method areas
that are supported for geometry management are the status
area and the preedit area.</small></p>
<p><small>The fundamental concept on which geometry
management for input method windows is based is the proper
division of responsibilities between the client (or toolkit)
and the input method. The division of responsibilities is as
follows:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The client is responsible for the geometry of the
input method window.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The input method is responsible for the contents
of the input method window.</small></p>
</td>
</table>
<p><small>An input method is able to suggest a size to the
client, but it cannot suggest a placement. Also the input
method can only suggest a size. It does not determine the
size, and it must accept the size it is given.</small></p>
<p><small>Before a client provides geometry management for
an input method, it must determine if geometry management is
needed. The input method indicates the need for geometry
management by setting <i>XIMPreeditArea</i> or
<i>XIMStatusArea</i> in its <i>XIMStyles</i> value returned
by <i>XGetIMValues</i>. When a client has decided that it
will provide geometry management for an input method, it
indicates that decision by setting the <i>XNInputStyle</i>
value in the <i>XIC</i>.</small></p>
<p><small>After a client has established with the input
method that it will do geometry management, the client must
negotiate the geometry with the input method. The geometry
is negotiated by the following steps:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The client suggests an area to the input method
by setting the <i>XNAreaNeeded</i> value for that area. If
the client has no constraints for the input method, it
either will not suggest an area or will set the width and
height to zero. Otherwise, it will set one of the
values.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The client will get the XIC value
<i>XNAreaNeeded</i>. The input method will return its
suggested size in this value. The input method should pay
attention to any constraints suggested by the
client.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The client sets the XIC value <i>XNArea</i> to
inform the input method of the geometry of its window. The
client should try to honor the geometry requested by the
input method. The input method must accept this
geometry.</small></p>
</td>
</table>
<p><small>Clients doing geometry management must be aware
that setting other XIC values may affect the geometry
desired by an input method. For example, <i>XNFontSet</i>
and <i>XNLineSpacing</i> may change the geometry desired by
the input method.</small></p>
<p><small>The table of XIC values (see section 13.5.6)
indicates the values that can cause the desired geometry to
change when they are set. It is the responsibility of the
client to renegotiate the geometry of the input method
window when it is needed.</small></p>
<p><small>In addition, a geometry management callback is
provided by which an input method can initiate a geometry
change.</small></p>
<a name="13.5.1.6. Event Filtering"></a>
<h2>13.5.1.6. Event Filtering</h2>
<p><small>A filtering mechanism is provided to allow input
methods to capture X events transparently to clients. It is
expected that toolkits (or clients) using
<i>XmbLookupString</i> or <i>XwcLookupString</i> will call
this filter at some point in the event processing mechanism
to make sure that events needed by an input method can be
filtered by that input method.</small></p>
<p><small>If there were no filter, a client could receive
and discard events that are necessary for the proper
functioning of an input method. The following provides a few
examples of such events:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Expose events on preedit window in local
mode.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Events may be used by an input method to
communicate with an input server. Such input server
protocol-related events have to be intercepted if one does
not want to disturb client code.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Key events can be sent to a filter before they
are bound to translations such as those the X Toolkit
Intrinsics library provides.</small></p>
</td>
</table>
<p><small>Clients are expected to get the XIC value
<i>XNFilterEvents</i> and augment the event mask for the
client window with that event mask. This mask may be
zero.</small></p>
<a name="13.5.1.7. Callbacks"></a>
<h2>13.5.1.7. Callbacks</h2>
<p><small>When an on-the-spot input method is implemented,
only the client can insert or delete preedit data in place
and possibly scroll existing text. This means that the echo
of the keystrokes has to be achieved by the client itself,
tightly coupled with the input method logic.</small></p>
<p><small>When the user enters a keystroke, the client
calls <i>XmbLookupString</i> or <i>XwcLookupString</i>. At
this point, in the on-the-spot case, the echo of the
keystroke in the preedit has not yet been done. Before
returning to the client logic that handles the input
characters, the look-up function must call the echoing logic
to insert the new keystroke. If the keystrokes entered so
far make up a character, the keystrokes entered need to be
deleted, and the composed character will be returned. Hence,
what happens is that, while being called by client code, the
input method logic has to call back to the client before it
returns. The client code, that is, a callback procedure, is
called from the input method logic.</small></p>
<p><small>There are a number of cases where the input
method logic has to call back the client. Each of those
cases is associated with a well-defined callback action. It
is possible for the client to specify, for each input
context, what callback is to be called for each
action.</small></p>
<p><small>There are also callbacks provided for feedback of
status information and a callback to initiate a geometry
request for an input method.</small></p>
<a name="13.5.1.8. Visible Position Feedback Masks"></a>
<h2>13.5.1.8. Visible Position Feedback Masks</h2>
<p><small>In the on-the-spot input style, there is a
problem when attempting to draw preedit strings that are
longer than the available space. Once the display area is
exceeded, it is not clear how best to display the preedit
string. The visible position feedback masks of
<i>XIMText</i> help resolve this problem by allowing the
input method to specify hints that indicate the essential
portions of the preedit string. For example, such hints can
help developers implement scrolling of a long preedit string
within a short preedit display area.</small></p>
<a name="13.5.1.9. Preedit String Management"></a>
<h2>13.5.1.9. Preedit String Management</h2>
<p><small>As highlighted before, the input method
architecture provides preediting, which supports a type of
preprocessor input composition. In this case, composition
consists of interpreting a sequence of key events and
returning a committed string via <i>XmbLookupString</i> or
<i>XwcLookupString</i>. This provides the basics for input
methods.</small></p>
<p><small>In addition to preediting based on key events, a
general framework is provided to give a client that desires
it more advanced preediting based on the text within the
client. This framework is called <i>string conversion</i>
and is provided using XIC values. The fundamental concept of
string conversion is to allow the input method to manipulate
the client’s text independent of any user preediting
operation.</small></p>
<p><small>The need for string conversion is based on
language needs and input method capabilities. The following
are some examples of string conversion:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Transliteration conversion provides
language-specific conversions within the input method. In
the case of Korean input, users wish to convert a Hangul
string into a Hanja string while in preediting, after
preediting, or in other situations (for example, on a
selected string). The conversion is triggered when the user
presses a Hangul-to-Hanja key sequence (which may be input
method specific). Sometimes the user may want to invoke the
conversion after finishing preediting or on a user-selected
string. Thus, the string to be converted is in an
application buffer, not in the preedit area of the input
method. The string conversion services allow the client to
request this transliteration conversion from the input
method. There are many other transliteration conversions
defined for various languages, for example, Kana-to-Kanji
conversion in Japanese.</small></p>
</td>
</table>
<p><small>The key to remember is that transliteration
conversions are triggered at the request of the user and
returned to the client immediately without affecting the
preedit area of the input method.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Reconversion of a previously committed string or
a selected string is supported by many input methods as a
convenience to the user. For example, a user tends to
mistype the commit key while preediting. In that case, some
input methods provide a special key sequence to request a
‘‘reconvert’’ operation on the
committed string, similiar to the undo facility provided by
most text editors. Another example is where the user is
proofreading a document that has some misconversions from
preediting and wants to correct the misconverted text. Such
reconversion is again triggered by the user invoking some
special action, but reconversions should not affect the
state of the preedit area.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Context-sensitive conversion is required for some
languages and input methods that need to retrieve text that
surrounds the current spot location (cursor position) of the
client’s buffer. Such text is needed when the
preediting operation depends on some surrounding characters
(usually preceding the spot location). For example, in Thai
language input, certain character sequences may be invalid
and the input method may want to check whether characters
constitute a valid word. Input methods that do such
context-dependent checking need to retrieve the characters
surrounding the current cursor position to obtain complete
words.</small></p>
</td>
</table>
<p><small>Unlike other conversions, this conversion is not
explicitly requested by the user. Input methods that provide
such context-sensitive conversion continuously need to
request context from the client, and any change in the
context of the spot location may affect such conversions.
The client’s context would be needed if the user moves
the cursor and starts editing again.</small></p>
<p><small>For this reason, an input method supporting this
type of conversion should take notice of when the client
calls <i>XmbResetIC</i> or <i>XwcResetIC</i>, which is
usually an indication of a context change.</small></p>
<p><small>Context-sensitive conversions just need a copy of
the client’s text, while other conversions replace the
client’s text with new text to achieve the
reconversion or transliteration. Yet in all cases the result
of a conversion, either immediately or via preediting, is
returned by the <i>XmbLookupString</i> and
<i>XwcLookupString</i> functions.</small></p>
<p><small>String conversion support is dependent on the
availability of the <i>XNStringConversion</i> or
<i>XNStringConversionCallback</i> XIC values. Because the
input method may not support string conversions, clients
have to query the availability of string conversion
operations by checking the supported XIC values list by
calling <i>XGetIMValues</i> with the
<i>XNQueryICValuesList</i> IM value.</small></p>
<p><small>The difference between these two values is
whether the conversion is invoked by the client or the input
method. The <i>XNStringConversion</i> XIC value is used by
clients to request a string conversion from the input
method. The client is responsible for determining which
events are used to trigger the string conversion and whether
the string to be converted should be copied or deleted. The
type of conversion is determined by the input method; the
client can only pass the string to be converted. The client
is guaranteed that no <i>XNStringConversionCallback</i> will
be issued when this value is set; thus, the client need only
set one of these values.</small></p>
<p><small>The <i>XNStringConversionCallback</i> XIC value
is used by the client to notify the input method that it
will accept requests from the input method for string
conversion. If this value is set, it is the input
method’s responsibility to determine which events are
used to trigger the string conversion. When such events
occur, the input method issues a call to the client-supplied
procedure to retrieve the string to be converted. The
client’s callback procedure is notified whether to
copy or delete the string and is provided with hints as to
the amount of text needed. The
<i>XIMStringConversionCallbackStruct</i> specifies which
text should be passed back to the input method.</small></p>
<p><small>Finally, the input method may call the
client’s <i>XNStringConversionCallback</i> procedure
multiple times if the string returned from the callback is
not sufficient to perform a successful conversion. The
arguments to the client’s procedure allow the input
method to define a position (in character units) relative to
the client’s cursor position and the size of the text
needed. By varying the position and size of the desired text
in subsequent callbacks, the input method can retrieve
additional text.</small></p>
<a name="13.5.2. Input Method Management"></a>
<h2>13.5.2. Input Method Management</h2>
<p><small>The interface to input methods might appear to be
simply creating an input method (<i>XOpenIM</i>) and freeing
an input method (<i>XCloseIM</i>). However, input methods
may require complex communication with input method servers
(IM servers), for example:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If the X server, IM server, and X clients are
started asynchronously, some clients may attempt to connect
to the IM server before it is fully operational, and fail.
Therefore, some mechanism is needed to allow clients to
detect when an IM server has started.</small></p>
</td>
</table>
<p><small>It is up to clients to decide what should be done
when an IM server is not available (for example, wait, or
use some other IM server).</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Some input methods may allow the underlying IM
server to be switched. Such customization may be desired
without restarting the entire client.</small></p>
</td>
</table>
<p><small>To support management of input methods in these
cases, the following functions are provided:</small></p>
<p align=center><small><img src="grohtml-1439246.png"></small></p>
<p><small>Input methods that support switching of IM
servers may exhibit some side-effects:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The input method will ensure that any new IM
server supports any of the input styles being used by input
contexts already associated with the input method. However,
the list of supported input styles may be
different.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Geometry management requests on previously
created input contexts may be initiated by the new IM
server.</small></p>
</td>
</table>
<a name="13.5.2.1. Hot Keys"></a>
<h2>13.5.2.1. Hot Keys</h2>
<p><small>Some clients need to guarantee which keys can be
used to escape from the input method, regardless of the
input method state; for example, the client-specific Help
key or the keys to move the input focus. The HotKey
mechanism allows clients to specify a set of keys for this
purpose. However, the input method might not allow clients
to specify hot keys. Therefore, clients have to query
support of hot keys by checking the supported XIC values
list by calling <i>XGetIMValues</i> with the
<i>XNQueryICValuesList</i> IM value. When the hot keys
specified conflict with the key bindings of the input
method, hot keys take precedence over the key bindings of
the input method.</small></p>
<a name="13.5.2.2. Preedit State Operation"></a>
<h2>13.5.2.2. Preedit State Operation</h2>
<p><small>An input method may have several internal states,
depending on its implementation and the locale. However, one
state that is independent of locale and implementation is
whether the input method is currently performing a
preediting operation. Xlib provides the ability for an
application to manage the preedit state programmatically.
Two methods are provided for retrieving the preedit state of
an input context. One method is to query the state by
calling <i>XGetICValues</i> with the <i>XNPreeditState</i>
XIC value. Another method is to receive notification
whenever the preedit state is changed. To receive such
notification, an application needs to register a callback by
calling <i>XSetICValues</i> with the
<i>XNPreeditStateNotifyCallback</i> XIC value. In order to
change the preedit state programmatically, an application
needs to call <i>XSetICValues</i> with
<i>XNPreeditState.</i></small></p>
<p><small>Availability of the preedit state is input method
dependent. The input method may not provide the ability to
set the state or to retrieve the state programmatically.
Therefore, clients have to query availability of preedit
state operations by checking the supported XIC values list
by calling <i>XGetIMValues</i> with the
<i>XNQueryICValuesList</i> IM value.</small></p>
<a name="13.5.3. Input Method Functions"></a>
<h2>13.5.3. Input Method Functions</h2>
<p><small>To open a connection, use
<i>XOpenIM</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XIM XOpenIM(<i>display</i>, <i>db</i>, <i>res_name</i>, <i>res_class</i>)
Display *<i>display</i>;
XrmDatabase <i>db</i>;
char *<i>res_name</i>;
char *<i>res_class</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>db</i></small></p>
</td>
<td width="16%"></td>
<td width="80%">
<p><small>Specifies a pointer to the resource
database.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>res_name</i></small></p>
</td>
<td width="4%"></td>
<td width="78%">
<p><small>Specifies the full resource name of the
application.</small></p>
</td>
<td width="1%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>res_class</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the full class name of the
application.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XOpenIM</i> function opens an input
method, matching the current locale and modifiers
specification. Current locale and modifiers are bound to the
input method at opening time. The locale associated with an
input method cannot be changed dynamically. This implies
that the strings returned by <i>XmbLookupString</i> or
<i>XwcLookupString</i>, for any input context affiliated
with a given input method, will be encoded in the locale
current at the time the input method is opened.</small></p>
<p><small>The specific input method to which this call will
be routed is identified on the basis of the current locale.
<i>XOpenIM</i> will identify a default input method
corresponding to the current locale. That default can be
modified using <i>XSetLocaleModifiers</i> for the input
method modifier.</small></p>
<p><small>The db argument is the resource database to be
used by the input method for looking up resources that are
private to the input method. It is not intended that this
database be used to look up values that can be set as IC
values in an input context. If db is NULL, no database is
passed to the input method.</small></p>
<p><small>The res_name and res_class arguments specify the
resource name and class of the application. They are
intended to be used as prefixes by the input method when
looking up resources that are common to all input contexts
that may be created for this input method. The characters
used for resource names and classes must be in the X
Portable Character Set. The resources looked up are not
fully specified if res_name or res_class is
NULL.</small></p>
<p><small>The res_name and res_class arguments are not
assumed to exist beyond the call to <i>XOpenIM</i>. The
specified resource database is assumed to exist for the
lifetime of the input method.</small></p>
<p><small><i>XOpenIM</i> returns NULL if no input method
could be opened.</small></p>
<p><small>To close a connection, use
<i>XCloseIM</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XCloseIM(<i>im</i>)
XIM <i>im</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>im</i></small></p>
</td>
<td width="16%"></td>
<td width="54%">
<p><small>Specifies the input method.</small></p>
</td>
<td width="25%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XCloseIM</i> function closes the specified
input method.</small></p>
<p><small>To set input method attributes, use
<i>XSetIMValues</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char * XSetIMValues(<i>im</i>, ...)
XIM <i>im</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>im</i></small></p>
</td>
<td width="16%"></td>
<td width="54%">
<p><small>Specifies the input method.</small></p>
</td>
<td width="25%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="1" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="100%">
<p><small>Specifies the variable-length argument list to
set XIM values.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetIMValues</i> function presents a
variable argument list programming interface for setting
attributes of the specified input method. It returns NULL if
it succeeds; otherwise, it returns the name of the first
argument that could not be set. Xlib does not attempt to set
arguments from the supplied list that follow the failed
argument; all arguments in the list preceding the failed
argument have been set correctly.</small></p>
<p><small>To query an input method, use
<i>XGetIMValues</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char * XGetIMValues(<i>im</i>, ...)
XIM <i>im</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>im</i></small></p>
</td>
<td width="16%"></td>
<td width="54%">
<p><small>Specifies the input method.</small></p>
</td>
<td width="25%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="1" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="100%">
<p><small>Specifies the variable length argument list to
get XIM values.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetIMValues</i> function presents a
variable argument list programming interface for querying
properties or features of the specified input method. This
function returns NULL if it succeeds; otherwise, it returns
the name of the first argument that could not be
obtained.</small></p>
<p><small>Each XIM value argument (following a name) must
point to a location where the XIM value is to be stored.
That is, if the XIM value is of type T, the argument must be
of type T*. If T itself is a pointer type, then
<i>XGetIMValues</i> allocates memory to store the actual
data, and the client is responsible for freeing this data by
calling <i>XFree</i> with the returned pointer.</small></p>
<p><small>To obtain the display associated with an input
method, use <i>XDisplayOfIM</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Display * XDisplayOfIM(<i>im</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XIM <i>im</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>im</i></small></p>
</td>
<td width="16%"></td>
<td width="54%">
<p><small>Specifies the input method.</small></p>
</td>
<td width="25%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XDisplayOfIM</i> function returns the
display associated with the specified input
method.</small></p>
<p><small>To get the locale associated with an input
method, use <i>XLocaleOfIM</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char * XLocaleOfIM(<i>im</i>)
XIM <i>im</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>im</i></small></p>
</td>
<td width="16%"></td>
<td width="54%">
<p><small>Specifies the input method.</small></p>
</td>
<td width="25%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XLocaleOfIM</i> function returns the
locale associated with the specified input
method.</small></p>
<p><small>To register an input method instantiate callback,
use <i>XRegisterIMInstantiateCallback</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XRegisterIMInstantiateCallback(<i>display</i>, <i>db</i>, <i>res_name</i>, <i>res_class</i>, <i>callback</i>, <i>client_data</i>)
Display *<i>display</i>;
XrmDatabase <i>db</i>;
char *<i>res_name</i>;
char *<i>res_class</i>;
XIMProc <i> callback</i>;
XPointer *<i>client_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>db</i></small></p>
</td>
<td width="16%"></td>
<td width="80%">
<p><small>Specifies a pointer to the resource
database.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>res_name</i></small></p>
</td>
<td width="4%"></td>
<td width="78%">
<p><small>Specifies the full resource name of the
application.</small></p>
</td>
<td width="1%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>res_class</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the full class name of the
application.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>callback</i></small></p>
</td>
<td width="4%"></td>
<td width="78%">
<p><small>Specifies a pointer to the input method
instantiate callback.</small></p>
</td>
<td width="1%">
</td>
</table>
<p><small><i>client_data</i> Specifies the additional
client data.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XRegisterIMInstantiateCallback</i>
function registers a callback to be invoked whenever a new
input method becomes available for the specified display
that matches the current locale and modifiers.</small></p>
<p><small>The function returns <i>True</i> if it succeeds;
otherwise, it returns <i>False</i>.</small></p>
<p><small>The generic prototype is as follows:</small></p>
<p><small>__ │</small></p>
<pre><small>void IMInstantiateCallback(<i>display</i>, <i>client_data</i>, <i>call_data</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<p><small>XPointer <i>client_data</i>;</small></p>
</table>
<p><small>XPointer <i>call_data</i>;</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>client_data</i> Specifies the additional
client data.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>call_data</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Not used for this callback and always passed as
NULL.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>To unregister an input method instantiation
callback, use
<i>XUnregisterIMInstantiateCallback</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>Bool XUnregisterIMInstantiateCallback(<i>display</i>, <i>db</i>, <i>res_name</i>, <i>res_class</i>, <i>callback</i>, <i>client_data</i>)
Display *<i>display</i>;
XrmDatabase <i>db</i>;
char *<i>res_name</i>;
char *<i>res_class</i>;
XIMProc <i> callback</i>;
XPointer *<i>client_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>db</i></small></p>
</td>
<td width="16%"></td>
<td width="80%">
<p><small>Specifies a pointer to the resource
database.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>res_name</i></small></p>
</td>
<td width="4%"></td>
<td width="78%">
<p><small>Specifies the full resource name of the
application.</small></p>
</td>
<td width="1%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>res_class</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the full class name of the
application.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>callback</i></small></p>
</td>
<td width="4%"></td>
<td width="78%">
<p><small>Specifies a pointer to the input method
instantiate callback.</small></p>
</td>
<td width="1%">
</td>
</table>
<p><small><i>client_data</i> Specifies the additional
client data.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XUnregisterIMInstantiateCallback</i>
function removes an input method instantiation callback
previously registered. The function returns <i>True</i> if
it succeeds; otherwise, it returns <i>False</i>.</small></p>
<a name="13.5.4. Input Method Values"></a>
<h2>13.5.4. Input Method Values</h2>
<p><small>The following table describes how XIM values are
interpreted by an input method. The first column lists the
XIM values. The second column indicates how each of the XIM
values are treated by that input style.</small></p>
<p><small>The following keys apply to this
table.</small></p>
<p align=center><small><img src="grohtml-1439247.png"></small></p>
<p align=center><small><img src="grohtml-1439248.png"></small></p>
<p><small><i>XNR6PreeditCallbackBehavior</i> is obsolete
and its use is not recommended (see section
13.5.4.6).</small></p>
<a name="13.5.4.1. Query Input Style"></a>
<h2>13.5.4.1. Query Input Style</h2>
<p><small>A client should always query the input method to
determine which input styles are supported. The client
should then find an input style it is capable of
supporting.</small></p>
<p><small>If the client cannot find an input style that it
can support, it should negotiate with the user the
continuation of the program (exit, choose another input
method, and so on).</small></p>
<p><small>The argument value must be a pointer to a
location where the returned value will be stored. The
returned value is a pointer to a structure of type
<i>XIMStyles</i>. Clients are responsible for freeing the
<i>XIMStyles</i> structure. To do so, use
<i>XFree</i>.</small></p>
<p><small>The <i>XIMStyles</i> structure is defined as
follows:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef unsigned long XIMStyle;
</small></pre>
<p align=center><small><img src="grohtml-1439249.png"></small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned short count_styles;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XIMStyle * supported_styles;</small></p>
</td>
<td width="49%">
</td>
</table>
<p><small>} XIMStyles;</small></p>
<p><small>│__</small></p>
<p><small>An <i>XIMStyles</i> structure contains the number
of input styles supported in its count_styles field. This is
also the size of the supported_styles array.</small></p>
<p><small>The supported styles is a list of bitmask
combinations, which indicate the combination of styles for
each of the areas supported. These areas are described
later. Each element in the list should select one of the
bitmask values for each area. The list describes the
complete set of combinations supported. Only these
combinations are supported by the input method.</small></p>
<p><small>The preedit category defines what type of support
is provided by the input method for preedit
information.</small></p>
<p align=center><small><img src="grohtml-1439250.png"></small></p>
<p><small>The status category defines what type of support
is provided by the input method for status
information.</small></p>
<p align=center><small><img src="grohtml-1439251.png"></small></p>
<a name="13.5.4.2. Resource Name and Class"></a>
<h2>13.5.4.2. Resource Name and Class</h2>
<p><small>The <i>XNResourceName</i> and
<i>XNResourceClass</i> arguments are strings that specify
the full name and class used by the input method. These
values should be used as prefixes for the name and class
when looking up resources that may vary according to the
input method. If these values are not set, the resources
will not be fully specified.</small></p>
<p><small>It is not intended that values that can be set as
XIM values be set as resources.</small></p>
<a name="13.5.4.3. Destroy Callback"></a>
<h2>13.5.4.3. Destroy Callback</h2>
<p><small>The <i>XNDestroyCallback</i> argument is a
pointer to a structure of type <i>XIMCallback</i>.
<i>XNDestroyCallback</i> is triggered when an input method
stops its service for any reason. After the callback is
invoked, the input method is closed and the associated input
context(s) are destroyed by Xlib. Therefore, the client
should not call <i>XCloseIM</i> or
<i>XDestroyIC</i>.</small></p>
<p><small>The generic prototype of this callback function
is as follows:</small></p>
<p><small>__ │</small></p>
<pre><small>void DestroyCallback(<i>im</i>, <i>client_data</i>, <i>call_data</i>)
XIM <i>im</i>;
XPointer <i>client_data</i>;
XPointer <i>call_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>im</i></small></p>
</td>
<td width="16%"></td>
<td width="54%">
<p><small>Specifies the input method.</small></p>
</td>
<td width="25%">
</td>
</table>
<p><small><i>client_data</i> Specifies the additional
client data.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>call_data</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Not used for this callback and always passed as
NULL.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>A DestroyCallback is always called with a NULL
call_data argument.</small></p>
<a name="13.5.4.4. Query IM/IC Values List"></a>
<h2>13.5.4.4. Query IM/IC Values List</h2>
<p><small><i>XNQueryIMValuesList</i> and
<i>XNQueryICValuesList</i> are used to query about XIM and
XIC values supported by the input method.</small></p>
<p><small>The argument value must be a pointer to a
location where the returned value will be stored. The
returned value is a pointer to a structure of type
<i>XIMValuesList</i>. Clients are responsible for freeing
the <i>XIMValuesList</i> structure. To do so, use
<i>XFree</i>.</small></p>
<p><small>The <i>XIMValuesList</i> structure is defined as
follows:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned short count_values;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>char **supported_values;</small></p>
</td>
<td width="49%">
</td>
</table>
<p><small>} XIMValuesList;</small></p>
<p><small>│__</small></p>
<a name="13.5.4.5. Visible Position"></a>
<h2>13.5.4.5. Visible Position</h2>
<p><small>The <i>XNVisiblePosition</i> argument indicates
whether the visible position masks of <i>XIMFeedback</i> in
<i>XIMText</i> are available.</small></p>
<p><small>The argument value must be a pointer to a
location where the returned value will be stored. The
returned value is of type <i>Bool</i>. If the returned value
is <i>True</i>, the input method uses the visible position
masks of <i>XIMFeedback</i> in <i>XIMText</i>; otherwise,
the input method does not use the masks.</small></p>
<p><small>Because this XIM value is optional, a client
should call <i>XGetIMValues</i> with argument
<i>XNQueryIMValues</i> before using this argument. If the
<i>XNVisiblePosition</i> does not exist in the IM values
list returned from <i>XNQueryIMValues</i>, the visible
position masks of <i>XIMFeedback</i> in <i>XIMText</i> are
not used to indicate the visible position.</small></p>
<a name="13.5.4.6. Preedit Callback Behavior"></a>
<h2>13.5.4.6. Preedit Callback Behavior</h2>
<p><small>The <i>XNR6PreeditCallbackBehavior</i> argument
originally included in the X11R6 specification has been
deprecated.†</small></p>
<p align=center><small><img src="grohtml-1439252.png"></small></p>
<p><small>The <i>XNR6PreeditCallbackBehavior</i> argument
indicates whether the behavior of preedit callbacks
regarding <i>XIMPreeditDrawCallbackStruct</i> values follows
Release 5 or Release 6 semantics.</small></p>
<p><small>The value is of type <i>Bool</i>. When querying
for <i>XNR6PreeditCallbackBehavior</i>, if the returned
value is <i>True</i>, the input method uses the Release 6
behavior; otherwise, it uses the Release 5 behavior. The
default value is <i>False</i>. In order to use Release 6
semantics, the value of <i>XNR6PreeditCallbackBehavior</i>
must be set to <i>True</i>.</small></p>
<p><small>Because this XIM value is optional, a client
should call <i>XGetIMValues</i> with argument
<i>XNQueryIMValues</i> before using this argument. If the
<i>XNR6PreeditCallbackBehavior</i> does not exist in the IM
values list returned from <i>XNQueryIMValues</i>, the
PreeditCallback behavior is Release 5 semantics.</small></p>
<a name="13.5.5. Input Context Functions"></a>
<h2>13.5.5. Input Context Functions</h2>
<p><small>An input context is an abstraction that is used
to contain both the data required (if any) by an input
method and the information required to display that data.
There may be multiple input contexts for one input method.
The programming interfaces for creating, reading, or
modifying an input context use a variable argument list. The
name elements of the argument lists are referred to as XIC
values. It is intended that input methods be controlled by
these XIC values. As new XIC values are created, they should
be registered with the X Consortium.</small></p>
<p><small>To create an input context, use
<i>XCreateIC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XIC XCreateIC(<i>im</i>, ...)
XIM <i>im</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>im</i></small></p>
</td>
<td width="16%"></td>
<td width="54%">
<p><small>Specifies the input method.</small></p>
</td>
<td width="25%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="1" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="100%">
<p><small>Specifies the variable length argument list to
set XIC values.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XCreateIC</i> function creates a context
within the specified input method.</small></p>
<p><small>Some of the arguments are mandatory at creation
time, and the input context will not be created if those
arguments are not provided. The mandatory arguments are the
input style and the set of text callbacks (if the input
style selected requires callbacks). All other input context
values can be set later.</small></p>
<p><small><i>XCreateIC</i> returns a NULL value if no input
context could be created. A NULL value could be returned for
any of the following reasons:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="64%">
<p><small>A required argument was not set.</small></p>
</td>
<td width="25%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="84%">
<p><small>A read-only argument was set (for example,
<i>XNFilterEvents</i>).</small></p>
</td>
<td width="5%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="72%">
<p><small>The argument name is not recognized.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="88%">
<p><small>The input method encountered an input method
implementation-dependent error.</small></p>
</td>
<td width="1%">
</td>
</table>
<p><small><i>XCreateIC</i> can generate <i>BadAtom</i>,
<i>BadColor</i>, <i>BadPixmap</i>, and <i>BadWindow</i>
errors.</small></p>
<p><small>To destroy an input context, use
<i>XDestroyIC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XDestroyIC(<i>ic</i>)
XIC <i>ic</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the input context.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small><i>XDestroyIC</i> destroys the specified input
context.</small></p>
<p><small>To communicate to and synchronize with input
method for any changes in keyboard focus from the client
side, use <i>XSetICFocus</i> and
<i>XUnsetICFocus</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XSetICFocus(<i>ic</i>)
XIC <i>ic</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the input context.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetICFocus</i> function allows a client
to notify an input method that the focus window attached to
the specified input context has received keyboard focus. The
input method should take action to provide appropriate
feedback. Complete feedback specification is a matter of
user interface policy.</small></p>
<p><small>Calling <i>XSetICFocus</i> does not affect the
focus window value.</small></p>
<p><small>__ │</small></p>
<pre><small>void XUnsetICFocus(<i>ic</i>)
XIC <i>ic</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the input context.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XUnsetICFocus</i> function allows a client
to notify an input method that the specified input context
has lost the keyboard focus and that no more input is
expected on the focus window attached to that input context.
The input method should take action to provide appropriate
feedback. Complete feedback specification is a matter of
user interface policy.</small></p>
<p><small>Calling <i>XUnsetICFocus</i> does not affect the
focus window value; the client may still receive events from
the input method that are directed to the focus
window.</small></p>
<p><small>To reset the state of an input context to its
initial state, use <i>XmbResetIC</i> or
<i>XwcResetIC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char * XmbResetIC(<i>ic</i>)
XIC <i>ic</i>;
</small></pre>
<pre><small>wchar_t * XwcResetIC(<i>ic</i>)
XIC <i>ic</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the input context.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>When <i>XNResetState</i> is set to
<i>XIMInitialState</i>, <i>XmbResetIC</i> and
<i>XwcResetIC</i> reset an input context to its initial
state; when <i>XNResetState</i> is set to
<i>XIMPreserveState</i>, the current input context state is
preserved. In both cases, any input pending on that context
is deleted. The input method is required to clear the
preedit area, if any, and update the status accordingly.
Calling <i>XmbResetIC</i> or <i>XwcResetIC</i> does not
change the focus.</small></p>
<p><small>The return value of <i>XmbResetIC</i> is its
current preedit string as a multibyte string. If there is
any preedit text drawn or visible to the user, then these
procedures must return a non-NULL string. If there is no
visible preedit text, then it is input method
implementation-dependent whether these procedures return a
non-NULL string or NULL.</small></p>
<p><small>The client should free the returned string by
calling <i>XFree</i>.</small></p>
<p><small>To get the input method associated with an input
context, use <i>XIMOfIC</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XIM XIMOfIC(<i>ic</i>)
XIC <i>ic</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the input context.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XIMOfIC</i> function returns the input
method associated with the specified input
context.</small></p>
<p><small>Xlib provides two functions for setting and
reading XIC values, respectively, <i>XSetICValues</i> and
<i>XGetICValues</i>. Both functions have a variable-length
argument list. In that argument list, any XIC value’s
name must be denoted with a character string using the X
Portable Character Set.</small></p>
<p><small>To set XIC values, use
<i>XSetICValues</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char * XSetICValues(<i>ic</i>, ...)
XIC <i>ic</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the input context.</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="1" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="100%">
<p><small>Specifies the variable length argument list to
set XIC values.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetICValues</i> function returns NULL if
no error occurred; otherwise, it returns the name of the
first argument that could not be set. An argument might not
be set for any of the following reasons:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="78%">
<p><small>The argument is read-only (for example,
<i>XNFilterEvents</i>).</small></p>
</td>
<td width="11%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="72%">
<p><small>The argument name is not recognized.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="82%">
<p><small>An implementation-dependent error
occurs.</small></p>
</td>
<td width="7%">
</td>
</table>
<p><small>Each value to be set must be an appropriate
datum, matching the data type imposed by the semantics of
the argument.</small></p>
<p><small><i>XSetICValues</i> can generate <i>BadAtom</i>,
<i>BadColor</i>, <i>BadCursor</i>, <i>BadPixmap</i>, and
<i>BadWindow</i> errors.</small></p>
<p><small>To obtain XIC values, use
<i>XGetICValues</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char * XGetICValues(<i>ic</i>, ...)
XIC <i>ic</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the input context.</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="1" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="100%">
<p><small>Specifies the variable length argument list to
get XIC values.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetICValues</i> function returns NULL if
no error occurred; otherwise, it returns the name of the
first argument that could not be obtained. An argument could
not be obtained for any of the following
reasons:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="72%">
<p><small>The argument name is not recognized.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>The input method encountered an
implementation-dependent error.</small></p>
</td>
<td width="27%">
</td>
</table>
<p><small>Each IC attribute value argument (following a
name) must point to a location where the IC value is to be
stored. That is, if the IC value is of type T, the argument
must be of type T*. If T itself is a pointer type, then
<i>XGetICValues</i> allocates memory to store the actual
data, and the client is responsible for freeing this data by
calling <i>XFree</i> with the returned pointer. The
exception to this rule is for an IC value of type
<i>XVaNestedList</i> (for preedit and status attributes). In
this case, the argument must also be of type
<i>XVaNestedList</i>. Then, the rule of changing type T to
T* and freeing the allocated data applies to each element of
the nested list.</small></p>
<a name="13.5.6. Input Context Values"></a>
<h2>13.5.6. Input Context Values</h2>
<p><small>The following tables describe how XIC values are
interpreted by an input method depending on the input style
chosen by the user.</small></p>
<p><small>The first column lists the XIC values. The second
column indicates which values are involved in affecting,
negotiating, and setting the geometry of the input method
windows. The subentries under the third column indicate the
different input styles that are supported. Each of these
columns indicates how each of the XIC values are treated by
that input style.</small></p>
<p><small>The following keys apply to these
tables.</small></p>
<p align=center><small><img src="grohtml-1439253.png"></small></p>
<p align=center><small><img src="grohtml-1439254.png"></small></p>
<p align=center><small><img src="grohtml-1439255.png"></small></p>
<a name="13.5.6.1. Input Style"></a>
<h2>13.5.6.1. Input Style</h2>
<p><small>The <i>XNInputStyle</i> argument specifies the
input style to be used. The value of this argument must be
one of the values returned by the <i>XGetIMValues</i>
function with the <i>XNQueryInputStyle</i> argument
specified in the supported_styles list.</small></p>
<p><small>Note that this argument must be set at creation
time and cannot be changed.</small></p>
<a name="13.5.6.2. Client Window"></a>
<h2>13.5.6.2. Client Window</h2>
<p><small>The <i>XNClientWindow</i> argument specifies to
the input method the client window in which the input method
can display data or create subwindows. Geometry values for
input method areas are given with respect to the client
window. Dynamic change of client window is not supported.
This argument may be set only once and should be set before
any input is done using this input context. If it is not
set, the input method may not operate correctly.</small></p>
<p><small>If an attempt is made to set this value a second
time with <i>XSetICValues</i>, the string
<i>XNClientWindow</i> will be returned by
<i>XSetICValues</i>, and the client window will not be
changed.</small></p>
<p><small>If the client window is not a valid window ID on
the display attached to the input method, a <i>BadWindow</i>
error can be generated when this value is used by the input
method.</small></p>
<a name="13.5.6.3. Focus Window"></a>
<h2>13.5.6.3. Focus Window</h2>
<p><small>The <i>XNFocusWindow</i> argument specifies the
focus window. The primary purpose of the
<i>XNFocusWindow</i> is to identify the window that will
receive the key event when input is composed. In addition,
the input method may possibly affect the focus window as
follows:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="38%">
<p><small>Select events on it</small></p>
</td>
<td width="51%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="34%">
<p><small>Send events to it</small></p>
</td>
<td width="55%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>Modify its properties</small></p>
</td>
<td width="47%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="72%">
<p><small>Grab the keyboard within that window</small></p>
</td>
<td width="17%">
</td>
</table>
<p><small>The associated value must be of type
<i>Window</i>. If the focus window is not a valid window ID
on the display attached to the input method, a
<i>BadWindow</i> error can be generated when this value is
used by the input method.</small></p>
<p><small>When this XIC value is left unspecified, the
input method will use the client window as the default focus
window.</small></p>
<a name="13.5.6.4. Resource Name and Class"></a>
<h2>13.5.6.4. Resource Name and Class</h2>
<p><small>The <i>XNResourceName</i> and
<i>XNResourceClass</i> arguments are strings that specify
the full name and class used by the client to obtain
resources for the client window. These values should be used
as prefixes for name and class when looking up resources
that may vary according to the input context. If these
values are not set, the resources will not be fully
specified.</small></p>
<p><small>It is not intended that values that can be set as
XIC values be set as resources.</small></p>
<a name="13.5.6.5. Geometry Callback"></a>
<h2>13.5.6.5. Geometry Callback</h2>
<p><small>The <i>XNGeometryCallback</i> argument is a
structure of type <i>XIMCallback</i> (see section
13.5.6.13.12).</small></p>
<p><small>The <i>XNGeometryCallback</i> argument specifies
the geometry callback that a client can set. This callback
is not required for correct operation of either an input
method or a client. It can be set for a client whose user
interface policy permits an input method to request the
dynamic change of that input method’s window. An input
method that does dynamic change will need to filter any
events that it uses to initiate the change.</small></p>
<a name="13.5.6.6. Filter Events"></a>
<h2>13.5.6.6. Filter Events</h2>
<p><small>The <i>XNFilterEvents</i> argument returns the
event mask that an input method needs to have selected for.
The client is expected to augment its own event mask for the
client window with this one.</small></p>
<p><small>This argument is read-only, is set by the input
method at create time, and is never changed.</small></p>
<p><small>The type of this argument is <i>unsigned
long</i>. Setting this value will cause an
error.</small></p>
<a name="13.5.6.7. Destroy Callback"></a>
<h2>13.5.6.7. Destroy Callback</h2>
<p><small>The <i>XNDestroyCallback</i> argument is a
pointer to a structure of type <i>XIMCallback</i> (see
section 13.5.6.13.12). This callback is triggered when the
input method stops its service for any reason; for example,
when a connection to an IM server is broken. After the
destroy callback is called, the input context is destroyed
and the input method is closed. Therefore, the client should
not call <i>XDestroyIC</i> and <i>XCloseIM</i>.</small></p>
<a name="13.5.6.8. String Conversion Callback"></a>
<h2>13.5.6.8. String Conversion Callback</h2>
<p><small>The <i>XNStringConversionCallback</i> argument is
a structure of type <i>XIMCallback</i> (see section
13.5.6.13.12).</small></p>
<p><small>The <i>XNStringConversionCallback</i> argument
specifies a string conversion callback. This callback is not
required for correct operation of either the input method or
the client. It can be set by a client to support string
conversions that may be requested by the input method. An
input method that does string conversions will filter any
events that it uses to initiate the conversion.</small></p>
<p><small>Because this XIC value is optional, a client
should call <i>XGetIMValues</i> with argument
<i>XNQueryICValuesList</i> before using this
argument.</small></p>
<a name="13.5.6.9. String Conversion"></a>
<h2>13.5.6.9. String Conversion</h2>
<p><small>The <i>XNStringConversion</i> argument is a
structure of type
<i>XIMStringConversionText</i>.</small></p>
<p><small>The <i>XNStringConversion</i> argument specifies
the string to be converted by an input method. This argument
is not required for correct operation of either the input
method or the client.</small></p>
<p><small>String conversion facilitates the manipulation of
text independent of preediting. It is essential for some
input methods and clients to manipulate text by performing
context-sensitive conversion, reconversion, or
transliteration conversion on it.</small></p>
<p><small>Because this XIC value is optional, a client
should call <i>XGetIMValues</i> with argument
<i>XNQueryICValuesList</i> before using this
argument.</small></p>
<p><small>The <i>XIMStringConversionText</i> structure is
defined as follows:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct _XIMStringConversionText {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="5" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>unsigned short length;</small></p>
</td>
<td width="10%"></td>
<td width="10%"></td>
<td width="59%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>XIMStringConversionFeedback
*feedback;</small></p>
</td>
<td width="10%"></td>
<td width="10%"></td>
<td width="59%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>Bool encoding_is_wchar;</small></p>
</td>
<td width="10%"></td>
<td width="10%"></td>
<td width="59%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>union {</small></p>
</td>
<td width="10%"></td>
<td width="10%"></td>
<td width="59%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
</td>
<td width="10%">
<p><small>char</small></p>
</td>
<td width="10%">
<p><small>*mbs;</small></p>
</td>
<td width="59%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
</td>
<td width="10%">
<p><small>wchar_t *wcs;</small></p>
</td>
<td width="10%"></td>
<td width="59%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>} string;</small></p>
</td>
<td width="10%"></td>
<td width="10%"></td>
<td width="59%">
</td>
</table>
<p><small>} XIMStringConversionText;</small></p>
<p><small>typedef unsigned long
XIMStringConversionFeedback;</small></p>
<p><small>│__</small></p>
<p><small>The feedback member is reserved for future use.
The text to be converted is defined by the string and length
members. The length is indicated in characters. To prevent
the library from freeing memory pointed to by an
uninitialized pointer, the client should set the feedback
element to NULL.</small></p>
<a name="13.5.6.10. Reset State"></a>
<h2>13.5.6.10. Reset State</h2>
<p><small>The <i>XNResetState</i> argument specifies the
state the input context will return to after calling
<i>XmbResetIC</i> or <i>XwcResetIC</i>.</small></p>
<p><small>The XIC state may be set to its initial state, as
specified by the <i>XNPreeditState</i> value when
<i>XCreateIC</i> was called, or it may be set to preserve
the current state.</small></p>
<p><small>The valid masks for <i>XIMResetState</i> are as
follows:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef unsigned long XIMResetState;
</small></pre>
<p align=center><small><img src="grohtml-1439256.png"></small></p>
<p><small>│__</small></p>
<p><small>If <i>XIMInitialState</i> is set, then
<i>XmbResetIC</i> and <i>XwcResetIC</i> will return to the
initial <i>XNPreeditState</i> state of the XIC.</small></p>
<p><small>If <i>XIMPreserveState</i> is set, then
<i>XmbResetIC</i> and <i>XwcResetIC</i> will preserve the
current state of the XIC.</small></p>
<p><small>If <i>XNResetState</i> is left unspecified, the
default is <i>XIMInitialState</i>.</small></p>
<p><small><i>XIMResetState</i> values other than those
specified above will default to
<i>XIMInitialState</i>.</small></p>
<p><small>Because this XIC value is optional, a client
should call <i>XGetIMValues</i> with argument
<i>XNQueryICValuesList</i> before using this
argument.</small></p>
<a name="13.5.6.11. Hot Keys"></a>
<h2>13.5.6.11. Hot Keys</h2>
<p><small>The <i>XNHotKey</i> argument specifies the hot
key list to the XIC. The hot key list is a pointer to the
structure of type <i>XIMHotKeyTriggers</i>, which specifies
the key events that must be received without any
interruption of the input method. For the hot key list set
with this argument to be utilized, the client must also set
<i>XNHotKeyState</i> to <i>XIMHotKeyStateON</i>.</small></p>
<p><small>Because this XIC value is optional, a client
should call <i>XGetIMValues</i> with argument
<i>XNQueryICValuesList</i> before using this
functionality.</small></p>
<p><small>The value of the argument is a pointer to a
structure of type <i>XIMHotKeyTriggers</i>.</small></p>
<p><small>If an event for a key in the hot key list is
found, then the process will receive the event and it will
be processed inside the client.</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>KeySym keysym;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned int modifier;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned int modifier_mask;</small></p>
</td>
<td width="49%">
</td>
</table>
<p><small>} XIMHotKeyTrigger;</small></p>
<p><small>typedef struct {</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>int num_hot_key;</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>XIMHotKeyTrigger *key;</small></p>
</td>
</table>
<p><small>} XIMHotKeyTriggers;</small></p>
<p><small>│__</small></p>
<p><small>The combination of modifier and modifier_mask are
used to represent one of three states for each modifier:
either the modifier must be on, or the modifier must be off,
or the modifier is a ‘‘don’t
care’’ − it may be on or off. When a
modifier_mask bit is set to 0, the state of the associated
modifier is ignored when evaluating whether the key is hot
or not.</small></p>
<p align=center><small><img src="grohtml-1439257.png"></small></p>
<a name="13.5.6.12. Hot Key State"></a>
<h2>13.5.6.12. Hot Key State</h2>
<p><small>The <i>XNHotKeyState</i> argument specifies the
hot key state of the input method. This is usually used to
switch the input method between hot key operation and normal
input processing.</small></p>
<p><small>The value of the argument is a pointer to a
structure of type XIMHotKeyState .</small></p>
<p><small>__ │</small></p>
<pre><small>typedef unsigned long XIMHotKeyState;
</small></pre>
<p align=center><small><img src="grohtml-1439258.png"></small></p>
<p><small>│__</small></p>
<p><small>If not specified, the default is
<i>XIMHotKeyStateOFF</i>.</small></p>
<a name="13.5.6.13. Preedit and Status Attributes"></a>
<h2>13.5.6.13. Preedit and Status Attributes</h2>
<p><small>The <i>XNPreeditAttributes</i> and
<i>XNStatusAttributes</i> arguments specify to an input
method the attributes to be used for the preedit and status
areas, if any. Those attributes are passed to
<i>XSetICValues</i> or <i>XGetICValues</i> as a nested
variable-length list. The names to be used in these lists
are described in the following sections.</small></p>
<a name="13.5.6.13.1. Area"></a>
<h2>13.5.6.13.1. Area</h2>
<p><small>The value of the <i>XNArea</i> argument must be a
pointer to a structure of type <i>XRectangle.</i> The
interpretation of the <i>XNArea</i> argument is dependent on
the input method style that has been set.</small></p>
<p><small>If the input method style is
<i>XIMPreeditPosition</i>, <i>XNArea</i> specifies the
clipping region within which preediting will take place. If
the focus window has been set, the coordinates are assumed
to be relative to the focus window. Otherwise, the
coordinates are assumed to be relative to the client window.
If neither has been set, the results are
undefined.</small></p>
<p><small>If <i>XNArea</i> is not specified, is set to
NULL, or is invalid, the input method will default the
clipping region to the geometry of the <i>XNFocusWindow</i>.
If the area specified is NULL or invalid, the results are
undefined.</small></p>
<p><small>If the input style is <i>XIMPreeditArea</i> or
<i>XIMStatusArea</i>, <i>XNArea</i> specifies the geometry
provided by the client to the input method. The input method
may use this area to display its data, either preedit or
status depending on the area designated. The input method
may create a window as a child of the client window with
dimensions that fit the <i>XNArea</i>. The coordinates are
relative to the client window. If the client window has not
been set yet, the input method should save these values and
apply them when the client window is set. If <i>XNArea</i>
is not specified, is set to NULL, or is invalid, the results
are undefined.</small></p>
<a name="13.5.6.13.2. Area Needed"></a>
<h2>13.5.6.13.2. Area Needed</h2>
<p><small>When set, the <i>XNAreaNeeded</i> argument
specifies the geometry suggested by the client for this area
(preedit or status). The value associated with the argument
must be a pointer to a structure of type <i>XRectangle</i>.
Note that the x, y values are not used and that nonzero
values for width or height are the constraints that the
client wishes the input method to respect.</small></p>
<p><small>When read, the <i>XNAreaNeeded</i> argument
specifies the preferred geometry desired by the input method
for the area.</small></p>
<p><small>This argument is only valid if the input style is
<i>XIMPreeditArea</i> or <i>XIMStatusArea</i>. It is used
for geometry negotiation between the client and the input
method and has no other effect on the input method (see
section 13.5.1.5).</small></p>
<a name="13.5.6.13.3. Spot Location"></a>
<h2>13.5.6.13.3. Spot Location</h2>
<p><small>The <i>XNSpotLocation</i> argument specifies to
the input method the coordinates of the spot to be used by
an input method executing with <i>XNInputStyle</i> set to
<i>XIMPreeditPosition</i>. When specified to any input
method other than <i>XIMPreeditPosition</i>, this XIC value
is ignored.</small></p>
<p><small>The x coordinate specifies the position where the
next character would be inserted. The y coordinate is the
position of the baseline used by the current text line in
the focus window. The x and y coordinates are relative to
the focus window, if it has been set; otherwise, they are
relative to the client window. If neither the focus window
nor the client window has been set, the results are
undefined.</small></p>
<p><small>The value of the argument is a pointer to a
structure of type <i>XPoint</i>.</small></p>
<a name="13.5.6.13.4. Colormap"></a>
<h2>13.5.6.13.4. Colormap</h2>
<p><small>Two different arguments can be used to indicate
what colormap the input method should use to allocate
colors, a colormap ID, or a standard colormap
name.</small></p>
<p><small>The <i>XNColormap</i> argument is used to specify
a colormap ID. The argument value is of type
<i>Colormap</i>. An invalid argument may generate a
<i>BadColor</i> error when it is used by the input
method.</small></p>
<p><small>The <i>XNStdColormap</i> argument is used to
indicate the name of the standard colormap in which the
input method should allocate colors. The argument value is
an <i>Atom</i> that should be a valid atom for calling
<i>XGetRGBColormaps</i>. An invalid argument may generate a
<i>BadAtom</i> error when it is used by the input
method.</small></p>
<p><small>If the colormap is left unspecified, the client
window colormap becomes the default.</small></p>
<a name="13.5.6.13.5. Foreground and Background"></a>
<h2>13.5.6.13.5. Foreground and Background</h2>
<p><small>The <i>XNForeground</i> and <i>XNBackground</i>
arguments specify the foreground and background pixel,
respectively. The argument value is of type <i>unsigned
long</i>. It must be a valid pixel in the input method
colormap.</small></p>
<p><small>If these values are left unspecified, the default
is determined by the input method.</small></p>
<a name="13.5.6.13.6. Background Pixmap"></a>
<h2>13.5.6.13.6. Background Pixmap</h2>
<p><small>The <i>XNBackgroundPixmap</i> argument specifies
a background pixmap to be used as the background of the
window. The value must be of type <i>Pixmap</i>. An invalid
argument may generate a <i>BadPixmap</i> error when it is
used by the input method.</small></p>
<p><small>If this value is left unspecified, the default is
determined by the input method.</small></p>
<a name="13.5.6.13.7. Font Set"></a>
<h2>13.5.6.13.7. Font Set</h2>
<p><small>The <i>XNFontSet</i> argument specifies to the
input method what font set is to be used. The argument value
is of type <i>XFontSet</i>.</small></p>
<p><small>If this value is left unspecified, the default is
determined by the input method.</small></p>
<a name="13.5.6.13.8. Line Spacing"></a>
<h2>13.5.6.13.8. Line Spacing</h2>
<p><small>The <i>XNLineSpace</i> argument specifies to the
input method what line spacing is to be used in the preedit
window if more than one line is to be used. This argument is
of type <i>int</i>.</small></p>
<p><small>If this value is left unspecified, the default is
determined by the input method.</small></p>
<a name="13.5.6.13.9. Cursor"></a>
<h2>13.5.6.13.9. Cursor</h2>
<p><small>The <i>XNCursor</i> argument specifies to the
input method what cursor is to be used in the specified
window. This argument is of type <i>Cursor</i>.</small></p>
<p><small>An invalid argument may generate a
<i>BadCursor</i> error when it is used by the input method.
If this value is left unspecified, the default is determined
by the input method.</small></p>
<a name="13.5.6.13.10. Preedit State"></a>
<h2>13.5.6.13.10. Preedit State</h2>
<p><small>The <i>XNPreeditState</i> argument specifies the
state of input preediting for the input method. Input
preediting can be on or off.</small></p>
<p><small>The valid mask names for <i>XNPreeditState</i>
are as follows:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef unsigned long XIMPreeditState;
</small></pre>
<p align=center><small><img src="grohtml-1439259.png"></small></p>
<p><small>│__</small></p>
<p><small>If a value of <i>XIMPreeditEnable</i> is set,
then input preediting is turned on by the input
method.</small></p>
<p><small>If a value of <i>XIMPreeditDisable</i> is set,
then input preediting is turned off by the input
method.</small></p>
<p><small>If <i>XNPreeditState</i> is left unspecified,
then the state will be implementation-dependent.</small></p>
<p><small>When <i>XNResetState</i> is set to
<i>XIMInitialState</i>, the <i>XNPreeditState</i> value
specified at the creation time will be reflected as the
initial state for <i>XmbResetIC</i> and
<i>XwcResetIC</i>.</small></p>
<p><small>Because this XIC value is optional, a client
should call <i>XGetIMValues</i> with argument
<i>XNQueryICValuesList</i> before using this
argument.</small></p>
<a name="13.5.6.13.11. Preedit State Notify Callback"></a>
<h2>13.5.6.13.11. Preedit State Notify Callback</h2>
<p><small>The preedit state notify callback is triggered by
the input method when the preediting state has changed. The
value of the <i>XNPreeditStateNotifyCallback</i> argument is
a pointer to a structure of type <i>XIMCallback</i>. The
generic prototype is as follows:</small></p>
<p><small>__ │</small></p>
<pre><small>void PreeditStateNotifyCallback(<i>ic</i>, <i>client_data</i>, <i>call_data</i>)
XIC <i>ic</i>;
XPointer <i>client_data</i>;
XIMPreeditStateNotifyCallbackStruct *<i>call_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the input context.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small><i>client_data</i> Specifies the additional
client data.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>call_data</i></small></p>
</td>
<td width="2%"></td>
<td width="72%">
<p><small>Specifies the current preedit state.</small></p>
</td>
<td width="7%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XIMPreeditStateNotifyCallbackStruct</i>
structure is defined as follows:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct _XIMPreeditStateNotifyCallbackStruct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XIMPreeditState state;</small></p>
</td>
<td width="49%">
</td>
</table>
<p><small>}
XIMPreeditStateNotifyCallbackStruct;</small></p>
<p><small>│__</small></p>
<p><small>Because this XIC value is optional, a client
should call <i>XGetIMValues</i> with argument
<i>XNQueryICValuesList</i> before using this
argument.</small></p>
<a name="13.5.6.13.12. Preedit and Status Callbacks"></a>
<h2>13.5.6.13.12. Preedit and Status Callbacks</h2>
<p><small>A client that wants to support the input style
<i>XIMPreeditCallbacks</i> must provide a set of preedit
callbacks to the input method. The set of preedit callbacks
is as follows:</small></p>
<p align=center><small><img src="grohtml-1439260.png"></small></p>
<p><small>A client that wants to support the input style
<i>XIMStatusCallbacks</i> must provide a set of status
callbacks to the input method. The set of status callbacks
is as follows:</small></p>
<p align=center><small><img src="grohtml-1439261.png"></small></p>
<p><small>The value of any status or preedit argument is a
pointer to a structure of type
<i>XIMCallback</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>typedef void (*XIMProc)();
typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XPointer client_data;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XIMProc callback;</small></p>
</td>
<td width="49%">
</td>
</table>
<p><small>} XIMCallback;</small></p>
<p><small>│__</small></p>
<p><small>Each callback has some particular semantics and
will carry the data that expresses the environment necessary
to the client into a specific data structure. This paragraph
only describes the arguments to be used to set the
callback.</small></p>
<p><small>Setting any of these values while doing preedit
may cause unexpected results.</small></p>
<a name="13.5.7. Input Method Callback Semantics"></a>
<h2>13.5.7. Input Method Callback Semantics</h2>
<p><small>XIM callbacks are procedures defined by clients
or text drawing packages that are to be called from the
input method when selected events occur. Most clients will
use a text editing package or a toolkit and, hence, will not
need to define such callbacks. This section defines the
callback semantics, when they are triggered, and what their
arguments are. This information is mostly useful for X
toolkit implementors.</small></p>
<p><small>Callbacks are mostly provided so that clients (or
text editing packages) can implement on-the-spot preediting
in their own window. In that case, the input method needs to
communicate and synchronize with the client. The input
method needs to communicate changes in the preedit window
when it is under control of the client. Those callbacks
allow the client to initialize the preedit area, display a
new preedit string, move the text insertion point during
preedit, terminate preedit, or update the status
area.</small></p>
<p><small>All callback procedures follow the generic
prototype:</small></p>
<p><small>__ │</small></p>
<pre><small>void CallbackPrototype(<i>ic</i>, <i>client_data</i>, <i>call_data</i>)
XIC <i>ic</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<p><small>XPointer <i>client_data</i>;</small></p>
</table>
<p><small>SomeType <i>call_data</i>;</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the input context.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small><i>client_data</i> Specifies the additional
client data.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>call_data</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies data specific to the
callback.</small></p>
</td>
<td width="0%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The call_data argument is a structure that
expresses the arguments needed to achieve the semantics;
that is, it is a specific data structure appropriate to the
callback. In cases where no data is needed in the callback,
this call_data argument is NULL. The client_data argument is
a closure that has been initially specified by the client
when specifying the callback and passed back. It may serve,
for example, to inherit application context in the
callback.</small></p>
<p><small>The following paragraphs describe the programming
semantics and specific data structure associated with the
different reasons.</small></p>
<a name="13.5.7.1. Geometry Callback"></a>
<h2>13.5.7.1. Geometry Callback</h2>
<p><small>The geometry callback is triggered by the input
method to indicate that it wants the client to negotiate
geometry. The generic prototype is as follows:</small></p>
<p><small>__ │</small></p>
<pre><small>void GeometryCallback(<i>ic</i>, <i>client_data</i>, <i>call_data</i>)
XIC <i>ic</i>;
XPointer <i>client_data</i>;
XPointer <i>call_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the input context.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small><i>client_data</i> Specifies the additional
client data.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>call_data</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Not used for this callback and always passed as
NULL.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The callback is called with a NULL call_data
argument.</small></p>
<a name="13.5.7.2. Destroy Callback"></a>
<h2>13.5.7.2. Destroy Callback</h2>
<p><small>The destroy callback is triggered by the input
method when it stops service for any reason. After the
callback is invoked, the input context will be freed by
Xlib. The generic prototype is as follows:</small></p>
<p><small>__ │</small></p>
<pre><small>void DestroyCallback(<i>ic</i>, <i>client_data</i>, <i>call_data</i>)
XIC <i>ic</i>;
XPointer <i>client_data</i>;
XPointer <i>call_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the input context.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small><i>client_data</i> Specifies the additional
client data.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>call_data</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Not used for this callback and always passed as
NULL.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The callback is called with a NULL call_data
argument.</small></p>
<a name="13.5.7.3. String Conversion Callback"></a>
<h2>13.5.7.3. String Conversion Callback</h2>
<p><small>The string conversion callback is triggered by
the input method to request the client to return the string
to be converted. The returned string may be either a
multibyte or wide character string, with an encoding
matching the locale bound to the input context. The callback
prototype is as follows:</small></p>
<p><small>__ │</small></p>
<pre><small>void StringConversionCallback(<i>ic</i>, <i>client_data</i>, <i>call_data</i>)
XIC <i>ic</i>;
XPointer <i>client_data</i>;
XIMStringConversionCallbackStruct *<i>call_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="54%">
<p><small>Specifies the input method.</small></p>
</td>
<td width="25%">
</td>
</table>
<p><small><i>client_data</i> Specifies the additional
client data.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>call_data</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the amount of the string to be
converted.</small></p>
</td>
<td width="0%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The callback is passed an
<i>XIMStringConversionCallbackStruct</i> structure in the
call_data argument. The text member is an
<i>XIMStringConversionText</i> structure (see section
13.5.6.9) to be filled in by the client and describes the
text to be sent to the input method. The data pointed to by
the string and feedback elements of the
<i>XIMStringConversionText</i> structure will be freed using
<i>XFree</i> by the input method after the callback returns.
So the client should not point to internal buffers that are
critical to the client. Similarly, because the feedback
element is currently reserved for future use, the client
should set feedback to NULL to prevent the library from
freeing memory at some random location due to an
uninitialized pointer.</small></p>
<p><small>The <i>XIMStringConversionCallbackStruct</i>
structure is defined as follows:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct _XIMStringConversionCallbackStruct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="5" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>XIMStringConversionPosition position;</small></p>
</td>
<td width="70%"></td>
<td width="10%">
</td>
<td width="0%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>XIMCaretDirection direction;</small></p>
</td>
<td width="70%"></td>
<td width="10%"></td>
<td width="0%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>short factor;</small></p>
</td>
<td width="70%"></td>
<td width="10%"></td>
<td width="0%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>XIMStringConversionOperation
operation;</small></p>
</td>
<td width="70%"></td>
<td width="10%"></td>
<td width="0%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>XIMStringConversionText *text;</small></p>
</td>
<td width="70%"></td>
<td width="10%"></td>
<td width="0%">
</td>
</table>
<p><small>} XIMStringConversionCallbackStruct;</small></p>
<p><small>typedef short
XIMStringConversionPosition;</small></p>
<p><small>typedef unsigned short
XIMStringConversionOperation;</small></p>
<p align=center><small><img src="grohtml-1439262.png"></small></p>
<p><small>│__</small></p>
<p><small><i>XIMStringConversionPosition</i> specifies the
starting position of the string to be returned in the
<i>XIMStringConversionText</i> structure. The value
identifies a position, in units of characters, relative to
the client’s cursor position in the client’s
buffer.</small></p>
<p><small>The ending position of the text buffer is
determined by the direction and factor members.
Specifically, it is the character position relative to the
starting point as defined by the <i>XIMCaretDirection</i>.
The factor member of
<i>XIMStringConversionCallbackStruct</i> specifies the
number of <i>XIMCaretDirection</i> positions to be applied.
For example, if the direction specifies <i>XIMLineEnd</i>
and factor is 1, then all characters from the starting
position to the end of the current display line are
returned. If the direction specifies <i>XIMForwardChar</i>
or <i>XIMBackwardChar</i>, then the factor specifies a
relative position, indicated in characters, from the
starting position.</small></p>
<p><small><i>XIMStringConversionOperation</i> specifies
whether the string to be converted should be deleted
(substitution) or copied (retrieval) from the client’s
buffer. When the <i>XIMStringConversionOperation</i> is
<i>XIMStringConversionSubstitution</i>, the client must
delete the string to be converted from its own buffer. When
the <i>XIMStringConversionOperation</i> is
<i>XIMStringConversionRetrieval</i>, the client must not
delete the string to be converted from its buffer. The
substitute operation is typically used for reconversion and
transliteration conversion, while the retrieval operation is
typically used for context-sensitive conversion.</small></p>
<a name="13.5.7.4. Preedit State Callbacks"></a>
<h2>13.5.7.4. Preedit State Callbacks</h2>
<p><small>When the input method turns preediting on or off,
a <i>PreeditStartCallback</i> or <i>PreeditDoneCallback</i>
callback is triggered to let the toolkit do the setup or the
cleanup for the preedit region.</small></p>
<p><small>__ │</small></p>
<pre><small>int PreeditStartCallback(<i>ic</i>, <i>client_data</i>, <i>call_data</i>)
XIC <i>ic</i>;
XPointer <i>client_data</i>;
XPointer <i>call_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the input context.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small><i>client_data</i> Specifies the additional
client data.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>call_data</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Not used for this callback and always passed as
NULL.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>When preedit starts on the specified input
context, the callback is called with a NULL call_data
argument. <i>PreeditStartCallback</i> will return the
maximum size of the preedit string. A positive number
indicates the maximum number of bytes allowed in the preedit
string, and a value of −1 indicates there is no
limit.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>void PreeditDoneCallback(<i>ic</i>, <i>client_data</i>, <i>call_data</i>)
XIC <i>ic</i>;
XPointer <i>client_data</i>;
XPointer <i>call_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the input context.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small><i>client_data</i> Specifies the additional
client data.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>call_data</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Not used for this callback and always passed as
NULL.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>When preedit stops on the specified input
context, the callback is called with a NULL call_data
argument. The client can release the data allocated by
<i>PreeditStartCallback</i>.</small></p>
<p><small><i>PreeditStartCallback</i> should initialize
appropriate data needed for displaying preedit information
and for handling further <i>PreeditDrawCallback</i> calls.
Once <i>PreeditStartCallback</i> is called, it will not be
called again before <i>PreeditDoneCallback</i> has been
called.</small></p>
<a name="13.5.7.5. Preedit Draw Callback"></a>
<h2>13.5.7.5. Preedit Draw Callback</h2>
<p><small>This callback is triggered to draw and insert,
delete or replace, preedit text in the preedit region. The
preedit text may include unconverted input text such as
Japanese Kana, converted text such as Japanese Kanji
characters, or characters of both kinds. That string is
either a multibyte or wide character string, whose encoding
matches the locale bound to the input context. The callback
prototype is as follows:</small></p>
<p><small>__ │</small></p>
<pre><small>void PreeditDrawCallback(<i>ic</i>, <i>client_data</i>, <i>call_data</i>)
XIC <i>ic</i>;
XPointer <i>client_data</i>;
XIMPreeditDrawCallbackStruct *<i>call_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the input context.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small><i>client_data</i> Specifies the additional
client data.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>call_data</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the preedit drawing
information.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The callback is passed an
<i>XIMPreeditDrawCallbackStruct</i> structure in the
call_data argument. The text member of this structure
contains the text to be drawn. After the string has been
drawn, the caret should be moved to the specified
location.</small></p>
<p><small>The <i>XIMPreeditDrawCallbackStruct</i> structure
is defined as follows:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct _XIMPreeditDrawCallbackStruct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int caret;</small></p>
</td>
<td width="50%">
<p><small>/* Cursor offset within preedit string
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int chg_first;</small></p>
</td>
<td width="50%">
<p><small>/* Starting change position */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int chg_length;</small></p>
</td>
<td width="50%">
<p><small>/* Length of the change in character count
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XIMText *text;</small></p>
</td>
<td width="50%">
</td>
</table>
<p><small>} XIMPreeditDrawCallbackStruct;</small></p>
<p><small>│__</small></p>
<p><small>The client must keep updating a buffer of the
preedit text and the callback arguments referring to indexes
in that buffer. The call_data fields have specific meanings
according to the operation, as follows:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>To indicate text deletion, the call_data member
specifies a NULL text field. The text to be deleted is then
the current text in the buffer from position chg_first
(starting at zero) on a character length of
chg_length.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>When text is non-NULL, it indicates insertion or
replacement of text in the buffer.</small></p>
</td>
</table>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The chg_length member identifies the number of
characters in the current preedit buffer that are affected
by this call. A positive chg_length indicates that
chg_length number of characters, starting at chg_first, must
be deleted or must be replaced by text, whose length is
specified in the <i>XIMText</i> structure.</small></p>
<!-- INDENTATION -->
<p><small>A chg_length value of zero indicates that text
must be inserted right at the position specified by
chg_first. A value of zero for chg_first specifies the first
character in the buffer.</small></p>
<!-- INDENTATION -->
<p><small>chg_length and chg_first combine to identify the
modification required to the preedit buffer; beginning at
chg_first, replace chg_length number of characters with the
text in the supplied <i>XIMText</i> structure. For example,
suppose the preedit buffer contains the string
"ABCDE".</small></p>
<!-- INDENTATION -->
<pre><small> Text: A B C D E
^ ^ ^ ^ ^ ^
CharPos: 0 1 2 3 4 5
</small></pre>
<!-- INDENTATION -->
<p><small>The CharPos in the diagram shows the location of
the character position relative to the
character.</small></p>
<!-- INDENTATION -->
<p><small>If the value of chg_first is 1 and the value of
chg_length is 3, this says to replace 3 characters beginning
at character position 1 with the string in the
<i>XIMText</i> structure. Hence, BCD would be replaced by
the value in the structure.</small></p>
<!-- INDENTATION -->
<p><small>Though chg_length and chg_first are both signed
integers they will never have a negative value.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The caret member identifies the character
position before which the cursor should be placed −
after modification to the preedit buffer has been completed.
For example, if caret is zero, the cursor is at the
beginning of the buffer. If the caret is one, the cursor is
between the first and second character.</small></p>
</td>
</table>
<p><small>__ │</small></p>
<pre><small> typedef struct _XIMText {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<p><small>unsigned short length;<br>
XIMFeedback * feedback;<br>
Bool encoding_is_wchar;<br>
union {</small></p>
<td width="19%"></td>
<td width="10%">
<p><small>char * multi_byte;</small></p>
</td>
<td width="10%"></td>
<td width="59%">
</td>
<tr valign="top" align="left">
<td width="19%"></td>
<td width="10%">
<p><small>wchar_t * wide_char;<br>
} string;</small></p>
</td>
<td width="10%"></td>
<td width="59%">
</td>
</table>
<p><small>} XIMText;</small></p>
<p><small>│__</small></p>
<p><small>The text string passed is actually a structure
specifying as follows:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The length member is the text length in
characters.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The encoding_is_wchar member is a value that
indicates if the text string is encoded in wide character or
multibyte format. The text string may be passed either as
multibyte or as wide character; the input method controls in
which form data is passed. The client’s callback
routine must be able to handle data passed in either
form.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="74%">
<p><small>The string member is the text string.</small></p>
</td>
<td width="15%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The feedback member indicates rendering type for
each character in the string member. If string is NULL
(indicating that only highlighting of the existing preedit
buffer should be updated), feedback points to length
highlight elements that should be applied to the existing
preedit buffer, beginning at chg_first.</small></p>
</td>
</table>
<p><small>The feedback member expresses the types of
rendering feedback the callback should apply when drawing
text. Rendering of the text to be drawn is specified either
in generic ways (for example, primary, secondary) or in
specific ways (reverse, underline). When generic indications
are given, the client is free to choose the rendering style.
It is necessary, however, that primary and secondary be
mapped to two distinct rendering styles.</small></p>
<p><small>If an input method wants to control display of
the preedit string, an input method can indicate the
visibility hints using feedbacks in a specific way. The
<i>XIMVisibleToForward</i>, <i>XIMVisibleToBackward</i>, and
<i>XIMVisibleCenter</i> masks are exclusively used for these
visibility hints. The <i>XIMVisibleToForward</i> mask
indicates that the preedit text is preferably displayed in
the primary draw direction from the caret position in the
preedit area forward. The <i>XIMVisibleToBackward</i> mask
indicates that the preedit text is preferably displayed from
the caret position in the preedit area backward, relative to
the primary draw direction. The <i>XIMVisibleCenter</i> mask
indicates that the preedit text is preferably displayed with
the caret position in the preedit area centered.</small></p>
<p><small>The insertion point of the preedit string could
exist outside of the visible area when visibility hints are
used. Only one of the masks is valid for the entire preedit
string, and only one character can hold one of these
feedbacks for a given input context at one time. This
feedback may be OR’ed together with another highlight
(such as <i>XIMReverse</i>). Only the most recently set
feedback is valid, and any previous feedback is
automatically canceled. This is a hint to the client, and
the client is free to choose how to display the preedit
string.</small></p>
<p><small>The feedback member also specifies how rendering
of the text argument should be performed. If the feedback is
NULL, the callback should apply the same feedback as is used
for the surrounding characters in the preedit buffer; if
chg_first is at a highlight boundary, the client can choose
which of the two highlights to use. If feedback is not NULL,
feedback specifies an array defining the rendering for each
character of the string, and the length of the array is thus
length.</small></p>
<p><small>If an input method wants to indicate that it is
only updating the feedback of the preedit text without
changing the content of it, the <i>XIMText</i> structure
will contain a NULL value for the string field, the number
of characters affected (relative to chg_first) will be in
the length field, and the feedback field will point to an
array of <i>XIMFeedback</i>.</small></p>
<p><small>Each element in the feedback array is a bitmask
represented by a value of type <i>XIMFeedback</i>. The valid
mask names are as follows:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef unsigned long XIMFeedback;
</small></pre>
<p align=center><small><img src="grohtml-1439263.png"></small></p>
<p><small>│__</small></p>
<p><small>Characters drawn with the <i>XIMReverse</i>
highlight should be drawn by swapping the foreground and
background colors used to draw normal, unhighlighted
characters. Characters drawn with the <i>XIMUnderline</i>
highlight should be underlined. Characters drawn with the
<i>XIMHighlight</i>, <i>XIMPrimary</i>, <i>XIMSecondary</i>,
and <i>XIMTertiary</i> highlights should be drawn in some
unique manner that must be different from <i>XIMReverse</i>
and <i>XIMUnderline</i>.</small></p>
<p align=center><small><img src="grohtml-1439264.png"></small></p>
<a name="13.5.7.6. Preedit Caret Callback"></a>
<h2>13.5.7.6. Preedit Caret Callback</h2>
<p><small>An input method may have its own navigation keys
to allow the user to move the text insertion point in the
preedit area (for example, to move backward or forward).
Consequently, input method needs to indicate to the client
that it should move the text insertion point. It then calls
the PreeditCaretCallback.</small></p>
<p><small>__ │</small></p>
<pre><small>void PreeditCaretCallback(<i>ic</i>, <i>client_data</i>, <i>call_data</i>)
XIC <i>ic</i>;
XPointer <i>client_data</i>;
XIMPreeditCaretCallbackStruct *<i>call_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the input context.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small><i>client_data</i> Specifies the additional
client data.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>call_data</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the preedit caret
information.</small></p>
</td>
<td width="0%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The input method will trigger
PreeditCaretCallback to move the text insertion point during
preedit. The call_data argument contains a pointer to an
<i>XIMPreeditCaretCallbackStruct</i> structure, which
indicates where the caret should be moved. The callback must
move the insertion point to its new location and return, in
field position, the new offset value from the initial
position.</small></p>
<p><small>The <i>XIMPreeditCaretCallbackStruct</i>
structure is defined as follows:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct _XIMPreeditCaretCallbackStruct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int position;</small></p>
</td>
<td width="50%">
<p><small>/* Caret offset within preedit string
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XIMCaretDirection direction;/* Caret moves
direction */</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XIMCaretStyle style;/* Feedback of the caret
*/</small></p>
</td>
<td width="50%">
</td>
</table>
<p><small>} XIMPreeditCaretCallbackStruct;</small></p>
<p><small>│__</small></p>
<p><small>The <i>XIMCaretStyle</i> structure is defined as
follows:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef enum {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XIMIsInvisible,</small></p>
</td>
<td width="50%">
<p><small>/* Disable caret feedback */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XIMIsPrimary,</small></p>
</td>
<td width="50%">
<p><small>/* UI defined caret feedback */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XIMIsSecondary,</small></p>
</td>
<td width="50%">
<p><small>/* UI defined caret feedback */</small></p>
</td>
</table>
<p><small>} XIMCaretStyle;</small></p>
<p><small>│__</small></p>
<p><small>The <i>XIMCaretDirection</i> structure is defined
as follows:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef enum {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XIMForwardChar, XIMBackwardChar,</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XIMForwardWord, XIMBackwardWord,</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XIMCaretUp, XIMCaretDown,</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XIMNextLine, XIMPreviousLine,</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XIMLineStart, XIMLineEnd,</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XIMAbsolutePosition,</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XIMDontChange,</small></p>
</td>
<td width="49%">
</td>
</table>
<p><small>} XIMCaretDirection;</small></p>
<p><small>│__</small></p>
<p><small>These values are defined as follows:</small></p>
<p align=center><small><img src="grohtml-1439265.png"></small></p>
<a name="13.5.7.7. Status Callbacks"></a>
<h2>13.5.7.7. Status Callbacks</h2>
<p><small>An input method may communicate changes in the
status of an input context (for example, created, destroyed,
or focus changes) with three status callbacks:
StatusStartCallback, StatusDoneCallback, and
StatusDrawCallback.</small></p>
<p><small>When the input context is created or gains focus,
the input method calls the StatusStartCallback
callback.</small></p>
<p><small>__ │</small></p>
<pre><small>void StatusStartCallback(<i>ic</i>, <i>client_data</i>, <i>call_data</i>)
XIC <i>ic</i>;
XPointer <i>client_data</i>;
XPointer <i>call_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the input context.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small><i>client_data</i> Specifies the additional
client data.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>call_data</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Not used for this callback and always passed as
NULL.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The callback should initialize appropriate data
for displaying status and for responding to
StatusDrawCallback calls. Once StatusStartCallback is
called, it will not be called again before
StatusDoneCallback has been called.</small></p>
<p><small>When an input context is destroyed or when it
loses focus, the input method calls
StatusDoneCallback.</small></p>
<p><small>__ │</small></p>
<pre><small>void StatusDoneCallback(<i>ic</i>, <i>client_data</i>, <i>call_data</i>)
XIC <i>ic</i>;
XPointer <i>client_data</i>;
XPointer <i>call_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the input context.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small><i>client_data</i> Specifies the additional
client data.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>call_data</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Not used for this callback and always passed as
NULL.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The callback may release any data allocated on
<i>StatusStart</i>.</small></p>
<p><small>When an input context status has to be updated,
the input method calls StatusDrawCallback.</small></p>
<p><small>__ │</small></p>
<pre><small>void StatusDrawCallback(<i>ic</i>, <i>client_data</i>, <i>call_data</i>)
XIC <i>ic</i>;
XPointer <i>client_data</i>;
XIMStatusDrawCallbackStruct *<i>call_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the input context.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small><i>client_data</i> Specifies the additional
client data.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>call_data</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the status drawing
information.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The callback should update the status area by
either drawing a string or imaging a bitmap in the status
area.</small></p>
<p><small>The <i>XIMStatusDataType</i> and
<i>XIMStatusDrawCallbackStruct</i> structures are defined as
follows:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef enum {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>XIMTextType,</small></p>
</td>
<td width="79%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>XIMBitmapType,</small></p>
</td>
<td width="79%">
</td>
</table>
<p><small>} XIMStatusDataType;</small></p>
<p><small>typedef struct _XIMStatusDrawCallbackStruct
{</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="5" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="0%"></td>
<td width="10%">
<p><small>XIMStatusDataType type;</small></p>
</td>
<td width="40%"></td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="0%"></td>
<td width="10%">
<p><small>union {</small></p>
</td>
<td width="40%"></td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="0%"></td>
<td width="10%">
</td>
<td width="40%">
<p><small>XIMText *text;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="0%"></td>
<td width="10%">
</td>
<td width="40%">
<p><small>Pixmap bitmap;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="0%"></td>
<td width="10%">
<p><small>} data;</small></p>
</td>
<td width="40%"></td>
<td width="39%">
</td>
</table>
<p><small>} XIMStatusDrawCallbackStruct;</small></p>
<p><small>│__</small></p>
<p><small>The feedback styles <i>XIMVisibleToForward</i>,
<i>XIMVisibleToBackward</i>, and <i>XIMVisibleToCenter</i>
are not relevant and will not appear in the
<i>XIMFeedback</i> element of the <i>XIMText</i>
structure.</small></p>
<a name="13.5.8. Event Filtering"></a>
<h2>13.5.8. Event Filtering</h2>
<p><small>Xlib provides the ability for an input method to
register a filter internal to Xlib. This filter is called by
a client (or toolkit) by calling <i>XFilterEvent</i> after
calling <i>XNextEvent</i>. Any client that uses the
<i>XIM</i> interface should call <i>XFilterEvent</i> to
allow input methods to process their events without
knowledge of the client’s dispatching mechanism. A
client’s user interface policy may determine the
priority of event filters with respect to other
event-handling mechanisms (for example, modal
grabs).</small></p>
<p><small>Clients may not know how many filters there are,
if any, and what they do. They may only know if an event has
been filtered on return of <i>XFilterEvent</i>. Clients
should discard filtered events.</small></p>
<p><small>To filter an event, use
<i>XFilterEvent</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XFilterEvent(<i>event</i>, <i>w</i>)
XEvent *<i>event</i>;
Window <i>w</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>event</i></small></p>
</td>
<td width="10%"></td>
<td width="60%">
<p><small>Specifies the event to filter.</small></p>
</td>
<td width="19%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the window for which the filter is to
be applied.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>If the window argument is <i>None</i>,
<i>XFilterEvent</i> applies the filter to the window
specified in the <i>XEvent</i> structure. The window
argument is provided so that layers above Xlib that do event
redirection can indicate to which window an event has been
redirected.</small></p>
<p><small>If <i>XFilterEvent</i> returns <i>True</i>, then
some input method has filtered the event, and the client
should discard the event. If <i>XFilterEvent</i> returns
<i>False</i>, then the client should continue processing the
event.</small></p>
<p><small>If a grab has occurred in the client and
<i>XFilterEvent</i> returns <i>True</i>, the client should
ungrab the keyboard.</small></p>
<a name="13.5.9. Getting Keyboard Input"></a>
<h2>13.5.9. Getting Keyboard Input</h2>
<p><small>To get composed input from an input method, use
<i>XmbLookupString</i> or
<i>XwcLookupString</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XmbLookupString(<i>ic</i>, <i>event</i>, <i>buffer_return</i>, <i>bytes_buffer</i>, <i>keysym_return</i>, <i>status_return</i>)
XIC <i>ic</i>;
XKeyPressedEvent *<i>event</i>;
char *<i>buffer_return</i>;
int <i>bytes_buffer</i>;
KeySym *<i>keysym_return</i>;
Status *<i>status_return</i>;
</small></pre>
<pre><small>int XwcLookupString(<i>ic</i>, <i>event</i>, <i>buffer_return</i>, <i>bytes_buffer</i>, <i>keysym_return</i>, <i>status_return</i>)
XIC <i>ic</i>;
XKeyPressedEvent *<i>event</i>;
wchar_t *<i>buffer_return</i>;
int <i>wchars_buffer</i>;
KeySym *<i>keysym_return</i>;
Status *<i>status_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>ic</i></small></p>
</td>
<td width="16%"></td>
<td width="56%">
<p><small>Specifies the input context.</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>event</i></small></p>
</td>
<td width="10%"></td>
<td width="70%">
<p><small>Specifies the key event to be used.</small></p>
</td>
<td width="9%">
</td>
</table>
<p><small><i>buffer_return</i> Returns a multibyte string
or wide character string (if any) from the input
method.</small></p>
<p><small><i>bytes_buffer</i></small></p>
<p><small><i>wchars_buffer</i> Specifies space available in
the return buffer.</small></p>
<p><small><i>keysym_return</i> Returns the KeySym computed
from the event if this argument is not NULL.</small></p>
<p><small><i>status_return</i> Returns a value indicating
what kind of data is returned.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XmbLookupString</i> and
<i>XwcLookupString</i> functions return the string from the
input method specified in the buffer_return argument. If no
string is returned, the buffer_return argument is
unchanged.</small></p>
<p><small>The KeySym into which the KeyCode from the event
was mapped is returned in the keysym_return argument if it
is non-NULL and the status_return argument indicates that a
KeySym was returned. If both a string and a KeySym are
returned, the KeySym value does not necessarily correspond
to the string returned.</small></p>
<p><small><i>XmbLookupString</i> returns the length of the
string in bytes, and <i>XwcLookupString</i> returns the
length of the string in characters. Both
<i>XmbLookupString</i> and <i>XwcLookupString</i> return
text in the encoding of the locale bound to the input method
of the specified input context.</small></p>
<p><small>Each string returned by <i>XmbLookupString</i>
and <i>XwcLookupString</i> begins in the initial state of
the encoding of the locale (if the encoding of the locale is
state-dependent).</small></p>
<p align=center><small>Note</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>To insure proper input processing, it is essential
that the client pass only <i>KeyPress</i> events to
<i>XmbLookupString</i> and <i>XwcLookupString</i>. Their
behavior when a client passes a <i>KeyRelease</i> event is
undefined.</small></p>
</td>
</table>
<p><small>Clients should check the status_return argument
before using the other returned values. These two functions
both return a value to status_return that indicates what has
been returned in the other arguments. The possible values
returned are:</small></p>
<p align=center><small><img src="grohtml-1439266.png"></small></p>
<p><small>It does not make any difference if the input
context passed as an argument to <i>XmbLookupString</i> and
<i>XwcLookupString</i> is the one currently in possession of
the focus or not. Input may have been composed within an
input context before it lost the focus, and that input may
be returned on subsequent calls to <i>XmbLookupString</i> or
<i>XwcLookupString</i> even though it does not have any more
keyboard focus.</small></p>
<a name="13.5.10. Input Method Conventions"></a>
<h2>13.5.10. Input Method Conventions</h2>
<p><small>The input method architecture is transparent to
the client. However, clients should respect a number of
conventions in order to work properly. Clients must also be
aware of possible effects of synchronization between input
method and library in the case of a remote input
server.</small></p>
<a name="13.5.10.1. Client Conventions"></a>
<h2>13.5.10.1. Client Conventions</h2>
<p><small>A well-behaved client (or toolkit) should first
query the input method style. If the client cannot satisfy
the requirements of the supported styles (in terms of
geometry management or callbacks), it should negotiate with
the user continuation of the program or raise an exception
or error of some sort.</small></p>
<a name="13.5.10.2. Synchronization Conventions"></a>
<h2>13.5.10.2. Synchronization Conventions</h2>
<p><small>A <i>KeyPress</i> event with a KeyCode of zero is
used exclusively as a signal that an input method has
composed input that can be returned by
<i>XmbLookupString</i> or <i>XwcLookupString</i>. No other
use is made of a <i>KeyPress</i> event with KeyCode of
zero.</small></p>
<p><small>Such an event may be generated by either a
front-end or a back-end input method in an
implementation-dependent manner. Some possible ways to
generate this event include:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>A synthetic event sent by an input method
server</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>An artificial event created by a input method
filter and pushed onto a client’s event
queue</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>A <i>KeyPress</i> event whose KeyCode value is
modified by an input method filter</small></p>
</td>
</table>
<p><small>When callback support is specified by the client,
input methods will not take action unless they explicitly
called back the client and obtained no response (the
callback is not specified or returned invalid
data).</small></p>
<a name="13.6. String Constants"></a>
<h2>13.6. String Constants</h2>
<p><small>The following symbols for string constants are
defined in <<i>X11/Xlib.h</i>>. Although they are
shown here with particular macro definitions, they may be
implemented as macros, as global symbols, or as a mixture of
the two. The string pointer value itself is not significant;
clients must not assume that inequality of two values
implies inequality of the actual string data.</small></p>
<p align=center><small><img src="grohtml-1439267.png"></small></p>
<p align=center><small><img src="grohtml-1439268.png"></small></p>
<p align=center><small><img src="grohtml-1439269.png"></small></p>
<p align=center><small><img src="grohtml-1439270.png"></small></p>
<p><small><b>13</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b><small>Chapter 14</small></b></p>
<p align=center><b><small>Inter-Client Communication
Functions</small></b></p>
<p><small>The <i>Inter-Client Communication Conventions
Manual</i>, hereafter referred to as the ICCCM, details the
X Consortium approved conventions that govern inter-client
communications. These conventions ensure peer-to-peer client
cooperation in the use of selections, cut buffers, and
shared resources as well as client cooperation with window
and session managers. For further information, see the
<i>Inter-Client Communication Conventions
Manual</i>.</small></p>
<p><small>Xlib provides a number of standard properties and
programming interfaces that are ICCCM compliant. The
predefined atoms for some of these properties are defined in
the <<i>X11/Xatom.h</i>> header file, where to avoid
name conflicts with user symbols their <i>#define</i> name
has an XA_ prefix. For further information about atoms and
properties, see section 4.3.</small></p>
<p><small>Xlib’s selection and cut buffer mechanisms
provide the primary programming interfaces by which peer
client applications communicate with each other (see
sections 4.5 and 16.6). The functions discussed in this
chapter provide the primary programming interfaces by which
client applications communicate with their window and
session managers as well as share standard
colormaps.</small></p>
<p><small>The standard properties that are of special
interest for communicating with window and session managers
are:</small></p>
<p align=center><small><img src="grohtml-1439271.png"></small></p>
<p><small>The remainder of this chapter
discusses:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="76%">
<p><small>Client to window manager
communication</small></p>
</td>
<td width="13%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="78%">
<p><small>Client to session manager
communication</small></p>
</td>
<td width="11%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="36%">
<p><small>Standard colormaps</small></p>
</td>
<td width="53%">
</td>
</table>
<a name="14.1. Client to Window Manager Communication"></a>
<h2>14.1. Client to Window Manager Communication</h2>
<p><small>This section discusses how to:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="56%">
<p><small>Manipulate top-level windows</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="40%">
<p><small>Convert string lists</small></p>
</td>
<td width="49%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="56%">
<p><small>Set and read text properties</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="66%">
<p><small>Set and read the WM_NAME property</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="76%">
<p><small>Set and read the WM_ICON_NAME
property</small></p>
</td>
<td width="13%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="68%">
<p><small>Set and read the WM_HINTS property</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="82%">
<p><small>Set and read the WM_NORMAL_HINTS
property</small></p>
</td>
<td width="7%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="68%">
<p><small>Set and read the WM_CLASS property</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="84%">
<p><small>Set and read the WM_TRANSIENT_FOR
property</small></p>
</td>
<td width="5%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="76%">
<p><small>Set and read the WM_PROTOCOLS
property</small></p>
</td>
<td width="13%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Set and read the WM_COLORMAP_WINDOWS
property</small></p>
</td>
<td width="0%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="76%">
<p><small>Set and read the WM_ICON_SIZE
property</small></p>
</td>
<td width="13%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Use window manager convenience
functions</small></p>
</td>
<td width="9%">
</td>
</table>
<a name="14.1.1. Manipulating Top-Level Windows"></a>
<h2>14.1.1. Manipulating Top-Level Windows</h2>
<p><small>Xlib provides functions that you can use to
change the visibility or size of top-level windows (that is,
those that were created as children of the root window).
Note that the subwindows that you create are ignored by
window managers. Therefore, you should use the basic window
functions described in chapter 3 to manipulate your
application’s subwindows.</small></p>
<p><small>To request that a top-level window be iconified,
use <i>XIconifyWindow</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XIconifyWindow(<i>display</i>, <i>w</i>, <i>screen_number</i>)
Display *<i>display</i>;
Window <i>w</i>;
int <i>screen_number</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XIconifyWindow</i> function sends a
WM_CHANGE_STATE <i>ClientMessage</i> event with a format of
32 and a first data element of <i>IconicState</i> (as
described in section 4.1.4 of the <i>Inter-Client
Communication Conventions Manual</i>) and a window of w to
the root window of the specified screen with an event mask
set to <i>SubstructureNotifyMask</i>|
<i>SubstructureRedirectMask</i>. Window managers may elect
to receive this message and if the window is in its normal
state, may treat it as a request to change the
window’s state from normal to iconic. If the
WM_CHANGE_STATE property cannot be interned,
<i>XIconifyWindow</i> does not send a message and returns a
zero status. It returns a nonzero status if the client
message is sent successfully; otherwise, it returns a zero
status.</small></p>
<p><small>To request that a top-level window be withdrawn,
use <i>XWithdrawWindow</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XWithdrawWindow(<i>display</i>, <i>w</i>, <i>screen_number</i>)
Display *<i>display</i>;
Window <i>w</i>;
int <i>screen_number</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XWithdrawWindow</i> function unmaps the
specified window and sends a synthetic <i>UnmapNotify</i>
event to the root window of the specified screen. Window
managers may elect to receive this message and may treat it
as a request to change the window’s state to
withdrawn. When a window is in the withdrawn state, neither
its normal nor its iconic representations is visible. It
returns a nonzero status if the <i>UnmapNotify</i> event is
successfully sent; otherwise, it returns a zero
status.</small></p>
<p><small><i>XWithdrawWindow</i> can generate a
<i>BadWindow</i> error.</small></p>
<p><small>To request that a top-level window be
reconfigured, use <i>XReconfigureWMWindow</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XReconfigureWMWindow(<i>display</i>, <i>w</i>, <i>screen_number</i>, <i>value_mask</i>, <i>values</i>)
Display *<i>display</i>;
Window <i>w</i>;
int <i>screen_number</i>;
unsigned int <i>value_mask</i>;
XWindowChanges *<i>values</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>screen_number</i> Specifies the appropriate
screen number on the host server.</small></p>
<p><small><i>value_mask</i> 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.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>values</i></small></p>
</td>
<td width="8%"></td>
<td width="78%">
<p><small>Specifies the <i>XWindowChanges</i>
structure.</small></p>
</td>
<td width="1%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XReconfigureWMWindow</i> function issues a
<i>ConfigureWindow</i> request on the specified top-level
window. If the stacking mode is changed and the request
fails with a <i>BadMatch</i> error, the error is trapped by
Xlib and a synthetic <i>ConfigureRequestEvent</i> containing
the same configuration parameters is sent to the root of the
specified window. Window managers may elect to receive this
event and treat it as a request to reconfigure the indicated
window. It returns a nonzero status if the request or event
is successfully sent; otherwise, it returns a zero
status.</small></p>
<p><small><i>XReconfigureWMWindow</i> can generate
<i>BadValue</i> and <i>BadWindow</i> errors.</small></p>
<a name="14.1.2. Converting String Lists"></a>
<h2>14.1.2. Converting String Lists</h2>
<p><small>Many of the text properties allow a variety of
types and formats. Because the data stored in these
properties are not simple null-terminated strings, an
<i>XTextProperty</i> structure is used to describe the
encoding, type, and length of the text as well as its value.
The <i>XTextProperty</i> structure contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned char *value;/* property data
*/</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>Atom encoding;</small></p>
</td>
<td width="50%">
<p><small>/* type of property */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int format;</small></p>
</td>
<td width="50%">
<p><small>/* 8, 16, or 32 */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned long nitems;/* number of items in value
*/</small></p>
</td>
<td width="50%">
</td>
</table>
<p><small>} XTextProperty;</small></p>
<p><small>│__</small></p>
<p><small>Xlib provides functions to convert localized text
to or from encodings that support the inter-client
communication conventions for text. In addition, functions
are provided for converting between lists of pointers to
character strings and text properties in the STRING
encoding.</small></p>
<p><small>The functions for localized text return a signed
integer error status that encodes <i>Success</i> as zero,
specific error conditions as negative numbers, and partial
conversion as a count of unconvertible
characters.</small></p>
<p><small>__ │</small></p>
<p align=center><small><img src="grohtml-1439272.png"></small></p>
<pre><small>typedef enum {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XStringStyle,</small></p>
</td>
<td width="50%">
<p><small>/* STRING */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XCompoundTextStyle,</small></p>
</td>
<td width="50%">
<p><small>/* COMPOUND_TEXT */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XTextStyle,</small></p>
</td>
<td width="50%">
<p><small>/* text in owner’s encoding (current
locale) */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XStdICCTextStyle</small></p>
</td>
<td width="50%">
<p><small>/* STRING, else COMPOUND_TEXT */</small></p>
</td>
</table>
<p><small>} XICCEncodingStyle;</small></p>
<p><small>│__</small></p>
<p><small>To convert a list of text strings to an
<i>XTextProperty</i> structure, use
<i>XmbTextListToTextProperty</i> or
<i>XwcTextListToTextProperty</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XmbTextListToTextProperty(<i>display</i>, <i>list</i>, <i>count</i>, <i>style</i>, <i>text_prop_return</i>)
Display *<i>display</i>;
char **<i>list</i>;
int <i>count</i>;
XICCEncodingStyle <i>style</i>;
XTextProperty *<i>text_prop_return</i>;
</small></pre>
<pre><small>int XwcTextListToTextProperty(<i>display</i>, <i>list</i>, <i>count</i>, <i>style</i>, <i>text_prop_return</i>)
Display *<i>display</i>;
wchar_t **<i>list</i>;
int <i>count</i>;
XICCEncodingStyle <i>style</i>;
XTextProperty *<i>text_prop_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>list</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies a list of null-terminated character
strings.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>count</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the number of strings
specified.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>style</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the manner in which the property is
encoded.</small></p>
</td>
</table>
<p><small><i>text_prop_return</i> Returns the
<i>XTextProperty</i> structure.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XmbTextListToTextProperty</i> and
<i>XwcTextListToTextProperty</i> functions set the specified
<i>XTextProperty</i> value to a set of null-separated
elements representing the concatenation of the specified
list of null-terminated text strings. A final terminating
null is stored at the end of the value field of
text_prop_return but is not included in the nitems
member.</small></p>
<p><small>The functions set the encoding field of
text_prop_return to an <i>Atom</i> for the specified display
naming the encoding determined by the specified style and
convert the specified text list to this encoding for storage
in the text_prop_return value field. If the style
<i>XStringStyle</i> or <i>XCompoundTextStyle</i> is
specified, this encoding is
‘‘STRING’’ or
‘‘COMPOUND_TEXT’’, respectively. If
the style <i>XTextStyle</i> is specified, this encoding is
the encoding of the current locale. If the style
<i>XStdICCTextStyle</i> is specified, this encoding is
‘‘STRING’’ if the text is fully
convertible to STRING, else
‘‘COMPOUND_TEXT’’.</small></p>
<p><small>If insufficient memory is available for the new
value string, the functions return <i>XNoMemory</i>. If the
current locale is not supported, the functions return
<i>XLocaleNotSupported</i>. In both of these error cases,
the functions do not set text_prop_return.</small></p>
<p><small>To determine if the functions are guaranteed not
to return <i>XLocaleNotSupported</i>, use
<i>XSupportsLocale</i>.</small></p>
<p><small>If the supplied text is not fully convertible to
the specified encoding, the functions return the number of
unconvertible characters. Each unconvertible character is
converted to an implementation-defined and encoding-specific
default string. Otherwise, the functions return
<i>Success</i>. Note that full convertibility to all styles
except <i>XStringStyle</i> is guaranteed.</small></p>
<p><small>To free the storage for the value field, use
<i>XFree</i>.</small></p>
<p><small>To obtain a list of text strings from an
<i>XTextProperty</i> structure, use
<i>XmbTextPropertyToTextList</i> or
<i>XwcTextPropertyToTextList</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XmbTextPropertyToTextList(<i>display</i>, <i>text_prop</i>, <i>list_return</i>, <i>count_return</i>)
Display *<i>display</i>;
XTextProperty *<i>text_prop</i>;
char ***<i>list_return</i>;
int *<i>count_return</i>;
</small></pre>
<pre><small>int XwcTextPropertyToTextList(<i>display</i>, <i>text_prop</i>, <i>list_return</i>, <i>count_return</i>)
Display *<i>display</i>;
XTextProperty *<i>text_prop</i>;
wchar_t ***<i>list_return</i>;
int *<i>count_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>text_prop</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the <i>XTextProperty</i> structure to
be used.</small></p>
</td>
</table>
<p><small><i>list_return</i> Returns a list of
null-terminated character strings.</small></p>
<p><small><i>count_return</i> Returns the number of
strings.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XmbTextPropertyToTextList</i> and
<i>XwcTextPropertyToTextList</i> functions return a list of
text strings in the current locale representing the
null-separated elements of the specified
<i>XTextProperty</i> structure. The data in text_prop must
be format 8.</small></p>
<p><small>Multiple elements of the property (for example,
the strings in a disjoint text selection) are separated by a
null byte. The contents of the property are not required to
be null-terminated; any terminating null should not be
included in text_prop.nitems.</small></p>
<p><small>If insufficient memory is available for the list
and its elements, <i>XmbTextPropertyToTextList</i> and
<i>XwcTextPropertyToTextList</i> return <i>XNoMemory</i>. If
the current locale is not supported, the functions return
<i>XLocaleNotSupported</i>. Otherwise, if the encoding field
of text_prop is not convertible to the encoding of the
current locale, the functions return
<i>XConverterNotFound</i>. For supported locales, existence
of a converter from COMPOUND_TEXT, STRING or the encoding of
the current locale is guaranteed if <i>XSupportsLocale</i>
returns <i>True</i> for the current locale (but the actual
text may contain unconvertible characters). Conversion of
other encodings is implementation-dependent. In all of these
error cases, the functions do not set any return
values.</small></p>
<p><small>Otherwise, <i>XmbTextPropertyToTextList</i> and
<i>XwcTextPropertyToTextList</i> return the list of
null-terminated text strings to list_return and the number
of text strings to count_return.</small></p>
<p><small>If the value field of text_prop is not fully
convertible to the encoding of the current locale, the
functions return the number of unconvertible characters.
Each unconvertible character is converted to a string in the
current locale that is specific to the current locale. To
obtain the value of this string, use <i>XDefaultString</i>.
Otherwise, <i>XmbTextPropertyToTextList</i> and
<i>XwcTextPropertyToTextList</i> return
<i>Success</i>.</small></p>
<p><small>To free the storage for the list and its contents
returned by <i>XmbTextPropertyToTextList</i>, use
<i>XFreeStringList</i>. To free the storage for the list and
its contents returned by <i>XwcTextPropertyToTextList</i>,
use <i>XwcFreeStringList</i>.</small></p>
<p><small>To free the in-memory data associated with the
specified wide character string list, use
<i>XwcFreeStringList</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XwcFreeStringList(<i>list</i>)
wchar_t **<i>list</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>list</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the list of strings to be
freed.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XwcFreeStringList</i> function frees
memory allocated by
<i>XwcTextPropertyToTextList</i>.</small></p>
<p><small>To obtain the default string for text conversion
in the current locale, use
<i>XDefaultString</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char *XDefaultString()
</small></pre>
<p><small>│__</small></p>
<p><small>The <i>XDefaultString</i> function returns the
default string used by Xlib for text conversion (for
example, in <i>XmbTextPropertyToTextList</i>). The default
string is the string in the current locale that is output
when an unconvertible character is found during text
conversion. If the string returned by <i>XDefaultString</i>
is the empty string (""), no character is output
in the converted text. <i>XDefaultString</i> does not return
NULL.</small></p>
<p><small>The string returned by <i>XDefaultString</i> is
independent of the default string for text drawing; see
<i>XCreateFontSet</i> to obtain the default string for an
<i>XFontSet</i>.</small></p>
<p><small>The behavior when an invalid codepoint is
supplied to any Xlib function is undefined.</small></p>
<p><small>The returned string is null-terminated. It is
owned by Xlib and should not be modified or freed by the
client. It may be freed after the current locale is changed.
Until freed, it will not be modified by Xlib.</small></p>
<p><small>To set the specified list of strings in the
STRING encoding to a <i>XTextProperty</i> structure, use
<i>XStringListToTextProperty</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XStringListToTextProperty(<i>list</i>, <i>count</i>, <i>text_prop_return</i>)
char **<i>list</i>;
int <i>count</i>;
XTextProperty *<i>text_prop_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>list</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies a list of null-terminated character
strings.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>count</i></small></p>
</td>
<td width="10%"></td>
<td width="64%">
<p><small>Specifies the number of strings.</small></p>
</td>
<td width="15%">
</td>
</table>
<p><small><i>text_prop_return</i> Returns the
<i>XTextProperty</i> structure.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XStringListToTextProperty</i> function
sets the specified <i>XTextProperty</i> to be of type STRING
(format 8) with a value representing the concatenation of
the specified list of null-separated character strings. An
extra null byte (which is not included in the nitems member)
is stored at the end of the value field of text_prop_return.
The strings are assumed (without verification) to be in the
STRING encoding. If insufficient memory is available for the
new value string, <i>XStringListToTextProperty</i> does not
set any fields in the <i>XTextProperty</i> structure and
returns a zero status. Otherwise, it returns a nonzero
status. To free the storage for the value field, use
<i>XFree</i>.</small></p>
<p><small>To obtain a list of strings from a specified
<i>XTextProperty</i> structure in the STRING encoding, use
<i>XTextPropertyToStringList</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XTextPropertyToStringList(<i>text_prop</i>, <i>list_return</i>, <i>count_return</i>)
XTextProperty *<i>text_prop</i>;
char ***<i>list_return</i>;
int *<i>count_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>text_prop</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the <i>XTextProperty</i> structure to
be used.</small></p>
</td>
</table>
<p><small><i>list_return</i> Returns a list of
null-terminated character strings.</small></p>
<p><small><i>count_return</i> Returns the number of
strings.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XTextPropertyToStringList</i> function
returns a list of strings representing the null-separated
elements of the specified <i>XTextProperty</i> structure.
The data in text_prop must be of type STRING and format 8.
Multiple elements of the property (for example, the strings
in a disjoint text selection) are separated by NULL
(encoding 0). The contents of the property are not
null-terminated. If insufficient memory is available for the
list and its elements, <i>XTextPropertyToStringList</i> sets
no return values and returns a zero status. Otherwise, it
returns a nonzero status. To free the storage for the list
and its contents, use <i>XFreeStringList</i>.</small></p>
<p><small>To free the in-memory data associated with the
specified string list, use
<i>XFreeStringList</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XFreeStringList(<i>list</i>)
char **<i>list</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>list</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the list of strings to be
freed.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XFreeStringList</i> function releases
memory allocated by <i>XmbTextPropertyToTextList</i> and
<i>XTextPropertyToStringList</i> and the missing charset
list allocated by <i>XCreateFontSet</i>.</small></p>
<a name="14.1.3. Setting and Reading Text Properties"></a>
<h2>14.1.3. Setting and Reading Text Properties</h2>
<p><small>Xlib provides two functions that you can use to
set and read the text properties for a given window. You can
use these functions to set and read those properties of type
TEXT (WM_NAME, WM_ICON_NAME, WM_COMMAND, and
WM_CLIENT_MACHINE). In addition, Xlib provides separate
convenience functions that you can use to set each of these
properties. For further information about these convenience
functions, see sections 14.1.4, 14.1.5, 14.2.1, and 14.2.2,
respectively.</small></p>
<p><small>To set one of a window’s text properties,
use <i>XSetTextProperty</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XSetTextProperty(<i>display</i>, <i>w</i>, <i>text_prop</i>, <i>property</i>)
Display *<i>display</i>;
Window <i>w</i>;
XTextProperty *<i>text_prop</i>;
Atom <i>property</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>text_prop</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the <i>XTextProperty</i> structure to
be used.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>property</i></small></p>
</td>
<td width="4%"></td>
<td width="56%">
<p><small>Specifies the property name.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetTextProperty</i> function replaces the
existing specified property for the named window with the
data, type, format, and number of items determined by the
value field, the encoding field, the format field, and the
nitems field, respectively, of the specified
<i>XTextProperty</i> structure. If the property does not
already exist, <i>XSetTextProperty</i> sets it for the
specified window.</small></p>
<p><small><i>XSetTextProperty</i> can generate
<i>BadAlloc</i>, <i>BadAtom</i>, <i>BadValue</i>, and
<i>BadWindow</i> errors.</small></p>
<p><small>To read one of a window’s text properties,
use <i>XGetTextProperty</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetTextProperty(<i>display</i>, <i>w</i>, <i>text_prop_return</i>, <i>property</i>)
Display *<i>display</i>;
Window <i>w</i>;
XTextProperty *<i>text_prop_return</i>;
Atom <i>property</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>text_prop_return</i> Returns the
<i>XTextProperty</i> structure.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>property</i></small></p>
</td>
<td width="4%"></td>
<td width="56%">
<p><small>Specifies the property name.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetTextProperty</i> function reads the
specified property from the window and stores the data in
the returned <i>XTextProperty</i> structure. It stores the
data in the value field, the type of the data in the
encoding field, the format of the data in the format field,
and the number of items of data in the nitems field. An
extra byte containing null (which is not included in the
nitems member) is stored at the end of the value field of
text_prop_return. The particular interpretation of the
property’s encoding and data as text is left to the
calling application. If the specified property does not
exist on the window, <i>XGetTextProperty</i> sets the value
field to NULL, the encoding field to <i>None</i>, the format
field to zero, and the nitems field to zero.</small></p>
<p><small>If it was able to read and store the data in the
<i>XTextProperty</i> structure, <i>XGetTextProperty</i>
returns a nonzero status; otherwise, it returns a zero
status.</small></p>
<p><small><i>XGetTextProperty</i> can generate
<i>BadAtom</i> and <i>BadWindow</i> errors.</small></p>
<a name="14.1.4. Setting and Reading the WM_NAME Property"></a>
<h2>14.1.4. Setting and Reading the WM_NAME Property</h2>
<p><small>Xlib provides convenience functions that you can
use to set and read the WM_NAME property for a given
window.</small></p>
<p><small>To set a window’s WM_NAME property with the
supplied convenience function, use
<i>XSetWMName</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XSetWMName(<i>display</i>, <i>w</i>, <i>text_prop</i>)
Display *<i>display</i>;
Window <i>w</i>;
XTextProperty *<i>text_prop</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>text_prop</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the <i>XTextProperty</i> structure to
be used.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetWMName</i> convenience function calls
<i>XSetTextProperty</i> to set the WM_NAME
property.</small></p>
<p><small>To read a window’s WM_NAME property with
the supplied convenience function, use
<i>XGetWMName</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetWMName(<i>display</i>, <i>w</i>, <i>text_prop_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
XTextProperty *<i>text_prop_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>text_prop_return</i> Returns the
<i>XTextProperty</i> structure.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetWMName</i> convenience function calls
<i>XGetTextProperty</i> to obtain the WM_NAME property. It
returns a nonzero status on success; otherwise, it returns a
zero status.</small></p>
<p><small>The following two functions have been superseded
by <i>XSetWMName</i> and <i>XGetWMName</i>, respectively.
You can use these additional convenience functions for
window names that are encoded as STRING
properties.</small></p>
<p><small>To assign a name to a window, use
<i>XStoreName</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XStoreName(<i>display</i>, <i>w</i>, <i>window_name</i>)
Display *<i>display</i>;
Window <i>w</i>;
char *<i>window_name</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>window_name</i> Specifies the window name,
which should be a null-terminated string.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XStoreName</i> function assigns the name
passed to window_name to the specified window. A window
manager can display the window name in some prominent place,
such as the title bar, to allow users to identify windows
easily. Some window managers may display a window’s
name in the window’s icon, although they are
encouraged to use the window’s icon name if one is
provided by the application. If the string is not in the
Host Portable Character Encoding, the result is
implementation-dependent.</small></p>
<p><small><i>XStoreName</i> can generate <i>BadAlloc</i>
and <i>BadWindow</i> errors.</small></p>
<p><small>To get the name of a window, use
<i>XFetchName</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XFetchName(<i>display</i>, <i>w</i>, <i>window_name_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
char **<i>window_name_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>window_name_return</i> Returns the window
name, which is a null-terminated string.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XFetchName</i> function returns the name
of the specified window. If it succeeds, it returns a
nonzero status; otherwise, no name has been set for the
window, and it returns zero. If the WM_NAME property has not
been set for this window, <i>XFetchName</i> sets
window_name_return to NULL. 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. When
finished with it, a client must free the window name string
using <i>XFree</i>.</small></p>
<p><small><i>XFetchName</i> can generate a <i>BadWindow</i>
error.</small></p>
<a name="14.1.5. Setting and Reading the WM_ICON_NAME Property"></a>
<h2>14.1.5. Setting and Reading the WM_ICON_NAME Property</h2>
<p><small>Xlib provides convenience functions that you can
use to set and read the WM_ICON_NAME property for a given
window.</small></p>
<p><small>To set a window’s WM_ICON_NAME property,
use <i>XSetWMIconName</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XSetWMIconName(<i>display</i>, <i>w</i>, <i>text_prop</i>)
Display *<i>display</i>;
Window <i>w</i>;
XTextProperty *<i>text_prop</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>text_prop</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the <i>XTextProperty</i> structure to
be used.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetWMIconName</i> convenience function
calls <i>XSetTextProperty</i> to set the WM_ICON_NAME
property.</small></p>
<p><small>To read a window’s WM_ICON_NAME property,
use <i>XGetWMIconName</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetWMIconName(<i>display</i>, <i>w</i>, <i>text_prop_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
XTextProperty *<i>text_prop_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>text_prop_return</i> Returns the
<i>XTextProperty</i> structure.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetWMIconName</i> convenience function
calls <i>XGetTextProperty</i> to obtain the WM_ICON_NAME
property. It returns a nonzero status on success; otherwise,
it returns a zero status.</small></p>
<p><small>The next two functions have been superseded by
<i>XSetWMIconName</i> and <i>XGetWMIconName</i>,
respectively. You can use these additional convenience
functions for window names that are encoded as STRING
properties.</small></p>
<p><small>To set the name to be displayed in a
window’s icon, use <i>XSetIconName</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetIconName(<i>display</i>, <i>w</i>, <i>icon_name</i>)
Display *<i>display</i>;
Window <i>w</i>;
char *<i>icon_name</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>icon_name</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the icon name, which should be a
null-terminated string.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>If the string is not in the Host Portable
Character Encoding, the result is implementation-dependent.
<i>XSetIconName</i> can generate <i>BadAlloc</i> and
<i>BadWindow</i> errors.</small></p>
<p><small>To get the name a window wants displayed in its
icon, use <i>XGetIconName</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetIconName(<i>display</i>, <i>w</i>, <i>icon_name_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
char **<i>icon_name_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>icon_name_return</i> Returns the
window’s icon name, which is a null-terminated
string.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetIconName</i> function returns the name
to be displayed in the specified window’s icon. If it
succeeds, it returns a nonzero status; otherwise, if no icon
name has been set for the window, it returns zero. If you
never assigned a name to the window, <i>XGetIconName</i>
sets icon_name_return to NULL. 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. When
finished with it, a client must free the icon name string
using <i>XFree</i>.</small></p>
<p><small><i>XGetIconName</i> can generate a
<i>BadWindow</i> error.</small></p>
<a name="14.1.6. Setting and Reading the WM_HINTS Property"></a>
<h2>14.1.6. Setting and Reading the WM_HINTS Property</h2>
<p><small>Xlib provides functions that you can use to set
and read the WM_HINTS property for a given window. These
functions use the flags and the <i>XWMHints</i> structure,
as defined in the <<i>X11/Xutil.h</i>> header
file.</small></p>
<p><small>To allocate an <i>XWMHints</i> structure, use
<i>XAllocWMHints</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XWMHints *XAllocWMHints()
</small></pre>
<p><small>│__</small></p>
<p><small>The <i>XAllocWMHints</i> function allocates and
returns a pointer to an <i>XWMHints</i> structure. Note that
all fields in the <i>XWMHints</i> structure are initially
set to zero. If insufficient memory is available,
<i>XAllocWMHints</i> returns NULL. To free the memory
allocated to this structure, use <i>XFree</i>.</small></p>
<p><small>The <i>XWMHints</i> structure
contains:</small></p>
<p><small>__ │<br>
/* Window manager hints mask bits */</small></p>
<p align=center><small><img src="grohtml-1439273.png"></small></p>
<pre><small>/* Values */
typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>long flags;</small></p>
</td>
<td width="50%">
<p><small>/* marks which fields in this structure are
defined */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>Bool input;</small></p>
</td>
<td width="50%">
<p><small>/* does this application rely on the window
manager to</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
</td>
<td width="50%">
<p><small>get keyboard input? */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int initial_state;</small></p>
</td>
<td width="50%">
<p><small>/* see below */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>Pixmap icon_pixmap;</small></p>
</td>
<td width="50%">
<p><small>/* pixmap to be used as icon */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>Window icon_window;</small></p>
</td>
<td width="50%">
<p><small>/* window to be used as icon */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int icon_x, icon_y;</small></p>
</td>
<td width="50%">
<p><small>/* initial position of icon */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>Pixmap icon_mask;</small></p>
</td>
<td width="50%">
<p><small>/* pixmap to be used as mask for icon_pixmap
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XID window_group;</small></p>
</td>
<td width="50%">
<p><small>/* id of related window group */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>/* this structure may be extended in the future
*/</small></p>
</td>
<td width="50%">
</td>
</table>
<p><small>} XWMHints;</small></p>
<p><small>│__</small></p>
<p><small>The input member is used to communicate to the
window manager the input focus model used by the
application. Applications that expect input but never
explicitly set focus to any of their subwindows (that is,
use the push model of focus management), such as X Version
10 style applications that use real-estate driven focus,
should set this member to <i>True</i>. Similarly,
applications that set input focus to their subwindows only
when it is given to their top-level window by a window
manager should also set this member to <i>True</i>.
Applications that manage their own input focus by explicitly
setting focus to one of their subwindows whenever they want
keyboard input (that is, use the pull model of focus
management) should set this member to <i>False</i>.
Applications that never expect any keyboard input also
should set this member to <i>False</i>.</small></p>
<p><small>Pull model window managers should make it
possible for push model applications to get input by setting
input focus to the top-level windows of applications whose
input member is <i>True</i>. Push model window managers
should make sure that pull model applications do not break
them by resetting input focus to <i>PointerRoot</i> when it
is appropriate (for example, whenever an application whose
input member is <i>False</i> sets input focus to one of its
subwindows).</small></p>
<p><small>The definitions for the initial_state flag
are:</small></p>
<p align=center><small><img src="grohtml-1439274.png"></small></p>
<p><small>The icon_mask specifies which pixels of the
icon_pixmap should be used as the icon. This allows for
nonrectangular icons. Both icon_pixmap and icon_mask must be
bitmaps. The icon_window lets an application provide a
window for use as an icon for window managers that support
such use. The window_group lets you specify that this window
belongs to a group of other windows. For example, if a
single application manipulates multiple top-level windows,
this allows you to provide enough information that a window
manager can iconify all of the windows rather than just the
one window.</small></p>
<p><small>The <i>UrgencyHint</i> flag, if set in the flags
field, indicates that the client deems the window contents
to be urgent, requiring the timely response of the user. The
window manager will make some effort to draw the
user’s attention to this window while this flag is
set. The client must provide some means by which the user
can cause the urgency flag to be cleared (either mitigating
the condition that made the window urgent or merely shutting
off the alarm) or the window to be withdrawn.</small></p>
<p><small>To set a window’s WM_HINTS property, use
<i>XSetWMHints</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetWMHints(<i>display</i>, <i>w</i>, <i>wmhints</i>)
Display *<i>display</i>;
Window <i>w</i>;
XWMHints *<i>wmhints</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>wmhints</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the <i>XWMHints</i> structure to be
used.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetWMHints</i> function sets the window
manager hints that include icon information and location,
the initial state of the window, and whether the application
relies on the window manager to get keyboard
input.</small></p>
<p><small><i>XSetWMHints</i> can generate <i>BadAlloc</i>
and <i>BadWindow</i> errors.</small></p>
<p><small>To read a window’s WM_HINTS property, use
<i>XGetWMHints</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XWMHints *XGetWMHints(<i>display</i>, <i>w</i>)
Display *<i>display</i>;
Window <i>w</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetWMHints</i> function reads the window
manager hints and returns NULL if no WM_HINTS property was
set on the window or returns a pointer to an <i>XWMHints</i>
structure if it succeeds. When finished with the data, free
the space used for it by calling <i>XFree</i>.</small></p>
<p><small><i>XGetWMHints</i> can generate a
<i>BadWindow</i> error.</small></p>
<a name="14.1.7. Setting and Reading the WM_NORMAL_HINTS Property"></a>
<h2>14.1.7. Setting and Reading the WM_NORMAL_HINTS Property</h2>
<p><small>Xlib provides functions that you can use to set
or read the WM_NORMAL_HINTS property for a given window. The
functions use the flags and the <i>XSizeHints</i> structure,
as defined in the <<i>X11/Xutil.h</i>> header
file.</small></p>
<p><small>The size of the <i>XSizeHints</i> structure may
grow in future releases, as new components are added to
support new ICCCM features. Passing statically allocated
instances of this structure into Xlib may result in memory
corruption when running against a future release of the
library. As such, it is recommended that only dynamically
allocated instances of the structure be used.</small></p>
<p><small>To allocate an <i>XSizeHints</i> structure, use
<i>XAllocSizeHints</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSizeHints *XAllocSizeHints()
</small></pre>
<p><small>│__</small></p>
<p><small>The <i>XAllocSizeHints</i> function allocates and
returns a pointer to an <i>XSizeHints</i> structure. Note
that all fields in the <i>XSizeHints</i> structure are
initially set to zero. If insufficient memory is available,
<i>XAllocSizeHints</i> returns NULL. To free the memory
allocated to this structure, use <i>XFree</i>.</small></p>
<p><small>The <i>XSizeHints</i> structure
contains:</small></p>
<p><small>__ │<br>
/* Size hints mask bits */</small></p>
<p align=center><small><img src="grohtml-1439275.png"></small></p>
<pre><small>/* Values */
typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>long flags;</small></p>
</td>
<td width="50%">
<p><small>/* marks which fields in this structure are
defined */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int x, y;</small></p>
</td>
<td width="50%">
<p><small>/* Obsolete */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int width, height;</small></p>
</td>
<td width="50%">
<p><small>/* Obsolete */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int min_width, min_height;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int max_width, max_height;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int width_inc, height_inc;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>struct {</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int x;</small></p>
</td>
<td width="50%">
<p><small>/* numerator */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int y;</small></p>
</td>
<td width="50%">
<p><small>/* denominator */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>} min_aspect, max_aspect;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int base_width, base_height;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int win_gravity;</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>/* this structure may be extended in the future
*/</small></p>
</td>
<td width="50%">
</td>
</table>
<p><small>} XSizeHints;</small></p>
<p><small>│__</small></p>
<p><small>The x, y, width, and height members are now
obsolete and are left solely for compatibility reasons. The
min_width and min_height members specify the minimum window
size that still allows the application to be useful. The
max_width and max_height members specify the maximum window
size. The width_inc and height_inc members define an
arithmetic progression of sizes (minimum to maximum) into
which the window prefers to be resized. The min_aspect and
max_aspect members are expressed as ratios of x and y, and
they allow an application to specify the range of aspect
ratios it prefers. The base_width and base_height members
define the desired size of the window. The window manager
will interpret the position of the window and its border
width to position the point of the outer rectangle of the
overall window specified by the win_gravity member. The
outer rectangle of the window includes any borders or
decorations supplied by the window manager. In other words,
if the window manager decides to place the window where the
client asked, the position on the parent window’s
border named by the win_gravity will be placed where the
client window would have been placed in the absence of a
window manager.</small></p>
<p><small>Note that use of the <i>PAllHints</i> macro is
highly discouraged.</small></p>
<p><small>To set a window’s WM_NORMAL_HINTS property,
use <i>XSetWMNormalHints</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XSetWMNormalHints(<i>display</i>, <i>w</i>, <i>hints</i>)
Display *<i>display</i>;
Window <i>w</i>;
XSizeHints *<i>hints</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>hints</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the size hints for the window in its
normal state.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetWMNormalHints</i> function replaces
the size hints for the WM_NORMAL_HINTS property on the
specified window. If the property does not already exist,
<i>XSetWMNormalHints</i> sets the size hints for the
WM_NORMAL_HINTS property on the specified window. The
property is stored with a type of WM_SIZE_HINTS and a format
of 32.</small></p>
<p><small><i>XSetWMNormalHints</i> can generate
<i>BadAlloc</i> and <i>BadWindow</i> errors.</small></p>
<p><small>To read a window’s WM_NORMAL_HINTS
property, use <i>XGetWMNormalHints</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetWMNormalHints(<i>display</i>, <i>w</i>, <i>hints_return</i>, <i>supplied_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
XSizeHints *<i>hints_return</i>;
long *<i>supplied_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>hints_return</i> Returns the size hints for
the window in its normal state.</small></p>
<p><small><i>supplied_return</i> Returns the hints that
were supplied by the user.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetWMNormalHints</i> function returns the
size hints stored in the WM_NORMAL_HINTS property on the
specified window. If the property is of type WM_SIZE_HINTS,
is of format 32, and is long enough to contain either an old
(pre-ICCCM) or new size hints structure,
<i>XGetWMNormalHints</i> sets the various fields of the
<i>XSizeHints</i> structure, sets the supplied_return
argument to the list of fields that were supplied by the
user (whether or not they contained defined values), and
returns a nonzero status. Otherwise, it returns a zero
status.</small></p>
<p><small>If <i>XGetWMNormalHints</i> returns successfully
and a pre-ICCCM size hints property is read, the
supplied_return argument will contain the following
bits:</small></p>
<pre><small> (USPosition|USSize|PPosition|PSize|PMinSize|
PMaxSize|PResizeInc|PAspect)
</small></pre>
<p><small>If the property is large enough to contain the
base size and window gravity fields as well, the
supplied_return argument will also contain the following
bits:</small></p>
<pre><small> PBaseSize|PWinGravity
</small></pre>
<p><small><i>XGetWMNormalHints</i> can generate a
<i>BadWindow</i> error.</small></p>
<p><small>To set a window’s WM_SIZE_HINTS property,
use <i>XSetWMSizeHints</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XSetWMSizeHints(<i>display</i>, <i>w</i>, <i>hints</i>, <i>property</i>)
Display *<i>display</i>;
Window <i>w</i>;
XSizeHints *<i>hints</i>;
Atom <i>property</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>hints</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the <i>XSizeHints</i> structure to be
used.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>property</i></small></p>
</td>
<td width="4%"></td>
<td width="56%">
<p><small>Specifies the property name.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetWMSizeHints</i> function replaces the
size hints for the specified property on the named window.
If the specified property does not already exist,
<i>XSetWMSizeHints</i> sets the size hints for the specified
property on the named window. The property is stored with a
type of WM_SIZE_HINTS and a format of 32. To set a
window’s normal size hints, you can use the
<i>XSetWMNormalHints</i> function.</small></p>
<p><small><i>XSetWMSizeHints</i> can generate
<i>BadAlloc</i>, <i>BadAtom</i>, and <i>BadWindow</i>
errors.</small></p>
<p><small>To read a window’s WM_SIZE_HINTS property,
use <i>XGetWMSizeHints</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetWMSizeHints(<i>display</i>, <i>w</i>, <i>hints_return</i>, <i>supplied_return</i>, <i>property</i>)
Display *<i>display</i>;
Window <i>w</i>;
XSizeHints *<i>hints_return</i>;
long *<i>supplied_return</i>;
Atom <i>property</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>hints_return</i> Returns the <i>XSizeHints</i>
structure.</small></p>
<p><small><i>supplied_return</i> Returns the hints that
were supplied by the user.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>property</i></small></p>
</td>
<td width="4%"></td>
<td width="56%">
<p><small>Specifies the property name.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetWMSizeHints</i> function returns the
size hints stored in the specified property on the named
window. If the property is of type WM_SIZE_HINTS, is of
format 32, and is long enough to contain either an old
(pre-ICCCM) or new size hints structure,
<i>XGetWMSizeHints</i> sets the various fields of the
<i>XSizeHints</i> structure, sets the supplied_return
argument to the list of fields that were supplied by the
user (whether or not they contained defined values), and
returns a nonzero status. Otherwise, it returns a zero
status. To get a window’s normal size hints, you can
use the <i>XGetWMNormalHints</i> function.</small></p>
<p><small>If <i>XGetWMSizeHints</i> returns successfully
and a pre-ICCCM size hints property is read, the
supplied_return argument will contain the following
bits:</small></p>
<pre><small> (USPosition|USSize|PPosition|PSize|PMinSize|
PMaxSize|PResizeInc|PAspect)
</small></pre>
<p><small>If the property is large enough to contain the
base size and window gravity fields as well, the
supplied_return argument will also contain the following
bits:</small></p>
<pre><small> PBaseSize|PWinGravity
</small></pre>
<p><small><i>XGetWMSizeHints</i> can generate
<i>BadAtom</i> and <i>BadWindow</i> errors.</small></p>
<a name="14.1.8. Setting and Reading the WM_CLASS Property"></a>
<h2>14.1.8. Setting and Reading the WM_CLASS Property</h2>
<p><small>Xlib provides functions that you can use to set
and get the WM_CLASS property for a given window. These
functions use the <i>XClassHint</i> structure, which is
defined in the <<i>X11/Xutil.h</i>> header
file.</small></p>
<p><small>To allocate an <i>XClassHint</i> structure, use
<i>XAllocClassHint</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XClassHint *XAllocClassHint()
</small></pre>
<p><small>│__</small></p>
<p><small>The <i>XAllocClassHint</i> function allocates and
returns a pointer to an <i>XClassHint</i> structure. Note
that the pointer fields in the <i>XClassHint</i> structure
are initially set to NULL. If insufficient memory is
available, <i>XAllocClassHint</i> returns NULL. To free the
memory allocated to this structure, use
<i>XFree</i>.</small></p>
<p><small>The <i>XClassHint</i> contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>char *res_name;</small></p>
</td>
<td width="79%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>char *res_class;</small></p>
</td>
<td width="79%">
</td>
</table>
<p><small>} XClassHint;</small></p>
<p><small>│__</small></p>
<p><small>The res_name member contains the application
name, and the res_class member contains the application
class. Note that the name set in this property may differ
from the name set as WM_NAME. That is, WM_NAME specifies
what should be displayed in the title bar and, therefore,
can contain temporal information (for example, the name of a
file currently in an editor’s buffer). On the other
hand, the name specified as part of WM_CLASS is the formal
name of the application that should be used when retrieving
the application’s resources from the resource
database.</small></p>
<p><small>To set a window’s WM_CLASS property, use
<i>XSetClassHint</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetClassHint(<i>display</i>, <i>w</i>, <i>class_hints</i>)
Display *<i>display</i>;
Window <i>w</i>;
XClassHint *<i>class_hints</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>class_hints</i> Specifies the
<i>XClassHint</i> structure that is to be used.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XSetClassHint</i> function sets the class
hint for the specified window. If the strings are not in the
Host Portable Character Encoding, the result is
implementation-dependent.</small></p>
<p><small><i>XSetClassHint</i> can generate <i>BadAlloc</i>
and <i>BadWindow</i> errors.</small></p>
<p><small>To read a window’s WM_CLASS property, use
<i>XGetClassHint</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetClassHint(<i>display</i>, <i>w</i>, <i>class_hints_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
XClassHint *<i>class_hints_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>class_hints_return</i> Returns the
<i>XClassHint</i> structure.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetClassHint</i> function returns the
class hint of the specified window to the members of the
supplied structure. 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. It
returns a nonzero status on success; otherwise, it returns a
zero status. To free res_name and res_class when finished
with the strings, use <i>XFree</i> on each
individually.</small></p>
<p><small><i>XGetClassHint</i> can generate a
<i>BadWindow</i> error.</small></p>
<a name="14.1.9. Setting and Reading the WM_TRANSIENT_FOR Property"></a>
<h2>14.1.9. Setting and Reading the WM_TRANSIENT_FOR Property</h2>
<p><small>Xlib provides functions that you can use to set
and read the WM_TRANSIENT_FOR property for a given
window.</small></p>
<p><small>To set a window’s WM_TRANSIENT_FOR
property, use <i>XSetTransientForHint</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetTransientForHint(<i>display</i>, <i>w</i>, <i>prop_window</i>)
Display *<i>display</i>;
Window <i>w</i>;
Window <i>prop_window</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>prop_window</i> Specifies the window that the
WM_TRANSIENT_FOR property is to be set to.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XSetTransientForHint</i> function sets the
WM_TRANSIENT_FOR property of the specified window to the
specified prop_window.</small></p>
<p><small><i>XSetTransientForHint</i> can generate
<i>BadAlloc</i> and <i>BadWindow</i> errors.</small></p>
<p><small>To read a window’s WM_TRANSIENT_FOR
property, use <i>XGetTransientForHint</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetTransientForHint(<i>display</i>, <i>w</i>, <i>prop_window_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
Window *<i>prop_window_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>prop_window_return</i> Returns the
WM_TRANSIENT_FOR property of the specified
window.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetTransientForHint</i> function returns
the WM_TRANSIENT_FOR property for the specified window. It
returns a nonzero status on success; otherwise, it returns a
zero status.</small></p>
<p><small><i>XGetTransientForHint</i> can generate a
<i>BadWindow</i> error.</small></p>
<a name="14.1.10. Setting and Reading the WM_PROTOCOLS Property"></a>
<h2>14.1.10. Setting and Reading the WM_PROTOCOLS Property</h2>
<p><small>Xlib provides functions that you can use to set
and read the WM_PROTOCOLS property for a given
window.</small></p>
<p><small>To set a window’s WM_PROTOCOLS property,
use <i>XSetWMProtocols</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XSetWMProtocols(<i>display</i>, <i>w</i>, <i>protocols</i>, <i>count</i>)
Display *<i>display</i>;
Window <i>w</i>;
Atom *<i>protocols</i>;
int <i>count</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>protocols</i></small></p>
</td>
<td width="2%"></td>
<td width="64%">
<p><small>Specifies the list of protocols.</small></p>
</td>
<td width="15%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>count</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the number of protocols in the
list.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetWMProtocols</i> function replaces the
WM_PROTOCOLS property on the specified window with the list
of atoms specified by the protocols argument. If the
property does not already exist, <i>XSetWMProtocols</i> sets
the WM_PROTOCOLS property on the specified window to the
list of atoms specified by the protocols argument. The
property is stored with a type of ATOM and a format of 32.
If it cannot intern the WM_PROTOCOLS atom,
<i>XSetWMProtocols</i> returns a zero status. Otherwise, it
returns a nonzero status.</small></p>
<p><small><i>XSetWMProtocols</i> can generate
<i>BadAlloc</i> and <i>BadWindow</i> errors.</small></p>
<p><small>To read a window’s WM_PROTOCOLS property,
use <i>XGetWMProtocols</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetWMProtocols(<i>display</i>, <i>w</i>, <i>protocols_return</i>, <i>count_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
Atom **<i>protocols_return</i>;
int *<i>count_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>protocols_return</i> Returns the list of
protocols.</small></p>
<p><small><i>count_return</i> Returns the number of
protocols in the list.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetWMProtocols</i> function returns the
list of atoms stored in the WM_PROTOCOLS property on the
specified window. These atoms describe window manager
protocols in which the owner of this window is willing to
participate. If the property exists, is of type ATOM, is of
format 32, and the atom WM_PROTOCOLS can be interned,
<i>XGetWMProtocols</i> sets the protocols_return argument to
a list of atoms, sets the count_return argument to the
number of elements in the list, and returns a nonzero
status. Otherwise, it sets neither of the return arguments
and returns a zero status. To release the list of atoms, use
<i>XFree</i>.</small></p>
<p><small><i>XGetWMProtocols</i> can generate a
<i>BadWindow</i> error.</small></p>
<a name="14.1.11. Setting and Reading the WM_COLORMAP_WINDOWS Property"></a>
<h2>14.1.11. Setting and Reading the WM_COLORMAP_WINDOWS Property</h2>
<p><small>Xlib provides functions that you can use to set
and read the WM_COLORMAP_WINDOWS property for a given
window.</small></p>
<p><small>To set a window’s WM_COLORMAP_WINDOWS
property, use <i>XSetWMColormapWindows</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XSetWMColormapWindows(<i>display</i>, <i>w</i>, <i>colormap_windows</i>, <i>count</i>)
Display *<i>display</i>;
Window <i>w</i>;
Window *<i>colormap_windows</i>;
int <i>count</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>colormap_windows</i> Specifies the list of
windows.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>count</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the number of windows in the
list.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetWMColormapWindows</i> function
replaces the WM_COLORMAP_WINDOWS property on the specified
window with the list of windows specified by the
colormap_windows argument. If the property does not already
exist, <i>XSetWMColormapWindows</i> sets the
WM_COLORMAP_WINDOWS property on the specified window to the
list of windows specified by the colormap_windows argument.
The property is stored with a type of WINDOW and a format of
32. If it cannot intern the WM_COLORMAP_WINDOWS atom,
<i>XSetWMColormapWindows</i> returns a zero status.
Otherwise, it returns a nonzero status.</small></p>
<p><small><i>XSetWMColormapWindows</i> can generate
<i>BadAlloc</i> and <i>BadWindow</i> errors.</small></p>
<p><small>To read a window’s WM_COLORMAP_WINDOWS
property, use <i>XGetWMColormapWindows</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetWMColormapWindows(<i>display</i>, <i>w</i>, <i>colormap_windows_return</i>, <i>count_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
Window **<i>colormap_windows_return</i>;
int *<i>count_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>colormap_windows_return</i> Returns the list
of windows.</small></p>
<p><small><i>count_return</i> Returns the number of windows
in the list.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetWMColormapWindows</i> function returns
the list of window identifiers stored in the
WM_COLORMAP_WINDOWS property on the specified window. These
identifiers indicate the colormaps that the window manager
may need to install for this window. If the property exists,
is of type WINDOW, is of format 32, and the atom
WM_COLORMAP_WINDOWS can be interned,
<i>XGetWMColormapWindows</i> sets the windows_return
argument to a list of window identifiers, sets the
count_return argument to the number of elements in the list,
and returns a nonzero status. Otherwise, it sets neither of
the return arguments and returns a zero status. To release
the list of window identifiers, use
<i>XFree</i>.</small></p>
<p><small><i>XGetWMColormapWindows</i> can generate a
<i>BadWindow</i> error.</small></p>
<a name="14.1.12. Setting and Reading the WM_ICON_SIZE Property"></a>
<h2>14.1.12. Setting and Reading the WM_ICON_SIZE Property</h2>
<p><small>Xlib provides functions that you can use to set
and read the WM_ICON_SIZE property for a given window. These
functions use the <i>XIconSize</i> structure, which is
defined in the <<i>X11/Xutil.h</i>> header
file.</small></p>
<p><small>To allocate an <i>XIconSize</i> structure, use
<i>XAllocIconSize</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XIconSize *XAllocIconSize()
</small></pre>
<p><small>│__</small></p>
<p><small>The <i>XAllocIconSize</i> function allocates and
returns a pointer to an <i>XIconSize</i> structure. Note
that all fields in the <i>XIconSize</i> structure are
initially set to zero. If insufficient memory is available,
<i>XAllocIconSize</i> returns NULL. To free the memory
allocated to this structure, use <i>XFree</i>.</small></p>
<p><small>The <i>XIconSize</i> structure
contains:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int min_width, min_height;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int max_width, max_height;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>int width_inc, height_inc;</small></p>
</td>
<td width="49%">
</td>
</table>
<p><small>} XIconSize;</small></p>
<p><small>│__</small></p>
<p><small>The width_inc and height_inc members define an
arithmetic progression of sizes (minimum to maximum) that
represent the supported icon sizes.</small></p>
<p><small>To set a window’s WM_ICON_SIZE property,
use <i>XSetIconSizes</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetIconSizes(<i>display</i>, <i>w</i>, <i>size_list</i>, <i>count</i>)
Display *<i>display</i>;
Window <i>w</i>;
XIconSize *<i>size_list</i>;
int <i>count</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>size_list</i></small></p>
</td>
<td width="2%"></td>
<td width="48%">
<p><small>Specifies the size list.</small></p>
</td>
<td width="31%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>count</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the number of items in the size
list.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetIconSizes</i> function is used only by
window managers to set the supported icon sizes.</small></p>
<p><small><i>XSetIconSizes</i> can generate <i>BadAlloc</i>
and <i>BadWindow</i> errors.</small></p>
<p><small>To read a window’s WM_ICON_SIZE property,
use <i>XGetIconSizes</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetIconSizes(<i>display</i>, <i>w</i>, <i>size_list_return</i>, <i>count_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
XIconSize **<i>size_list_return</i>;
int *<i>count_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>size_list_return</i> Returns the size
list.</small></p>
<p><small><i>count_return</i> Returns the number of items
in the size list.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetIconSizes</i> function returns zero if
a window manager has not set icon sizes; otherwise, it
returns nonzero. <i>XGetIconSizes</i> should be called by an
application that wants to find out what icon sizes would be
most appreciated by the window manager under which the
application is running. The application should then use
<i>XSetWMHints</i> to supply the window manager with an icon
pixmap or window in one of the supported sizes. To free the
data allocated in size_list_return, use
<i>XFree</i>.</small></p>
<p><small><i>XGetIconSizes</i> can generate a
<i>BadWindow</i> error.</small></p>
<a name="14.1.13. Using Window Manager Convenience Functions"></a>
<h2>14.1.13. Using Window Manager Convenience Functions</h2>
<p><small>The <i>XmbSetWMProperties</i> function stores the
standard set of window manager properties, with text
properties in standard encodings for internationalized text
communication. The standard window manager properties for a
given window are WM_NAME, WM_ICON_NAME, WM_HINTS,
WM_NORMAL_HINTS, WM_CLASS, WM_COMMAND, WM_CLIENT_MACHINE,
and WM_LOCALE_NAME.</small></p>
<p><small>__ │</small></p>
<pre><small>void XmbSetWMProperties(<i>display</i>, <i>w</i>, <i>window_name</i>, <i>icon_name</i>, <i>argv</i>, <i>argc</i>,
<i> normal_hints</i>, <i>wm_hints</i>, <i>class_hints</i>)
Display *<i>display</i>;
Window <i>w</i>;
char *<i>window_name</i>;
char *<i>icon_name</i>;
char *<i>argv</i>[];
int <i>argc</i>;
XSizeHints *<i>normal_hints</i>;
XWMHints *<i>wm_hints</i>;
XClassHint *<i>class_hints</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>window_name</i> Specifies the window name,
which should be a null-terminated string.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>icon_name</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the icon name, which should be a
null-terminated string.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>argv</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the application’s argument
list.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>argc</i></small></p>
</td>
<td width="12%"></td>
<td width="68%">
<p><small>Specifies the number of arguments.</small></p>
</td>
<td width="11%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>hints</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the size hints for the window in its
normal state.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>wm_hints</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the <i>XWMHints</i> structure to be
used.</small></p>
</td>
</table>
<p><small><i>class_hints</i> Specifies the
<i>XClassHint</i> structure to be used.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XmbSetWMProperties</i> convenience
function provides a simple programming interface for setting
those essential window properties that are used for
communicating with other clients (particularly window and
session managers).</small></p>
<p><small>If the window_name argument is non-NULL,
<i>XmbSetWMProperties</i> sets the WM_NAME property. If the
icon_name argument is non-NULL, <i>XmbSetWMProperties</i>
sets the WM_ICON_NAME property. The window_name and
icon_name arguments are null-terminated strings in the
encoding of the current locale. If the arguments can be
fully converted to the STRING encoding, the properties are
created with type ‘‘STRING’’;
otherwise, the arguments are converted to Compound Text, and
the properties are created with type
‘‘COMPOUND_TEXT’’.</small></p>
<p><small>If the normal_hints argument is non-NULL,
<i>XmbSetWMProperties</i> calls <i>XSetWMNormalHints</i>,
which sets the WM_NORMAL_HINTS property (see section
14.1.7). If the wm_hints argument is non-NULL,
<i>XmbSetWMProperties</i> calls <i>XSetWMHints</i>, which
sets the WM_HINTS property (see section 14.1.6).</small></p>
<p><small>If the argv argument is non-NULL,
<i>XmbSetWMProperties</i> sets the WM_COMMAND property from
argv and argc. An argc of zero indicates a zero-length
command.</small></p>
<p><small>The hostname of the machine is stored using
<i>XSetWMClientMachine</i> (see section 14.2.2).</small></p>
<p><small>If the class_hints argument is non-NULL,
<i>XmbSetWMProperties</i> sets the WM_CLASS property. If the
res_name member in the <i>XClassHint</i> structure is set to
the NULL pointer and the RESOURCE_NAME environment variable
is set, the value of the environment variable is substituted
for res_name. If the res_name member is NULL, the
environment variable is not set, and argv and argv[0] are
set, then the value of argv[0], stripped of any directory
prefixes, is substituted for res_name.</small></p>
<p><small>It is assumed that the supplied
class_hints.res_name and argv, the RESOURCE_NAME environment
variable, and the hostname of the machine are in the
encoding of the locale announced for the LC_CTYPE category
(on POSIX-compliant systems, the LC_CTYPE, else LANG
environment variable). The corresponding WM_CLASS,
WM_COMMAND, and WM_CLIENT_MACHINE properties are typed
according to the local host locale announcer. No encoding
conversion is performed prior to storage in the
properties.</small></p>
<p><small>For clients that need to process the property
text in a locale, <i>XmbSetWMProperties</i> sets the
WM_LOCALE_NAME property to be the name of the current
locale. The name is assumed to be in the Host Portable
Character Encoding and is converted to STRING for storage in
the property.</small></p>
<p><small><i>XmbSetWMProperties</i> can generate
<i>BadAlloc</i> and <i>BadWindow</i> errors.</small></p>
<p><small>To set a window’s standard window manager
properties with strings in client-specified encodings, use
<i>XSetWMProperties</i>. The standard window manager
properties for a given window are WM_NAME, WM_ICON_NAME,
WM_HINTS, WM_NORMAL_HINTS, WM_CLASS, WM_COMMAND, and
WM_CLIENT_MACHINE.</small></p>
<p><small>__ │</small></p>
<pre><small>void XSetWMProperties(<i>display</i>, <i>w</i>, <i>window_name</i>, <i>icon_name</i>, <i>argv</i>, <i>argc</i>, <i>normal_hints</i>, <i>wm_hints</i>, <i>class_hints</i>)
Display *<i>display</i>;
Window <i>w</i>;
XTextProperty *<i>window_name</i>;
XTextProperty *<i>icon_name</i>;
char **<i>argv</i>;
int <i>argc</i>;
XSizeHints *<i>normal_hints</i>;
XWMHints *<i>wm_hints</i>;
XClassHint *<i>class_hints</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>window_name</i> Specifies the window name,
which should be a null-terminated string.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>icon_name</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the icon name, which should be a
null-terminated string.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>argv</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the application’s argument
list.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>argc</i></small></p>
</td>
<td width="12%"></td>
<td width="68%">
<p><small>Specifies the number of arguments.</small></p>
</td>
<td width="11%">
</td>
</table>
<p><small><i>normal_hints</i> Specifies the size hints for
the window in its normal state.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>wm_hints</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the <i>XWMHints</i> structure to be
used.</small></p>
</td>
</table>
<p><small><i>class_hints</i> Specifies the
<i>XClassHint</i> structure to be used.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XSetWMProperties</i> convenience function
provides a single programming interface for setting those
essential window properties that are used for communicating
with other clients (particularly window and session
managers).</small></p>
<p><small>If the window_name argument is non-NULL,
<i>XSetWMProperties</i> calls <i>XSetWMName</i>, which, in
turn, sets the WM_NAME property (see section 14.1.4). If the
icon_name argument is non-NULL, <i>XSetWMProperties</i>
calls <i>XSetWMIconName</i>, which sets the WM_ICON_NAME
property (see section 14.1.5). If the argv argument is
non-NULL, <i>XSetWMProperties</i> calls <i>XSetCommand</i>,
which sets the WM_COMMAND property (see section 14.2.1).
Note that an argc of zero is allowed to indicate a
zero-length command. Note also that the hostname of this
machine is stored using <i>XSetWMClientMachine</i> (see
section 14.2.2).</small></p>
<p><small>If the normal_hints argument is non-NULL,
<i>XSetWMProperties</i> calls <i>XSetWMNormalHints</i>,
which sets the WM_NORMAL_HINTS property (see section
14.1.7). If the wm_hints argument is non-NULL,
<i>XSetWMProperties</i> calls <i>XSetWMHints</i>, which sets
the WM_HINTS property (see section 14.1.6).</small></p>
<p><small>If the class_hints argument is non-NULL,
<i>XSetWMProperties</i> calls <i>XSetClassHint</i>, which
sets the WM_CLASS property (see section 14.1.8). If the
res_name member in the <i>XClassHint</i> structure is set to
the NULL pointer and the RESOURCE_NAME environment variable
is set, then the value of the environment variable is
substituted for res_name. If the res_name member is NULL,
the environment variable is not set, and argv and argv[0]
are set, then the value of argv[0], stripped of any
directory prefixes, is substituted for res_name.</small></p>
<p><small><i>XSetWMProperties</i> can generate
<i>BadAlloc</i> and <i>BadWindow</i> errors.</small></p>
<a name="14.2. Client to Session Manager Communication"></a>
<h2>14.2. Client to Session Manager Communication</h2>
<p><small>This section discusses how to:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="72%">
<p><small>Set and read the WM_COMMAND property</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="86%">
<p><small>Set and read the WM_CLIENT_MACHINE
property</small></p>
</td>
<td width="3%">
</td>
</table>
<a name="14.2.1. Setting and Reading the WM_COMMAND Property"></a>
<h2>14.2.1. Setting and Reading the WM_COMMAND Property</h2>
<p><small>Xlib provides functions that you can use to set
and read the WM_COMMAND property for a given
window.</small></p>
<p><small>To set a window’s WM_COMMAND property, use
<i>XSetCommand</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetCommand(<i>display</i>, <i>w</i>, <i>argv</i>, <i>argc</i>)
Display *<i>display</i>;
Window <i>w</i>;
char **<i>argv</i>;
int <i>argc</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>argv</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the application’s argument
list.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>argc</i></small></p>
</td>
<td width="12%"></td>
<td width="68%">
<p><small>Specifies the number of arguments.</small></p>
</td>
<td width="11%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetCommand</i> function sets the command
and arguments used to invoke the application. (Typically,
argv is the argv array of your main program.) If the strings
are not in the Host Portable Character Encoding, the result
is implementation-dependent.</small></p>
<p><small><i>XSetCommand</i> can generate <i>BadAlloc</i>
and <i>BadWindow</i> errors.</small></p>
<p><small>To read a window’s WM_COMMAND property, use
<i>XGetCommand</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetCommand(<i>display</i>, <i>w</i>, <i>argv_return</i>, <i>argc_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
char ***<i>argv_return</i>;
int *<i>argc_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>argv_return</i> Returns the
application’s argument list.</small></p>
<p><small><i>argc_return</i> Returns the number of
arguments returned.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetCommand</i> 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, <i>XGetCommand</i>
fills in the argv_return and argc_return arguments and
returns a nonzero status. Otherwise, it returns a zero
status. 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. To free the memory
allocated to the string list, use
<i>XFreeStringList</i>.</small></p>
<a name="14.2.2. Setting and Reading the WM_CLIENT_MACHINE Property"></a>
<h2>14.2.2. Setting and Reading the WM_CLIENT_MACHINE Property</h2>
<p><small>Xlib provides functions that you can use to set
and read the WM_CLIENT_MACHINE property for a given
window.</small></p>
<p><small>To set a window’s WM_CLIENT_MACHINE
property, use <i>XSetWMClientMachine</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XSetWMClientMachine(<i>display</i>, <i>w</i>, <i>text_prop</i>)
Display *<i>display</i>;
Window <i>w</i>;
XTextProperty *<i>text_prop</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>text_prop</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the <i>XTextProperty</i> structure to
be used.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetWMClientMachine</i> convenience
function calls <i>XSetTextProperty</i> to set the
WM_CLIENT_MACHINE property.</small></p>
<p><small>To read a window’s WM_CLIENT_MACHINE
property, use <i>XGetWMClientMachine</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetWMClientMachine(<i>display</i>, <i>w</i>, <i>text_prop_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
XTextProperty *<i>text_prop_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>text_prop_return</i> Returns the
<i>XTextProperty</i> structure.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetWMClientMachine</i> convenience
function performs an <i>XGetTextProperty</i> on the
WM_CLIENT_MACHINE property. It returns a nonzero status on
success; otherwise, it returns a zero status.</small></p>
<a name="14.3. Standard Colormaps"></a>
<h2>14.3. Standard Colormaps</h2>
<p><small>Applications with color palettes, smooth-shaded
drawings, or digitized images demand large numbers of
colors. In addition, these applications often require an
efficient mapping from color triples to pixel values that
display the appropriate colors.</small></p>
<p><small>As an example, consider a three-dimensional
display program that wants to draw a smoothly shaded sphere.
At each pixel in the image of the sphere, the program
computes the intensity and color of light reflected back to
the viewer. The result of each computation is a triple of
red, green, and blue (RGB) coefficients in the range 0.0 to
1.0. To draw the sphere, the program needs a colormap that
provides a large range of uniformly distributed colors. The
colormap should be arranged so that the program can convert
its RGB triples into pixel values very quickly, because
drawing the entire sphere requires many such
conversions.</small></p>
<p><small>On many current workstations, the display is
limited to 256 or fewer colors. Applications must allocate
colors carefully, not only to make sure they cover the
entire range they need but also to make use of as many of
the available colors as possible. On a typical X display,
many applications are active at once. Most workstations have
only one hardware look-up table for colors, so only one
application colormap can be installed at a given time. The
application using the installed colormap is displayed
correctly, and the other applications go technicolor and are
displayed with false colors.</small></p>
<p><small>As another example, consider a user who is
running an image processing program to display
earth-resources data. The image processing program needs a
colormap set up with 8 reds, 8 greens, and 4 blues, for a
total of 256 colors. Because some colors are already in use
in the default colormap, the image processing program
allocates and installs a new colormap.</small></p>
<p><small>The user decides to alter some of the colors in
the image by invoking a color palette program to mix and
choose colors. The color palette program also needs a
colormap with eight reds, eight greens, and four blues, so
just like the image processing program, it must allocate and
install a new colormap.</small></p>
<p><small>Because only one colormap can be installed at a
time, the color palette may be displayed incorrectly
whenever the image processing program is active. Conversely,
whenever the palette program is active, the image may be
displayed incorrectly. The user can never match or compare
colors in the palette and image. Contention for colormap
resources can be reduced if applications with similar color
needs share colormaps.</small></p>
<p><small>The image processing program and the color
palette program could share the same colormap if there
existed a convention that described how the colormap was set
up. Whenever either program was active, both would be
displayed correctly.</small></p>
<p><small>The standard colormap properties define a set of
commonly used colormaps. Applications that share these
colormaps and conventions display true colors more often and
provide a better interface to the user.</small></p>
<p><small>Standard colormaps allow applications to share
commonly used color resources. This allows many applications
to be displayed in true colors simultaneously, even when
each application needs an entirely filled
colormap.</small></p>
<p><small>Several standard colormaps are described in this
section. Usually, a window manager creates these colormaps.
Applications should use the standard colormaps if they
already exist.</small></p>
<p><small>To allocate an <i>XStandardColormap</i>
structure, use <i>XAllocStandardColormap</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XStandardColormap *XAllocStandardColormap()
</small></pre>
<p><small>│__</small></p>
<p><small>The <i>XAllocStandardColormap</i> function
allocates and returns a pointer to an
<i>XStandardColormap</i> structure. Note that all fields in
the <i>XStandardColormap</i> structure are initially set to
zero. If insufficient memory is available,
<i>XAllocStandardColormap</i> returns NULL. To free the
memory allocated to this structure, use
<i>XFree</i>.</small></p>
<p><small>The <i>XStandardColormap</i> structure
contains:</small></p>
<p><small>__ │<br>
/* Hints */</small></p>
<p align=center><small><img src="grohtml-1439276.png"></small></p>
<p><small>/* Values */</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>Colormap colormap;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned long red_max;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned long red_mult;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned long green_max;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned long green_mult;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned long blue_max;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned long blue_mult;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>unsigned long base_pixel;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>VisualID visualid;</small></p>
</td>
<td width="49%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XID killid;</small></p>
</td>
<td width="49%">
</td>
</table>
<p><small>} XStandardColormap;</small></p>
<p><small>│__</small></p>
<p><small>The colormap member is the colormap created by
the <i>XCreateColormap</i> function. The red_max, green_max,
and blue_max members give the maximum red, green, and blue
values, respectively. Each color coefficient ranges from
zero to its max, inclusive. For example, a common colormap
allocation is 3/3/2 (3 planes for red, 3 planes for green,
and 2 planes for blue). This colormap would have red_max =
7, green_max = 7, and blue_max = 3. An alternate allocation
that uses only 216 colors is red_max = 5, green_max = 5, and
blue_max = 5.</small></p>
<p><small>The red_mult, green_mult, and blue_mult members
give the scale factors used to compose a full pixel value.
(See the discussion of the base_pixel members for further
information.) For a 3/3/2 allocation, red_mult might be 32,
green_mult might be 4, and blue_mult might be 1. For a
6-colors-each allocation, red_mult might be 36, green_mult
might be 6, and blue_mult might be 1.</small></p>
<p><small>The base_pixel member gives the base pixel value
used to compose a full pixel value. Usually, the base_pixel
is obtained from a call to the <i>XAllocColorPlanes</i>
function. Given integer red, green, and blue coefficients in
their appropriate ranges, one then can compute a
corresponding pixel value by using the following
expression:</small></p>
<pre><small> (r * red_mult + g * green_mult + b * blue_mult + base_pixel) & 0xFFFFFFFF
</small></pre>
<p><small>For <i>GrayScale</i> colormaps, only the
colormap, red_max, red_mult, and base_pixel members are
defined. The other members are ignored. To compute a
<i>GrayScale</i> pixel value, use the following
expression:</small></p>
<pre><small> (gray * red_mult + base_pixel) & 0xFFFFFFFF
</small></pre>
<p><small>Negative multipliers can be represented by
converting the 2’s complement representation of the
multiplier into an unsigned long and storing the result in
the appropriate _mult field. The step of masking by
0xFFFFFFFF effectively converts the resulting positive
multiplier into a negative one. The masking step will take
place automatically on many machine architectures, depending
on the size of the integer type used to do the
computation.</small></p>
<p><small>The visualid member gives the ID number of the
visual from which the colormap was created. The killid
member gives a resource ID that indicates whether the cells
held by this standard colormap are to be released by freeing
the colormap ID or by calling the <i>XKillClient</i>
function on the indicated resource. (Note that this method
is necessary for allocating out of an existing
colormap.)</small></p>
<p><small>The properties containing the
<i>XStandardColormap</i> information have the type
RGB_COLOR_MAP.</small></p>
<p><small>The remainder of this section discusses standard
colormap properties and atoms as well as how to manipulate
standard colormaps.</small></p>
<a name="14.3.1. Standard Colormap Properties and Atoms"></a>
<h2>14.3.1. Standard Colormap Properties and Atoms</h2>
<p><small>Several standard colormaps are available. Each
standard colormap is defined by a property, and each such
property is identified by an atom. The following list names
the atoms and describes the colormap associated with each
one. The <<i>X11/Xatom.h</i>> header file contains the
definitions for each of the following atoms, which are
prefixed with XA_.</small></p>
<p><small>RGB_DEFAULT_MAP</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>This atom names a property. The value of the
property is an array of <i>XStandardColormap</i> structures.
Each entry in the array describes an RGB subset of the
default color map for the Visual specified by
visual_id.</small></p>
<!-- INDENTATION -->
<p><small>Some applications only need a few RGB colors and
may be able to allocate them from the system default
colormap. This is the ideal situation because the fewer
colormaps that are active in the system the more
applications are displayed with correct colors at all
times.</small></p>
<!-- INDENTATION -->
<p><small>A typical allocation for the RGB_DEFAULT_MAP on
8-plane displays is 6 reds, 6 greens, and 6 blues. This
gives 216 uniformly distributed colors (6 intensities of 36
different hues) and still leaves 40 elements of a
256-element colormap available for special-purpose colors
for text, borders, and so on.</small></p>
</td>
</table>
<p><small>RGB_BEST_MAP</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>This atom names a property. The value of the
property is an <i>XStandardColormap</i>.</small></p>
<!-- INDENTATION -->
<p><small>The property defines the best RGB colormap
available on the screen. (Of course, this is a subjective
evaluation.) Many image processing and three-dimensional
applications need to use all available colormap cells and to
distribute as many perceptually distinct colors as possible
over those cells. This implies that there may be more green
values available than red, as well as more green or red than
blue.</small></p>
<!-- INDENTATION -->
<p><small>For an 8-plane <i>PseudoColor</i> visual,
RGB_BEST_MAP is likely to be a 3/3/2 allocation. For a
24-plane <i>DirectColor</i> visual, RGB_BEST_MAP is normally
an 8/8/8 allocation.</small></p>
</td>
</table>
<p><small>RGB_RED_MAP</small></p>
<p><small>RGB_GREEN_MAP</small></p>
<p><small>RGB_BLUE_MAP</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>These atoms name properties. The value of each
property is an <i>XStandardColormap</i>.</small></p>
<!-- INDENTATION -->
<p><small>The properties define all-red, all-green, and
all-blue colormaps, respectively. These maps are used by
applications that want to make color-separated images. For
example, a user might generate a full-color image on an
8-plane display both by rendering an image three times (once
with high color resolution in red, once with green, and once
with blue) and by multiply exposing a single frame in a
camera.</small></p>
</td>
</table>
<p><small>RGB_GRAY_MAP</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>This atom names a property. The value of the
property is an <i>XStandardColormap</i>.</small></p>
<!-- INDENTATION -->
<p><small>The property describes the best <i>GrayScale</i>
colormap available on the screen. As previously mentioned,
only the colormap, red_max, red_mult, and base_pixel members
of the <i>XStandardColormap</i> structure are used for
<i>GrayScale</i> colormaps.</small></p></td>
</table>
<a name="14.3.2. Setting and Obtaining Standard Colormaps"></a>
<h2>14.3.2. Setting and Obtaining Standard Colormaps</h2>
<p><small>Xlib provides functions that you can use to set
and obtain an <i>XStandardColormap</i>
structure.</small></p>
<p><small>To set an <i>XStandardColormap</i> structure, use
<i>XSetRGBColormaps</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XSetRGBColormaps(<i>display</i>, <i>w</i>, <i>std_colormap</i>, <i>count</i>, <i>property</i>)
Display *<i>display</i>;
Window <i>w</i>;
XStandardColormap *<i>std_colormap</i>;
int <i>count</i>;
Atom <i>property</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>std_colormap</i> Specifies the
<i>XStandardColormap</i> structure to be used.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>count</i></small></p>
</td>
<td width="10%"></td>
<td width="68%">
<p><small>Specifies the number of colormaps.</small></p>
</td>
<td width="11%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>property</i></small></p>
</td>
<td width="4%"></td>
<td width="56%">
<p><small>Specifies the property name.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetRGBColormaps</i> function replaces the
RGB colormap definition in the specified property on the
named window. If the property does not already exist,
<i>XSetRGBColormaps</i> sets the RGB colormap definition in
the specified property on the named window. The property is
stored with a type of RGB_COLOR_MAP and a format of 32. Note
that it is the caller’s responsibility to honor the
ICCCM restriction that only RGB_DEFAULT_MAP contain more
than one definition.</small></p>
<p><small>The <i>XSetRGBColormaps</i> function usually is
only used by window or session managers. To create a
standard colormap, follow this procedure:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small>1.</small></p>
</td>
<td width="6%"></td>
<td width="82%">
<p><small>Open a new connection to the same
server.</small></p>
</td>
<td width="7%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small>2.</small></p>
</td>
<td width="6%"></td>
<td width="32%">
<p><small>Grab the server.</small></p>
</td>
<td width="57%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small>3.</small></p>
</td>
<td width="6%"></td>
<td width="90%">
<p><small>See if the property is on the property list of
the root window for the screen.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small>4.</small></p>
</td>
<td width="6%"></td>
<td width="78%">
<p><small>If the desired property is not
present:</small></p>
</td>
<td width="11%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Create a colormap (unless you are using the
default colormap of the screen).</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Determine the color characteristics of the
visual.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Allocate cells in the colormap (or create it with
<i>AllocAll</i>).</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Call <i>XStoreColors</i> to store appropriate
color values in the colormap.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="5" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="76%">
<p><small>Fill in the descriptive members in the
<i>XStandardColormap</i> structure.</small></p>
</td>
<td width="3%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="5" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="78%">
<p><small>Attach the property to the root
window.</small></p>
</td>
<td width="1%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Use <i>XSetCloseDownMode</i> to make the resource
permanent.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small>5.</small></p>
</td>
<td width="6%"></td>
<td width="36%">
<p><small>Ungrab the server.</small></p>
</td>
<td width="53%">
</td>
</table>
<p><small><i>XSetRGBColormaps</i> can generate
<i>BadAlloc</i>, <i>BadAtom</i>, and <i>BadWindow</i>
errors.</small></p>
<p><small>To obtain the <i>XStandardColormap</i> structure
associated with the specified property, use
<i>XGetRGBColormaps</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetRGBColormaps(<i>display</i>, <i>w</i>, <i>std_colormap_return</i>, <i>count_return</i>, <i>property</i>)
Display *<i>display</i>;
Window <i>w</i>;
XStandardColormap **<i>std_colormap_return</i>;
int *<i>count_return</i>;
Atom <i>property</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>std_colormap_return</i> Returns the
<i>XStandardColormap</i> structure.</small></p>
<p><small><i>count_return</i> Returns the number of
colormaps.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>property</i></small></p>
</td>
<td width="4%"></td>
<td width="56%">
<p><small>Specifies the property name.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetRGBColormaps</i> function returns the
RGB colormap definitions stored in the specified property on
the named window. If the property exists, is of type
RGB_COLOR_MAP, is of format 32, and is long enough to
contain a colormap definition, <i>XGetRGBColormaps</i>
allocates and fills in space for the returned colormaps and
returns a nonzero status. If the visualid is not present,
<i>XGetRGBColormaps</i> assumes the default visual for the
screen on which the window is located; if the killid is not
present, <i>None</i> is assumed, which indicates that the
resources cannot be released. Otherwise, none of the fields
are set, and <i>XGetRGBColormaps</i> returns a zero status.
Note that it is the caller’s responsibility to honor
the ICCCM restriction that only RGB_DEFAULT_MAP contain more
than one definition.</small></p>
<p><small><i>XGetRGBColormaps</i> can generate
<i>BadAtom</i> and <i>BadWindow</i> errors.</small></p>
<p><small><b>14</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b>Chapter 15</b></p>
<p align=center><b>Resource Manager Functions</b></p>
<p><small>A program often needs a variety of options in the
X environment (for example, fonts, colors, icons, and
cursors). Specifying all of these options on the command
line is awkward because users may want to customize many
aspects of the program and need a convenient way to
establish these customizations as the default settings. The
resource manager is provided for this purpose. Resource
specifications are usually stored in human-readable files
and in server properties.</small></p>
<p><small>The resource manager is a database manager with a
twist. In most database systems, you perform a query using
an imprecise specification, and you get back a set of
records. The resource manager, however, allows you to
specify a large set of values with an imprecise
specification, to query the database with a precise
specification, and to get back only a single value. This
should be used by applications that need to know what the
user prefers for colors, fonts, and other resources. It is
this use as a database for dealing with X resources that
inspired the name ‘‘Resource
Manager,’’ although the resource manager can be
and is used in other ways.</small></p>
<p><small>For example, a user of your application may want
to specify that all windows should have a blue background
but that all mail-reading windows should have a red
background. With well-engineered and coordinated
applications, a user can define this information using only
two lines of specifications.</small></p>
<p><small>As an example of how the resource manager works,
consider a mail-reading application called xmh. Assume that
it is designed so that it uses a complex window hierarchy
all the way down to individual command buttons, which may be
actual small subwindows in some toolkits. These are often
called objects or widgets. In such toolkit systems, each
user interface object can be composed of other objects and
can be assigned a name and a class. Fully qualified names or
classes can have arbitrary numbers of component names, but a
fully qualified name always has the same number of component
names as a fully qualified class. This generally reflects
the structure of the application as composed of these
objects, starting with the application itself.</small></p>
<p><small>For example, the xmh mail program has a name
‘‘xmh’’ and is one of a class of
‘‘Mail’’ programs. By convention,
the first character of class components is capitalized, and
the first letter of name components is in lowercase. Each
name and class finally has an attribute (for example,
‘‘foreground’’ or
‘‘font’’). If each window is
properly assigned a name and class, it is easy for the user
to specify attributes of any portion of the
application.</small></p>
<p><small>At the top level, the application might consist
of a paned window (that is, a window divided into several
sections) named ‘‘toc’’. One pane of
the paned window is a button box window named
‘‘buttons’’ and is filled with
command buttons. One of these command buttons is used to
incorporate new mail and has the name
‘‘incorporate’’. This window has a
fully qualified name,
‘‘xmh.toc.buttons.incorporate’’, and
a fully qualified class,
‘‘Xmh.Paned.Box.Command’’. Its fully
qualified name is the name of its parent,
‘‘xmh.toc.buttons’’, followed by its
name, ‘‘incorporate’’. Its class is
the class of its parent,
‘‘Xmh.Paned.Box’’, followed by its
particular class, ‘‘Command’’. The
fully qualified name of a resource is the attribute’s
name appended to the object’s fully qualified name,
and the fully qualified class is its class appended to the
object’s class.</small></p>
<p><small>The incorporate button might need the following
resources: Title string, Font, Foreground color for its
inactive state, Background color for its inactive state,
Foreground color for its active state, and Background color
for its active state. Each resource is considered to be an
attribute of the button and, as such, has a name and a
class. For example, the foreground color for the button in
its active state might be named
‘‘activeForeground’’, and its class
might be ‘‘Foreground’’.</small></p>
<p><small>When an application looks up a resource (for
example, a color), it passes the complete name and complete
class of the resource to a look-up routine. The resource
manager compares this complete specification against the
incomplete specifications of entries in the resource
database, finds the best match, and returns the
corresponding value for that entry.</small></p>
<p><small>The definitions for the resource manager are
contained in <<i>X11/Xresource.h</i>>.</small></p>
<a name="15.1. Resource File Syntax"></a>
<h2>15.1. Resource File Syntax</h2>
<p><small>The syntax of a resource file is a sequence of
resource lines terminated by newline characters or the end
of the file. The syntax of an individual resource line
is:</small></p>
<pre><small>ResourceLine = Comment | IncludeFile | ResourceSpec | <empty line>
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="30%">
<p><small>Comment</small></p>
</td>
<td width="4%">
<p><small>=</small></p>
</td>
<td width="66%">
<p><small>"!" {<any character except null or
newline>}</small></p>
</td>
<tr valign="top" align="left">
<td width="30%">
<p><small>IncludeFile</small></p>
</td>
<td width="4%">
<p><small>=</small></p>
</td>
<td width="66%">
<p><small>"#" WhiteSpace "include"
WhiteSpace FileName WhiteSpace</small></p>
</td>
<tr valign="top" align="left">
<td width="30%">
<p><small>FileName</small></p>
</td>
<td width="4%">
<p><small>=</small></p>
</td>
<td width="66%">
<p><small><valid filename for operating
system></small></p>
</td>
<tr valign="top" align="left">
<td width="30%">
<p><small>ResourceSpec</small></p>
</td>
<td width="4%">
<p><small>=</small></p>
</td>
<td width="66%">
<p><small>WhiteSpace ResourceName WhiteSpace ":"
WhiteSpace Value</small></p>
</td>
<tr valign="top" align="left">
<td width="30%">
<p><small>ResourceName</small></p>
</td>
<td width="4%">
<p><small>=</small></p>
</td>
<td width="66%">
<p><small>[Binding] {Component Binding}
ComponentName</small></p>
</td>
<tr valign="top" align="left">
<td width="30%">
<p><small>Binding</small></p>
</td>
<td width="4%">
<p><small>=</small></p>
</td>
<td width="66%">
<p><small>"." | "*"</small></p>
</td>
<tr valign="top" align="left">
<td width="30%">
<p><small>WhiteSpace</small></p>
</td>
<td width="4%">
<p><small>=</small></p>
</td>
<td width="66%">
<p><small>{<space> | <horizontal
tab>}</small></p>
</td>
<tr valign="top" align="left">
<td width="30%">
<p><small>Component</small></p>
</td>
<td width="4%">
<p><small>=</small></p>
</td>
<td width="66%">
<p><small>"?" | ComponentName</small></p>
</td>
<tr valign="top" align="left">
<td width="30%">
<p><small>ComponentName</small></p>
</td>
<td width="4%">
<p><small>=</small></p>
</td>
<td width="66%">
<p><small>NameChar {NameChar}</small></p>
</td>
<tr valign="top" align="left">
<td width="30%">
<p><small>NameChar</small></p>
</td>
<td width="4%">
<p><small>=</small></p>
</td>
<td width="66%">
<p><small>"a"−"z" |
"A"−"Z" |
"0"−"9" | "_" |
"-"</small></p>
</td>
<tr valign="top" align="left">
<td width="30%">
<p><small>Value</small></p>
</td>
<td width="4%">
<p><small>=</small></p>
</td>
<td width="66%">
<p><small>{<any character except null or unescaped
newline>}</small></p>
</td>
</table>
<p><small>Elements separated by vertical bar (|) are
alternatives. Curly braces ({...}) indicate zero or more
repetitions of the enclosed elements. Square brackets
([...]) indicate that the enclosed element is optional.
Quotes ("...") are used around literal
characters.</small></p>
<p><small>IncludeFile lines are interpreted by replacing
the line with the contents of the specified file. The word
‘‘include’’ must be in lowercase.
The file name is interpreted relative to the directory of
the file in which the line occurs (for example, if the file
name contains no directory or contains a relative directory
specification).</small></p>
<p><small>If a ResourceName contains a contiguous sequence
of two or more Binding characters, the sequence will be
replaced with a single ‘‘.’’
character if the sequence contains only
‘‘.’’ characters; otherwise, the
sequence will be replaced with a single
‘‘*’’ character.</small></p>
<p><small>A resource database never contains more than one
entry for a given ResourceName. If a resource file contains
multiple lines with the same ResourceName, the last line in
the file is used.</small></p>
<p><small>Any white space characters before or after the
name or colon in a ResourceSpec are ignored. To allow a
Value to begin with white space, the two-character sequence
‘‘\<i>space</i>’’ (backslash
followed by space) is recognized and replaced by a space
character, and the two-character sequence
‘‘\<i>tab</i>’’ (backslash followed
by horizontal tab) is recognized and replaced by a
horizontal tab character. To allow a Value to contain
embedded newline characters, the two-character sequence
‘‘\n’’ is recognized and replaced by
a newline character. To allow a Value to be broken across
multiple lines in a text file, the two-character sequence
‘‘\<i>newline</i>’’ (backslash
followed by newline) is recognized and removed from the
value. To allow a Value to contain arbitrary character
codes, the four-character sequence
‘‘\<i>nnn</i>’’, where each <i>n</i>
is a digit character in the range of
‘‘0’’−‘‘7’’,
is recognized and replaced with a single byte that contains
the octal value specified by the sequence. Finally, the
two-character sequence ‘‘\\’’ is
recognized and replaced with a single backslash.</small></p>
<p><small>As an example of these sequences, the following
resource line contains a value consisting of four
characters: a backslash, a null, a
‘‘z’’, and a newline:</small></p>
<pre><small> magic.values: \\\000\
z\n
</small></pre>
<a name="15.2. Resource Manager Matching Rules"></a>
<h2>15.2. Resource Manager Matching Rules</h2>
<p><small>The algorithm for determining which resource
database entry matches a given query is the heart of the
resource manager. All queries must fully specify the name
and class of the desired resource (use of the characters
‘‘*’’ and
‘‘?’’ is not permitted). The library
supports up to 100 components in a full name or class.
Resources are stored in the database with only partially
specified names and classes, using pattern matching
constructs. An asterisk (*) is a loose binding and is used
to represent any number of intervening components, including
none. A period (.) is a tight binding and is used to
separate immediately adjacent components. A question mark
(?) is used to match any single component name or class. A
database entry cannot end in a loose binding; the final
component (which cannot be the character
‘‘?’’) must be specified. The lookup
algorithm searches the database for the entry that most
closely matches (is most specific for) the full name and
class being queried. When more than one database entry
matches the full name and class, precedence rules are used
to select just one.</small></p>
<p><small>The full name and class are scanned from left to
right (from highest level in the hierarchy to lowest), one
component at a time. At each level, the corresponding
component and/or binding of each matching entry is
determined, and these matching components and bindings are
compared according to precedence rules. Each of the rules is
applied at each level before moving to the next level, until
a rule selects a single entry over all others. The rules, in
order of precedence, are:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small>1.</small></p>
</td>
<td width="6%"></td>
<td width="90%">
<p><small>An entry that contains a matching component
(whether name, class, or the character
‘‘?’’) takes precedence over entries
that elide the level (that is, entries that match the level
in a loose binding).</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small>2.</small></p>
</td>
<td width="6%"></td>
<td width="90%">
<p><small>An entry with a matching name takes precedence
over both entries with a matching class and entries that
match using the character ‘‘?’’. An
entry with a matching class takes precedence over entries
that match using the character
‘‘?’’.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small>3.</small></p>
</td>
<td width="6%"></td>
<td width="90%">
<p><small>An entry preceded by a tight binding takes
precedence over entries preceded by a loose
binding.</small></p>
</td>
</table>
<p><small>To illustrate these rules, consider the following
resource database entries:</small></p>
<pre><small> xmh*Paned*activeForeground: red<i>(entry A)
</i></small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<p><small>*incorporate.Foreground:</small></p>
<td width="9%"></td>
<td width="50%">
<p><small>blue</small></p>
</td>
<td width="20%">
<p><small><i>(entry B)</i><br>
xmh.toc*Command*activeForeground:</small></p>
</td>
<td width="20%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%"></td>
<td width="20%">
<p><small>green<i>(entry C)</i><br>
xmh.toc*?.Foreground:</small></p>
</td>
<td width="20%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>white</small></p>
</td>
<td width="20%">
<p><small><i>(entry D)</i><br>
xmh.toc*Command.activeForeground:</small></p>
</td>
<td width="20%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%"></td>
<td width="20%">
<p><small>black<i>(entry E)</i></small></p>
</td>
<td width="20%">
</td>
</table>
<p><small>Consider a query for the resource:</small></p>
<pre><small> xmh.toc.messagefunctions.incorporate.activeForeground<i>(name)
</i></small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<p><small>Xmh.Paned.Box.Command.Foreground</small></p>
<td width="9%"></td>
<td width="70%">
<p><small><i>(class)</i></small></p>
</td>
<td width="20%">
</td>
</table>
<p><small>At the first level (xmh, Xmh), rule 1 eliminates
entry B. At the second level (toc, Paned), rule 2 eliminates
entry A. At the third level (messagefunctions, Box), no
entries are eliminated. At the fourth level (incorporate,
Command), rule 2 eliminates entry D. At the fifth level
(activeForeground, Foreground), rule 3 eliminates entry
C.</small></p>
<a name="15.3. Quarks"></a>
<h2>15.3. Quarks</h2>
<p><small>Most uses of the resource manager involve
defining names, classes, and representation types as string
constants. However, always referring to strings in the
resource manager can be slow, because it is so heavily used
in some toolkits. To solve this problem, a shorthand for a
string is used in place of the string in many of the
resource manager functions. Simple comparisons can be
performed rather than string comparisons. The shorthand name
for a string is called a quark and is the type
<i>XrmQuark</i>. On some occasions, you may want to allocate
a quark that has no string equivalent.</small></p>
<p><small>A quark is to a string what an atom is to a
string in the server, but its use is entirely local to your
application.</small></p>
<p><small>To allocate a new quark, use
<i>XrmUniqueQuark</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XrmQuark XrmUniqueQuark()
</small></pre>
<p><small>│__</small></p>
<p><small>The <i>XrmUniqueQuark</i> function allocates a
quark that is guaranteed not to represent any string that is
known to the resource manager.</small></p>
<p><small>Each name, class, and representation type is
typedef’d as an <i>XrmQuark</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>typedef int XrmQuark, *XrmQuarkList;
typedef XrmQuark XrmName;
typedef XrmQuark XrmClass;
typedef XrmQuark XrmRepresentation;
#define NULLQUARK ((XrmQuark) 0)
</small></pre>
<p><small>│__</small></p>
<p><small>Lists are represented as null-terminated arrays
of quarks. The size of the array must be large enough for
the number of components used.</small></p>
<p><small>__ │</small></p>
<pre><small>typedef XrmQuarkList XrmNameList;
typedef XrmQuarkList XrmClassList;
</small></pre>
<p><small>│__</small></p>
<p><small>To convert a string to a quark, use
<i>XrmStringToQuark</i> or
<i>XrmPermStringToQuark</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>#define XrmStringToName(string) XrmStringToQuark(string)
#define XrmStringToClass(string) XrmStringToQuark(string)
#define XrmStringToRepresentation(string) XrmStringToQuark(string)
XrmQuark XrmStringToQuark(<i>string</i>)
char *<i>string</i>;
XrmQuark XrmPermStringToQuark(<i>string</i>)
char *<i>string</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the string for which a quark is to be
allocated.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>These functions can be used to convert from
string to quark representation. If the string is not in the
Host Portable Character Encoding, the conversion is
implementation-dependent. The string argument to
<i>XrmStringToQuark</i> need not be permanently allocated
storage. <i>XrmPermStringToQuark</i> is just like
<i>XrmStringToQuark</i>, except that Xlib is permitted to
assume the string argument is permanently allocated, and,
hence, that it can be used as the value to be returned by
<i>XrmQuarkToString</i>.</small></p>
<p><small>For any given quark, if <i>XrmStringToQuark</i>
returns a non-NULL value, all future calls will return the
same value (identical address).</small></p>
<p><small>To convert a quark to a string, use
<i>XrmQuarkToString</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>#define XrmNameToString(name) XrmQuarkToString(name)
#define XrmClassToString(class) XrmQuarkToString(class)
#define XrmRepresentationToString(type) XrmQuarkToString(type)
char *XrmQuarkToString(<i>quark</i>)
XrmQuark <i>quark</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>quark</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the quark for which the equivalent
string is desired.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>These functions can be used to convert from quark
representation to string. The string pointed to by the
return value must not be modified or freed. The returned
string is byte-for-byte equal to the original string passed
to one of the string-to-quark routines. If no string exists
for that quark, <i>XrmQuarkToString</i> returns NULL. For
any given quark, if <i>XrmQuarkToString</i> returns a
non-NULL value, all future calls will return the same value
(identical address).</small></p>
<p><small>To convert a string with one or more components
to a quark list, use
<i>XrmStringToQuarkList</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>#define XrmStringToNameList(str, name) XrmStringToQuarkList((str), (name))
#define XrmStringToClassList(str, class) XrmStringToQuarkList((str), (class))
void XrmStringToQuarkList(<i>string</i>, <i>quarks_return</i>)
char *<i>string</i>;
XrmQuarkList <i>quarks_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the string for which a quark list is to
be allocated.</small></p>
</td>
</table>
<p><small><i>quarks_return</i> Returns the list of quarks.
The caller must allocate sufficient space for the quarks
list before calling <i>XrmStringToQuarkList</i>.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XrmStringToQuarkList</i> function converts
the null-terminated string (generally a fully qualified
name) to a list of quarks. Note that the string must be in
the valid ResourceName format (see section 15.1). If the
string is not in the Host Portable Character Encoding, the
conversion is implementation-dependent.</small></p>
<p><small>A binding list is a list of type
<i>XrmBindingList</i> and indicates if components of name or
class lists are bound tightly or loosely (that is, if
wildcarding of intermediate components is
specified).</small></p>
<pre><small>typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList;
</small></pre>
<p><small><i>XrmBindTightly</i> indicates that a period
separates the components, and <i>XrmBindLoosely</i>
indicates that an asterisk separates the
components.</small></p>
<p><small>To convert a string with one or more components
to a binding list and a quark list, use
<i>XrmStringToBindingQuarkList</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XrmStringToBindingQuarkList(<i>string</i>, <i>bindings_return</i>, <i>quarks_return</i>)
char *<i>string</i>;
XrmBindingList <i>bindings_return</i>;
XrmQuarkList <i>quarks_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the string for which a quark list is to
be allocated.</small></p>
</td>
</table>
<p><small><i>bindings_return</i> Returns the binding list.
The caller must allocate sufficient space for the binding
list before calling
<i>XrmStringToBindingQuarkList</i>.</small></p>
<p><small><i>quarks_return</i> Returns the list of quarks.
The caller must allocate sufficient space for the quarks
list before calling
<i>XrmStringToBindingQuarkList</i>.</small></p>
<p><small>│__</small></p>
<p><small>Component names in the list are separated by a
period or an asterisk character. The string must be in the
format of a valid ResourceName (see section 15.1). If the
string does not start with a period or an asterisk, a tight
binding is assumed. For example, the string
‘‘*a.b*c’’ becomes:</small></p>
<pre><small>quarks: a bc
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small>bindings:</small></p>
</td>
<td width="16%"></td>
<td width="14%">
<p><small>loose</small></p>
</td>
<td width="56%">
<p><small>tightloose</small></p>
</td>
</table>
<a name="15.4. Creating and Storing Databases"></a>
<h2>15.4. Creating and Storing Databases</h2>
<p><small>A resource database is an opaque type,
<i>XrmDatabase</i>. Each database value is stored in an
<i>XrmValue</i> structure. This structure consists of a
size, an address, and a representation type. The size is
specified in bytes. The representation type is a way for you
to store data tagged by some application-defined type (for
example, the strings ‘‘font’’ or
‘‘color’’). It has nothing to do
with the C data type or with its class. The <i>XrmValue</i>
structure is defined as:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned int size;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XPointer addr;</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>} XrmValue, *XrmValuePtr;</small></p>
<p><small>│__</small></p>
<p><small>To initialize the resource manager, use
<i>XrmInitialize</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XrmInitialize();
</small></pre>
<p><small>│__</small></p>
<p><small>To retrieve a database from disk, use
<i>XrmGetFileDatabase</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XrmDatabase XrmGetFileDatabase(<i>filename</i>)
char *<i>filename</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>filename</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the resource database file
name.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XrmGetFileDatabase</i> function opens the
specified file, creates a new resource database, and loads
it with the specifications read in from the specified file.
The specified file should contain a sequence of entries in
valid ResourceLine format (see section 15.1); the database
that results from reading a file with incorrect syntax is
implementation-dependent. The file is parsed in the current
locale, and the database is created in the current locale.
If it cannot open the specified file,
<i>XrmGetFileDatabase</i> returns NULL.</small></p>
<p><small>To store a copy of a database to disk, use
<i>XrmPutFileDatabase</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XrmPutFileDatabase(<i>database</i>, <i>stored_db</i>)
XrmDatabase <i>database</i>;
char *<i>stored_db</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>database</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the database that is to be
used.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>stored_db</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the file name for the stored
database.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XrmPutFileDatabase</i> function stores a
copy of the specified database in the specified file. Text
is written to the file as a sequence of entries in valid
ResourceLine format (see section 15.1). The file is written
in the locale of the database. Entries containing resource
names that are not in the Host Portable Character Encoding
or containing values that are not in the encoding of the
database locale, are written in an implementation-dependent
manner. The order in which entries are written is
implementation-dependent. Entries with representation types
other than ‘‘String’’ are
ignored.</small></p>
<p><small>To obtain a pointer to the screen-independent
resources of a display, use
<i>XResourceManagerString</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char *XResourceManagerString(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XResourceManagerString</i> function
returns the RESOURCE_MANAGER property from the
server’s root window of screen zero, which was
returned when the connection was opened using
<i>XOpenDisplay</i>. The property is converted from type
STRING to the current locale. The conversion is identical to
that produced by <i>XmbTextPropertyToTextList</i> for a
single element STRING property. The returned string is owned
by Xlib and should not be freed by the client. The property
value must be in a format that is acceptable to
<i>XrmGetStringDatabase</i>. If no property exists, NULL is
returned.</small></p>
<p><small>To obtain a pointer to the screen-specific
resources of a screen, use
<i>XScreenResourceString</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char *XScreenResourceString(<i>screen</i>)
Screen *<i>screen</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>Specifies the screen.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XScreenResourceString</i> function returns
the SCREEN_RESOURCES property from the root window of the
specified screen. The property is converted from type STRING
to the current locale. The conversion is identical to that
produced by <i>XmbTextPropertyToTextList</i> for a single
element STRING property. The property value must be in a
format that is acceptable to <i>XrmGetStringDatabase</i>. If
no property exists, NULL is returned. The caller is
responsible for freeing the returned string by using
<i>XFree</i>.</small></p>
<p><small>To create a database from a string, use
<i>XrmGetStringDatabase</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XrmDatabase XrmGetStringDatabase(<i>data</i>)
char *<i>data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>data</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the database contents using a
string.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XrmGetStringDatabase</i> function creates
a new database and stores the resources specified in the
specified null-terminated string.
<i>XrmGetStringDatabase</i> is similar to
<i>XrmGetFileDatabase</i> except that it reads the
information out of a string instead of out of a file. The
string should contain a sequence of entries in valid
ResourceLine format (see section 15.1) terminated by a null
character; the database that results from using a string
with incorrect syntax is implementation-dependent. The
string is parsed in the current locale, and the database is
created in the current locale.</small></p>
<p><small>To obtain the locale name of a database, use
<i>XrmLocaleOfDatabase</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char *XrmLocaleOfDatabase(<i>database</i>)
XrmDatabase <i>database</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>database</i></small></p>
</td>
<td width="4%"></td>
<td width="64%">
<p><small>Specifies the resource database.</small></p>
</td>
<td width="15%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XrmLocaleOfDatabase</i> function returns
the name of the locale bound to the specified database, as a
null-terminated string. The returned locale name string is
owned by Xlib and should not be modified or freed by the
client. Xlib is not permitted to free the string until the
database is destroyed. Until the string is freed, it will
not be modified by Xlib.</small></p>
<p><small>To destroy a resource database and free its
allocated memory, use <i>XrmDestroyDatabase</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XrmDestroyDatabase(<i>database</i>)
XrmDatabase <i>database</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>database</i></small></p>
</td>
<td width="4%"></td>
<td width="64%">
<p><small>Specifies the resource database.</small></p>
</td>
<td width="15%">
</td>
</table>
<p><small>│__</small></p>
<p><small>If database is NULL, <i>XrmDestroyDatabase</i>
returns immediately.</small></p>
<p><small>To associate a resource database with a display,
use <i>XrmSetDatabase</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XrmSetDatabase(<i>display</i>, <i>database</i>)
Display *<i>display</i>;
XrmDatabase <i>database</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>database</i></small></p>
</td>
<td width="4%"></td>
<td width="64%">
<p><small>Specifies the resource database.</small></p>
</td>
<td width="15%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XrmSetDatabase</i> function associates the
specified resource database (or NULL) with the specified
display. The database previously associated with the display
(if any) is not destroyed. A client or toolkit may find this
function convenient for retaining a database once it is
constructed.</small></p>
<p><small>To get the resource database associated with a
display, use <i>XrmGetDatabase</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XrmDatabase XrmGetDatabase(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XrmGetDatabase</i> function returns the
database associated with the specified display. It returns
NULL if a database has not yet been set.</small></p>
<a name="15.5. Merging Resource Databases"></a>
<h2>15.5. Merging Resource Databases</h2>
<p><small>To merge the contents of a resource file into a
database, use <i>XrmCombineFileDatabase</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XrmCombineFileDatabase(<i>filename</i>, <i>target_db</i>, <i>override</i>)
char *<i>filename</i>;
XrmDatabase *<i>target_db</i>;
Bool <i>override</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>filename</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the resource database file
name.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>target_db</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the resource database into which the
source database is to be merged.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>override</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies whether source entries override target
ones.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XrmCombineFileDatabase</i> function merges
the contents of a resource file into a database. If the same
specifier is used for an entry in both the file and the
database, the entry in the file will replace the entry in
the database if override is <i>True</i>; otherwise, the
entry in the file is discarded. The file is parsed in the
current locale. If the file cannot be read, a zero status is
returned; otherwise, a nonzero status is returned. If
target_db contains NULL, <i>XrmCombineFileDatabase</i>
creates and returns a new database to it. Otherwise, the
database pointed to by target_db is not destroyed by the
merge. The database entries are merged without changing
values or types, regardless of the locale of the database.
The locale of the target database is not
modified.</small></p>
<p><small>To merge the contents of one database into
another database, use <i>XrmCombineDatabase</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XrmCombineDatabase(<i>source_db</i>, <i>target_db</i>, <i>override</i>)
XrmDatabase <i>source_db</i>, *<i>target_db</i>;
Bool <i>override</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>source_db</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the resource database that is to be
merged into the target database.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>target_db</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the resource database into which the
source database is to be merged.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>override</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies whether source entries override target
ones.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XrmCombineDatabase</i> function merges the
contents of one database into another. If the same specifier
is used for an entry in both databases, the entry in the
source_db will replace the entry in the target_db if
override is <i>True</i>; otherwise, the entry in source_db
is discarded. If target_db contains NULL,
<i>XrmCombineDatabase</i> simply stores source_db in it.
Otherwise, source_db is destroyed by the merge, but the
database pointed to by target_db is not destroyed. The
database entries are merged without changing values or
types, regardless of the locales of the databases. The
locale of the target database is not modified.</small></p>
<p><small>To merge the contents of one database into
another database with override semantics, use
<i>XrmMergeDatabases</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XrmMergeDatabases(<i>source_db</i>, <i>target_db</i>)
XrmDatabase <i>source_db</i>, *<i>target_db</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>source_db</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the resource database that is to be
merged into the target database.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>target_db</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the resource database into which the
source database is to be merged.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Calling the <i>XrmMergeDatabases</i> function is
equivalent to calling the <i>XrmCombineDatabase</i> function
with an override argument of <i>True</i>.</small></p>
<a name="15.6. Looking Up Resources"></a>
<h2>15.6. Looking Up Resources</h2>
<p><small>To retrieve a resource from a resource database,
use <i>XrmGetResource</i>, <i>XrmQGetResource</i>, or
<i>XrmQGetSearchResource</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XrmGetResource(<i>database</i>, <i>str_name</i>, <i>str_class</i>, <i>str_type_return</i>, <i>value_return</i>)
XrmDatabase <i>database</i>;
char *<i>str_name</i>;
char *<i>str_class</i>;
char **<i>str_type_return</i>;
XrmValue *<i>value_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>database</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the database that is to be
used.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>str_name</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the fully qualified name of the value
being retrieved (as a string).</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>str_class</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the fully qualified class of the value
being retrieved (as a string).</small></p>
</td>
</table>
<p><small><i>str_type_return</i> Returns the representation
type of the destination (as a string).</small></p>
<p><small><i>value_return</i> Returns the value in the
database.</small></p>
<p><small>│__</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>Bool XrmQGetResource(<i>database</i>, <i>quark_name</i>, <i>quark_class</i>, <i>quark_type_return</i>, <i>value_return</i>)
XrmDatabase <i>database</i>;
XrmNameList <i>quark_name</i>;
XrmClassList <i>quark_class</i>;
XrmRepresentation *<i>quark_type_return</i>;
XrmValue *<i>value_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>database</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the database that is to be
used.</small></p>
</td>
</table>
<p><small><i>quark_name</i> Specifies the fully qualified
name of the value being retrieved (as a quark).</small></p>
<p><small><i>quark_class</i> Specifies the fully qualified
class of the value being retrieved (as a quark).</small></p>
<p><small><i>quark_type_return</i> Returns the
representation type of the destination (as a
quark).</small></p>
<p><small><i>value_return</i> Returns the value in the
database.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XrmGetResource</i> and
<i>XrmQGetResource</i> functions retrieve a resource from
the specified database. Both take a fully qualified
name/class pair, a destination resource representation, and
the address of a value (size/address pair). The value and
returned type point into database memory; therefore, you
must not modify the data.</small></p>
<p><small>The database only frees or overwrites entries on
<i>XrmPutResource</i>, <i>XrmQPutResource</i>, or
<i>XrmMergeDatabases</i>. A client that is not storing new
values into the database or is not merging the database
should be safe using the address passed back at any time
until it exits. If a resource was found, both
<i>XrmGetResource</i> and <i>XrmQGetResource</i> return
<i>True</i>; otherwise, they return
<i>False</i>.</small></p>
<p><small>Most applications and toolkits do not make random
probes into a resource database to fetch resources. The X
toolkit access pattern for a resource database is quite
stylized. A series of from 1 to 20 probes is made with only
the last name/class differing in each probe. The
<i>XrmGetResource</i> function is at worst a
<img src="grohtml-14392-108.png"> algorithm, where <i>n</i>
is the length of the name/class list. This can be improved
upon by the application programmer by prefetching a list of
database levels that might match the first part of a
name/class list.</small></p>
<p><small>To obtain a list of database levels, use
<i>XrmQGetSearchList</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>typedef XrmHashTable *XrmSearchList;
Bool XrmQGetSearchList(<i>database</i>, <i>names</i>, <i>classes</i>, <i>list_return</i>, <i>list_length</i>)
XrmDatabase <i>database</i>;
XrmNameList <i>names</i>;
XrmClassList <i>classes</i>;
XrmSearchList <i>list_return</i>;
int <i>list_length</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>database</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the database that is to be
used.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>names</i></small></p>
</td>
<td width="10%"></td>
<td width="70%">
<p><small>Specifies a list of resource names.</small></p>
</td>
<td width="9%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>classes</i></small></p>
</td>
<td width="6%"></td>
<td width="74%">
<p><small>Specifies a list of resource classes.</small></p>
</td>
<td width="5%">
</td>
</table>
<p><small><i>list_return</i> Returns a search list for
further use. The caller must allocate sufficient space for
the list before calling
<i>XrmQGetSearchList</i>.</small></p>
<p><small><i>list_length</i> Specifies the number of
entries (not the byte size) allocated for
list_return.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XrmQGetSearchList</i> function takes a
list of names and classes and returns a list of database
levels where a match might occur. The returned list is in
best-to-worst order and uses the same algorithm as
<i>XrmGetResource</i> for determining precedence. If
list_return was large enough for the search list,
<i>XrmQGetSearchList</i> returns <i>True</i>; otherwise, it
returns <i>False</i>.</small></p>
<p><small>The size of the search list that the caller must
allocate is dependent upon the number of levels and
wildcards in the resource specifiers that are stored in the
database. The worst case length is
<img src="grohtml-14392-109.png"> , where <i>n</i> is the
number of name or class components in names or
classes.</small></p>
<p><small>When using <i>XrmQGetSearchList</i> followed by
multiple probes for resources with a common name and class
prefix, only the common prefix should be specified in the
name and class list to <i>XrmQGetSearchList</i>.</small></p>
<p><small>To search resource database levels for a given
resource, use <i>XrmQGetSearchResource</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XrmQGetSearchResource(<i>list</i>, <i>name</i>, <i>class</i>, <i>type_return</i>, <i>value_return</i>)
XrmSearchList <i>list</i>;
XrmName <i>name</i>;
XrmClass <i>class</i>;
XrmRepresentation *<i>type_return</i>;
XrmValue *<i>value_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>list</i></small></p>
</td>
<td width="12%"></td>
<td width="74%">
<p><small>Specifies the search list returned by
<i>XrmQGetSearchList</i>.</small></p>
</td>
<td width="5%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>name</i></small></p>
</td>
<td width="12%"></td>
<td width="56%">
<p><small>Specifies the resource name.</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>class</i></small></p>
</td>
<td width="10%"></td>
<td width="58%">
<p><small>Specifies the resource class.</small></p>
</td>
<td width="21%">
</td>
</table>
<p><small><i>type_return</i> Returns data representation
type.</small></p>
<p><small><i>value_return</i> Returns the value in the
database.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XrmQGetSearchResource</i> function
searches the specified database levels for the resource that
is fully identified by the specified name and class. The
search stops with the first match.
<i>XrmQGetSearchResource</i> returns <i>True</i> if the
resource was found; otherwise, it returns
<i>False</i>.</small></p>
<p><small>A call to <i>XrmQGetSearchList</i> with a name
and class list containing all but the last component of a
resource name followed by a call to
<i>XrmQGetSearchResource</i> with the last component name
and class returns the same database entry as
<i>XrmGetResource</i> and <i>XrmQGetResource</i> with the
fully qualified name and class.</small></p>
<a name="15.7. Storing into a Resource Database"></a>
<h2>15.7. Storing into a Resource Database</h2>
<p><small>To store resources into the database, use
<i>XrmPutResource</i> or <i>XrmQPutResource</i>. Both
functions take a partial resource specification, a
representation type, and a value. This value is copied into
the specified database.</small></p>
<p><small>__ │</small></p>
<pre><small>void XrmPutResource(<i>database</i>, <i>specifier</i>, <i>type</i>, <i>value</i>)
XrmDatabase *<i>database</i>;
char *<i>specifier</i>;
char *<i>type</i>;
XrmValue *<i>value</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>database</i></small></p>
</td>
<td width="4%"></td>
<td width="64%">
<p><small>Specifies the resource database.</small></p>
</td>
<td width="15%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>specifier</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies a complete or partial specification of
the resource.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>type</i></small></p>
</td>
<td width="12%"></td>
<td width="70%">
<p><small>Specifies the type of the resource.</small></p>
</td>
<td width="9%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>value</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the value of the resource, which is
specified as a string.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>If database contains NULL, <i>XrmPutResource</i>
creates a new database and returns a pointer to it.
<i>XrmPutResource</i> is a convenience function that calls
<i>XrmStringToBindingQuarkList</i> followed by:</small></p>
<pre><small> XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), value)
</small></pre>
<p><small>If the specifier and type are not in the Host
Portable Character Encoding, the result is
implementation-dependent. The value is stored in the
database without modification.</small></p>
<p><small>__ │</small></p>
<pre><small>void XrmQPutResource(<i>database</i>, <i>bindings</i>, <i>quarks</i>, <i>type</i>, <i>value</i>)
XrmDatabase *<i>database</i>;
XrmBindingList <i>bindings</i>;
XrmQuarkList <i>quarks</i>;
XrmRepresentation <i>type</i>;
XrmValue *<i>value</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>database</i></small></p>
</td>
<td width="4%"></td>
<td width="64%">
<p><small>Specifies the resource database.</small></p>
</td>
<td width="15%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>bindings</i></small></p>
</td>
<td width="4%"></td>
<td width="58%">
<p><small>Specifies a list of bindings.</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>quarks</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the complete or partial name or the
class list of the resource.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>type</i></small></p>
</td>
<td width="12%"></td>
<td width="70%">
<p><small>Specifies the type of the resource.</small></p>
</td>
<td width="9%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>value</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the value of the resource, which is
specified as a string.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>If database contains NULL, <i>XrmQPutResource</i>
creates a new database and returns a pointer to it. If a
resource entry with the identical bindings and quarks
already exists in the database, the previous type and value
are replaced by the new specified type and value. The value
is stored in the database without modification.</small></p>
<p><small>To add a resource that is specified as a string,
use <i>XrmPutStringResource</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XrmPutStringResource(<i>database</i>, <i>specifier</i>, <i>value</i>)
XrmDatabase *<i>database</i>;
char *<i>specifier</i>;
char *<i>value</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>database</i></small></p>
</td>
<td width="4%"></td>
<td width="64%">
<p><small>Specifies the resource database.</small></p>
</td>
<td width="15%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>specifier</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies a complete or partial specification of
the resource.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>value</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the value of the resource, which is
specified as a string.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>If database contains NULL,
<i>XrmPutStringResource</i> creates a new database and
returns a pointer to it. <i>XrmPutStringResource</i> adds a
resource with the specified value to the specified database.
<i>XrmPutStringResource</i> is a convenience function that
first calls <i>XrmStringToBindingQuarkList</i> on the
specifier and then calls <i>XrmQPutResource</i>, using a
‘‘String’’ representation type. If
the specifier is not in the Host Portable Character
Encoding, the result is implementation-dependent. The value
is stored in the database without modification.</small></p>
<p><small>To add a string resource using quarks as a
specification, use <i>XrmQPutStringResource</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XrmQPutStringResource(<i>database</i>, <i>bindings</i>, <i>quarks</i>, <i>value</i>)
XrmDatabase *<i>database</i>;
XrmBindingList <i>bindings</i>;
XrmQuarkList <i>quarks</i>;
char *<i>value</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>database</i></small></p>
</td>
<td width="4%"></td>
<td width="64%">
<p><small>Specifies the resource database.</small></p>
</td>
<td width="15%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>bindings</i></small></p>
</td>
<td width="4%"></td>
<td width="58%">
<p><small>Specifies a list of bindings.</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>quarks</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the complete or partial name or the
class list of the resource.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>value</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the value of the resource, which is
specified as a string.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>If database contains NULL,
<i>XrmQPutStringResource</i> creates a new database and
returns a pointer to it. <i>XrmQPutStringResource</i> is a
convenience routine that constructs an <i>XrmValue</i> for
the value string (by calling <i>strlen</i> to compute the
size) and then calls <i>XrmQPutResource</i>, using a
‘‘String’’ representation type. The
value is stored in the database without
modification.</small></p>
<p><small>To add a single resource entry that is specified
as a string that contains both a name and a value, use
<i>XrmPutLineResource</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XrmPutLineResource(<i>database</i>, <i>line</i>)
XrmDatabase *<i>database</i>;
char *<i>line</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>database</i></small></p>
</td>
<td width="4%"></td>
<td width="64%">
<p><small>Specifies the resource database.</small></p>
</td>
<td width="15%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>line</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the resource name and value pair as a
single string.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>If database contains NULL,
<i>XrmPutLineResource</i> creates a new database and returns
a pointer to it. <i>XrmPutLineResource</i> adds a single
resource entry to the specified database. The line should be
in valid ResourceLine format (see section 15.1) terminated
by a newline or null character; the database that results
from using a string with incorrect syntax is
implementation-dependent. The string is parsed in the locale
of the database. If the <i>ResourceName</i> is not in the
Host Portable Character Encoding, the result is
implementation-dependent. Note that comment lines are not
stored.</small></p>
<a name="15.8. Enumerating Database Entries"></a>
<h2>15.8. Enumerating Database Entries</h2>
<p><small>To enumerate the entries of a database, use
<i>XrmEnumerateDatabase</i>.</small></p>
<p><small>__ │</small></p>
<p align=center><small><img src="grohtml-1439278.png"></small></p>
<pre><small>Bool XrmEnumerateDatabase(<i>database</i>, <i>name_prefix</i>, <i>class_prefix</i>, <i>mode</i>, <i>proc</i>, <i>arg</i>)
XrmDatabase <i>database</i>;
XrmNameList <i>name_prefix</i>;
XrmClassList <i>class_prefix</i>;
int <i>mode</i>;
Bool (*<i>proc</i>)();
XPointer <i>arg</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>database</i></small></p>
</td>
<td width="4%"></td>
<td width="64%">
<p><small>Specifies the resource database.</small></p>
</td>
<td width="15%">
</td>
</table>
<p><small><i>name_prefix</i> Specifies the resource name
prefix.</small></p>
<p><small><i>class_prefix</i> Specifies the resource class
prefix.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>mode</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the number of levels to
enumerate.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>proc</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the procedure that is to be called for
each matching entry.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>arg</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the user-supplied argument that will be
passed to the procedure.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XrmEnumerateDatabase</i> function calls
the specified procedure for each resource in the database
that would match some completion of the given name/class
resource prefix. The order in which resources are found is
implementation-dependent. If mode is <i>XrmEnumOneLevel</i>,
a resource must match the given name/class prefix with just
a single name and class appended. If mode is
<i>XrmEnumAllLevels</i>, the resource must match the given
name/class prefix with one or more names and classes
appended. If the procedure returns <i>True</i>, the
enumeration terminates and the function returns <i>True</i>.
If the procedure always returns <i>False</i>, all matching
resources are enumerated and the function returns
<i>False</i>.</small></p>
<p><small>The procedure is called with the following
arguments:</small></p>
<pre><small>(*<i>proc</i>)(<i>database</i>, <i>bindings</i>, <i>quarks</i>, <i>type</i>, <i>value</i>, <i>arg</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XrmDatabase *<i>database</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XrmBindingList <i>bindings</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XrmQuarkList <i>quarks</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XrmRepresentation *<i>type</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XrmValue *<i>value</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XPointer <i>arg</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>The bindings and quarks lists are terminated by
<i>NULLQUARK</i>. Note that pointers to the database and
type are passed, but these values should not be
modified.</small></p>
<p><small>The procedure must not modify the database. If
Xlib has been initialized for threads, the procedure is
called with the database locked and the result of a call by
the procedure to any Xlib function using the same database
is not defined.</small></p>
<a name="15.9. Parsing Command Line Options"></a>
<h2>15.9. Parsing Command Line Options</h2>
<p><small>The <i>XrmParseCommand</i> function can be used
to parse the command line arguments to a program and modify
a resource database with selected entries from the command
line.</small></p>
<p><small>__ │</small></p>
<pre><small>typedef enum {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XrmoptionNoArg,</small></p>
</td>
<td width="50%">
<p><small>/* Value is specified in XrmOptionDescRec.value
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XrmoptionIsArg,</small></p>
</td>
<td width="50%">
<p><small>/* Value is the option string itself
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XrmoptionStickyArg,</small></p>
</td>
<td width="50%">
<p><small>/* Value is characters immediately following
option */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XrmoptionSepArg,</small></p>
</td>
<td width="50%">
<p><small>/* Value is next argument in argv */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XrmoptionResArg,</small></p>
</td>
<td width="50%">
<p><small>/* Resource and value in next argument in argv
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XrmoptionSkipArg,</small></p>
</td>
<td width="50%">
<p><small>/* Ignore this option and the next argument in
argv */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XrmoptionSkipLine,</small></p>
</td>
<td width="50%">
<p><small>/* Ignore this option and the rest of argv
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XrmoptionSkipNArgs</small></p>
</td>
<td width="50%">
<p><small>/* Ignore this option and the next</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
</td>
<td width="50%">
<p><small>XrmOptionDescRec.value arguments in argv
*/</small></p>
</td>
</table>
<p><small>} XrmOptionKind;</small></p>
<p><small>│__</small></p>
<p><small>Note that <i>XrmoptionSkipArg</i> is equivalent
to <i>XrmoptionSkipNArgs</i> with the
<i>XrmOptionDescRec.value</i> field containing the value
one. Note also that the value zero for
<i>XrmoptionSkipNArgs</i> indicates that only the option
itself is to be skipped.</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>char *option;</small></p>
</td>
<td width="50%">
<p><small>/* Option specification string in argv
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>char *specifier;</small></p>
</td>
<td width="50%">
<p><small>/* Binding and resource name (sans application
name) */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XrmOptionKind argKind;/* Which style of option it
is */</small></p>
</td>
<td width="50%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
<p><small>XPointer value;</small></p>
</td>
<td width="50%">
<p><small>/* Value to provide if XrmoptionNoArg
or</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="40%">
</td>
<td width="50%">
<p><small>XrmoptionSkipNArgs */</small></p>
</td>
</table>
<p><small>} XrmOptionDescRec,
*XrmOptionDescList;</small></p>
<p><small>│__</small></p>
<p><small>To load a resource database from a C command
line, use <i>XrmParseCommand</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XrmParseCommand(<i>database</i>, <i>table</i>, <i>table_count</i>, <i>name</i>, <i>argc_in_out</i>, <i>argv_in_out</i>)
XrmDatabase *<i>database</i>;
XrmOptionDescList <i>table</i>;
int <i>table_count</i>;
char *<i>name</i>;
int *<i>argc_in_out</i>;
char **<i>argv_in_out</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>database</i></small></p>
</td>
<td width="4%"></td>
<td width="64%">
<p><small>Specifies the resource database.</small></p>
</td>
<td width="15%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>table</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the table of command line arguments to
be parsed.</small></p>
</td>
</table>
<p><small><i>table_count</i> Specifies the number of
entries in the table.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>name</i></small></p>
</td>
<td width="12%"></td>
<td width="62%">
<p><small>Specifies the application name.</small></p>
</td>
<td width="17%">
</td>
</table>
<p><small><i>argc_in_out</i> Specifies the number of
arguments and returns the number of remaining
arguments.</small></p>
<p><small><i>argv_in_out</i> Specifies the command line
arguments and returns the remaining arguments.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XrmParseCommand</i> function parses an
(argc, argv) pair according to the specified option table,
loads recognized options into the specified database with
type ‘‘String,’’ and modifies the
(argc, argv) pair to remove all recognized options. If
database contains NULL, <i>XrmParseCommand</i> creates a new
database and returns a pointer to it. Otherwise, entries are
added to the database specified. If a database is created,
it is created in the current locale.</small></p>
<p><small>The specified table is used to parse the command
line. Recognized options in the table are removed from argv,
and entries are added to the specified resource database in
the order they occur in argv. The table entries contain
information on the option string, the option name, the style
of option, and a value to provide if the option kind is
<i>XrmoptionNoArg</i>. The option names are compared
byte-for-byte to arguments in argv, independent of any
locale. The resource values given in the table are stored in
the resource database without modification. All resource
database entries are created using a
‘‘String’’ representation type. The
argc argument specifies the number of arguments in argv and
is set on return to the remaining number of arguments that
were not parsed. The name argument should be the name of
your application for use in building the database entry. The
name argument is prefixed to the resourceName in the option
table before storing a database entry. The name argument is
treated as a single component, even if it has embedded
periods. No separating (binding) character is inserted, so
the table must contain either a period (.) or an asterisk
(*) as the first character in each resourceName entry. To
specify a more completely qualified resource name, the
resourceName entry can contain multiple components. If the
name argument and the resourceNames are not in the Host
Portable Character Encoding, the result is
implementation-dependent.</small></p>
<p><small>The following provides a sample option
table:</small></p>
<pre><small>static XrmOptionDescRec opTable[] = {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="24%">
<p><small>{"−background",</small></p>
</td>
<td width="40%"></td>
<td width="30%">
<p><small>"*background",</small></p>
</td>
<td width="6%">
<p><small>XrmoptionSepArg,(XPointer) NULL},</small></p>
</td>
<tr valign="top" align="left">
<td width="24%">
<p><small>{"−bd",</small></p>
</td>
<td width="40%">
<p><small>"*borderColor",</small></p>
</td>
<td width="30%">
<p><small>XrmoptionSepArg,(XPointer) NULL},</small></p>
</td>
<td width="6%">
</td>
<tr valign="top" align="left">
<td width="24%">
<p><small>{"−bg",</small></p>
</td>
<td width="40%">
<p><small>"*background",</small></p>
</td>
<td width="30%">
<p><small>XrmoptionSepArg,(XPointer) NULL},</small></p>
</td>
<td width="6%">
</td>
<tr valign="top" align="left">
<td width="24%">
<p><small>{"−borderwidth",</small></p>
</td>
<td width="40%"></td>
<td width="30%">
<p><small>"*TopLevelShell.borderWidth",XrmoptionSepArg,(XPointer)
NULL},</small></p>
</td>
<td width="6%">
</td>
<tr valign="top" align="left">
<td width="24%">
<p><small>{"−bordercolor",</small></p>
</td>
<td width="40%"></td>
<td width="30%">
<p><small>"*borderColor",XrmoptionSepArg,(XPointer)
NULL},</small></p>
</td>
<td width="6%">
</td>
<tr valign="top" align="left">
<td width="24%">
<p><small>{"−bw",</small></p>
</td>
<td width="40%">
<p><small>"*TopLevelShell.borderWidth",</small></p>
</td>
<td width="30%"></td>
<td width="6%">
<p><small>XrmoptionSepArg,(XPointer) NULL},</small></p>
</td>
<tr valign="top" align="left">
<td width="24%">
<p><small>{"−display",</small></p>
</td>
<td width="40%"></td>
<td width="30%">
<p><small>".display",</small></p>
</td>
<td width="6%">
<p><small>XrmoptionSepArg,(XPointer) NULL},</small></p>
</td>
<tr valign="top" align="left">
<td width="24%">
<p><small>{"−fg",</small></p>
</td>
<td width="40%">
<p><small>"*foreground",</small></p>
</td>
<td width="30%">
<p><small>XrmoptionSepArg,(XPointer) NULL},</small></p>
</td>
<td width="6%">
</td>
<tr valign="top" align="left">
<td width="24%">
<p><small>{"−fn",</small></p>
</td>
<td width="40%">
<p><small>"*font",</small></p>
</td>
<td width="30%">
<p><small>XrmoptionSepArg,(XPointer) NULL},</small></p>
</td>
<td width="6%">
</td>
<tr valign="top" align="left">
<td width="24%">
<p><small>{"−font",</small></p>
</td>
<td width="40%">
<p><small>"*font",</small></p>
</td>
<td width="30%">
<p><small>XrmoptionSepArg,(XPointer) NULL},</small></p>
</td>
<td width="6%">
</td>
<tr valign="top" align="left">
<td width="24%">
<p><small>{"−foreground",</small></p>
</td>
<td width="40%"></td>
<td width="30%">
<p><small>"*foreground",</small></p>
</td>
<td width="6%">
<p><small>XrmoptionSepArg,(XPointer) NULL},</small></p>
</td>
<tr valign="top" align="left">
<td width="24%">
<p><small>{"−geometry",</small></p>
</td>
<td width="40%"></td>
<td width="30%">
<p><small>".TopLevelShell.geometry",XrmoptionSepArg,(XPointer)
NULL},</small></p>
</td>
<td width="6%">
</td>
<tr valign="top" align="left">
<td width="24%">
<p><small>{"−iconic",</small></p>
</td>
<td width="40%">
<p><small>".TopLevelShell.iconic",</small></p>
</td>
<td width="30%"></td>
<td width="6%">
<p><small>XrmoptionNoArg,(XPointer)
"on"},</small></p>
</td>
<tr valign="top" align="left">
<td width="24%">
<p><small>{"−name",</small></p>
</td>
<td width="40%">
<p><small>".name",</small></p>
</td>
<td width="30%">
<p><small>XrmoptionSepArg,(XPointer) NULL},</small></p>
</td>
<td width="6%">
</td>
<tr valign="top" align="left">
<td width="24%">
<p><small>{"−reverse",</small></p>
</td>
<td width="40%"></td>
<td width="30%">
<p><small>"*reverseVideo",XrmoptionNoArg,(XPointer)
"on"},</small></p>
</td>
<td width="6%">
</td>
<tr valign="top" align="left">
<td width="24%">
<p><small>{"−rv",</small></p>
</td>
<td width="40%">
<p><small>"*reverseVideo",</small></p>
</td>
<td width="30%">
<p><small>XrmoptionNoArg,(XPointer)
"on"},</small></p>
</td>
<td width="6%">
</td>
<tr valign="top" align="left">
<td width="24%">
<p><small>{"−synchronous",</small></p>
</td>
<td width="40%"></td>
<td width="30%">
<p><small>"*synchronous",XrmoptionNoArg,(XPointer)
"on"},</small></p>
</td>
<td width="6%">
</td>
<tr valign="top" align="left">
<td width="24%">
<p><small>{"−title",</small></p>
</td>
<td width="40%">
<p><small>".TopLevelShell.title",</small></p>
</td>
<td width="30%"></td>
<td width="6%">
<p><small>XrmoptionSepArg,(XPointer) NULL},</small></p>
</td>
<tr valign="top" align="left">
<td width="24%">
<p><small>{"−xrm",</small></p>
</td>
<td width="40%">
<p><small>NULL,</small></p>
</td>
<td width="30%">
<p><small>XrmoptionResArg,(XPointer) NULL},</small></p>
</td>
<td width="6%">
</td>
</table>
<p><small>};</small></p>
<p><small>In this table, if the −background (or
−bg) option is used to set background colors, the
stored resource specifier matches all resources of attribute
background. If the −borderwidth option is used, the
stored resource specifier applies only to border width
attributes of class TopLevelShell (that is, outer-most
windows, including pop-up windows). If the −title
option is used to set a window name, only the topmost
application windows receive the resource.</small></p>
<p><small>When parsing the command line, any unique
unambiguous abbreviation for an option name in the table is
considered a match for the option. Note that uppercase and
lowercase matter.</small></p>
<p><small><b>15</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b>Chapter 16</b></p>
<p align=center><b>Application Utility Functions</b></p>
<p><small>Once you have initialized the X system, you can
use the Xlib utility functions to:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="60%">
<p><small>Use keyboard utility functions</small></p>
</td>
<td width="29%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="72%">
<p><small>Use Latin-1 keyboard event functions</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="52%">
<p><small>Allocate permanent storage</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="50%">
<p><small>Parse the window geometry</small></p>
</td>
<td width="39%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="36%">
<p><small>Manipulate regions</small></p>
</td>
<td width="53%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="30%">
<p><small>Use cut buffers</small></p>
</td>
<td width="59%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="74%">
<p><small>Determine the appropriate visual type</small></p>
</td>
<td width="15%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="34%">
<p><small>Manipulate images</small></p>
</td>
<td width="55%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="36%">
<p><small>Manipulate bitmaps</small></p>
</td>
<td width="53%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="46%">
<p><small>Use the context manager</small></p>
</td>
<td width="43%">
</td>
</table>
<p><small>As a group, the functions discussed in this
chapter provide the functionality that is frequently needed
and that spans toolkits. Many of these functions do not
generate actual protocol requests to the server.</small></p>
<a name="16.1. Using Keyboard Utility Functions"></a>
<h2>16.1. Using Keyboard Utility Functions</h2>
<p><small>This section discusses mapping between KeyCodes
and KeySyms, classifying KeySyms, and mapping between
KeySyms and string names. The first three functions in this
section operate on a cached copy of the server keyboard
mapping. The first four KeySyms for each KeyCode are
modified according to the rules given in section 12.7. To
obtain the untransformed KeySyms defined for a key, use the
functions described in section 12.7.</small></p>
<p><small>To obtain a KeySym for the KeyCode of an event,
use <i>XLookupKeysym</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>KeySym XLookupKeysym(<i>key_event</i>, <i>index</i>)
XKeyEvent *<i>key_event</i>;
int <i>index</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>key_event</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the <i>KeyPress</i> or
<i>KeyRelease</i> event.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>index</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the index into the KeySyms list for the
event’s KeyCode.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XLookupKeysym</i> function uses a given
keyboard event and the index you specified to return the
KeySym from the list that corresponds to the KeyCode member
in the <i>XKeyPressedEvent</i> or <i>XKeyReleasedEvent</i>
structure. If no KeySym is defined for the KeyCode of the
event, <i>XLookupKeysym</i> returns
<i>NoSymbol</i>.</small></p>
<p><small>To obtain a KeySym for a specific KeyCode, use
<i>XKeycodeToKeysym</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>KeySym XKeycodeToKeysym(<i>display</i>, <i>keycode</i>, <i>index</i>)
Display *<i>display</i>;
KeyCode <i>keycode</i>;
int <i>index</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>keycode</i></small></p>
</td>
<td width="6%"></td>
<td width="44%">
<p><small>Specifies the KeyCode.</small></p>
</td>
<td width="35%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>index</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the element of KeyCode
vector.</small></p>
</td>
<td width="0%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XKeycodeToKeysym</i> function uses
internal Xlib tables and returns the KeySym defined for the
specified KeyCode and the element of the KeyCode vector. If
no symbol is defined, <i>XKeycodeToKeysym</i> returns
<i>NoSymbol</i>.</small></p>
<p><small>To obtain a KeyCode for a key having a specific
KeySym, use <i>XKeysymToKeycode</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>KeyCode XKeysymToKeycode(<i>display</i>, <i>keysym</i>)
Display *<i>display</i>;
KeySym <i>keysym</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>keysym</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the KeySym that is to be searched
for.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>If the specified KeySym is not defined for any
KeyCode, <i>XKeysymToKeycode</i> returns zero.</small></p>
<p><small>The mapping between KeyCodes and KeySyms is
cached internal to Xlib. When this information is changed at
the server, an Xlib function must be called to refresh the
cache. To refresh the stored modifier and keymap
information, use <i>XRefreshKeyboardMapping</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XRefreshKeyboardMapping(<i>event_map</i>)
XMappingEvent *<i>event_map</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>event_map</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the mapping event that is to be
used.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XRefreshKeyboardMapping</i> function
refreshes the stored modifier and keymap information. You
usually call this function when a <i>MappingNotify</i> event
with a request member of <i>MappingKeyboard</i> or
<i>MappingModifier</i> occurs. The result is to update
Xlib’s knowledge of the keyboard.</small></p>
<p><small>To obtain the uppercase and lowercase forms of a
KeySym, use <i>XConvertCase</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>void XConvertCase(<i>keysym</i>, <i>lower_return</i>, <i>upper_return</i>)
KeySym <i>keysym</i>;
KeySym *<i>lower_return</i>;
KeySym *<i>upper_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>keysym</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the KeySym that is to be
converted.</small></p>
</td>
</table>
<p><small><i>lower_return</i> Returns the lowercase form of
keysym, or keysym.</small></p>
<p><small><i>upper_return</i> Returns the uppercase form of
keysym, or keysym.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XConvertCase</i> function returns the
uppercase and lowercase forms of the specified Keysym, if
the KeySym is subject to case conversion; otherwise, the
specified KeySym is returned to both lower_return and
upper_return. Support for conversion of other than Latin and
Cyrillic KeySyms is implementation-dependent.</small></p>
<p><small>KeySyms have string names as well as numeric
codes. To convert the name of the KeySym to the KeySym code,
use <i>XStringToKeysym</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>KeySym XStringToKeysym(<i>string</i>)
char *<i>string</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the name of the KeySym that is to be
converted.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Standard KeySym names are obtained from
<<i>X11/keysymdef.h</i>> by removing the XK_ prefix
from each name. KeySyms that are not part of the Xlib
standard also may be obtained with this function. The set of
KeySyms that are available in this manner and the mechanisms
by which Xlib obtains them is
implementation-dependent.</small></p>
<p><small>If the KeySym name is not in the Host Portable
Character Encoding, the result is implementation-dependent.
If the specified string does not match a valid KeySym,
<i>XStringToKeysym</i> returns <i>NoSymbol</i>.</small></p>
<p><small>To convert a KeySym code to the name of the
KeySym, use <i>XKeysymToString</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char *XKeysymToString(<i>keysym</i>)
KeySym <i>keysym</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>keysym</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the KeySym that is to be
converted.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The returned string is in a static area and must
not be modified. The returned string is in the Host Portable
Character Encoding. If the specified KeySym is not defined,
<i>XKeysymToString</i> returns a NULL.</small></p>
<a name="16.1.1. KeySym Classification Macros"></a>
<h2>16.1.1. KeySym Classification Macros</h2>
<p><small>You may want to test if a KeySym is, for example,
on the keypad or on one of the function keys. You can use
KeySym macros to perform the following tests.</small></p>
<p><small>__ │</small></p>
<pre><small>IsCursorKey(<i>keysym</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>keysym</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the KeySym that is to be
tested.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Returns <i>True</i> if the specified KeySym is a
cursor key.</small></p>
<p><small>__ │</small></p>
<pre><small>IsFunctionKey(<i>keysym</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>keysym</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the KeySym that is to be
tested.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Returns <i>True</i> if the specified KeySym is a
function key.</small></p>
<p><small>__ │</small></p>
<pre><small>IsKeypadKey(<i>keysym</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>keysym</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the KeySym that is to be
tested.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Returns <i>True</i> if the specified KeySym is a
standard keypad key.</small></p>
<p><small>__ │</small></p>
<pre><small>IsPrivateKeypadKey(<i>keysym</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>keysym</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the KeySym that is to be
tested.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Returns <i>True</i> if the specified KeySym is a
vendor-private keypad key.</small></p>
<p><small>__ │</small></p>
<pre><small>IsMiscFunctionKey(<i>keysym</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>keysym</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the KeySym that is to be
tested.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Returns <i>True</i> if the specified KeySym is a
miscellaneous function key.</small></p>
<p><small>__ │</small></p>
<pre><small>IsModifierKey(<i>keysym</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>keysym</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the KeySym that is to be
tested.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Returns <i>True</i> if the specified KeySym is a
modifier key.</small></p>
<p><small>__ │</small></p>
<pre><small>IsPFKey(<i>keysym</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>keysym</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the KeySym that is to be
tested.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Returns <i>True</i> if the specified KeySym is a
PF key.</small></p>
<a name="16.2. Using Latin-1 Keyboard Event Functions"></a>
<h2>16.2. Using Latin-1 Keyboard Event Functions</h2>
<p><small>Chapter 13 describes internationalized text input
facilities, but sometimes it is expedient to write an
application that only deals with Latin-1 characters and
ASCII controls, so Xlib provides a simple function for that
purpose. <i>XLookupString</i> handles the standard modifier
semantics described in section 12.7. This function does not
use any of the input method facilities described in chapter
13 and does not depend on the current locale.</small></p>
<p><small>To map a key event to an ISO Latin-1 string, use
<i>XLookupString</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XLookupString(<i>event_struct</i>, <i>buffer_return</i>, <i>bytes_buffer</i>, <i>keysym_return</i>, <i>status_in_out</i>)
XKeyEvent *<i>event_struct</i>;
char *<i>buffer_return</i>;
int <i>bytes_buffer</i>;
KeySym *<i>keysym_return</i>;
XComposeStatus *<i>status_in_out</i>;
</small></pre>
<p><small><i>event_struct</i> Specifies the key event
structure to be used. You can pass <i>XKeyPressedEvent</i>
or <i>XKeyReleasedEvent</i>.</small></p>
<p><small><i>buffer_return</i> Returns the translated
characters.</small></p>
<p><small><i>bytes_buffer</i> Specifies the length of the
buffer. No more than bytes_buffer of translation are
returned.</small></p>
<p><small><i>keysym_return</i> Returns the KeySym computed
from the event if this argument is not NULL.</small></p>
<p><small><i>status_in_out</i> Specifies or returns the
<i>XComposeStatus</i> structure or NULL.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XLookupString</i> function translates a
key event to a KeySym and a string. The KeySym is obtained
by using the standard interpretation of the <i>Shift</i>,
<i>Lock</i>, group, and numlock modifiers as defined in the
X Protocol specification. If the KeySym has been rebound
(see <i>XRebindKeysym</i>), the bound string will be stored
in the buffer. Otherwise, the KeySym is mapped, if possible,
to an ISO Latin-1 character or (if the Control modifier is
on) to an ASCII control character, and that character is
stored in the buffer. <i>XLookupString</i> returns the
number of characters that are stored in the
buffer.</small></p>
<p><small>If present (non-NULL), the <i>XComposeStatus</i>
structure records the state, which is private to Xlib, that
needs preservation across calls to <i>XLookupString</i> to
implement compose processing. The creation of
<i>XComposeStatus</i> structures is
implementation-dependent; a portable program must pass NULL
for this argument.</small></p>
<p><small><i>XLookupString</i> depends on the cached
keyboard information mentioned in the previous section, so
it is necessary to use <i>XRefreshKeyboardMapping</i> to
keep this information up-to-date.</small></p>
<p><small>To rebind the meaning of a KeySym for
<i>XLookupString</i>, use <i>XRebindKeysym</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XRebindKeysym(<i>display</i>, <i>keysym</i>, <i>list</i>, <i>mod_count</i>, <i>string</i>, <i>num_bytes</i>)
Display *<i>display</i>;
KeySym <i>keysym</i>;
KeySym <i>list</i>[];
int <i>mod_count</i>;
unsigned char *<i>string</i>;
int <i>num_bytes</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>keysym</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the KeySym that is to be
rebound.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>list</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the KeySyms to be used as
modifiers.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>mod_count</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the number of modifiers in the modifier
list.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>string</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the string that is copied and will be
returned by <i>XLookupString</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>num_bytes</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the number of bytes in the string
argument.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XRebindKeysym</i> function can be used to
rebind the meaning of a KeySym for the client. It does not
redefine any key in the X server but merely provides an easy
way for long strings to be attached to keys.
<i>XLookupString</i> returns this string when the
appropriate set of modifier keys are pressed and when the
KeySym would have been used for the translation. No text
conversions are performed; the client is responsible for
supplying appropriately encoded strings. Note that you can
rebind a KeySym that may not exist.</small></p>
<a name="16.3. Allocating Permanent Storage"></a>
<h2>16.3. Allocating Permanent Storage</h2>
<p><small>To allocate some memory you will never give back,
use <i>Xpermalloc</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char *Xpermalloc(<i>size</i>)
unsigned int <i>size</i>;
</small></pre>
<p><small>│__</small></p>
<p><small>The <i>Xpermalloc</i> function allocates storage
that can never be freed for the life of the program. The
memory is allocated with alignment for the C type double.
This function may provide some performance and space savings
over the standard operating system memory
allocator.</small></p>
<a name="16.4. Parsing the Window Geometry"></a>
<h2>16.4. Parsing the Window Geometry</h2>
<p><small>To parse standard window geometry strings, use
<i>XParseGeometry</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XParseGeometry(<i>parsestring</i>, <i>x_return</i>, <i>y_return</i>, <i>width_return</i>, <i>height_return</i>)
char *<i>parsestring</i>;
int *<i>x_return</i>, *<i>y_return</i>;
unsigned int *<i>width_return</i>, *<i>height_return</i>;
</small></pre>
<p><small><i>parsestring</i> Specifies the string you want
to parse.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>x_return</i></small></p>
</td>
<td width="83%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>y_return</i></small></p>
</td>
<td width="4%"></td>
<td width="54%">
<p><small>Return the x and y offsets.</small></p>
</td>
<td width="25%">
</td>
</table>
<p><small><i>width_return</i></small></p>
<p><small><i>height_return</i> Return the width and height
determined.</small></p>
<p><small>│__</small></p>
<p><small>By convention, X applications use a standard
string to indicate window size and placement.
<i>XParseGeometry</i> makes it easier to conform to this
standard because it allows you to parse the standard window
geometry. Specifically, this function lets you parse strings
of the form:</small></p>
<pre><small> [=][<<i>width</i>>{xX}<<i>height</i>>][{+-}<<i>xoffset</i>>{+-}<<i>yoffset</i>>]
</small></pre>
<p><small>The fields map into the arguments associated with
this function. (Items enclosed in <> are integers,
items in [] are optional, and items enclosed in {} indicate
‘‘choose one of.’’ Note that the
brackets should not appear in the actual string.) If the
string is not in the Host Portable Character Encoding, the
result is implementation-dependent.</small></p>
<p><small>The <i>XParseGeometry</i> function returns a
bitmask that indicates which of the four values (width,
height, xoffset, and yoffset) were actually found in the
string and whether the x and y values are negative. By
convention, −0 is not equal to +0, because the user
needs to be able to say ‘‘position the window
relative to the right or bottom edge.’’ For each
value found, the corresponding argument is updated. For each
value not found, the argument is left unchanged. The bits
are represented by <i>XValue</i>, <i>YValue</i>,
<i>WidthValue</i>, <i>HeightValue</i>, <i>XNegative</i>, or
<i>YNegative</i> and are defined in
<<i>X11/Xutil.h</i>>. They will be set whenever one of
the values is defined or one of the signs is
set.</small></p>
<p><small>If the function returns either the <i>XValue</i>
or <i>YValue</i> flag, you should place the window at the
requested position.</small></p>
<p><small>To construct a window’s geometry
information, use <i>XWMGeometry</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XWMGeometry(<i>display</i>, <i>screen</i>, <i>user_geom</i>, <i>def_geom</i>, <i>bwidth</i>, <i>hints</i>, <i>x_return</i>, <i>y_return</i>,
<i> width_return</i>, <i>height_return</i>, <i>gravity_return</i>)
Display *<i>display</i>;
int <i>screen</i>;
char *<i>user_geom</i>;
char *<i>def_geom</i>;
unsigned int <i>bwidth</i>;
XSizeHints *<i>hints</i>;
int *<i>x_return</i>, *<i>y_return</i>;
int *<i>width_return</i>;
int *<i>height_return</i>;
int *<i>gravity_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>Specifies the screen.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>user_geom</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the user-specified geometry or
NULL.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>def_geom</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the application’s default
geometry or NULL.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>bwidth</i></small></p>
</td>
<td width="8%"></td>
<td width="54%">
<p><small>Specifies the border width.</small></p>
</td>
<td width="25%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>hints</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the size hints for the window in its
normal state.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>x_return</i></small></p>
</td>
<td width="83%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>y_return</i></small></p>
</td>
<td width="4%"></td>
<td width="54%">
<p><small>Return the x and y offsets.</small></p>
</td>
<td width="25%">
</td>
</table>
<p><small><i>width_return</i></small></p>
<p><small><i>height_return</i> Return the width and height
determined.</small></p>
<p><small><i>gravity_return</i> Returns the window
gravity.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XWMGeometry</i> function combines any
geometry information (given in the format used by
<i>XParseGeometry</i>) specified by the user and by the
calling program with size hints (usually the ones to be
stored in WM_NORMAL_HINTS) and returns the position, size,
and gravity (<i>NorthWestGravity</i>,
<i>NorthEastGravity</i>, <i>SouthEastGravity</i>, or
<i>SouthWestGravity</i>) that describe the window. If the
base size is not set in the <i>XSizeHints</i> structure, the
minimum size is used if set. Otherwise, a base size of zero
is assumed. If no minimum size is set in the hints
structure, the base size is used. A mask (in the form
returned by <i>XParseGeometry</i>) that describes which
values came from the user specification and whether or not
the position coordinates are relative to the right and
bottom edges is returned. Note that these coordinates will
have already been accounted for in the x_return and y_return
values.</small></p>
<p><small>Note that invalid geometry specifications can
cause a width or height of zero to be returned. The caller
may pass the address of the hints win_gravity field as
gravity_return to update the hints directly.</small></p>
<a name="16.5. Manipulating Regions"></a>
<h2>16.5. Manipulating Regions</h2>
<p><small>Regions are arbitrary sets of pixel locations.
Xlib provides functions for manipulating regions. The opaque
type <i>Region</i> is defined in <<i>X11/Xutil.h</i>>.
Xlib provides functions that you can use to manipulate
regions. This section discusses how to:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="64%">
<p><small>Create, copy, or destroy regions</small></p>
</td>
<td width="25%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="44%">
<p><small>Move or shrink regions</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="40%">
<p><small>Compute with regions</small></p>
</td>
<td width="49%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="78%">
<p><small>Determine if regions are empty or
equal</small></p>
</td>
<td width="11%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="78%">
<p><small>Locate a point or rectangle in a
region</small></p>
</td>
<td width="11%">
</td>
</table>
<a name="16.5.1. Creating, Copying, or Destroying Regions"></a>
<h2>16.5.1. Creating, Copying, or Destroying Regions</h2>
<p><small>To create a new empty region, use
<i>XCreateRegion</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Region XCreateRegion()
</small></pre>
<p><small>│__</small></p>
<p><small>To generate a region from a polygon, use
<i>XPolygonRegion</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Region XPolygonRegion(<i>points</i>, <i>n</i>, <i>fill_rule</i>)
XPoint <i>points[]</i>;
int <i>n</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<p><small>int <i>fill_rule</i>;</small></p>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>points</i></small></p>
</td>
<td width="8%"></td>
<td width="58%">
<p><small>Specifies an array of points.</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>n</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the number of points in the
polygon.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>fill_rule</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the fill-rule you want to set for the
specified GC. You can pass <i>EvenOddRule</i> or
<i>WindingRule</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XPolygonRegion</i> function returns a
region for the polygon defined by the points array. For an
explanation of fill_rule, see <i>XCreateGC</i>.</small></p>
<p><small>To set the clip-mask of a GC to a region, use
<i>XSetRegion</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetRegion(<i>display</i>, <i>gc</i>, <i>r</i>)
Display *<i>display</i>;
GC <i>gc</i>;
Region <i>r</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>r</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the region.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetRegion</i> function sets the clip-mask
in the GC to the specified region. The region is specified
relative to the drawable’s origin. The resulting GC
clip origin is implementation-dependent. Once it is set in
the GC, the region can be destroyed.</small></p>
<p><small>To deallocate the storage associated with a
specified region, use <i>XDestroyRegion</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XDestroyRegion(<i>r</i>)
Region <i>r</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>r</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the region.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<a name="16.5.2. Moving or Shrinking Regions"></a>
<h2>16.5.2. Moving or Shrinking Regions</h2>
<p><small>To move a region by a specified amount, use
<i>XOffsetRegion</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XOffsetRegion(<i>r</i>, <i>dx</i>, <i>dy</i>)
Region <i>r</i>;
int <i>dx</i>, <i>dy</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>r</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the region.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>dx</i></small></p>
</td>
<td width="95%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>dy</i></small></p>
</td>
<td width="16%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which define the
amount you want to move the specified region.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>To reduce a region by a specified amount, use
<i>XShrinkRegion</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>XShrinkRegion(<i>r</i>, <i>dx</i>, <i>dy</i>)
Region <i>r</i>;
int <i>dx</i>, <i>dy</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>r</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the region.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>dx</i></small></p>
</td>
<td width="95%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>dy</i></small></p>
</td>
<td width="16%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which define the
amount you want to shrink the specified region.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Positive values shrink the size of the region,
and negative values expand the region.</small></p>
<a name="16.5.3. Computing with Regions"></a>
<h2>16.5.3. Computing with Regions</h2>
<p><small>To generate the smallest rectangle enclosing a
region, use <i>XClipBox</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XClipBox(<i>r</i>, <i>rect_return</i>)
Region <i>r</i>;
XRectangle *<i>rect_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>r</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the region.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>rect_return</i> Returns the smallest enclosing
rectangle.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XClipBox</i> function returns the smallest
rectangle enclosing the specified region.</small></p>
<p><small>To compute the intersection of two regions, use
<i>XIntersectRegion</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XIntersectRegion(<i>sra</i>, <i>srb</i>, <i>dr_return</i>)
Region <i>sra</i>, <i>srb</i>, <i>dr_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>sra</i></small></p>
</td>
<td width="93%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>srb</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specify the two regions with which you want to
perform the computation.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>dr_return</i></small></p>
</td>
<td width="2%"></td>
<td width="76%">
<p><small>Returns the result of the
computation.</small></p>
</td>
<td width="3%">
</td>
</table>
<p><small>│__</small></p>
<p><small>To compute the union of two regions, use
<i>XUnionRegion</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>XUnionRegion(<i>sra</i>, <i>srb</i>, <i>dr_return</i>)
Region <i>sra</i>, <i>srb</i>, <i>dr_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>sra</i></small></p>
</td>
<td width="93%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>srb</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specify the two regions with which you want to
perform the computation.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>dr_return</i></small></p>
</td>
<td width="2%"></td>
<td width="76%">
<p><small>Returns the result of the
computation.</small></p>
</td>
<td width="3%">
</td>
</table>
<p><small>│__</small></p>
<p><small>To create a union of a source region and a
rectangle, use <i>XUnionRectWithRegion</i>.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>XUnionRectWithRegion(<i>rectangle</i>, <i>src_region</i>, <i>dest_region_return</i>)
XRectangle *<i>rectangle</i>;
Region <i>src_region</i>;
Region <i>dest_region_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>rectangle</i></small></p>
</td>
<td width="2%"></td>
<td width="48%">
<p><small>Specifies the rectangle.</small></p>
</td>
<td width="31%">
</td>
</table>
<p><small><i>src_region</i> Specifies the source region to
be used.</small></p>
<p><small><i>dest_region_return</i> Returns the destination
region.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XUnionRectWithRegion</i> function updates
the destination region from a union of the specified
rectangle and the specified source region.</small></p>
<p><small>To subtract two regions, use
<i>XSubtractRegion</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSubtractRegion(<i>sra</i>, <i>srb</i>, <i>dr_return</i>)
Region <i>sra</i>, <i>srb</i>, <i>dr_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>sra</i></small></p>
</td>
<td width="93%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>srb</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specify the two regions with which you want to
perform the computation.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>dr_return</i></small></p>
</td>
<td width="2%"></td>
<td width="76%">
<p><small>Returns the result of the
computation.</small></p>
</td>
<td width="3%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSubtractRegion</i> function subtracts srb
from sra and stores the results in dr_return.</small></p>
<p><small>To calculate the difference between the union and
intersection of two regions, use
<i>XXorRegion</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XXorRegion(<i>sra</i>, <i>srb</i>, <i>dr_return</i>)
Region <i>sra</i>, <i>srb</i>, <i>dr_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>sra</i></small></p>
</td>
<td width="93%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>srb</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specify the two regions with which you want to
perform the computation.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>dr_return</i></small></p>
</td>
<td width="2%"></td>
<td width="76%">
<p><small>Returns the result of the
computation.</small></p>
</td>
<td width="3%">
</td>
</table>
<p><small>│__</small></p>
<a name="16.5.4. Determining if Regions Are Empty or Equal"></a>
<h2>16.5.4. Determining if Regions Are Empty or Equal</h2>
<p><small>To determine if the specified region is empty,
use <i>XEmptyRegion</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XEmptyRegion(<i>r</i>)
Region <i>r</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>r</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the region.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XEmptyRegion</i> function returns
<i>True</i> if the region is empty.</small></p>
<p><small>To determine if two regions have the same offset,
size, and shape, use <i>XEqualRegion</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XEqualRegion(<i>r1</i>, <i>r2</i>)
Region <i>r1</i>, <i>r2</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>r1</i></small></p>
</td>
<td width="95%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>r2</i></small></p>
</td>
<td width="16%"></td>
<td width="48%">
<p><small>Specify the two regions.</small></p>
</td>
<td width="31%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XEqualRegion</i> function returns
<i>True</i> if the two regions have the same offset, size,
and shape.</small></p>
<a name="16.5.5. Locating a Point or a Rectangle in a Region"></a>
<h2>16.5.5. Locating a Point or a Rectangle in a Region</h2>
<p><small>To determine if a specified point resides in a
specified region, use <i>XPointInRegion</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XPointInRegion(<i>r</i>, <i>x</i>, <i>y</i>)
Region <i>r</i>;
int <i>x</i>, <i>y</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>r</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the region.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which define the
point.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XPointInRegion</i> function returns
<i>True</i> if the point (x, y) is contained in the region
r.</small></p>
<p><small>To determine if a specified rectangle is inside a
region, use <i>XRectInRegion</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XRectInRegion(<i>r</i>, <i>x</i>, <i>y</i>, <i>width</i>, <i>height</i>)
Region <i>r</i>;
int <i>x</i>, <i>y</i>;
unsigned int <i>width</i>, <i>height</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>r</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the region.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specify the x and y coordinates, which define the
coordinates of the upper-left corner of the
rectangle.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the width and height, which define the
rectangle.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XRectInRegion</i> function returns
<i>RectangleIn</i> if the rectangle is entirely in the
specified region, <i>RectangleOut</i> if the rectangle is
entirely out of the specified region, and
<i>RectanglePart</i> if the rectangle is partially in the
specified region.</small></p>
<a name="16.6. Using Cut Buffers"></a>
<h2>16.6. Using Cut Buffers</h2>
<p><small>Xlib provides functions to manipulate cut
buffers, a very simple form of cut-and-paste inter-client
communication. Selections are a much more powerful and
useful mechanism for interchanging data between clients (see
section 4.5) and generally should be used instead of cut
buffers.</small></p>
<p><small>Cut buffers are implemented as properties on the
first root window of the display. The buffers can only
contain text, in the STRING encoding. The text encoding is
not changed by Xlib when fetching or storing. Eight buffers
are provided and can be accessed as a ring or as explicit
buffers (numbered 0 through 7).</small></p>
<p><small>To store data in cut buffer 0, use
<i>XStoreBytes</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XStoreBytes(<i>display</i>, <i>bytes</i>, <i>nbytes</i>)
Display *<i>display</i>;
char *<i>bytes</i>;
int <i>nbytes</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>bytes</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the bytes, which are not necessarily
ASCII or null-terminated.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>nbytes</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the number of bytes to be
stored.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The data can have embedded null characters and
need not be null-terminated. The cut buffer’s contents
can be retrieved later by any client calling
<i>XFetchBytes</i>.</small></p>
<p><small><i>XStoreBytes</i> can generate a <i>BadAlloc</i>
error.</small></p>
<p><small>To store data in a specified cut buffer, use
<i>XStoreBuffer</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XStoreBuffer(<i>display</i>, <i>bytes</i>, <i>nbytes</i>, <i>buffer</i>)
Display *<i>display</i>;
char *<i>bytes</i>;
int <i>nbytes</i>;
int <i>buffer</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>bytes</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the bytes, which are not necessarily
ASCII or null-terminated.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>nbytes</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the number of bytes to be
stored.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>buffer</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the buffer in which you want to store
the bytes.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>If an invalid buffer is specified, the call has
no effect. The data can have embedded null characters and
need not be null-terminated.</small></p>
<p><small><i>XStoreBuffer</i> can generate a
<i>BadAlloc</i> error.</small></p>
<p><small>To return data from cut buffer 0, use
<i>XFetchBytes</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char *XFetchBytes(<i>display</i>, <i>nbytes_return</i>)
Display *<i>display</i>;
int *<i>nbytes_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>nbytes_return</i> Returns the number of bytes
in the buffer.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XFetchBytes</i> function returns the
number of bytes in the nbytes_return argument, if the buffer
contains data. Otherwise, the function returns NULL and sets
nbytes to 0. The appropriate amount of storage is allocated
and the pointer returned. The client must free this storage
when finished with it by calling <i>XFree</i>.</small></p>
<p><small>To return data from a specified cut buffer, use
<i>XFetchBuffer</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char *XFetchBuffer(<i>display</i>, <i>nbytes_return</i>, <i>buffer</i>)
Display *<i>display</i>;
int *<i>nbytes_return</i>;
int <i>buffer</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>nbytes_return</i> Returns the number of bytes
in the buffer.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>buffer</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the buffer from which you want the
stored data returned.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XFetchBuffer</i> function returns zero to
the nbytes_return argument if there is no data in the buffer
or if an invalid buffer is specified.</small></p>
<p><small>To rotate the cut buffers, use
<i>XRotateBuffers</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XRotateBuffers(<i>display</i>, <i>rotate</i>)
Display *<i>display</i>;
int <i>rotate</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>rotate</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies how much to rotate the cut
buffers.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XRotateBuffers</i> function rotates the
cut buffers, such that buffer 0 becomes buffer n, buffer 1
becomes n + 1 mod 8, and so on. This cut buffer numbering is
global to the display. Note that <i>XRotateBuffers</i>
generates <i>BadMatch</i> errors if any of the eight buffers
have not been created.</small></p>
<a name="16.7. Determining the Appropriate Visual Type"></a>
<h2>16.7. Determining the Appropriate Visual Type</h2>
<p><small>A single display can support multiple screens.
Each screen can have several different visual types
supported at different depths. You can use the functions
described in this section to determine which visual to use
for your application.</small></p>
<p><small>The functions in this section use the visual
information masks and the <i>XVisualInfo</i> structure,
which is defined in <<i>X11/Xutil.h</i>> and
contains:</small></p>
<p><small>__ │</small></p>
<p><small>/* Visual information mask bits */</small></p>
<p align=center><small><img src="grohtml-1439279.png"></small></p>
<pre><small>/* Values */
typedef struct {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Visual *visual;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>VisualID visualid;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int screen;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned int depth;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int class;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long red_mask;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long green_mask;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>unsigned long blue_mask;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int colormap_size;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int bits_per_rgb;</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>} XVisualInfo;</small></p>
<p><small>│__</small></p>
<p><small>To obtain a list of visual information structures
that match a specified template, use
<i>XGetVisualInfo</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XVisualInfo *XGetVisualInfo(<i>display</i>, <i>vinfo_mask</i>, <i>vinfo_template</i>, <i>nitems_return</i>)
Display *<i>display</i>;
long <i>vinfo_mask</i>;
XVisualInfo *<i>vinfo_template</i>;
int *<i>nitems_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>vinfo_mask</i> Specifies the visual mask
value.</small></p>
<p><small><i>vinfo_template</i> Specifies the visual
attributes that are to be used in matching the visual
structures.</small></p>
<p><small><i>nitems_return</i> Returns the number of
matching visual structures.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetVisualInfo</i> function returns a list
of visual structures that have attributes equal to the
attributes specified by vinfo_template. If no visual
structures match the template using the specified
vinfo_mask, <i>XGetVisualInfo</i> returns a NULL. To free
the data returned by this function, use
<i>XFree</i>.</small></p>
<p><small>To obtain the visual information that matches the
specified depth and class of the screen, use
<i>XMatchVisualInfo</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XMatchVisualInfo(<i>display</i>, <i>screen</i>, <i>depth</i>, <i>class</i>, <i>vinfo_return</i>)
Display *<i>display</i>;
int <i>screen</i>;
int <i>depth</i>;
int <i>class</i>;
XVisualInfo *<i>vinfo_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>Specifies the screen.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>depth</i></small></p>
</td>
<td width="10%"></td>
<td width="68%">
<p><small>Specifies the depth of the screen.</small></p>
</td>
<td width="11%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>class</i></small></p>
</td>
<td width="10%"></td>
<td width="68%">
<p><small>Specifies the class of the screen.</small></p>
</td>
<td width="11%">
</td>
</table>
<p><small><i>vinfo_return</i> Returns the matched visual
information.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XMatchVisualInfo</i> function returns the
visual information for a visual that matches the specified
depth and class for a screen. Because multiple visuals that
match the specified depth and class can exist, the exact
visual chosen is undefined. If a visual is found,
<i>XMatchVisualInfo</i> returns nonzero and the information
on the visual to vinfo_return. Otherwise, when a visual is
not found, <i>XMatchVisualInfo</i> returns zero.</small></p>
<a name="16.8. Manipulating Images"></a>
<h2>16.8. Manipulating Images</h2>
<p><small>Xlib provides several functions that perform
basic operations on images. All operations on images are
defined using an <i>XImage</i> structure, as defined in
<<i>X11/Xlib.h</i>>. Because the number of different
types of image formats can be very large, this hides details
of image storage properly from applications.</small></p>
<p><small>This section describes the functions for generic
operations on images. Manufacturers can provide very fast
implementations of these for the formats frequently
encountered on their hardware. These functions are neither
sufficient nor desirable to use for general image
processing. Rather, they are here to provide minimal
functions on screen format images. The basic operations for
getting and putting images are <i>XGetImage</i> and
<i>XPutImage</i>.</small></p>
<p><small>Note that no functions have been defined, as yet,
to read and write images to and from disk files.</small></p>
<p><small>The <i>XImage</i> structure describes an image as
it exists in the client’s memory. The user can request
that some of the members such as height, width, and xoffset
be changed when the image is sent to the server. Note that
bytes_per_line in concert with offset can be used to extract
a subset of the image. Other members (for example, byte
order, bitmap_unit, and so forth) are characteristics of
both the image and the server. If these members differ
between the image and the server, <i>XPutImage</i> makes the
appropriate conversions. The first byte of the first line of
plane n must be located at the address (data + (n * height *
bytes_per_line)). For a description of the <i>XImage</i>
structure, see section 8.7.</small></p>
<p><small>To allocate an <i>XImage</i> structure and
initialize it with image format values from a display, use
<i>XCreateImage</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XImage *XCreateImage(<i>display</i>, <i>visual</i>, <i>depth</i>, <i>format</i>, <i>offset</i>, <i>data</i>, <i>width</i>, <i>height</i>, <i>bitmap_pad</i>,
<i> bytes_per_line</i>)
Display *<i>display</i>;
Visual *<i>visual</i>;
unsigned int <i>depth</i>;
int <i>format</i>;
int <i>offset</i>;
char *<i>data</i>;
unsigned int <i>width</i>;
unsigned int <i>height</i>;
int <i>bitmap_pad</i>;
int <i>bytes_per_line</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>visual</i></small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Specifies the <i>Visual</i>
structure.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>depth</i></small></p>
</td>
<td width="10%"></td>
<td width="66%">
<p><small>Specifies the depth of the image.</small></p>
</td>
<td width="13%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>format</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the format for the image. You can pass
<i>XYBitmap</i>, <i>XYPixmap</i>, or
<i>ZPixmap</i>.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>offset</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the number of pixels to ignore at the
beginning of the scanline.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>data</i></small></p>
</td>
<td width="12%"></td>
<td width="50%">
<p><small>Specifies the image data.</small></p>
</td>
<td width="29%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the width of the image, in
pixels.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies the height of the image, in
pixels.</small></p>
</td>
</table>
<p><small><i>bitmap_pad</i> 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.</small></p>
<p><small><i>bytes_per_line</i> Specifies the number of
bytes in the client image between the start of one scanline
and the start of the next.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XCreateImage</i> function allocates the
memory needed for an <i>XImage</i> 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 <i>XImage</i> structure. The red,
green, and blue mask values are defined for Z format images
only and are derived from the <i>Visual</i> 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.</small></p>
<p><small>Note that when the image is created using
<i>XCreateImage</i>, <i>XGetImage</i>, or <i>XSubImage</i>,
the destroy procedure that the <i>XDestroyImage</i> function
calls frees both the image structure and the data pointed to
by the image structure.</small></p>
<p><small>The basic functions used to get a pixel, set a
pixel, create a subimage, and add a constant value to an
image are defined in the image object. The functions in this
section are really macro invocations of the functions in the
image object and are defined in
<<i>X11/Xutil.h</i>>.</small></p>
<p><small>To obtain a pixel value in an image, use
<i>XGetPixel</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>unsigned long XGetPixel(<i>ximage</i>, <i>x</i>, <i>y</i>)
XImage *<i>ximage</i>;
int <i>x</i>;
int <i>y</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>ximage</i></small></p>
</td>
<td width="8%"></td>
<td width="40%">
<p><small>Specifies the image.</small></p>
</td>
<td width="39%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="64%">
<p><small>Specify the x and y coordinates.</small></p>
</td>
<td width="15%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetPixel</i> function returns the
specified pixel from the named image. The pixel value is
returned in normalized format (that is, the least
significant byte of the long is the least significant byte
of the pixel). The image must contain the x and y
coordinates.</small></p>
<p><small>To set a pixel value in an image, use
<i>XPutPixel</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XPutPixel(<i>ximage</i>, <i>x</i>, <i>y</i>, <i>pixel</i>)
XImage *<i>ximage</i>;
int <i>x</i>;
int <i>y</i>;
unsigned long <i>pixel</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>ximage</i></small></p>
</td>
<td width="8%"></td>
<td width="40%">
<p><small>Specifies the image.</small></p>
</td>
<td width="39%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="64%">
<p><small>Specify the x and y coordinates.</small></p>
</td>
<td width="15%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>pixel</i></small></p>
</td>
<td width="10%"></td>
<td width="60%">
<p><small>Specifies the new pixel value.</small></p>
</td>
<td width="19%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XPutPixel</i> function overwrites the
pixel in the named image with the specified pixel value. The
input pixel value must be in normalized format (that is, the
least significant byte of the long is the least significant
byte of the pixel). The image must contain the x and y
coordinates.</small></p>
<p><small>To create a subimage, use
<i>XSubImage</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XImage *XSubImage(<i>ximage</i>, <i>x</i>, <i>y</i>, <i>subimage_width</i>, <i>subimage_height</i>)
XImage *<i>ximage</i>;
int <i>x</i>;
int <i>y</i>;
unsigned int <i>subimage_width</i>;
unsigned int <i>subimage_height</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>ximage</i></small></p>
</td>
<td width="8%"></td>
<td width="40%">
<p><small>Specifies the image.</small></p>
</td>
<td width="39%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>x</i></small></p>
</td>
<td width="97%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>y</i></small></p>
</td>
<td width="18%"></td>
<td width="64%">
<p><small>Specify the x and y coordinates.</small></p>
</td>
<td width="15%">
</td>
</table>
<p><small><i>subimage_width</i> Specifies the width of the
new subimage, in pixels.</small></p>
<p><small><i>subimage_height</i> Specifies the height of
the new subimage, in pixels.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XSubImage</i> function creates a new image
that is a subsection of an existing one. It allocates the
memory necessary for the new <i>XImage</i> structure and
returns a pointer to the new image. The data is copied from
the source image, and the image must contain the rectangle
defined by x, y, subimage_width, and
subimage_height.</small></p>
<p><small>To increment each pixel in an image by a constant
value, use <i>XAddPixel</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XAddPixel(<i>ximage</i>, <i>value</i>)
XImage *<i>ximage</i>;
long <i>value</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>ximage</i></small></p>
</td>
<td width="8%"></td>
<td width="40%">
<p><small>Specifies the image.</small></p>
</td>
<td width="39%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>value</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the constant value that is to be
added.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XAddPixel</i> function adds a constant
value to every pixel in an image. It is useful when you have
a base pixel value from allocating color resources and need
to manipulate the image to that form.</small></p>
<p><small>To deallocate the memory allocated in a previous
call to <i>XCreateImage</i>, use
<i>XDestroyImage</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XDestroyImage(<i>ximage</i>)
XImage *<i>ximage</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>ximage</i></small></p>
</td>
<td width="8%"></td>
<td width="40%">
<p><small>Specifies the image.</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XDestroyImage</i> function deallocates the
memory associated with the <i>XImage</i>
structure.</small></p>
<p><small>Note that when the image is created using
<i>XCreateImage</i>, <i>XGetImage</i>, or <i>XSubImage</i>,
the destroy procedure that this macro calls frees both the
image structure and the data pointed to by the image
structure.</small></p>
<a name="16.9. Manipulating Bitmaps"></a>
<h2>16.9. Manipulating Bitmaps</h2>
<p><small>Xlib provides functions that you can use to read
a bitmap from a file, save a bitmap to a file, or create a
bitmap. This section describes those functions that transfer
bitmaps to and from the client’s file system, thus
allowing their reuse in a later connection (for example,
from an entirely different client or to a different display
or server).</small></p>
<p><small>The X version 11 bitmap file format
is:</small></p>
<p><small>__ │</small></p>
<pre><small>#define <i>name</i>_width <i>width
</i>#define <i>name</i>_height <i>height
</i>#define <i>name</i>_x_hot <i>x
</i>#define <i>name</i>_y_hot <i>y
</i>static unsigned char <i>name</i>_bits[] = { 0x<i>NN</i>,... }
</small></pre>
<p><small>│__</small></p>
<p><small>The lines for the variables ending with _x_hot
and _y_hot suffixes are optional because they are present
only if a hotspot has been defined for this bitmap. The
lines for the other variables are required. The word
‘‘unsigned’’ is optional; that is,
the type of the _bits array can be
‘‘char’’ or ‘‘unsigned
char’’. The _bits array must be large enough to
contain the size bitmap. The bitmap unit is 8.</small></p>
<p><small>To read a bitmap from a file and store it in a
pixmap, use <i>XReadBitmapFile</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XReadBitmapFile(<i>display</i>, <i>d</i>, <i>filename</i>, <i>width_return</i>, <i>height_return</i>, <i>bitmap_return</i>, <i>x_hot_return</i>,
<i> y_hot_return</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
char *<i>filename</i>;
unsigned int *<i>width_return</i>, *<i>height_return</i>;
Pixmap *<i>bitmap_return</i>;
int *<i>x_hot_return</i>, *<i>y_hot_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the drawable that indicates the
screen.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>filename</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the file name to use. The format of the
file name is operating-system dependent.</small></p>
</td>
</table>
<p><small><i>width_return</i></small></p>
<p><small><i>height_return</i> Return the width and height
values of the read in bitmap file.</small></p>
<p><small><i>bitmap_return</i> Returns the bitmap that is
created.</small></p>
<p><small><i>x_hot_return</i></small></p>
<p><small><i>y_hot_return</i> Return the hotspot
coordinates.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XReadBitmapFile</i> function reads in a
file containing a bitmap. The file is parsed in the encoding
of the current locale. The ability to read other than the
standard format is implementation-dependent. If the file
cannot be opened, <i>XReadBitmapFile</i> returns
<i>BitmapOpenFailed</i>. If the file can be opened but does
not contain valid bitmap data, it returns
<i>BitmapFileInvalid</i>. If insufficient working storage is
allocated, it returns <i>BitmapNoMemory</i>. If the file is
readable and valid, it returns
<i>BitmapSuccess</i>.</small></p>
<p><small><i>XReadBitmapFile</i> returns the bitmap’s
height and width, as read from the file, to width_return and
height_return. It then creates a pixmap of the appropriate
size, reads the bitmap data from the file into the pixmap,
and assigns the pixmap to the caller’s variable
bitmap. The caller must free the bitmap using
<i>XFreePixmap</i> when finished. If <i>name</i>_x_hot and
<i>name</i>_y_hot exist, <i>XReadBitmapFile</i> returns them
to x_hot_return and y_hot_return; otherwise, it returns
−1,−1.</small></p>
<p><small><i>XReadBitmapFile</i> can generate
<i>BadAlloc</i>, <i>BadDrawable</i>, and <i>BadGC</i>
errors.</small></p>
<p><small>To read a bitmap from a file and return it as
data, use <i>XReadBitmapFileData</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XReadBitmapFileData(<i>filename</i>, <i>width_return</i>, <i>height_return</i>, <i>data_return</i>, <i>x_hot_return</i>, <i>y_hot_return</i>)
char *<i>filename</i>;
unsigned int *<i>width_return</i>, *<i>height_return</i>;
unsigned char *<i>data_return</i>;
int *<i>x_hot_return</i>, *<i>y_hot_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>filename</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the file name to use. The format of the
file name is operating-system dependent.</small></p>
</td>
</table>
<p><small><i>width_return</i></small></p>
<p><small><i>height_return</i> Return the width and height
values of the read in bitmap file.</small></p>
<p><small><i>data_return</i> Returns the bitmap
data.</small></p>
<p><small><i>x_hot_return</i></small></p>
<p><small><i>y_hot_return</i> Return the hotspot
coordinates.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XReadBitmapFileData</i> function reads in
a file containing a bitmap, in the same manner as
<i>XReadBitmapFile</i>, but returns the data directly rather
than creating a pixmap in the server. The bitmap data is
returned in data_return; the client must free this storage
when finished with it by calling <i>XFree</i>. The status
and other return values are the same as for
<i>XReadBitmapFile</i>.</small></p>
<p><small>To write out a bitmap from a pixmap to a file,
use <i>XWriteBitmapFile</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XWriteBitmapFile(<i>display</i>, <i>filename</i>, <i>bitmap</i>, <i>width</i>, <i>height</i>, <i>x_hot</i>, <i>y_hot</i>)
Display *<i>display</i>;
char *<i>filename</i>;
Pixmap <i>bitmap</i>;
unsigned int <i>width</i>, <i>height</i>;
int <i>x_hot</i>, <i>y_hot</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>filename</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the file name to use. The format of the
file name is operating-system dependent.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>bitmap</i></small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>Specifies the bitmap.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="58%">
<p><small>Specify the width and height.</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>x_hot</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>y_hot</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specify where to place the hotspot coordinates
(or −1,−1 if none are present) in the
file.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XWriteBitmapFile</i> function writes a
bitmap out to a file in the X Version 11 format. The name
used in the output file is derived from the file name by
deleting the directory prefix. The file is written in the
encoding of the current locale. If the file cannot be opened
for writing, it returns <i>BitmapOpenFailed</i>. If
insufficient memory is allocated, <i>XWriteBitmapFile</i>
returns <i>BitmapNoMemory</i>; otherwise, on no error, it
returns <i>BitmapSuccess</i>. If x_hot and y_hot are not
−1, −1, <i>XWriteBitmapFile</i> writes them out
as the hotspot coordinates for the bitmap.</small></p>
<p><small><i>XWriteBitmapFile</i> can generate
<i>BadDrawable</i> and <i>BadMatch</i> errors.</small></p>
<p><small>To create a pixmap and then store bitmap-format
data into it, use
<i>XCreatePixmapFromBitmapData</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Pixmap XCreatePixmapFromBitmapData(<i>display</i>, <i>d</i>, <i>data</i>, <i>width</i>, <i>height</i>, <i>fg</i>, <i>bg</i>, <i>depth</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
char *<i>data</i>;
unsigned int <i>width</i>, <i>height</i>;
unsigned long <i>fg</i>, <i>bg</i>;
unsigned int <i>depth</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the drawable that indicates the
screen.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>data</i></small></p>
</td>
<td width="12%"></td>
<td width="72%">
<p><small>Specifies the data in bitmap format.</small></p>
</td>
<td width="7%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="58%">
<p><small>Specify the width and height.</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>fg</i></small></p>
</td>
<td width="95%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>bg</i></small></p>
</td>
<td width="16%"></td>
<td width="80%">
<p><small>Specify the foreground and background pixel
values to use.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>depth</i></small></p>
</td>
<td width="10%"></td>
<td width="68%">
<p><small>Specifies the depth of the pixmap.</small></p>
</td>
<td width="11%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XCreatePixmapFromBitmapData</i> function
creates a pixmap of the given depth and then does a
bitmap-format <i>XPutImage</i> of the data into it. The
depth must be supported by the screen of the specified
drawable, or a <i>BadMatch</i> error results.</small></p>
<p><small><i>XCreatePixmapFromBitmapData</i> can generate
<i>BadAlloc</i>, <i>BadDrawable</i>, <i>BadGC</i>, and
<i>BadValue</i> errors.</small></p>
<p><small>To include a bitmap written out by
<i>XWriteBitmapFile</i> in a program directly, as opposed to
reading it in every time at run time, use
<i>XCreateBitmapFromData</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Pixmap XCreateBitmapFromData(<i>display</i>, <i>d</i>, <i>data</i>, <i>width</i>, <i>height</i>)
Display *<i>display</i>;
Drawable <i>d</i>;
char *<i>data</i>;
unsigned int <i>width</i>, <i>height</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="80%">
<p><small>Specifies the drawable that indicates the
screen.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>data</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the location of the bitmap
data.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>width</i></small></p>
</td>
<td width="89%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>height</i></small></p>
</td>
<td width="8%"></td>
<td width="58%">
<p><small>Specify the width and height.</small></p>
</td>
<td width="21%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XCreateBitmapFromData</i> function allows
you to include in your C program (using <i>#include</i>) a
bitmap file that was written out by <i>XWriteBitmapFile</i>
(X version 11 format only) without reading in the bitmap
file. The following example creates a gray
bitmap:</small></p>
<pre><small>#include "gray.bitmap"
Pixmap bitmap;
bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height);
</small></pre>
<p><small>If insufficient working storage was allocated,
<i>XCreateBitmapFromData</i> returns <i>None</i>. It is your
responsibility to free the bitmap using <i>XFreePixmap</i>
when finished.</small></p>
<p><small><i>XCreateBitmapFromData</i> can generate
<i>BadAlloc</i> and <i>BadGC</i> errors.</small></p>
<a name="16.10. Using the Context Manager"></a>
<h2>16.10. Using the Context Manager</h2>
<p><small>The context manager provides a way of associating
data with an X resource ID (mostly typically a window) in
your program. Note that this is local to your program; the
data is not stored in the server on a property list. Any
amount of data in any number of pieces can be associated
with a resource ID, and each piece of data has a type
associated with it. The context manager requires knowledge
of the resource ID and type to store or retrieve
data.</small></p>
<p><small>Essentially, the context manager can be viewed as
a two-dimensional, sparse array: one dimension is
subscripted by the X resource ID and the other by a context
type field. Each entry in the array contains a pointer to
the data. Xlib provides context management functions with
which you can save data values, get data values, delete
entries, and create a unique context type. The symbols used
are in <<i>X11/Xutil.h</i>>.</small></p>
<p><small>To save a data value that corresponds to a
resource ID and context type, use
<i>XSaveContext</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XSaveContext(<i>display</i>, <i>rid</i>, <i>context</i>, <i>data</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<p><small>Display *<i>display</i>;</small></p>
</table>
<p><small>XID <i>rid</i>;<br>
XContext <i>context</i>;<br>
XPointer <i>data</i>;</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>rid</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the resource ID with which the data is
associated.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>context</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the context type to which the data
belongs.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>data</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the data to be associated with the
window and type.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>If an entry with the specified resource ID and
type already exists, <i>XSaveContext</i> overrides it with
the specified context. The <i>XSaveContext</i> function
returns a nonzero error code if an error has occurred and
zero otherwise. Possible errors are <i>XCNOMEM</i> (out of
memory).</small></p>
<p><small>To get the data associated with a resource ID and
type, use <i>XFindContext</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XFindContext(<i>display</i>, <i>rid</i>, <i>context</i>, <i>data_return</i>)
Display *<i>display</i>;
XID <i>rid</i>;
XContext <i>context</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<p><small>XPointer *<i>data_return</i>;</small></p>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>rid</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the resource ID with which the data is
associated.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>context</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the context type to which the data
belongs.</small></p>
</td>
</table>
<p><small><i>data_return</i> Returns the data.</small></p>
<p><small>│__</small></p>
<p><small>Because it is a return value, the data is a
pointer. The <i>XFindContext</i> function returns a nonzero
error code if an error has occurred and zero otherwise.
Possible errors are <i>XCNOENT</i>
(context-not-found).</small></p>
<p><small>To delete an entry for a given resource ID and
type, use <i>XDeleteContext</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XDeleteContext(<i>display</i>, <i>rid</i>, <i>context</i>)
Display *<i>display</i>;
XID <i>rid</i>;
XContext <i>context</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>rid</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the resource ID with which the data is
associated.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>context</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the context type to which the data
belongs.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XDeleteContext</i> function deletes the
entry for the given resource ID and type from the data
structure. This function returns the same error codes that
<i>XFindContext</i> returns if called with the same
arguments. <i>XDeleteContext</i> does not free the data
whose address was saved.</small></p>
<p><small>To create a unique context type that may be used
in subsequent calls to <i>XSaveContext</i> and
<i>XFindContext</i>, use <i>XUniqueContext</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XContext XUniqueContext()
</small></pre>
<p><small>│__</small></p>
<p><small><b>16</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b>Appendix A</b></p>
<p align=center><b>Xlib Functions and Protocol
Requests</b></p>
<p><small>This appendix provides two tables that relate to
Xlib functions and the X protocol. The following table lists
each Xlib function (in alphabetical order) and the
corresponding protocol request that it
generates.</small></p>
<p align=center><small><img src="grohtml-1439280.png"></small></p>
<p><small><b>17</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p><small>The following table lists each X protocol request
(in alphabetical order) and the Xlib functions that
reference it.</small></p>
<p align=center><small><img src="grohtml-1439281.png"></small></p>
<p><small><b>18</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b><small>Appendix B</small></b></p>
<p align=center><b><small>X Font Cursors</small></b></p>
<p><small>The following are the available cursors that can
be used with <i>XCreateFontCursor</i>.</small></p>
<pre><small>#define XC_X_cursor 0 #define XC_ll_angle 76
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_arrow 2</small></p>
</td>
<td width="40%">
<p><small>#define XC_lr_angle 78</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_based_arrow_down 4</small></p>
</td>
<td width="40%">
<p><small>#define XC_man 80</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_based_arrow_up 6</small></p>
</td>
<td width="40%">
<p><small>#define XC_middlebutton 82</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_boat 8</small></p>
</td>
<td width="40%">
<p><small>#define XC_mouse 84</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_bogosity 10</small></p>
</td>
<td width="40%">
<p><small>#define XC_pencil 86</small></p>
</td>
</table>
<p><small>#define XC_bottom_left_corner 12#define XC_pirate
88<br>
#define XC_bottom_right_corner 14#define XC_plus
90</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_bottom_side 16</small></p>
</td>
<td width="40%">
<p><small>#define XC_question_arrow 92</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_bottom_tee 18</small></p>
</td>
<td width="40%">
<p><small>#define XC_right_ptr 94</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_box_spiral 20</small></p>
</td>
<td width="40%">
<p><small>#define XC_right_side 96</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_center_ptr 22</small></p>
</td>
<td width="40%">
<p><small>#define XC_right_tee 98</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_circle 24</small></p>
</td>
<td width="40%">
<p><small>#define XC_rightbutton 100</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_clock 26</small></p>
</td>
<td width="40%">
<p><small>#define XC_rtl_logo 102</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_coffee_mug 28</small></p>
</td>
<td width="40%">
<p><small>#define XC_sailboat 104</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_cross 30</small></p>
</td>
<td width="40%">
<p><small>#define XC_sb_down_arrow 106</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_cross_reverse 32</small></p>
</td>
<td width="40%">
<p><small>#define XC_sb_h_double_arrow 108</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_crosshair 34</small></p>
</td>
<td width="40%">
<p><small>#define XC_sb_left_arrow 110</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_diamond_cross 36</small></p>
</td>
<td width="40%">
<p><small>#define XC_sb_right_arrow 112</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_dot 38</small></p>
</td>
<td width="40%">
<p><small>#define XC_sb_up_arrow 114</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_dot_box_mask 40</small></p>
</td>
<td width="40%">
<p><small>#define XC_sb_v_double_arrow 116</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_double_arrow 42</small></p>
</td>
<td width="40%">
<p><small>#define XC_shuttle 118</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_draft_large 44</small></p>
</td>
<td width="40%">
<p><small>#define XC_sizing 120</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_draft_small 46</small></p>
</td>
<td width="40%">
<p><small>#define XC_spider 122</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_draped_box 48</small></p>
</td>
<td width="40%">
<p><small>#define XC_spraycan 124</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_exchange 50</small></p>
</td>
<td width="40%">
<p><small>#define XC_star 126</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_fleur 52</small></p>
</td>
<td width="40%">
<p><small>#define XC_target 128</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_gobbler 54</small></p>
</td>
<td width="40%">
<p><small>#define XC_tcross 130</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_gumby 56</small></p>
</td>
<td width="40%">
<p><small>#define XC_top_left_arrow 132</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_hand1 58</small></p>
</td>
<td width="40%">
<p><small>#define XC_top_left_corner 134</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_hand2 60</small></p>
</td>
<td width="40%">
<p><small>#define XC_top_right_corner 136</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_heart 62</small></p>
</td>
<td width="40%">
<p><small>#define XC_top_side 138</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_icon 64</small></p>
</td>
<td width="40%">
<p><small>#define XC_top_tee 140</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_iron_cross 66</small></p>
</td>
<td width="40%">
<p><small>#define XC_trek 142</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_left_ptr 68</small></p>
</td>
<td width="40%">
<p><small>#define XC_ul_angle 144</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_left_side 70</small></p>
</td>
<td width="40%">
<p><small>#define XC_umbrella 146</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_left_tee 72</small></p>
</td>
<td width="40%">
<p><small>#define XC_ur_angle 148</small></p>
</td>
<tr valign="top" align="left">
<td width="60%">
<p><small>#define XC_leftbutton 74</small></p>
</td>
<td width="40%">
<p><small>#define XC_watch 150</small></p>
</td>
<tr valign="top" align="left">
<td width="60%"></td>
<td width="40%">
<p><small>#define XC_xterm 152</small></p>
</td>
</table>
<p><small><b>19</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b>Appendix C</b></p>
<p align=center><b>Extensions</b></p>
<p><small>Because X can evolve by extensions to the core
protocol, it is important that extensions not be perceived
as second-class citizens. At some point, your favorite
extensions may be adopted as additional parts of the X
Standard.</small></p>
<p><small>Therefore, there should be little to distinguish
the use of an extension from that of the core protocol. To
avoid having to initialize extensions explicitly in
application programs, it is also important that extensions
perform lazy evaluations, automatically initializing
themselves when called for the first time.</small></p>
<p><small>This appendix describes techniques for writing
extensions to Xlib that will run at essentially the same
performance as the core protocol requests.</small></p>
<p align=center><small>Note</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>It is expected that a given extension to X
consists of multiple requests. Defining 10 new features as
10 separate extensions is a bad practice. Rather, they
should be packaged into a single extension and should use
minor opcodes to distinguish the requests.</small></p>
</td>
</table>
<p><small>The symbols and macros used for writing stubs to
Xlib are listed in <<i>X11/Xlibint.h</i>>.</small></p>
<a name="Basic Protocol Support Routines"></a>
<h2>Basic Protocol Support Routines</h2>
<p><small>The basic protocol requests for extensions are
<i>XQueryExtension</i> and
<i>XListExtensions</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool XQueryExtension(<i>display</i>, <i>name</i>, <i>major_opcode_return</i>, <i>first_event_return</i>, <i>first_error_return</i>)
Display *<i>display</i>;
char *<i>name;
</i> int *<i>major_opcode_return</i>;
int *<i>first_event_return</i>;
int *<i>first_error_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>name</i></small></p>
</td>
<td width="12%"></td>
<td width="58%">
<p><small>Specifies the extension name.</small></p>
</td>
<td width="21%">
</td>
</table>
<p><small><i>major_opcode_return</i> Returns the major
opcode.</small></p>
<p><small><i>first_event_return</i> Returns the first event
code, if any.</small></p>
<p><small><i>first_error_return</i> Returns the first error
code, if any.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XQueryExtension</i> function determines if
the named extension is present. If the extension is not
present, <i>XQueryExtension</i> returns <i>False</i>;
otherwise, it returns <i>True</i>. If the extension is
present, <i>XQueryExtension</i> returns the major opcode for
the extension to major_opcode_return; otherwise, it returns
zero. Any minor opcode and the request formats are specific
to the extension. If the extension involves additional event
types, <i>XQueryExtension</i> returns the base event type
code to first_event_return; otherwise, it returns zero. The
format of the events is specific to the extension. If the
extension involves additional error codes,
<i>XQueryExtension</i> returns the base error code to
first_error_return; otherwise, it returns zero. The format
of additional data in the errors is specific to the
extension.</small></p>
<p><small>If the extension name is not in the Host Portable
Character Encoding the result is implementation-dependent.
Uppercase and lowercase matter; the strings
‘‘thing’’,
‘‘Thing’’, and
‘‘thinG’’ are all considered
different names.</small></p>
<p><small>__ │</small></p>
<pre><small>char **XListExtensions(<i>display</i>, <i>nextensions_return</i>)
Display *<i>display</i>;
int *<i>nextensions_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>nextensions_return</i> Returns the number of
extensions listed.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XListExtensions</i> 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.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>XFreeExtensionList(<i>list</i>)
char **<i>list</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>list</i></small></p>
</td>
<td width="12%"></td>
<td width="76%">
<p><small>Specifies the list of extension
names.</small></p>
</td>
<td width="3%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XFreeExtensionList</i> function frees the
memory allocated by <i>XListExtensions</i>.</small></p>
<a name="Hooking into Xlib"></a>
<h2>Hooking into Xlib</h2>
<p><small>These functions allow you to hook into the
library. They are not normally used by application
programmers but are used by people who need to extend the
core X protocol and the X library interface. The functions,
which generate protocol requests for X, are typically called
stubs.</small></p>
<p><small>In extensions, stubs first should check to see if
they have initialized themselves on a connection. If they
have not, they then should call <i>XInitExtension</i> to
attempt to initialize themselves on the
connection.</small></p>
<p><small>If the extension needs to be informed of GC/font
allocation or deallocation or if the extension defines new
event types, the functions described here allow the
extension to be called when these events occur.</small></p>
<p><small>The <i>XExtCodes</i> structure returns the
information from <i>XInitExtension</i> and is defined in
<<i>X11/Xlib.h</i>>:</small></p>
<p><small>__ │</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small>typedef struct _XExtCodes {</small></p>
</td>
<td width="50%"></td>
<td width="40%">
<p><small>/* public to extension, cannot be changed
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="50%">
<p><small>int extension;</small></p>
</td>
<td width="40%">
<p><small>/* extension number */</small></p>
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="50%">
<p><small>int major_opcode;</small></p>
</td>
<td width="40%">
<p><small>/* major op-code assigned by server
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="50%">
<p><small>int first_event;</small></p>
</td>
<td width="40%">
<p><small>/* first event number for the extension
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="10%">
</td>
<td width="50%">
<p><small>int first_error;</small></p>
</td>
<td width="40%">
<p><small>/* first error number for the extension
*/</small></p>
</td>
</table>
<p><small>} XExtCodes;</small></p>
<p><small>│__</small></p>
<p><small>__ │</small></p>
<pre><small>XExtCodes *XInitExtension(<i>display</i>, <i>name</i>)
Display *<i>display</i>;
char *<i>name</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>name</i></small></p>
</td>
<td width="12%"></td>
<td width="58%">
<p><small>Specifies the extension name.</small></p>
</td>
<td width="21%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XInitExtension</i> function determines if
the named extension exists. Then, it allocates storage for
maintaining the information about the extension on the
connection, chains this onto the extension list for the
connection, and returns the information the stub implementor
will need to access the extension. If the extension does not
exist, <i>XInitExtension</i> returns NULL.</small></p>
<p><small>If the extension name is not in the Host Portable
Character Encoding, the result is implementation-dependent.
Uppercase and lowercase matter; the strings
‘‘thing’’,
‘‘Thing’’, and
‘‘thinG’’ are all considered
different names.</small></p>
<p><small>The extension number in the <i>XExtCodes</i>
structure is needed in the other calls that follow. This
extension number is unique only to a single
connection.</small></p>
<p><small>__ │</small></p>
<pre><small>XExtCodes *XAddExtension(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>For local Xlib extensions, the
<i>XAddExtension</i> function allocates the <i>XExtCodes</i>
structure, bumps the extension number count, and chains the
extension onto the extension list. (This permits extensions
to Xlib without requiring server extensions.)</small></p>
<a name="Hooks into the Library"></a>
<h2>Hooks into the Library</h2>
<p><small>These functions allow you to define procedures
that are to be called when various circumstances occur. The
procedures include the creation of a new GC for a
connection, the copying of a GC, the freeing of a GC, the
creating and freeing of fonts, the conversion of events
defined by extensions to and from wire format, and the
handling of errors.</small></p>
<p><small>All of these functions return the previous
procedure defined for this extension.</small></p>
<p><small>__ │</small></p>
<pre><small>int (*XESetCloseDisplay(<i>display</i>, <i>extension</i>, <i>proc</i>))()
Display *<i>display</i>;
int <i>extension</i>;
int (*<i>proc</i>)();
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>extension</i></small></p>
</td>
<td width="2%"></td>
<td width="62%">
<p><small>Specifies the extension number.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>proc</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the procedure to call when the display
is closed.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XESetCloseDisplay</i> function defines a
procedure to be called whenever <i>XCloseDisplay</i> is
called. It returns any previously defined procedure, usually
NULL.</small></p>
<p><small>When <i>XCloseDisplay</i> is called, your
procedure is called with these arguments:</small></p>
<p><small>__ │</small></p>
<pre><small>(*<i>proc</i>)(<i>display</i>, <i>codes</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *<i>display</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XExtCodes *<i>codes</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>│__</small></p>
<p><small>__ │</small></p>
<pre><small>int (*XESetCreateGC(<i>display</i>, <i>extension</i>, <i>proc</i>))()
Display *<i>display</i>;
int <i>extension</i>;
int (*<i>proc</i>)();
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>extension</i></small></p>
</td>
<td width="2%"></td>
<td width="62%">
<p><small>Specifies the extension number.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>proc</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the procedure to call when a GC is
closed.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XESetCreateGC</i> function defines a
procedure to be called whenever a new GC is created. It
returns any previously defined procedure, usually
NULL.</small></p>
<p><small>When a GC is created, your procedure is called
with these arguments:</small></p>
<p><small>__ │</small></p>
<pre><small>(*<i>proc</i>)(<i>display</i>, <i>gc</i>, <i>codes</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *<i>display</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>GC <i>gc</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XExtCodes *<i>codes</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>│__</small></p>
<p><small>__ │</small></p>
<pre><small>int (*XESetCopyGC(<i>display</i>, <i>extension</i>, <i>proc</i>))()
Display *<i>display</i>;
int <i>extension</i>;
int (*<i>proc</i>)();
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>extension</i></small></p>
</td>
<td width="2%"></td>
<td width="62%">
<p><small>Specifies the extension number.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>proc</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the procedure to call when GC
components are copied.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XESetCopyGC</i> function defines a
procedure to be called whenever a GC is copied. It returns
any previously defined procedure, usually NULL.</small></p>
<p><small>When a GC is copied, your procedure is called
with these arguments:</small></p>
<p><small>__ │</small></p>
<pre><small>(*<i>proc</i>)(<i>display</i>, <i>gc</i>, <i>codes</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *<i>display</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>GC <i>gc</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XExtCodes *<i>codes</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>│__</small></p>
<p><small>__ │</small></p>
<pre><small>int (*XESetFreeGC(<i>display</i>, <i>extension</i>, <i>proc)</i>)()
Display *<i>display</i>;
int <i>extension</i>;
int (*<i>proc</i>)();
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>extension</i></small></p>
</td>
<td width="2%"></td>
<td width="62%">
<p><small>Specifies the extension number.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>proc</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the procedure to call when a GC is
freed.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XESetFreeGC</i> function defines a
procedure to be called whenever a GC is freed. It returns
any previously defined procedure, usually NULL.</small></p>
<p><small>When a GC is freed, your procedure is called with
these arguments:</small></p>
<p><small>__ │</small></p>
<pre><small>(*<i>proc</i>)(<i>display</i>, <i>gc</i>, <i>codes</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *<i>display</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>GC <i>gc</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XExtCodes *<i>codes</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>│__</small></p>
<p><small>__ │</small></p>
<pre><small>int (*XESetCreateFont(<i>display</i>, <i>extension</i>, <i>proc</i>))()
Display *<i>display</i>;
int <i>extension</i>;
int (*<i>proc</i>)();
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>extension</i></small></p>
</td>
<td width="2%"></td>
<td width="62%">
<p><small>Specifies the extension number.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>proc</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the procedure to call when a font is
created.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XESetCreateFont</i> function defines a
procedure to be called whenever <i>XLoadQueryFont</i> and
<i>XQueryFont</i> are called. It returns any previously
defined procedure, usually NULL.</small></p>
<p><small>When <i>XLoadQueryFont</i> or <i>XQueryFont</i>
is called, your procedure is called with these
arguments:</small></p>
<p><small>__ │</small></p>
<pre><small>(*<i>proc</i>)(<i>display</i>, <i>fs</i>, <i>codes</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *<i>display</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XFontStruct *<i>fs</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XExtCodes *<i>codes</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>│__</small></p>
<p><small>__ │</small></p>
<pre><small>int (*XESetFreeFont(<i>display</i>, <i>extension</i>, <i>proc</i>))()
Display *<i>display</i>;
int <i>extension</i>;
int (*<i>proc</i>)();
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>extension</i></small></p>
</td>
<td width="2%"></td>
<td width="62%">
<p><small>Specifies the extension number.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>proc</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the procedure to call when a font is
freed.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XESetFreeFont</i> function defines a
procedure to be called whenever <i>XFreeFont</i> is called.
It returns any previously defined procedure, usually
NULL.</small></p>
<p><small>When <i>XFreeFont</i> is called, your procedure
is called with these arguments:</small></p>
<p><small>__ │</small></p>
<pre><small>(*<i>proc</i>)(<i>display</i>, <i>fs</i>, <i>codes</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *<i>display</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XFontStruct *<i>fs</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XExtCodes *<i>codes</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XESetWireToEvent</i> and
<i>XESetEventToWire</i> functions allow you to define new
events to the library. An <i>XEvent</i> structure always has
a type code (type <i>int</i>) as the first component. This
uniquely identifies what kind of event it is. The second
component is always the serial number (type <i>unsigned
long</i>) of the last request processed by the server. The
third component is always a Boolean (type <i>Bool</i>)
indicating whether the event came from a <i>SendEvent</i>
protocol request. The fourth component is always a pointer
to the display the event was read from. The fifth component
is always a resource ID of one kind or another, usually a
window, carefully selected to be useful to toolkit
dispatchers. The fifth component should always exist, even
if the event does not have a natural destination; if there
is no value from the protocol to put in this component,
initialize it to zero.</small></p>
<p align=center><small>Note</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>There is an implementation limit such that your
host event structure size cannot be bigger than the size of
the <i>XEvent</i> union of structures. There also is no way
to guarantee that more than 24 elements or 96 characters in
the structure will be fully portable between
machines.</small></p>
</td>
</table>
<p><small>__ │</small></p>
<pre><small>int (*XESetWireToEvent(<i>display</i>, <i>event_number</i>, <i>proc</i>))()
Display *<i>display</i>;
int <i>event_number</i>;
Status (*<i>proc</i>)();
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>event_number</i> Specifies the event
code.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>proc</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the procedure to call when converting
an event.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XESetWireToEvent</i> function defines a
procedure to be called when an event needs to be converted
from wire format (<i>xEvent</i>) to host format
(<i>XEvent</i>). The event number defines which protocol
event number to install a conversion procedure for.
<i>XESetWireToEvent</i> returns any previously defined
procedure.</small></p>
<p align=center><small>Note</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>You can replace a core event conversion function
with one of your own, although this is not encouraged. It
would, however, allow you to intercept a core event and
modify it before being placed in the queue or otherwise
examined.</small></p>
</td>
</table>
<p><small>When Xlib needs to convert an event from wire
format to host format, your procedure is called with these
arguments:</small></p>
<p><small>__ │</small></p>
<pre><small>Status (*<i>proc</i>)(<i>display</i>, <i>re</i>, <i>event</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *<i>display</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XEvent *<i>re</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>xEvent *<i>event</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>│__</small></p>
<p><small>Your procedure must return status to indicate if
the conversion succeeded. The re argument is a pointer to
where the host format event should be stored, and the event
argument is the 32-byte wire event structure. In the
<i>XEvent</i> structure you are creating, you must fill in
the five required members of the event structure. You should
fill in the type member with the type specified for the
<i>xEvent</i> structure. You should copy all other members
from the <i>xEvent</i> structure (wire format) to the
<i>XEvent</i> structure (host format). Your conversion
procedure should return <i>True</i> if the event should be
placed in the queue or <i>False</i> if it should not be
placed in the queue.</small></p>
<p><small>To initialize the serial number component of the
event, call <i>_XSetLastRequestRead</i> with the event and
use the return value.</small></p>
<p><small>__ │</small></p>
<pre><small>unsigned long _XSetLastRequestRead(<i>display</i>, <i>rep</i>)
Display *<i>display</i>;
xGenericReply *<i>rep</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>rep</i></small></p>
</td>
<td width="14%"></td>
<td width="70%">
<p><small>Specifies the wire event structure.</small></p>
</td>
<td width="9%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>_XSetLastRequestRead</i> function computes
and returns a complete serial number from the partial serial
number in the event.</small></p>
<p><small>__ │</small></p>
<pre><small>Status (*XESetEventToWire(<i>display</i>, <i>event_number</i>, <i>proc</i>))()
Display *<i>display</i>;
int <i>event_number</i>;
int (*<i>proc</i>)();
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>event_number</i> Specifies the event
code.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>proc</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the procedure to call when converting
an event.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XESetEventToWire</i> function defines a
procedure to be called when an event needs to be converted
from host format (<i>XEvent</i>) to wire format
(<i>xEvent</i>) form. The event number defines which
protocol event number to install a conversion procedure for.
<i>XESetEventToWire</i> returns any previously defined
procedure. It returns zero if the conversion fails or
nonzero otherwise.</small></p>
<p align=center><small>Note</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>You can replace a core event conversion function
with one of your own, although this is not encouraged. It
would, however, allow you to intercept a core event and
modify it before being sent to another client.</small></p>
</td>
</table>
<p><small>When Xlib needs to convert an event from host
format to wire format, your procedure is called with these
arguments:</small></p>
<p><small>__ │</small></p>
<pre><small>(*<i>proc</i>)(<i>display</i>, <i>re</i>, <i>event</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *<i>display</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XEvent *<i>re</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>xEvent *<i>event</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The re argument is a pointer to the host format
event, and the event argument is a pointer to where the
32-byte wire event structure should be stored. You should
fill in the type with the type from the <i>XEvent</i>
structure. All other members then should be copied from the
host format to the <i>xEvent</i> structure.</small></p>
<p><small>__ │</small></p>
<pre><small>Bool (*XESetWireToError(<i>display</i>, <i>error_number</i>, <i>proc</i>)()
Display *<i>display</i>;
int <i>error_number</i>;
Bool (*<i>proc</i>)();
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>error_number</i> Specifies the error
code.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>proc</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the procedure to call when an error is
received.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XESetWireToError</i> function defines a
procedure to be called when an extension error needs to be
converted from wire format to host format. The error number
defines which protocol error code to install the conversion
procedure for. <i>XESetWireToError</i> returns any
previously defined procedure.</small></p>
<p><small>Use this function for extension errors that
contain additional error values beyond those in a core X
error, when multiple wire errors must be combined into a
single Xlib error, or when it is necessary to intercept an X
error before it is otherwise examined.</small></p>
<p><small>When Xlib needs to convert an error from wire
format to host format, the procedure is called with these
arguments:</small></p>
<p><small>__ │</small></p>
<pre><small>Bool (*<i>proc</i>)(<i>display</i>, <i>he</i>, <i>we</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *<i>display</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XErrorEvent *<i>he</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>xError *<i>we</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The he argument is a pointer to where the host
format error should be stored. The structure pointed at by
he is guaranteed to be as large as an <i>XEvent</i>
structure and so can be cast to a type larger than an
<i>XErrorEvent</i> to store additional values. If the error
is to be completely ignored by Xlib (for example, several
protocol error structures will be combined into one Xlib
error), then the function should return <i>False</i>;
otherwise, it should return <i>True</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int (*XESetError(<i>display</i>, <i>extension</i>, <i>proc</i>))()
Display *<i>display</i>;
int <i>extension</i>;
int (*<i>proc</i>)();
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>extension</i></small></p>
</td>
<td width="2%"></td>
<td width="62%">
<p><small>Specifies the extension number.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>proc</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the procedure to call when an error is
received.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>Inside Xlib, there are times that you may want to
suppress the calling of the external error handling when an
error occurs. This allows status to be returned on a call at
the cost of the call being synchronous (though most such
functions are query operations, in any case, and are
typically programmed to be synchronous).</small></p>
<p><small>When Xlib detects a protocol error in
<i>_XReply</i>, it calls your procedure with these
arguments:</small></p>
<p><small>__ │</small></p>
<pre><small>int (*<i>proc</i>)(<i>display</i>, <i>err</i>, <i>codes</i>, <i>ret_code</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *<i>display</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>xError *<i>err</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XExtCodes *<i>codes</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int *<i>ret_code</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The err argument is a pointer to the 32-byte wire
format error. The codes argument is a pointer to the
extension codes structure. The ret_code argument is the
return code you may want <i>_XReply</i> returned
to.</small></p>
<p><small>If your procedure returns a zero value, the error
is not suppressed, and the client’s error handler is
called. (For further information, see section 11.8.2.) If
your procedure returns nonzero, the error is suppressed, and
<i>_XReply</i> returns the value of ret_code.</small></p>
<p><small>__ │</small></p>
<pre><small>char *(*XESetErrorString(<i>display</i>, <i>extension</i>, <i>proc</i>))()
Display *<i>display</i>;
int <i>extension</i>;
char *(*<i>proc</i>)();
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>extension</i></small></p>
</td>
<td width="2%"></td>
<td width="62%">
<p><small>Specifies the extension number.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>proc</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the procedure to call to obtain an
error string.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetErrorText</i> function returns a
string to the user for an error. <i>XESetErrorString</i>
allows you to define a procedure to be called that should
return a pointer to the error message. The following is an
example.</small></p>
<p><small>__ │</small></p>
<pre><small>(*<i>proc</i>)(<i>display</i>, <i>code</i>, <i>codes</i>, <i>buffer</i>, <i>nbytes</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *<i>display</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int <i>code</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XExtCodes *<i>codes</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>char *<i>buffer</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int <i>nbytes</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>│__</small></p>
<p><small>Your procedure is called with the error code for
every error detected. You should copy nbytes of a
null-terminated string containing the error message into
buffer.</small></p>
<p><small>__ │</small></p>
<pre><small>void (*XESetPrintErrorValues(<i>display</i>, <i>extension</i>, <i>proc</i>))()
Display *<i>display</i>;
int <i>extension</i>;
void (*<i>proc</i>)();
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>extension</i></small></p>
</td>
<td width="2%"></td>
<td width="62%">
<p><small>Specifies the extension number.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>proc</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the procedure to call when an error is
printed.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XESetPrintErrorValues</i> function defines
a procedure to be called when an extension error is printed,
to print the error values. Use this function for extension
errors that contain additional error values beyond those in
a core X error. It returns any previously defined
procedure.</small></p>
<p><small>When Xlib needs to print an error, the procedure
is called with these arguments:</small></p>
<p><small>__ │</small></p>
<pre><small>void (*<i>proc</i>)(<i>display</i>, <i>ev</i>, <i>fp</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *<i>display</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XErrorEvent *<i>ev</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>void *<i>fp</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The structure pointed at by ev is guaranteed to
be as large as an <i>XEvent</i> structure and so can be cast
to a type larger than an <i>XErrorEvent</i> to obtain
additional values set by using <i>XESetWireToError</i>. The
underlying type of the fp argument is system dependent; on a
POSIX-compliant system, fp should be cast to type
FILE*.</small></p>
<p><small>__ │</small></p>
<pre><small>int (*XESetFlushGC(<i>display</i>, <i>extension</i>, <i>proc</i>))()
Display *<i>display</i>;
int <i>extension</i>;
int *(*<i>proc</i>)();
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>extension</i></small></p>
</td>
<td width="2%"></td>
<td width="62%">
<p><small>Specifies the extension number.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>proc</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the procedure to call when a GC is
flushed.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The procedure set by the <i>XESetFlushGC</i>
function has the same interface as the procedure set by the
<i>XESetCopyGC</i> function, but is called when a GC cache
needs to be updated in the server.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>int (*XESetBeforeFlush(<i>display</i>, <i>extension</i>, <i>proc</i>))()
Display *<i>display</i>;
int <i>extension</i>;
int *(*<i>proc</i>)();
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>extension</i></small></p>
</td>
<td width="2%"></td>
<td width="62%">
<p><small>Specifies the extension number.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>proc</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the procedure to call when a buffer is
flushed.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XESetBeforeFlush</i> function defines a
procedure to be called when data is about to be sent to the
server. When data is about to be sent, your procedure is
called one or more times with these arguments:</small></p>
<p><small>__ │</small></p>
<pre><small>void (*<i>proc</i>)(<i>display</i>, <i>codes</i>, <i>data</i>, <i>len</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *<i>display</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XExtCodes *<i>codes</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>char *<i>data</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>long <i>len</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The data argument specifies a portion of the
outgoing data buffer, and its length in bytes is specified
by the len argument. Your procedure must not alter the
contents of the data and must not do additional protocol
requests to the same display.</small></p>
<a name="Hooks onto Xlib Data Structures"></a>
<h2>Hooks onto Xlib Data Structures</h2>
<p><small>Various Xlib data structures have provisions for
extension procedures to chain extension supplied data onto a
list. These structures are <i>GC</i>, <i>Visual</i>,
<i>Screen</i>, <i>ScreenFormat</i>, <i>Display</i>, and
<i>XFontStruct</i>. Because the list pointer is always the
first member in the structure, a single set of procedures
can be used to manipulate the data on these
lists.</small></p>
<p><small>The following structure is used in the functions
in this section and is defined in
<<i>X11/Xlib.h</i>>:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct _XExtData {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int number;</small></p>
</td>
<td width="40%">
<p><small>/* number returned by XInitExtension
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>struct _XExtData *next;</small></p>
</td>
<td width="40%">
<p><small>/* next item on list of data for structure
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int (*free_private)();</small></p>
</td>
<td width="40%">
<p><small>/* if defined, called to free private
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XPointer private_data;</small></p>
</td>
<td width="40%">
<p><small>/* data private to this extension. */</small></p>
</td>
</table>
<p><small>} XExtData;</small></p>
<p><small>│__</small></p>
<p><small>When any of the data structures listed above are
freed, the list is walked, and the structure’s free
procedure (if any) is called. If free is NULL, then the
library frees both the data pointed to by the private_data
member and the structure itself.</small></p>
<p><small>__ │</small></p>
<pre><small>union {Display *display;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>GC gc;</small></p>
</td>
<td width="79%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>Visual *visual;</small></p>
</td>
<td width="79%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>Screen *screen;</small></p>
</td>
<td width="79%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>ScreenFormat *pixmap_format;</small></p>
</td>
<td width="79%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="10%">
<p><small>XFontStruct *font } XEDataObject;</small></p>
</td>
<td width="79%">
</td>
</table>
<p><small>│__</small></p>
<p><small>__ │</small></p>
<pre><small>XExtData **XEHeadOfExtensionList(<i>object</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>XEDataObject <i>object</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>object</i></small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>Specifies the object.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XEHeadOfExtensionList</i> function returns
a pointer to the list of extension structures attached to
the specified object. In concert with
<i>XAddToExtensionList</i>, <i>XEHeadOfExtensionList</i>
allows an extension to attach arbitrary data to any of the
structures of types contained in
<i>XEDataObject</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XAddToExtensionList(<i>structure</i>, <i>ext_data</i>)
XExtData **<i>structure</i>;
XExtData *<i>ext_data</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>structure</i></small></p>
</td>
<td width="2%"></td>
<td width="58%">
<p><small>Specifies the extension list.</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>ext_data</i></small></p>
</td>
<td width="4%"></td>
<td width="80%">
<p><small>Specifies the extension data structure to
add.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The structure argument is a pointer to one of the
data structures enumerated above. You must initialize
ext_data->number with the extension number before calling
this function.</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>XExtData *XFindOnExtensionList(<i>structure</i>, <i>number</i>)
struct _XExtData **<i>structure</i>;
int <i>number</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>structure</i></small></p>
</td>
<td width="2%"></td>
<td width="58%">
<p><small>Specifies the extension list.</small></p>
</td>
<td width="21%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>number</i></small></p>
</td>
<td width="8%"></td>
<td width="70%">
<p><small>Specifies the extension number from
<i>XInitExtension</i>.</small></p>
</td>
<td width="9%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XFindOnExtensionList</i> function returns
the first extension data structure for the extension
numbered number. It is expected that an extension will add
at most one extension data structure to any single data
structure’s extension data list. There is no way to
find additional structures.</small></p>
<p><small>The <i>XAllocID</i> macro, which allocates and
returns a resource ID, is defined in
<<i>X11/Xlib.h</i>>.</small></p>
<p><small>__ │</small></p>
<pre><small>XAllocID(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>This macro is a call through the <i>Display</i>
structure to an internal resource ID allocator. It returns a
resource ID that you can use when creating new
resources.</small></p>
<p><small>The <i>XAllocIDs</i> macro allocates and returns
an array of resource ID.</small></p>
<p><small>__ │</small></p>
<pre><small>XAllocIDs(<i>display</i>, <i>ids_return</i>, <i>count</i>)
Display *<i>display</i>;
XID *<i>ids_return</i>;
int <i>count</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>ids_return</i> Returns the resource
IDs.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>rep</i></small></p>
</td>
<td width="14%"></td>
<td width="80%">
<p><small>Specifies the number of resource IDs
requested.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>This macro is a call through the <i>Display</i>
structure to an internal resource ID allocator. It returns
resource IDs to the array supplied by the caller. To
correctly handle automatic reuse of resource IDs, you must
call <i>XAllocIDs</i> when requesting multiple resource IDs.
This call might generate protocol requests.</small></p>
<a name="GC Caching"></a>
<h2>GC Caching</h2>
<p><small>GCs are cached by the library to allow merging of
independent change requests to the same GC into single
protocol requests. This is typically called a write-back
cache. Any extension procedure whose behavior depends on the
contents of a GC must flush the GC cache to make sure the
server has up-to-date contents in its GC.</small></p>
<p><small>The <i>FlushGC</i> macro checks the dirty bits in
the library’s GC structure and calls
<i>_XFlushGCCache</i> if any elements have changed. The
<i>FlushGC</i> macro is defined as follows:</small></p>
<p><small>__ │</small></p>
<pre><small>FlushGC(<i>display</i>, <i>gc</i>)
Display *<i>display</i>;
GC <i>gc</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<p><small>│__</small></p>
<p><small>Note that if you extend the GC to add additional
resource ID components, you should ensure that the library
stub sends the change request immediately. This is because a
client can free a resource immediately after using it, so if
you only stored the value in the cache without forcing a
protocol request, the resource might be destroyed before
being set into the GC. You can use the <i>_XFlushGCCache</i>
procedure to force the cache to be flushed. The
<i>_XFlushGCCache</i> procedure is defined as
follows:</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>_XFlushGCCache(<i>display</i>, <i>gc</i>)
Display *<i>display</i>;
GC <i>gc</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<p><small>│__</small></p>
<a name="Graphics Batching"></a>
<h2>Graphics Batching</h2>
<p><small>If you extend X to add more poly graphics
primitives, you may be able to take advantage of facilities
in the library to allow back-to-back single calls to be
transformed into poly requests. This may dramatically
improve performance of programs that are not written using
poly requests. A pointer to an <i>xReq</i>, called last_req
in the display structure, is the last request being
processed. By checking that the last request type, drawable,
gc, and other options are the same as the new one and that
there is enough space left in the buffer, you may be able to
just extend the previous graphics request by extending the
length field of the request and appending the data to the
buffer. This can improve performance by five times or more
in naive programs. For example, here is the source for the
<i>XDrawPoint</i> stub. (Writing extension stubs is
discussed in the next section.)</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>__ │</small></p>
<!-- INDENTATION -->
<pre><small>#include <X11/Xlibint.h>
/* precompute the maximum size of batching request allowed */
static int size = sizeof(xPolyPointReq) + EPERBATCH * sizeof(xPoint);
XDrawPoint(dpy, d, gc, x, y)
register Display *dpy;
Drawable d;
GC gc;
int x, y; /* INT16 */
{
xPoint *point;
LockDisplay(dpy);
FlushGC(dpy, gc);
{
register xPolyPointReq *req = (xPolyPointReq *) dpy->last_req;
/* if same as previous request, with same drawable, batch requests */
if (
(req->reqType == X_PolyPoint)
&& (req->drawable == d)
&& (req->gc == gc->gid)
&& (req->coordMode == CoordModeOrigin)
&& ((dpy->bufptr + sizeof (xPoint)) <= dpy->bufmax)
&& (((char *)dpy->bufptr - (char *)req) < size) ) {
point = (xPoint *) dpy->bufptr;
req->length += sizeof (xPoint) >> 2;
dpy->bufptr += sizeof (xPoint);
}
else {
GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */
req->drawable = d;
req->gc = gc->gid;
req->coordMode = CoordModeOrigin;
point = (xPoint *) (req + 1);
}
point->x = x;
point->y = y;
}
UnlockDisplay(dpy);
SyncHandle();
}
</small></pre>
</td>
</table>
<p><small>│__</small></p>
<p><small>To keep clients from generating very long
requests that may monopolize the server, there is a symbol
defined in <<i>X11/Xlibint.h</i>> of EPERBATCH on the
number of requests batched. Most of the performance benefit
occurs in the first few merged requests. Note that
<i>FlushGC</i> is called <i>before</i> picking up the value
of last_req, because it may modify this field.</small></p>
<a name="Writing Extension Stubs"></a>
<h2>Writing Extension Stubs</h2>
<p><small>All X requests always contain the length of the
request, expressed as a 16-bit quantity of 32 bits. This
means that a single request can be no more than 256K bytes
in length. Some servers may not support single requests of
such a length. The value of dpy->max_request_size
contains the maximum length as defined by the server
implementation. For further information, see ‘‘X
Window System Protocol.’’</small></p>
<a name="Requests, Replies, and Xproto.h"></a>
<h2>Requests, Replies, and Xproto.h</h2>
<p><small>The <<i>X11/Xproto.h</i>> file contains
three sets of definitions that are of interest to the stub
implementor: request names, request structures, and reply
structures.</small></p>
<p><small>You need to generate a file equivalent to
<<i>X11/Xproto.h</i>> for your extension and need to
include it in your stub procedure. Each stub procedure also
must include <<i>X11/Xlibint.h</i>>.</small></p>
<p><small>The identifiers are deliberately chosen in such a
way that, if the request is called X_DoSomething, then its
request structure is xDoSomethingReq, and its reply is
xDoSomethingReply. The GetReq family of macros, defined in
<<i>X11/Xlibint.h</i>>, takes advantage of this naming
scheme.</small></p>
<p><small>For each X request, there is a definition in
<<i>X11/Xproto.h</i>> that looks similar to
this:</small></p>
<pre><small> #define X_DoSomething 42
</small></pre>
<p><small>In your extension header file, this will be a
minor opcode, instead of a major opcode.</small></p>
<a name="Request Format"></a>
<h2>Request Format</h2>
<p><small>Every request contains an 8-bit major opcode and
a 16-bit length field expressed in units of 4 bytes. Every
request consists of 4 bytes of header (containing the major
opcode, the length field, and a data byte) followed by zero
or more additional bytes of data. The length field defines
the total length of the request, including the header. The
length field in a request must equal the minimum length
required to contain the request. If the specified length is
smaller or larger than the required length, the server
should generate a <i>BadLength</i> error. Unused bytes in a
request are not required to be zero. Extensions should be
designed in such a way that long protocol requests can be
split up into smaller requests, if it is possible to exceed
the maximum request size of the server. The protocol
guarantees the maximum request size to be no smaller than
4096 units (16384 bytes).</small></p>
<p><small>Major opcodes 128 through 255 are reserved for
extensions. Extensions are intended to contain multiple
requests, so extension requests typically have an additional
minor opcode encoded in the second data byte in the request
header, but the placement and interpretation of this minor
opcode as well as all other fields in extension requests are
not defined by the core protocol. Every request is
implicitly assigned a sequence number (starting with one)
used in replies, errors, and events.</small></p>
<p><small>To help but not cure portability problems to
certain machines, the <i>B16</i> and <i>B32</i> macros have
been defined so that they can become bitfield specifications
on some machines. For example, on a Cray, these should be
used for all 16-bit and 32-bit quantities, as discussed
below.</small></p>
<p><small>Most protocol requests have a corresponding
structure typedef in <<i>X11/Xproto.h</i>>, which
looks like:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct _DoSomethingReq {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>CARD8 reqType;</small></p>
</td>
<td width="40%">
<p><small>/* X_DoSomething */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>CARD8 someDatum;</small></p>
</td>
<td width="40%">
<p><small>/* used differently in different requests
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>CARD16 length B16;</small></p>
</td>
<td width="40%">
<p><small>/* total # of bytes in request, divided by 4
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>...</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>/* request-specific data */</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>...</small></p>
</td>
<td width="40%">
</td>
</table>
<p><small>} xDoSomethingReq;</small></p>
<p><small>│__</small></p>
<p><small>If a core protocol request has a single 32-bit
argument, you need not declare a request structure in your
extension header file. Instead, such requests use the
<i>xResourceReq</i> structure in
<<i>X11/Xproto.h</i>>. This structure is used for any
request whose single argument is a <i>Window</i>,
<i>Pixmap</i>, <i>Drawable</i>, <i>GContext</i>,
<i>Font</i>, <i>Cursor</i>, <i>Colormap</i>, <i>Atom</i>, or
<i>VisualID</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct _ResourceReq {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>CARD8 reqType;</small></p>
</td>
<td width="40%">
<p><small>/* the request type, e.g. X_DoSomething
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>BYTE pad;</small></p>
</td>
<td width="40%">
<p><small>/* not used */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>CARD16 length B16;</small></p>
</td>
<td width="40%">
<p><small>/* 2 (= total # of bytes in request, divided by
4) */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>CARD32 id B32;</small></p>
</td>
<td width="40%">
<p><small>/* the Window, Drawable, Font, GContext, etc.
*/</small></p>
</td>
</table>
<p><small>} xResourceReq;</small></p>
<p><small>│__</small></p>
<p><small>If convenient, you can do something similar in
your extension header file.</small></p>
<p><small>In both of these structures, the reqType field
identifies the type of the request (for example, X_MapWindow
or X_CreatePixmap). The length field tells how long the
request is in units of 4-byte longwords. This length
includes both the request structure itself and any
variable-length data, such as strings or lists, that follow
the request structure. Request structures come in different
sizes, but all requests are padded to be multiples of four
bytes long.</small></p>
<p><small>A few protocol requests take no arguments at all.
Instead, they use the <i>xReq</i> structure in
<<i>X11/Xproto.h</i>>, which contains only a reqType
and a length (and a pad byte).</small></p>
<p><small>If the protocol request requires a reply, then
<<i>X11/Xproto.h</i>> also contains a reply structure
typedef:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct _DoSomethingReply {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>BYTE type;</small></p>
</td>
<td width="40%">
<p><small>/* always X_Reply */</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>BYTE someDatum;</small></p>
</td>
<td width="40%">
<p><small>/* used differently in different requests
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>CARD16 sequenceNumber B16;/* # of requests sent
so far */</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>CARD32 length B32;</small></p>
</td>
<td width="40%">
<p><small>/* # of additional bytes, divided by 4
*/</small></p>
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>...</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>/* request-specific data */</small></p>
</td>
<td width="40%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>...</small></p>
</td>
<td width="40%">
</td>
</table>
<p><small>} xDoSomethingReply;</small></p>
<p><small>│__</small></p>
<p><small>Most of these reply structures are 32 bytes long.
If there are not that many reply values, then they contain a
sufficient number of pad fields to bring them up to 32
bytes. The length field is the total number of bytes in the
request minus 32, divided by 4. This length will be nonzero
only if:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The reply structure is followed by
variable-length data, such as a list or string.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="88%">
<p><small>The reply structure is longer than 32
bytes.</small></p>
</td>
<td width="1%">
</td>
</table>
<p><small>Only <i>GetWindowAttributes</i>,
<i>QueryFont</i>, <i>QueryKeymap</i>, and
<i>GetKeyboardControl</i> have reply structures longer than
32 bytes in the core protocol.</small></p>
<p><small>A few protocol requests return replies that
contain no data. <<i>X11/Xproto.h</i>> does not define
reply structures for these. Instead, they use the
<i>xGenericReply</i> structure, which contains only a type,
length, and sequence number (and sufficient padding to make
it 32 bytes long).</small></p>
<a name="Starting to Write a Stub Procedure"></a>
<h2>Starting to Write a Stub Procedure</h2>
<p><small>An Xlib stub procedure should start like
this:</small></p>
<pre><small> #include "<X11/Xlibint.h>
XDoSomething (arguments, ... )
/* argument declarations */
{
register XDoSomethingReq *req;
...
</small></pre>
<p><small>If the protocol request has a reply, then the
variable declarations should include the reply structure for
the request. The following is an example:</small></p>
<pre><small> xDoSomethingReply rep;
</small></pre>
<a name="Locking Data Structures"></a>
<h2>Locking Data Structures</h2>
<p><small>To lock the display structure for systems that
want to support multithreaded access to a single display
connection, each stub will need to lock its critical
section. Generally, this section is the point from just
before the appropriate GetReq call until all arguments to
the call have been stored into the buffer. The precise
instructions needed for this locking depend upon the machine
architecture. Two calls, which are generally implemented as
macros, have been provided.</small></p>
<p><small>__ │</small></p>
<pre><small>LockDisplay(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<pre><small>UnlockDisplay(<i>display</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small>│__</small></p>
<a name="Sending the Protocol Request and Arguments"></a>
<h2>Sending the Protocol Request and Arguments</h2>
<p><small>After the variable declarations, a stub procedure
should call one of four macros defined in
<<i>X11/Xlibint.h</i>>: <i>GetReq</i>,
<i>GetReqExtra</i>, <i>GetResReq</i>, or <i>GetEmptyReq</i>.
All of these macros take, as their first argument, the name
of the protocol request as declared in
<<i>X11/Xproto.h</i>> except with X_ removed. Each one
declares a <i>Display</i> structure pointer, called dpy, and
a pointer to a request structure, called req, which is of
the appropriate type. The macro then appends the request
structure to the output buffer, fills in its type and length
field, and sets req to point to it.</small></p>
<p><small>If the protocol request has no arguments (for
instance, X_GrabServer), then use
<i>GetEmptyReq</i>.</small></p>
<pre><small> GetEmptyReq (DoSomething, req);
</small></pre>
<p><small>If the protocol request has a single 32-bit
argument (such as a <i>Pixmap</i>, <i>Window</i>,
<i>Drawable</i>, <i>Atom</i>, and so on), then use
<i>GetResReq</i>. The second argument to the macro is the
32-bit object. <i>X_MapWindow</i> is a good
example.</small></p>
<pre><small> GetResReq (DoSomething, rid, req);
</small></pre>
<p><small>The rid argument is the <i>Pixmap</i>,
<i>Window</i>, or other resource ID.</small></p>
<p><small>If the protocol request takes any other argument
list, then call <i>GetReq</i>. After the <i>GetReq</i>, you
need to set all the other fields in the request structure,
usually from arguments to the stub procedure.</small></p>
<pre><small> GetReq (DoSomething, req);
/* fill in arguments here */
req->arg1 = arg1;
req->arg2 = arg2;
...
</small></pre>
<p><small>A few stub procedures (such as <i>XCreateGC</i>
and <i>XCreatePixmap</i>) return a resource ID to the caller
but pass a resource ID as an argument to the protocol
request. Such procedures use the macro <i>XAllocID</i> to
allocate a resource ID from the range of IDs that were
assigned to this client when it opened the
connection.</small></p>
<pre><small> rid = req->rid = XAllocID();
...
return (rid);
</small></pre>
<p><small>Finally, some stub procedures transmit a fixed
amount of variable-length data after the request. Typically,
these procedures (such as <i>XMoveWindow</i> and
<i>XSetBackground</i>) are special cases of more general
functions like <i>XMoveResizeWindow</i> and
<i>XChangeGC</i>. These procedures use <i>GetReqExtra</i>,
which is the same as <i>GetReq</i> except that it takes an
additional argument (the number of extra bytes to allocate
in the output buffer after the request structure). This
number should always be a multiple of four.</small></p>
<a name="Variable Length Arguments"></a>
<h2>Variable Length Arguments</h2>
<p><small>Some protocol requests take additional
variable-length data that follow the <i>xDoSomethingReq</i>
structure. The format of this data varies from request to
request. Some requests require a sequence of 8-bit bytes,
others a sequence of 16-bit or 32-bit entities, and still
others a sequence of structures.</small></p>
<p><small>It is necessary to add the length of any
variable-length data to the length field of the request
structure. That length field is in units of 32-bit
longwords. If the data is a string or other sequence of
8-bit bytes, then you must round the length up and shift it
before adding:</small></p>
<pre><small> req->length += (nbytes+3)>>2;
</small></pre>
<p><small>To transmit variable-length data, use the
<i>Data</i> macros. If the data fits into the output buffer,
then this macro copies it to the buffer. If it does not fit,
however, the <i>Data</i> macro calls <i>_XSend</i>, which
transmits first the contents of the buffer and then your
data. The <i>Data</i> macros take three arguments: the
display, a pointer to the beginning of the data, and the
number of bytes to be sent.</small></p>
<p><small>__ │</small></p>
<pre><small>Data(<i>display</i>, (char *) <i>data</i>, <i>nbytes</i>);
Data16(<i>display</i>, (short *) <i>data</i>, <i>nbytes</i>);
Data32(<i>display</i>, (long *) <i>data</i>, <i>nbytes</i>);
</small></pre>
<p><small>│__</small></p>
<p><small><i>Data</i>, <i>Data16</i>, and <i>Data32</i> are
macros that may use their last argument more than once, so
that argument should be a variable rather than an expression
such as ‘‘nitems*sizeof(item)’’. You
should do that kind of computation in a separate statement
before calling them. Use the appropriate macro when sending
byte, short, or long data.</small></p>
<p><small>If the protocol request requires a reply, then
call the procedure <i>_XSend</i> instead of the <i>Data</i>
macro. <i>_XSend</i> takes the same arguments, but because
it sends your data immediately instead of copying it into
the output buffer (which would later be flushed anyway by
the following call on <i>_XReply</i>), it is
faster.</small></p>
<a name="Replies"></a>
<h2>Replies</h2>
<p><small>If the protocol request has a reply, then call
<i>_XReply</i> after you have finished dealing with all the
fixed-length and variable-length arguments. <i>_XReply</i>
flushes the output buffer and waits for an <i>xReply</i>
packet to arrive. If any events arrive in the meantime,
<i>_XReply</i> places them in the queue for later
use.</small></p>
<p><small>__ │</small></p>
<pre><small>Status _XReply(<i>display</i>, <i>rep</i>, <i>extra</i>, <i>discard</i>)
Display *<i>display</i>;
xReply *<i>rep</i>;
int <i>extra</i>;
Bool <i>discard</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>rep</i></small></p>
</td>
<td width="14%"></td>
<td width="60%">
<p><small>Specifies the reply structure.</small></p>
</td>
<td width="19%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>extra</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies the number of 32-bit words expected
after the replay.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>discard</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies if any data beyond that specified in
the extra argument should be discarded.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>_XReply</i> function waits for a reply
packet and copies its contents into the specified rep.
<i>_XReply</i> handles error and event packets that occur
before the reply is received. <i>_XReply</i> takes four
arguments:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>A <i>Display</i> * structure</small></p>
</td>
<td width="47%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>A pointer to a reply structure (which must be
cast to an <i>xReply</i> *)</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>The number of additional 32-bit words (beyond
sizeof(<i>xReply</i>) = 32 bytes) in the reply
structure</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>A Boolean that indicates whether <i>_XReply</i>
is to discard any additional bytes beyond those it was told
to read</small></p>
</td>
</table>
<p><small>Because most reply structures are 32 bytes long,
the third argument is usually 0. The only core protocol
exceptions are the replies to <i>GetWindowAttributes</i>,
<i>QueryFont</i>, <i>QueryKeymap</i>, and
<i>GetKeyboardControl</i>, which have longer
replies.</small></p>
<p><small>The last argument should be <i>False</i> if the
reply structure is followed by additional variable-length
data (such as a list or string). It should be <i>True</i> if
there is not any variable-length data.</small></p>
<p align=center><small>Note</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>This last argument is provided for
upward-compatibility reasons to allow a client to
communicate properly with a hypothetical later version of
the server that sends more data than the client expected.
For example, some later version of
<i>GetWindowAttributes</i> might use a larger, but
compatible, <i>xGetWindowAttributesReply</i> that contains
additional attribute data at the end.</small></p>
</td>
</table>
<p><small><i>_XReply</i> returns <i>True</i> if it received
a reply successfully or <i>False</i> if it received any sort
of error.</small></p>
<p><small>For a request with a reply that is not followed
by variable-length data, you write something
like:</small></p>
<pre><small> _XReply(display, (xReply *)&rep, 0, True);
*ret1 = rep.ret1;
*ret2 = rep.ret2;
*ret3 = rep.ret3;
...
UnlockDisplay(dpy);
SyncHandle();
return (rep.ret4);
}
</small></pre>
<p><small>If there is variable-length data after the reply,
change the <i>True</i> to <i>False</i>, and use the
appropriate <i>_XRead</i> function to read the
variable-length data.</small></p>
<p><small>__ │</small></p>
<pre><small>_XRead(<i>display</i>, <i>data_return</i>, <i>nbytes</i>)
Display *<i>display</i>;
char *<i>data_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<p><small>long <i>nbytes</i>;</small></p>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>data_return</i> Specifies the
buffer.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>nbytes</i></small></p>
</td>
<td width="8%"></td>
<td width="78%">
<p><small>Specifies the number of bytes
required.</small></p>
</td>
<td width="1%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>_XRead</i> function reads the specified
number of bytes into data_return.</small></p>
<p><small>__ │</small></p>
<pre><small>_XRead16(<i>display</i>, <i>data_return</i>, <i>nbytes</i>)
Display *<i>display</i>;
short *<i>data_return</i>;
long <i>nbytes</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>data_return</i> Specifies the
buffer.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>nbytes</i></small></p>
</td>
<td width="8%"></td>
<td width="78%">
<p><small>Specifies the number of bytes
required.</small></p>
</td>
<td width="1%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>_XRead16</i> function reads the specified
number of bytes, unpacking them as 16-bit quantities, into
the specified array as shorts.</small></p>
<p><small>__ │</small></p>
<pre><small>_XRead32(<i>display</i>, <i>data_return</i>, <i>nbytes</i>)
Display *<i>display</i>;
long *<i>data_return</i>;
long <i>nbytes</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>data_return</i> Specifies the
buffer.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>nbytes</i></small></p>
</td>
<td width="8%"></td>
<td width="78%">
<p><small>Specifies the number of bytes
required.</small></p>
</td>
<td width="1%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>_XRead32</i> function reads the specified
number of bytes, unpacking them as 32-bit quantities, into
the specified array as longs.</small></p>
<p><small>__ │</small></p>
<pre><small>_XRead16Pad(<i>display</i>, <i>data_return</i>, <i>nbytes</i>)
Display *<i>display</i>;
short *<i>data_return</i>;
long <i>nbytes</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>data_return</i> Specifies the
buffer.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>nbytes</i></small></p>
</td>
<td width="8%"></td>
<td width="78%">
<p><small>Specifies the number of bytes
required.</small></p>
</td>
<td width="1%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>_XRead16Pad</i> function reads the
specified number of bytes, unpacking them as 16-bit
quantities, into the specified array as shorts. If the
number of bytes is not a multiple of four,
<i>_XRead16Pad</i> reads and discards up to two additional
pad bytes.</small></p>
<p><small>__ │</small></p>
<pre><small>_XReadPad(<i>display</i>, <i>data_return</i>, <i>nbytes</i>)
Display *<i>display</i>;
char *<i>data_return</i>;
long <i>nbytes</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<p><small><i>data_return</i> Specifies the
buffer.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>nbytes</i></small></p>
</td>
<td width="8%"></td>
<td width="78%">
<p><small>Specifies the number of bytes
required.</small></p>
</td>
<td width="1%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>_XReadPad</i> function reads the specified
number of bytes into data_return. If the number of bytes is
not a multiple of four, <i>_XReadPad</i> reads and discards
up to three additional pad bytes.</small></p>
<p><small>Each protocol request is a little different. For
further information, see the Xlib sources for
examples.</small></p>
<a name="Synchronous Calling"></a>
<h2>Synchronous Calling</h2>
<p><small>Each procedure should have a call, just before
returning to the user, to a macro called <i>SyncHandle</i>.
If synchronous mode is enabled (see <i>XSynchronize</i>),
the request is sent immediately. The library, however, waits
until any error the procedure could generate at the server
has been handled.</small></p>
<a name="Allocating and Deallocating Memory"></a>
<h2>Allocating and Deallocating Memory</h2>
<p><small>To support the possible reentry of these
procedures, you must observe several conventions when
allocating and deallocating memory, most often done when
returning data to the user from the window system of a size
the caller could not know in advance (for example, a list of
fonts or a list of extensions). The standard C library
functions on many systems are not protected against signals
or other multithreaded uses. The following analogies to
standard I/O library functions have been
defined:</small></p>
<p align=center><small><img src="grohtml-1439282.png"></small></p>
<p><small>These should be used in place of any calls you
would make to the normal C library functions.</small></p>
<p><small>If you need a single scratch buffer inside a
critical section (for example, to pack and unpack data to
and from the wire protocol), the general memory allocators
may be too expensive to use (particularly in output
functions, which are performance critical). The following
function returns a scratch buffer for use within a critical
section:</small></p>
<p><small>__ │</small></p>
<pre><small>char *_XAllocScratch(<i>display</i>, <i>nbytes</i>)
Display *<i>display</i>;
unsigned long <i>nbytes</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>nbytes</i></small></p>
</td>
<td width="8%"></td>
<td width="78%">
<p><small>Specifies the number of bytes
required.</small></p>
</td>
<td width="1%">
</td>
</table>
<p><small>│__</small></p>
<p><small>This storage must only be used inside of a
critical section of your stub. The returned pointer cannot
be assumed valid after any call that might permit another
thread to execute inside Xlib. For example, the pointer
cannot be assumed valid after any use of the <i>GetReq</i>
or <i>Data</i> families of macros, after any use of
<i>_XReply</i>, or after any use of the <i>_XSend</i> or
<i>_XRead</i> families of functions.</small></p>
<p><small>The following function returns a scratch buffer
for use across critical sections:</small></p>
<p><small>__ │</small></p>
<pre><small>char *_XAllocTemp(<i>display</i>, <i>nbytes</i>)
Display *<i>display</i>;
unsigned long <i>nbytes</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>nbytes</i></small></p>
</td>
<td width="8%"></td>
<td width="78%">
<p><small>Specifies the number of bytes
required.</small></p>
</td>
<td width="1%">
</td>
</table>
<p><small>│__</small></p>
<p><small>This storage can be used across calls that might
permit another thread to execute inside Xlib. The storage
must be explicitly returned to Xlib. The following function
returns the storage:</small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="19%"></td>
<td width="80%">
<p><small>__ │</small></p>
</td>
</table>
<pre><small>void _XFreeTemp(<i>display</i>, <i>buf</i>, <i>nbytes</i>)
Display *<i>display</i>;
char *<i>buf</i>;
unsigned long <i>nbytes</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="6%">
<p><small><i>buf</i></small></p>
</td>
<td width="14%"></td>
<td width="62%">
<p><small>Specifies the buffer to return.</small></p>
</td>
<td width="17%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>nbytes</i></small></p>
</td>
<td width="8%"></td>
<td width="66%">
<p><small>Specifies the size of the buffer.</small></p>
</td>
<td width="13%">
</td>
</table>
<p><small>│__</small></p>
<p><small>You must pass back the same pointer and size that
were returned by <i>_XAllocTemp</i>.</small></p>
<a name="Portability Considerations"></a>
<h2>Portability Considerations</h2>
<p><small>Many machine architectures, including many of the
more recent RISC architectures, do not correctly access data
at unaligned locations; their compilers pad out structures
to preserve this characteristic. Many other machines capable
of unaligned references pad inside of structures as well to
preserve alignment, because accessing aligned data is
usually much faster. Because the library and the server use
structures to access data at arbitrary points in a byte
stream, all data in request and reply packets <i>must</i> be
naturally aligned; that is, 16-bit data starts on 16-bit
boundaries in the request and 32-bit data on 32-bit
boundaries. All requests <i>must</i> be a multiple of 32
bits in length to preserve the natural alignment in the data
stream. You must pad structures out to 32-bit boundaries.
Pad information does not have to be zeroed unless you want
to preserve such fields for future use in your protocol
requests. Floating point varies radically between machines
and should be avoided completely if at all
possible.</small></p>
<p><small>This code may run on machines with 16-bit ints.
So, if any integer argument, variable, or return value
either can take only nonnegative values or is declared as a
<i>CARD16</i> in the protocol, be sure to declare it as
<i>unsigned int</i> and not as <i>int</i>. (This, of course,
does not apply to Booleans or enumerations.)</small></p>
<p><small>Similarly, if any integer argument or return
value is declared <i>CARD32</i> in the protocol, declare it
as an <i>unsigned long</i> and not as <i>int</i> or
<i>long</i>. This also goes for any internal variables that
may take on values larger than the maximum 16-bit
<i>unsigned int</i>.</small></p>
<p><small>The library currently assumes that a <i>char</i>
is 8 bits, a <i>short</i> is 16 bits, an <i>int</i> is 16 or
32 bits, and a <i>long</i> is 32 bits. The <i>PackData</i>
macro is a half-hearted attempt to deal with the possibility
of 32 bit shorts. However, much more work is needed to make
this work properly.</small></p>
<a name="Deriving the Correct Extension Opcode"></a>
<h2>Deriving the Correct Extension Opcode</h2>
<p><small>The remaining problem a writer of an extension
stub procedure faces that the core protocol does not face is
to map from the call to the proper major and minor opcodes.
While there are a number of strategies, the simplest and
fastest is outlined below.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small>1.</small></p>
</td>
<td width="6%"></td>
<td width="90%">
<p><small>Declare an array of pointers, _NFILE long (this
is normally found in <<i>stdio.h</i>> and is the
number of file descriptors supported on the system) of type
<i>XExtCodes</i>. Make sure these are all initialized to
NULL.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small>2.</small></p>
</td>
<td width="6%"></td>
<td width="90%">
<p><small>When your stub is entered, your initialization
test is just to use the display pointer passed in to access
the file descriptor and an index into the array. If the
entry is NULL, then this is the first time you are entering
the procedure for this display. Call your initialization
procedure and pass to it the display pointer.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small>3.</small></p>
</td>
<td width="6%"></td>
<td width="90%">
<p><small>Once in your initialization procedure, call
<i>XInitExtension</i>; if it succeeds, store the pointer
returned into this array. Make sure to establish a close
display handler to allow you to zero the entry. Do whatever
other initialization your extension requires. (For example,
install event handlers and so on.) Your initialization
procedure would normally return a pointer to the
<i>XExtCodes</i> structure for this extension, which is what
would normally be found in your array of
pointers.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small>4.</small></p>
</td>
<td width="6%"></td>
<td width="90%">
<p><small>After returning from your initialization
procedure, the stub can now continue normally, because it
has its major opcode safely in its hand in the
<i>XExtCodes</i> structure.</small></p>
</td>
</table>
<p><small><b>20</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b>Appendix D</b></p>
<p align=center><b>Compatibility Functions</b></p>
<p><small>The X Version 11 and X Version 10 functions
discussed in this appendix are obsolete, have been
superseded by newer X Version 11 functions, and are
maintained for compatibility reasons only.</small></p>
<a name="X Version 11 Compatibility Functions"></a>
<h2>X Version 11 Compatibility Functions</h2>
<p><small>You can use the X Version 11 compatibility
functions to:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="46%">
<p><small>Set standard properties</small></p>
</td>
<td width="43%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="62%">
<p><small>Set and get window sizing hints</small></p>
</td>
<td width="27%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="84%">
<p><small>Set and get an <i>XStandardColormap</i>
structure</small></p>
</td>
<td width="5%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>Parse window geometry</small></p>
</td>
<td width="47%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="52%">
<p><small>Get X environment defaults</small></p>
</td>
<td width="37%">
</td>
</table>
<a name="Setting Standard Properties"></a>
<h2>Setting Standard Properties</h2>
<p><small>To specify a minimum set of properties describing
the simplest application, use <i>XSetStandardProperties</i>.
This function has been superseded by <i>XSetWMProperties</i>
and sets all or portions of the WM_NAME, WM_ICON_NAME,
WM_HINTS, WM_COMMAND, and WM_NORMAL_HINTS
properties.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetStandardProperties(<i>display</i>, <i>w</i>, <i>window_name</i>, <i>icon_name</i>, <i>icon_pixmap</i>, <i>argv</i>, <i>argc</i>, <i>hints</i>)
Display *<i>display</i>;
Window <i>w</i>;
char *<i>window_name</i>;
char *<i>icon_name</i>;
Pixmap <i>icon_pixmap</i>;
char **<i>argv</i>;
int <i>argc</i>;
XSizeHints *<i>hints</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>window_name</i> Specifies the window name,
which should be a null-terminated string.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="18%">
<p><small><i>icon_name</i></small></p>
</td>
<td width="2%"></td>
<td width="80%">
<p><small>Specifies the icon name, which should be a
null-terminated string.</small></p>
</td>
</table>
<p><small><i>icon_pixmap</i> Specifies the bitmap that is
to be used for the icon or <i>None</i>.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>argv</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the application’s argument
list.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>argc</i></small></p>
</td>
<td width="12%"></td>
<td width="68%">
<p><small>Specifies the number of arguments.</small></p>
</td>
<td width="11%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>hints</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies a pointer to the size hints for the
window in its normal state.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetStandardProperties</i> function
provides a means by which simple applications set the most
essential properties with a single call.
<i>XSetStandardProperties</i> should be used to give a
window manager some information about your program’s
preferences. It should not be used by applications that need
to communicate more information than is possible with
<i>XSetStandardProperties</i>. (Typically, argv is the argv
array of your main program.) If the strings are not in the
Host Portable Character Encoding, the result is
implementation-dependent.</small></p>
<p><small><i>XSetStandardProperties</i> can generate
<i>BadAlloc</i> and <i>BadWindow</i> errors.</small></p>
<a name="Setting and Getting Window Sizing Hints"></a>
<h2>Setting and Getting Window Sizing Hints</h2>
<p><small>Xlib provides functions that you can use to set
or get window sizing hints. The functions discussed in this
section use the flags and the <i>XSizeHints</i> structure,
as defined in the <<i>X11/Xutil.h</i>> header file and
use the WM_NORMAL_HINTS property.</small></p>
<p><small>To set the size hints for a given window in its
normal state, use <i>XSetNormalHints</i>. This function has
been superseded by <i>XSetWMNormalHints</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetNormalHints(<i>display</i>, <i>w</i>, <i>hints</i>)
Display *<i>display</i>;
Window <i>w</i>;
XSizeHints *<i>hints</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>hints</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies a pointer to the size hints for the
window in its normal state.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetNormalHints</i> function sets the size
hints structure for the specified window. Applications use
<i>XSetNormalHints</i> to inform the window manager of the
size or position desirable for that window. In addition, an
application that wants to move or resize itself should call
<i>XSetNormalHints</i> and specify its new desired location
and size as well as making direct Xlib calls to move or
resize. This is because window managers may ignore
redirected configure requests, but they pay attention to
property changes.</small></p>
<p><small>To set size hints, an application not only must
assign values to the appropriate members in the hints
structure but also must set the flags member of the
structure to indicate which information is present and where
it came from. A call to <i>XSetNormalHints</i> is
meaningless, unless the flags member is set to indicate
which members of the structure have been assigned
values.</small></p>
<p><small><i>XSetNormalHints</i> can generate
<i>BadAlloc</i> and <i>BadWindow</i> errors.</small></p>
<p><small>To return the size hints for a window in its
normal state, use <i>XGetNormalHints</i>. This function has
been superseded by <i>XGetWMNormalHints</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetNormalHints(<i>display</i>, <i>w</i>, <i>hints_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
XSizeHints *<i>hints_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>hints_return</i> Returns the size hints for
the window in its normal state.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetNormalHints</i> function returns the
size hints for a window in its normal state. It returns a
nonzero status if it succeeds or zero if the application
specified no normal size hints for this window.</small></p>
<p><small><i>XGetNormalHints</i> can generate a
<i>BadWindow</i> error.</small></p>
<p><small>The next two functions set and read the
WM_ZOOM_HINTS property.</small></p>
<p><small>To set the zoom hints for a window, use
<i>XSetZoomHints</i>. This function is no longer supported
by the <i>Inter-Client Communication Conventions
Manual</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetZoomHints(<i>display</i>, <i>w</i>, <i>zhints</i>)
Display *<i>display</i>;
Window <i>w</i>;
XSizeHints *<i>zhints</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>zhints</i></small></p>
</td>
<td width="8%"></td>
<td width="76%">
<p><small>Specifies a pointer to the zoom
hints.</small></p>
</td>
<td width="3%">
</td>
</table>
<p><small>│__</small></p>
<p><small>Many window managers think of windows in one of
three states: iconic, normal, or zoomed. The
<i>XSetZoomHints</i> function provides the window manager
with information for the window in the zoomed
state.</small></p>
<p><small><i>XSetZoomHints</i> can generate <i>BadAlloc</i>
and <i>BadWindow</i> errors.</small></p>
<p><small>To read the zoom hints for a window, use
<i>XGetZoomHints</i>. This function is no longer supported
by the <i>Inter-Client Communication Conventions
Manual</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetZoomHints(<i>display</i>, <i>w</i>, <i>zhints_return</i>)
Display *<i>display</i>;
Window <i>w</i>;
XSizeHints *<i>zhints_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>zhints_return</i> Returns the zoom
hints.</small></p>
<p><small>│__</small></p>
<p><small>The <i>XGetZoomHints</i> function returns the
size hints for a window in its zoomed state. It returns a
nonzero status if it succeeds or zero if the application
specified no zoom size hints for this window.</small></p>
<p><small><i>XGetZoomHints</i> can generate a
<i>BadWindow</i> error.</small></p>
<p><small>To set the value of any property of type
WM_SIZE_HINTS, use <i>XSetSizeHints</i>. This function has
been superseded by <i>XSetWMSizeHints</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetSizeHints(<i>display</i>, <i>w</i>, <i>hints</i>, <i>property</i>)
Display *<i>display</i>;
Window <i>w</i>;
XSizeHints *<i>hints</i>;
Atom <i>property</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>hints</i></small></p>
</td>
<td width="10%"></td>
<td width="76%">
<p><small>Specifies a pointer to the size
hints.</small></p>
</td>
<td width="3%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>property</i></small></p>
</td>
<td width="4%"></td>
<td width="56%">
<p><small>Specifies the property name.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetSizeHints</i> function sets the
<i>XSizeHints</i> structure for the named property and the
specified window. This is used by <i>XSetNormalHints</i> and
<i>XSetZoomHints</i> and can be used to set the value of any
property of type WM_SIZE_HINTS. Thus, it may be useful if
other properties of that type get defined.</small></p>
<p><small><i>XSetSizeHints</i> can generate
<i>BadAlloc</i>, <i>BadAtom</i>, and <i>BadWindow</i>
errors.</small></p>
<p><small>To read the value of any property of type
WM_SIZE_HINTS, use <i>XGetSizeHints</i>. This function has
been superseded by <i>XGetWMSizeHints</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetSizeHints(<i>display</i>, <i>w</i>, <i>hints_return</i>, <i>property</i>)
Display *<i>display</i>;
Window <i>w</i>;
XSizeHints *<i>hints_return</i>;
Atom <i>property</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>hints_return</i> Returns the size
hints.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>property</i></small></p>
</td>
<td width="4%"></td>
<td width="56%">
<p><small>Specifies the property name.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetSizeHints</i> function returns the
<i>XSizeHints</i> structure for the named property and the
specified window. This is used by <i>XGetNormalHints</i> and
<i>XGetZoomHints</i>. It also can be used to retrieve the
value of any property of type WM_SIZE_HINTS. Thus, it may be
useful if other properties of that type get defined.
<i>XGetSizeHints</i> returns a nonzero status if a size hint
was defined or zero otherwise.</small></p>
<p><small><i>XGetSizeHints</i> can generate <i>BadAtom</i>
and <i>BadWindow</i> errors.</small></p>
<a name="Getting and Setting an XStandardColormap Structure"></a>
<h2>Getting and Setting an XStandardColormap Structure</h2>
<p><small>To get the <i>XStandardColormap</i> structure
associated with one of the described atoms, use
<i>XGetStandardColormap</i>. This function has been
superseded by <i>XGetRGBColormap</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>Status XGetStandardColormap(<i>display</i>, <i>w</i>, <i>colormap_return</i>, <i>property</i>)
Display *<i>display</i>;
Window <i>w</i>;
XStandardColormap *<i>colormap_return</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<p><small>Atom <i>property</i>;</small></p>
<td width="11%"></td>
<td width="-2%"></td>
<td width="50%"></td>
<td width="40%">
<p><small>/* RGB_BEST_MAP, etc. */</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<p><small><i>colormap_return</i> Returns the colormap
associated with the specified atom.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>property</i></small></p>
</td>
<td width="4%"></td>
<td width="56%">
<p><small>Specifies the property name.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetStandardColormap</i> function returns
the colormap definition associated with the atom supplied as
the property argument. <i>XGetStandardColormap</i> returns a
nonzero status if successful and zero otherwise. For
example, to fetch the standard <i>GrayScale</i> colormap for
a display, you use <i>XGetStandardColormap</i> with the
following syntax:</small></p>
<p><small>__ │</small></p>
<pre><small>XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_MAP);
</small></pre>
<p><small>│__</small></p>
<p><small>See section 14.3 for the semantics of standard
colormaps.</small></p>
<p><small><i>XGetStandardColormap</i> can generate
<i>BadAtom</i> and <i>BadWindow</i> errors.</small></p>
<p><small>To set a standard colormap, use
<i>XSetStandardColormap</i>. This function has been
superseded by <i>XSetRGBColormap</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XSetStandardColormap(<i>display</i>, <i>w</i>, <i>colormap</i>, <i>property</i>)
Display *<i>display</i>;
Window <i>w</i>;
XStandardColormap *<i>colormap</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<p><small>Atom <i>property</i>;</small></p>
<td width="11%"></td>
<td width="-2%"></td>
<td width="50%"></td>
<td width="40%">
<p><small>/* RGB_BEST_MAP, etc. */</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>w</i></small></p>
</td>
<td width="18%"></td>
<td width="42%">
<p><small>Specifies the window.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>colormap</i></small></p>
</td>
<td width="4%"></td>
<td width="46%">
<p><small>Specifies the colormap.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>property</i></small></p>
</td>
<td width="4%"></td>
<td width="56%">
<p><small>Specifies the property name.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XSetStandardColormap</i> function usually
is only used by window or session managers.</small></p>
<p><small><i>XSetStandardColormap</i> can generate
<i>BadAlloc</i>, <i>BadAtom</i>, <i>BadDrawable</i>, and
<i>BadWindow</i> errors.</small></p>
<a name="Parsing Window Geometry"></a>
<h2>Parsing Window Geometry</h2>
<p><small>To parse window geometry given a user-specified
position and a default position, use <i>XGeometry</i>. This
function has been superseded by
<i>XWMGeometry</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>int XGeometry(<i>display</i>, <i>screen</i>, <i>position</i>, <i>default_position</i>, <i>bwidth</i>, <i>fwidth</i>, <i>fheight</i>, <i>xadder</i>,
<i> yadder</i>, <i>x_return</i>, <i>y_return</i>, <i>width_return</i>, <i>height_return</i>)
Display *<i>display</i>;
int <i>screen</i>;
char *<i>position</i>, *<i>default_position</i>;
unsigned int <i>bwidth</i>;
unsigned int <i>fwidth</i>, <i>fheight</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<p><small>int <i>xadder</i>, <i>yadder</i>;</small></p>
</table>
<p><small>int *<i>x_return</i>, *<i>y_return</i>;<br>
int *<i>width_return</i>, *<i>height_return</i>;</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>screen</i></small></p>
</td>
<td width="8%"></td>
<td width="42%">
<p><small>Specifies the screen.</small></p>
</td>
<td width="37%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>position</i></small></p>
</td>
<td width="83%">
</td>
</table>
<p><small><i>default_position</i> Specify the geometry
specifications.</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>bwidth</i></small></p>
</td>
<td width="8%"></td>
<td width="54%">
<p><small>Specifies the border width.</small></p>
</td>
<td width="25%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>fheight</i></small></p>
</td>
<td width="85%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>fwidth</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify the font height and width in pixels
(increment size).</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>xadder</i></small></p>
</td>
<td width="87%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>yadder</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specify additional interior padding needed in the
window.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>x_return</i></small></p>
</td>
<td width="83%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="16%">
<p><small><i>y_return</i></small></p>
</td>
<td width="4%"></td>
<td width="54%">
<p><small>Return the x and y offsets.</small></p>
</td>
<td width="25%">
</td>
</table>
<p><small><i>width_return</i></small></p>
<p><small><i>height_return</i> Return the width and height
determined.</small></p>
<p><small>│__</small></p>
<p><small>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
<i>XGeometry</i> function returns the position the window
should be placed given a position and a default position.
<i>XGeometry</i> determines the placement of a window using
a geometry specification as specified by
<i>XParseGeometry</i> and the additional information about
the window. Given a fully qualified default geometry
specification and an incomplete geometry specification,
<i>XParseGeometry</i> returns a bitmask value as defined
above in the <i>XParseGeometry</i> call, by using the
position argument.</small></p>
<p><small>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.</small></p>
<a name="Getting the X Environment Defaults"></a>
<h2>Getting the X Environment Defaults</h2>
<p><small>The <i>XGetDefault</i> function provides a
primitive interface to the resource manager facilities
discussed in chapter 15. It is only useful in very simple
applications.</small></p>
<p><small>__ │</small></p>
<pre><small>char *XGetDefault(<i>display</i>, <i>program</i>, <i>option</i>)
Display *<i>display</i>;
char *<i>program</i>;
char *<i>option</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>program</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the program name for the Xlib defaults
(usually argv[0] of the main program).</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>option</i></small></p>
</td>
<td width="8%"></td>
<td width="52%">
<p><small>Specifies the option name.</small></p>
</td>
<td width="27%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XGetDefault</i> function returns the value
of the resource <i>prog</i>.<i>option</i>, where <i>prog</i>
is the program argument with the directory prefix removed
and <i>option</i> must be a single component. Note that
multilevel resources cannot be used with <i>XGetDefault</i>.
The class "Program.Name" is always used for the
resource lookup. If the specified option name does not exist
for this program, <i>XGetDefault</i> returns NULL. The
strings returned by <i>XGetDefault</i> are owned by Xlib and
should not be modified or freed by the client.</small></p>
<p><small>If a database has been set with
<i>XrmSetDatabase</i>, that database is used for the lookup.
Otherwise, a database is created and is set in the display
(as if by calling <i>XrmSetDatabase</i>). The database is
created in the current locale. To create a database,
<i>XGetDefault</i> 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 <i>$HOME/.Xdefaults</i>. After loading these defaults,
<i>XGetDefault</i> 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,
<i>XGetDefault</i> looks for <i>$HOME/.Xdefaults-name, where
name specifies the name of the machine on which the
application is running.</i></small></p>
<a name="X Version 10 Compatibility Functions"></a>
<h2>X Version 10 Compatibility Functions</h2>
<p><small>You can use the X Version 10 compatibility
functions to:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="66%">
<p><small>Draw and fill polygons and curves</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="64%">
<p><small>Associate user data with a value</small></p>
</td>
<td width="25%">
</td>
</table>
<a name="Drawing and Filling Polygons and Curves"></a>
<h2>Drawing and Filling Polygons and Curves</h2>
<p><small>Xlib provides functions that you can use to draw
or fill arbitrary polygons or curves. These functions are
provided mainly for compatibility with X Version 10 and have
no server support. That is, they call other Xlib functions,
not the server directly. Thus, if you just have straight
lines to draw, using <i>XDrawLines</i> or
<i>XDrawSegments</i> is much faster.</small></p>
<p><small>The functions discussed here provide all the
functionality of the X Version 10 functions <i>XDraw</i>,
<i>XDrawFilled</i>, <i>XDrawPatterned</i>,
<i>XDrawDashed</i>, and <i>XDrawTiled</i>. They are as
compatible as possible given X Version 11’s new
line-drawing functions. One thing to note, however, is that
<i>VertexDrawLastPoint</i> is no longer supported. Also, the
error status returned is the opposite of what it was under X
Version 10 (this is the X Version 11 standard error status).
<i>XAppendVertex</i> and <i>XClearVertexFlag</i> from X
Version 10 also are not supported.</small></p>
<p><small>Just how the graphics context you use is set up
actually determines whether you get dashes or not, and so
on. Lines are properly joined if they connect and include
the closing of a closed figure (see <i>XDrawLines</i>). The
functions discussed here fail (return zero) only if they run
out of memory or are passed a <i>Vertex</i> list that has a
<i>Vertex</i> with <i>VertexStartClosed</i> set that is not
followed by a <i>Vertex</i> with <i>VertexEndClosed</i>
set.</small></p>
<p><small>To achieve the effects of the X Version 10
<i>XDraw</i>, <i>XDrawDashed</i>, and <i>XDrawPatterned</i>,
use <i>XDraw</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>#include <X11/X10.h>
Status XDraw(<i>display</i>, <i>d</i>, <i>gc</i>, <i>vlist</i>, <i>vcount</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *<i>display</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Drawable <i>d</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>GC <i>gc</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Vertex *<i>vlist</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int <i>vcount</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>vlist</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies a pointer to the list of vertices that
indicate what to draw.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>vcount</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies how many vertices are in
vlist.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XDraw</i> function draws an arbitrary
polygon or curve. The figure drawn is defined by the
specified list of vertices (vlist). The points are connected
by lines as specified in the flags in the vertex
structure.</small></p>
<p><small>Each Vertex, as defined in
<<i>X11/X10.h</i>>, is a structure with the following
members:</small></p>
<p><small>__ │</small></p>
<pre><small>typedef struct _Vertex {
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="20%">
<p><small>short x,y;</small></p>
</td>
<td width="69%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="20%">
<p><small>unsigned short flags;</small></p>
</td>
<td width="69%">
</td>
</table>
<p><small>} Vertex;</small></p>
<p><small>│__</small></p>
<p><small>The x and y members are the coordinates of the
vertex that are relative to either the upper left inside
corner of the drawable (if <i>VertexRelative</i> is zero) or
the previous vertex (if <i>VertexRelative</i> is
one).</small></p>
<p><small>The flags, as defined in
<<i>X11/X10.h</i>>, are as follows:</small></p>
<p><small>__ │</small></p>
<p align=center><small><img src="grohtml-1439283.png"></small></p>
<p><small>│__</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If <i>VertexRelative</i> is not set, the
coordinates are absolute (that is, relative to the
drawable’s origin). The first vertex must be an
absolute vertex.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If <i>VertexDontDraw</i> is one, no line or curve
is drawn from the previous vertex to this one. This is
analogous to picking up the pen and moving to another place
before drawing another line.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If <i>VertexCurved</i> is one, a spline algorithm
is used to draw a smooth curve from the previous vertex
through this one to the next vertex. Otherwise, a straight
line is drawn from the previous vertex to this one. It makes
sense to set <i>VertexCurved</i> to one only if a previous
and next vertex are both defined (either explicitly in the
array or through the definition of a closed
curve).</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>It is permissible for <i>VertexDontDraw</i> bits
and <i>VertexCurved</i> bits both to be one. This is useful
if you want to define the previous point for the smooth
curve but do not want an actual curve drawing to start until
this point.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>If <i>VertexStartClosed</i> is one, then this
point marks the beginning of a closed curve. This vertex
must be followed later in the array by another vertex whose
effective coordinates are identical and that has a
<i>VertexEndClosed</i> bit of one. The points in between
form a cycle to determine predecessor and successor vertices
for the spline algorithm.</small></p>
</td>
</table>
<p><small>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.</small></p>
<p><small>To achieve the effects of the X Version 10
<i>XDrawTiled</i> and <i>XDrawFilled</i>, use
<i>XDrawFilled</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>#include <X11/X10.h>
Status XDrawFilled(<i>display</i>, <i>d</i>, <i>gc</i>, <i>vlist</i>, <i>vcount</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Display *<i>display</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Drawable <i>d</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>GC <i>gc</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>Vertex *<i>vlist</i>;</small></p>
</td>
<td width="39%">
</td>
<tr valign="top" align="left">
<td width="9%"></td>
<td width="50%">
<p><small>int <i>vcount</i>;</small></p>
</td>
<td width="39%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small><i>d</i></small></p>
</td>
<td width="18%"></td>
<td width="46%">
<p><small>Specifies the drawable.</small></p>
</td>
<td width="33%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="4%">
<p><small><i>gc</i></small></p>
</td>
<td width="16%"></td>
<td width="34%">
<p><small>Specifies the GC.</small></p>
</td>
<td width="45%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>vlist</i></small></p>
</td>
<td width="10%"></td>
<td width="80%">
<p><small>Specifies a pointer to the list of vertices that
indicate what to draw.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="12%">
<p><small><i>vcount</i></small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Specifies how many vertices are in
vlist.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XDrawFilled</i> function draws arbitrary
polygons or curves and then fills them.</small></p>
<p><small>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,
dash-list, fill-style, and fill-rule.</small></p>
<a name="Associating User Data with a Value"></a>
<h2>Associating User Data with a Value</h2>
<p><small>These functions have been superseded by the
context management functions (see section 16.10). It is
often necessary to associate arbitrary information with
resource IDs. Xlib provides the <i>XAssocTable</i> functions
that you can use to make such an association. Application
programs often need to be able to easily refer to their own
data structures when an event arrives. The
<i>XAssocTable</i> system provides users of the X library
with a method for associating their own data structures with
X resources (<i>Pixmaps</i>, <i>Fonts</i>, <i>Windows</i>,
and so on).</small></p>
<p><small>An <i>XAssocTable</i> can be used to type X
resources. For example, the user may want to have three or
four types of windows, each with different properties. This
can be accomplished by associating each X window ID with a
pointer to a window property data structure defined by the
user. A generic type has been defined in the X library for
resource IDs. It is called an XID.</small></p>
<p><small>There are a few guidelines that should be
observed when using an <i>XAssocTable</i>:</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>All XIDs are relative to the specified
display.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="90%">
<p><small>Because of the hashing scheme used by the
association mechanism, the following rules for determining
the size of a <i>XAssocTable</i> should be followed.
Associations will be made and looked up more efficiently if
the table size (number of buckets in the hashing system) is
a power of two and if there are not more than 8 XIDs per
bucket.</small></p>
</td>
</table>
<p><small>To return a pointer to a new <i>XAssocTable</i>,
use <i>XCreateAssocTable</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XAssocTable *XCreateAssocTable(<i>size</i>)
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<p><small>int <i>size</i>;</small></p>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>size</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the number of buckets in the hash
system of <i>XAssocTable</i>.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The size argument specifies the number of buckets
in the hash system of <i>XAssocTable</i>. For reasons of
efficiency the number of buckets should be a power of two.
Some size suggestions might be: use 32 buckets per 100
objects, and a reasonable maximum number of objects per
buckets is 8. If an error allocating memory for the
<i>XAssocTable</i> occurs, a NULL pointer is
returned.</small></p>
<p><small>To create an entry in a given <i>XAssocTable</i>,
use <i>XMakeAssoc</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XMakeAssoc(<i>display</i>, <i>table</i>, <i>x_id</i>, <i>data</i>)
Display *<i>display</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<p><small>XAssocTable *<i>table</i>;</small></p>
</table>
<p><small>XID <i>x_id</i>;<br>
char *<i>data</i>;</small></p>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>table</i></small></p>
</td>
<td width="10%"></td>
<td width="52%">
<p><small>Specifies the assoc table.</small></p>
</td>
<td width="27%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>x_id</i></small></p>
</td>
<td width="12%"></td>
<td width="56%">
<p><small>Specifies the X resource ID.</small></p>
</td>
<td width="23%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>data</i></small></p>
</td>
<td width="12%"></td>
<td width="80%">
<p><small>Specifies the data to be associated with the X
resource ID.</small></p>
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XMakeAssoc</i> function inserts data into
an <i>XAssocTable</i> keyed on an XID. Data is inserted into
the table only once. Redundant inserts are ignored. The
queue in each association bucket is sorted from the lowest
XID to the highest XID.</small></p>
<p><small>To obtain data from a given <i>XAssocTable</i>,
use <i>XLookUpAssoc</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>char *XLookUpAssoc(<i>display</i>, <i>table</i>, <i>x_id</i>)
Display *<i>display</i>;
XAssocTable *<i>table</i>;
XID <i>x_id</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>table</i></small></p>
</td>
<td width="10%"></td>
<td width="52%">
<p><small>Specifies the assoc table.</small></p>
</td>
<td width="27%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>x_id</i></small></p>
</td>
<td width="12%"></td>
<td width="56%">
<p><small>Specifies the X resource ID.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XLookUpAssoc</i> function retrieves the
data stored in an <i>XAssocTable</i> by its XID. If an
appropriately matching XID can be found in the table,
<i>XLookUpAssoc</i> returns the data associated with it. If
the x_id cannot be found in the table, it returns
NULL.</small></p>
<p><small>To delete an entry from a given
<i>XAssocTable</i>, use <i>XDeleteAssoc</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XDeleteAssoc(<i>display</i>, <i>table</i>, <i>x_id</i>)
Display *<i>display</i>;
XAssocTable *<i>table</i>;
XID <i>x_id</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="3" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="14%">
<p><small><i>display</i></small></p>
</td>
<td width="6%"></td>
<td width="80%">
<p><small>Specifies the connection to the X
server.</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>table</i></small></p>
</td>
<td width="10%"></td>
<td width="52%">
<p><small>Specifies the assoc table.</small></p>
</td>
<td width="27%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%">
<p><small><i>x_id</i></small></p>
</td>
<td width="12%"></td>
<td width="56%">
<p><small>Specifies the X resource ID.</small></p>
</td>
<td width="23%">
</td>
</table>
<p><small>│__</small></p>
<p><small>The <i>XDeleteAssoc</i> function deletes an
association in an <i>XAssocTable</i> keyed on its XID.
Redundant deletes (and deletes of nonexistent XIDs) are
ignored. Deleting associations in no way impairs the
performance of an <i>XAssocTable</i>.</small></p>
<p><small>To free the memory associated with a given
<i>XAssocTable</i>, use
<i>XDestroyAssocTable</i>.</small></p>
<p><small>__ │</small></p>
<pre><small>XDestroyAssocTable(<i>table</i>)
XAssocTable *<i>table</i>;
</small></pre>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="10%">
<p><small><i>table</i></small></p>
</td>
<td width="10%"></td>
<td width="52%">
<p><small>Specifies the assoc table.</small></p>
</td>
<td width="27%">
</td>
</table>
<p><small>│__</small></p>
<p><small><b>21</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b>Glossary</b></p>
<p><b><small>Access control list</small></b></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>X maintains a list of hosts from which client
programs can be run. By default, only programs on the local
host and hosts specified in an initial list read by the
server can use the display. This access control list can be
changed by clients on the local host. Some server
implementations can also implement other authorization
mechanisms in addition to or in place of this mechanism. The
action of this mechanism can be conditional based on the
authorization protocol name and data received by the server
at connection setup.</small></p>
</td>
</table>
<p><small><b>Active grab</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A grab is active when the pointer or keyboard is
actually owned by the single grabbing client.</small></p>
</td>
</table>
<p><small><b>Ancestors</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>If W is an inferior of A, then A is an ancestor of
W.</small></p>
</td>
</table>
<p><small><b>Atom</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>An atom is a unique ID corresponding to a string
name. Atoms are used to identify properties, types, and
selections.</small></p>
</td>
</table>
<p><small><b>Background</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>An <i>InputOutput</i> window can have a
background, which is defined as a pixmap. When regions of
the window have their contents lost or invalidated, the
server automatically tiles those regions with the
background.</small></p>
</td>
</table>
<p><small><b>Backing store</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>When a server maintains the contents of a window,
the pixels saved off-screen are known as a backing
store.</small></p>
</td>
</table>
<p><small><b>Base font name</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A font name used to select a family of fonts whose
members may be encoded in various charsets. The
<i>CharSetRegistry</i> and <i>CharSetEncoding</i> fields of
an XLFD name identify the charset of the font. A base font
name may be a full XLFD name, with all fourteen
’-’ delimiters, or an abbreviated XLFD name
containing only the first 12 fields of an XLFD name, up to
but not including <i>CharSetRegistry</i>, with or without
the thirteenth ’-’, or a non-XLFD name. Any XLFD
fields may contain wild cards.</small></p>
<!-- INDENTATION -->
<p><small>When creating an <i>XFontSet</i>, Xlib accepts
from the client a list of one or more base font names which
select one or more font families. They are combined with
charset names obtained from the encoding of the locale to
load the fonts required to render text.</small></p>
</td>
</table>
<p><small><b>Bit gravity</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>When a window is resized, the contents of the
window are not necessarily discarded. It is possible to
request that the server relocate the previous contents to
some region of the window (though no guarantees are made).
This attraction of window contents for some location of a
window is known as bit gravity.</small></p>
</td>
</table>
<p><small><b>Bit plane</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>When a pixmap or window is thought of as a stack
of bitmaps, each bitmap is called a bit plane or
plane.</small></p>
</td>
</table>
<p><small><b>Bitmap</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A bitmap is a pixmap of depth one.</small></p>
</td>
</table>
<p><small><b>Border</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>An <i>InputOutput</i> window can have a border of
equal thickness on all four sides of the window. The
contents of the border are defined by a pixmap, and the
server automatically maintains the contents of the border.
Exposure events are never generated for border
regions.</small></p>
</td>
</table>
<p><small><b>Button grabbing</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Buttons on the pointer can be passively grabbed by
a client. When the button is pressed, the pointer is then
actively grabbed by the client.</small></p>
</td>
</table>
<p><small><b>Byte order</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>For image (pixmap/bitmap) data, the server defines
the byte order, and clients with different native byte
ordering must swap bytes as necessary. For all other parts
of the protocol, the client defines the byte order, and the
server swaps bytes as necessary.</small></p>
</td>
</table>
<p><small><b>Character</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A member of a set of elements used for the
organization, control, or representation of text (ISO2022,
as adapted by XPG3). Note that in ISO2022 terms, a character
is not bound to a coded value until it is identified as part
of a coded character set.</small></p>
</td>
</table>
<p><small><b>Character glyph</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The abstract graphical symbol for a character.
Character glyphs may or may not map one-to-one to font
glyphs, and may be context-dependent, varying with the
adjacent characters. Multiple characters may map to a single
character glyph.</small></p>
</td>
</table>
<p><small><b>Character set</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A collection of characters.</small></p>
</td>
</table>
<p><small><b>Charset</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>An encoding with a uniform, state-independent
mapping from characters to codepoints. A coded character
set.</small></p>
<!-- INDENTATION -->
<p><small>For display in X, there can be a direct mapping
from a charset to one font, if the width of all characters
in the charset is either one or two bytes. A text string
encoded in an encoding such as Shift-JIS cannot be passed
directly to the X server, because the text imaging requests
accept only single-width charsets (either 8 or 16 bits).
Charsets which meet these restrictions can serve as
‘‘font charsets’’. Font charsets
strictly speaking map font indices to font glyphs, not
characters to character glyphs.</small></p>
<!-- INDENTATION -->
<p><small>Note that a single font charset is sometimes used
as the encoding of a locale, for example,
ISO8859-1.</small></p>
</td>
</table>
<p><small><b>Children</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The children of a window are its first-level
subwindows.</small></p>
</td>
</table>
<p><small><b>Class</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Windows can be of different classes or types. See
the entries for <i>InputOnly</i> and <i>InputOutput</i>
windows for further information about valid window
types.</small></p>
</td>
</table>
<p><small><b>Client</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>An application program connects to the window
system server by some interprocess communication (IPC) path,
such as a TCP connection or a shared memory buffer. This
program is referred to as a client of the window system
server. More precisely, the client is the IPC path itself. A
program with multiple paths open to the server is viewed as
multiple clients by the protocol. Resource lifetimes are
controlled by connection lifetimes, not by program
lifetimes.</small></p>
</td>
</table>
<p><small><b>Clipping region</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>In a graphics context, a bitmap or list of
rectangles can be specified to restrict output to a
particular region of the window. The image defined by the
bitmap or rectangles is called a clipping
region.</small></p>
</td>
</table>
<p><small><b>Coded character</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A character bound to a codepoint.</small></p>
</td>
</table>
<p><small><b>Coded character set</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A set of unambiguous rules that establishes a
character set and the one-to-one relationship between each
character of the set and its bit representation. (ISO2022,
as adapted by XPG3) A definition of a one-to-one mapping of
a set of characters to a set of codepoints.</small></p>
</td>
</table>
<p><small><b>Codepoint</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The coded representation of a single character in
a coded character set.</small></p>
</td>
</table>
<p><small><b>Colormap</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A colormap consists of a set of entries defining
color values. The colormap associated with a window is used
to display the contents of the window; each pixel value
indexes the colormap to produce an RGB value that drives the
guns of a monitor. Depending on hardware limitations, one or
more colormaps can be installed at one time so that windows
associated with those maps display with true
colors.</small></p>
</td>
</table>
<p><small><b>Connection</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The IPC path between the server and client program
is known as a connection. A client program typically (but
not necessarily) has one connection to the server over which
requests and events are sent.</small></p>
</td>
</table>
<p><small><b>Containment</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A window contains the pointer if the window is
viewable and the hotspot of the cursor is within a visible
region of the window or a visible region of one of its
inferiors. The border of the window is included as part of
the window for containment. The pointer is in a window if
the window contains the pointer but no inferior contains the
pointer.</small></p>
</td>
</table>
<p><small><b>Coordinate system</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The coordinate system has X horizontal and Y
vertical, with the origin [0, 0] at the upper left.
Coordinates are integral 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.</small></p>
</td>
</table>
<p><small><b>Cursor</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A cursor is the visible shape of the pointer on a
screen. It consists of a hotspot, a source bitmap, a shape
bitmap, and a pair of colors. The cursor defined for a
window controls the visible appearance when the pointer is
in that window.</small></p>
</td>
</table>
<p><small><b>Depth</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The depth of a window or pixmap is the number of
bits per pixel it has. The depth of a graphics context is
the depth of the drawables it can be used in conjunction
with graphics output.</small></p>
</td>
</table>
<p><small><b>Device</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Keyboards, mice, tablets, track-balls, button
boxes, and so on are all collectively known as input
devices. Pointers can have one or more buttons (the most
common number is three). The core protocol only deals with
two devices: the keyboard and the pointer.</small></p>
</td>
</table>
<p><small><b>DirectColor</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small><i>DirectColor</i> is a class of colormap in which
a pixel value is decomposed into three separate subfields
for indexing. The first subfield indexes an array to produce
red intensity values. The second subfield indexes a second
array to produce blue intensity values. The third subfield
indexes a third array to produce green intensity values. The
RGB (red, green, and blue) values in the colormap entry can
be changed dynamically.</small></p>
</td>
</table>
<p><small><b>Display</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A server, together with its screens and input
devices, is called a display. The Xlib <i>Display</i>
structure contains all information about the particular
display and its screens as well as the state that Xlib needs
to communicate with the display over a particular
connection.</small></p>
</td>
</table>
<p><small><b>Drawable</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Both windows and pixmaps can be used as sources
and destinations in graphics operations. These windows and
pixmaps are collectively known as drawables. However, an
<i>InputOnly</i> window cannot be used as a source or
destination in a graphics operation.</small></p>
</td>
</table>
<p><small><b>Encoding</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A set of unambiguous rules that establishes a
character set and a relationship between the characters and
their representations. The character set does not have to be
fixed to a finite pre-defined set of characters. The
representations do not have to be of uniform length.
Examples are an ISO2022 graphic set, a state-independent or
state-dependent combination of graphic sets, possibly
including control sets, and the X Compound Text
encoding.</small></p>
<!-- INDENTATION -->
<p><small>In X, encodings are identified by a string which
appears as: the <i>CharSetRegistry</i> and
<i>CharSetEncoding</i> components of an XLFD name; the name
of a charset of the locale for which a font could not be
found; or an atom which identifies the encoding of a text
property or which names an encoding for a text selection
target type. Encoding names should be composed of characters
from the X Portable Character Set.</small></p>
</td>
</table>
<p><small><b>Escapement</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The escapement of a string is the distance in
pixels in the primary draw direction from the drawing origin
to the origin of the next character (that is, the one
following the given string) to be drawn.</small></p>
</td>
</table>
<p><small><b>Event</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Clients are informed of information asynchronously
by means of events. These events can be either
asynchronously generated from devices or generated as side
effects of client requests. Events are grouped into types.
The server never sends an event to a client unless the
client has specifically asked to be informed of that type of
event. However, clients can force events to be sent to other
clients. Events are typically reported relative to a
window.</small></p>
</td>
</table>
<p><small><b>Event mask</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Events are requested relative to a window. The set
of event types a client requests relative to a window is
described by using an event mask.</small></p>
</td>
</table>
<p><small><b>Event propagation</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Device-related events propagate from the source
window to ancestor windows until some client has expressed
interest in handling that type of event or until the event
is discarded explicitly.</small></p>
</td>
</table>
<p><small><b>Event source</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The deepest viewable window that the pointer is in
is called the source of a device-related event.</small></p>
</td>
</table>
<p><small><b>Event synchronization</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>There are certain race conditions possible when
demultiplexing device events to clients (in particular,
deciding where pointer and keyboard events should be sent
when in the middle of window management operations). The
event synchronization mechanism allows synchronous
processing of device events.</small></p>
</td>
</table>
<p><small><b>Exposure event</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Servers do not guarantee to preserve the contents
of windows when windows are obscured or reconfigured.
Exposure events are sent to clients to inform them when
contents of regions of windows have been lost.</small></p>
</td>
</table>
<p><small><b>Extension</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Named extensions to the core protocol can be
defined to extend the system. Extensions to output requests,
resources, and event types are all possible and
expected.</small></p>
</td>
</table>
<p><small><b>Font</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A font is an array of glyphs (typically
characters). The protocol does no translation or
interpretation of character sets. The client simply
indicates values used to index the glyph array. A font
contains additional metric information to determine
interglyph and interline spacing.</small></p>
</td>
</table>
<p><small><b>Font glyph</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The abstract graphical symbol for an index into a
font.</small></p>
</td>
</table>
<p><small><b>Frozen events</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Clients can freeze event processing during
keyboard and pointer grabs.</small></p>
</td>
</table>
<p><small><b>GC</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>GC is an abbreviation for graphics context. See
<b>Graphics context</b>.</small></p>
</td>
</table>
<p><small><b>Glyph</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>An identified abstract graphical symbol
independent of any actual image. (ISO/IEC/DIS 9541-1) An
abstract visual representation of a graphic character, not
bound to a codepoint.</small></p>
</td>
</table>
<p><small><b>Glyph image</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>An image of a glyph, as obtained from a glyph
representation displayed on a presentation surface.
(ISO/IEC/DIS 9541-1)</small></p>
</td>
</table>
<p><small><b>Grab</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Keyboard keys, the keyboard, pointer buttons, the
pointer, and the server can be grabbed for exclusive use by
a client. In general, these facilities are not intended to
be used by normal applications but are intended for various
input and window managers to implement various styles of
user interfaces.</small></p>
</td>
</table>
<p><small><b>Graphics context</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Various information for graphics output is stored
in a graphics context (GC), such as foreground pixel,
background pixel, line width, clipping region, and so on. A
graphics context can only be used with drawables that have
the same root and the same depth as the graphics
context.</small></p>
</td>
</table>
<p><small><b>Gravity</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The contents of windows and windows themselves
have a gravity, which determines how the contents move when
a window is resized. See <b>Bit gravity</b> and <b>Window
gravity</b>.</small></p>
</td>
</table>
<p><small><b>GrayScale</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small><i>GrayScale</i> can be viewed as a degenerate
case of <i>PseudoColor</i>, in which the red, green, and
blue values in any given colormap entry are equal and thus,
produce shades of gray. The gray values can be changed
dynamically.</small></p>
</td>
</table>
<p><small><b>Host Portable Character
Encoding</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The encoding of the X Portable Character Set on
the host. The encoding itself is not defined by this
standard, but the encoding must be the same in all locales
supported by Xlib on the host. If a string is said to be in
the Host Portable Character Encoding, then it only contains
characters from the X Portable Character Set, in the host
encoding.</small></p>
</td>
</table>
<p><small><b>Hotspot</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A cursor has an associated hotspot, which defines
the point in the cursor corresponding to the coordinates
reported for the pointer.</small></p>
</td>
</table>
<p><small><b>Identifier</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>An identifier is a unique value associated with a
resource that clients use to name that resource. The
identifier can be used over any connection to name the
resource.</small></p>
</td>
</table>
<p><small><b>Inferiors</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The inferiors of a window are all of the
subwindows nested below it: the children, the
children’s children, and so on.</small></p>
</td>
</table>
<p><small><b>Input focus</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The input focus is usually a window defining the
scope for processing of keyboard input. If a generated
keyboard event usually would be reported to this window or
one of its inferiors, the event is reported as usual.
Otherwise, the event is reported with respect to the focus
window. The input focus also can be set such that all
keyboard events are discarded and such that the focus window
is dynamically taken to be the root window of whatever
screen the pointer is on at each keyboard event.</small></p>
</td>
</table>
<p><small><b>Input manager</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Control over keyboard input is typically provided
by an input manager client, which usually is part of a
window manager.</small></p>
</td>
</table>
<p><small><b>InputOnly window</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>An <i>InputOnly</i> window is a window that cannot
be used for graphics requests. <i>InputOnly</i> windows are
invisible and are used to control such things as cursors,
input event generation, and grabbing. <i>InputOnly</i>
windows cannot have <i>InputOutput</i> windows as
inferiors.</small></p>
</td>
</table>
<p><small><b>InputOutput window</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>An <i>InputOutput</i> window is the normal kind of
window that is used for both input and output.
<i>InputOutput</i> windows can have both <i>InputOutput</i>
and <i>InputOnly</i> windows as inferiors.</small></p>
</td>
</table>
<p><small><b>Internationalization</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The process of making software adaptable to the
requirements of different native languages, local customs,
and character string encodings. Making a computer program
adaptable to different locales without program source
modifications or recompilation.</small></p>
</td>
</table>
<p><small><b>ISO2022</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>ISO standard for code extension techniques for
7-bit and 8-bit coded character sets.</small></p>
</td>
</table>
<p><small><b>Key grabbing</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Keys on the keyboard can be passively grabbed by a
client. When the key is pressed, the keyboard is then
actively grabbed by the client.</small></p>
</td>
</table>
<p><small><b>Keyboard grabbing</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A client can actively grab control of the
keyboard, and key events will be sent to that client rather
than the client the events would normally have been sent
to.</small></p>
</td>
</table>
<p><small><b>Keysym</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>An encoding of a symbol on a keycap on a
keyboard.</small></p>
</td>
</table>
<p><small><b>Latin-1</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The coded character set defined by the ISO8859-1
standard.</small></p>
</td>
</table>
<p><small><b>Latin Portable Character
Encoding</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The encoding of the X Portable Character Set using
the Latin-1 codepoints plus ASCII control characters. If a
string is said to be in the Latin Portable Character
Encoding, then it only contains characters from the X
Portable Character Set, not all of Latin-1.</small></p>
</td>
</table>
<p><small><b>Locale</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The international environment of a computer
program defining the ‘‘localized’’
behavior of that program at run-time. This information can
be established from one or more sets of localization data.
ANSI C defines locale-specific processing by C system
library calls. See ANSI C and the X/Open Portability Guide
specifications for more details. In this specification, on
implementations that conform to the ANSI C library, the
‘‘current locale’’ is the current
setting of the LC_CTYPE <i>setlocale</i> category.
Associated with each locale is a text encoding. When text is
processed in the context of a locale, the text must be in
the encoding of the locale. The current locale affects Xlib
in its:</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Encoding and processing of input method
text</small></p>
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="5" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="74%">
<p><small>Encoding of resource files and values</small></p>
</td>
<td width="5%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="5" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="72%">
<p><small>Encoding and imaging of text strings</small></p>
</td>
<td width="7%">
</td>
</table>
<!-- TABS -->
<table width="100%" border=0 rules="none" frame="void"
cols="4" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="2%">
<p><small>•</small></p>
</td>
<td width="8%"></td>
<td width="80%">
<p><small>Encoding and decoding for inter-client text
communication</small></p>
</td>
</table>
<p><small><b>Locale name</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The identifier used to select the desired locale
for the host C library and X library functions. On ANSI C
library compliant systems, the locale argument to the
<i>setlocale</i> function.</small></p>
</td>
</table>
<p><small><b>Localization</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The process of establishing information within a
computer system specific to the operation of particular
native languages, local customs and coded character sets.
(XPG3)</small></p>
</td>
</table>
<p><small><b>Mapped</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A window is said to be mapped if a map call has
been performed on it. Unmapped windows and their inferiors
are never viewable or visible.</small></p>
</td>
</table>
<p><small><b>Modifier keys</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Shift, Control, Meta, Super, Hyper, Alt, Compose,
Apple, CapsLock, ShiftLock, and similar keys are called
modifier keys.</small></p>
</td>
</table>
<p><small><b>Monochrome</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Monochrome is a special case of <i>StaticGray</i>
in which there are only two colormap entries.</small></p>
</td>
</table>
<p><small><b>Multibyte</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A character whose codepoint is stored in more than
one byte; any encoding which can contain multibyte
characters; text in a multibyte encoding. The
‘‘char *’’ null-terminated string
datatype in ANSI C. Note that references in this document to
multibyte strings imply only that the strings <i>may</i>
contain multibyte characters.</small></p>
</td>
</table>
<p><small><b>Obscure</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A window is obscured if some other window obscures
it. A window can be partially obscured and so still have
visible regions. Window A obscures window B if both are
viewable <i>InputOutput</i> windows, if A is higher in the
global stacking order, and if the rectangle defined by the
outside edges of A intersects the rectangle defined by the
outside edges of B. Note the distinction between obscures
and occludes. Also note that window borders are included in
the calculation.</small></p>
</td>
</table>
<p><small><b>Occlude</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A window is occluded if some other window occludes
it. Window A occludes window B if both are mapped, if A is
higher in the global stacking order, and if the rectangle
defined by the outside edges of A intersects the rectangle
defined by the outside edges of B. Note the distinction
between occludes and obscures. Also note that window borders
are included in the calculation and that <i>InputOnly</i>
windows never obscure other windows but can occlude other
windows.</small></p>
</td>
</table>
<p><small><b>Padding</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Some padding bytes are inserted in the data stream
to maintain alignment of the protocol requests on natural
boundaries. This increases ease of portability to some
machine architectures.</small></p>
</td>
</table>
<p><small><b>Parent window</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>If C is a child of P, then P is the parent of
C.</small></p>
</td>
</table>
<p><small><b>Passive grab</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Grabbing a key or button is a passive grab. The
grab activates when the key or button is actually
pressed.</small></p>
</td>
</table>
<p><small><b>Pixel value</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A pixel is an N-bit value, where N is the number
of bit planes used in a particular window or pixmap (that
is, is the depth of the window or pixmap). A pixel in a
window indexes a colormap to derive an actual color to be
displayed.</small></p>
</td>
</table>
<p><small><b>Pixmap</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A pixmap is a three-dimensional array of bits. A
pixmap is normally thought of as a two-dimensional array of
pixels, where each pixel can be a value from 0 to
<img src="grohtml-14392-117.png"> −1, and where N is
the depth (z axis) of the pixmap. A pixmap can also be
thought of as a stack of N bitmaps. A pixmap can only be
used on the screen that it was created in.</small></p>
</td>
</table>
<p><small><b>Plane</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>When a pixmap or window is thought of as a stack
of bitmaps, each bitmap is called a plane or bit
plane.</small></p>
</td>
</table>
<p><small><b>Plane mask</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Graphics operations can be restricted to only
affect a subset of bit planes of a destination. A plane mask
is a bit mask describing which planes are to be modified.
The plane mask is stored in a graphics context.</small></p>
</td>
</table>
<p><small><b>Pointer</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The pointer is the pointing device currently
attached to the cursor and tracked on the
screens.</small></p>
</td>
</table>
<p><small><b>Pointer grabbing</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A client can actively grab control of the pointer.
Then button and motion events will be sent to that client
rather than the client the events would normally have been
sent to.</small></p>
</td>
</table>
<p><small><b>Pointing device</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A pointing device is typically a mouse, tablet, or
some other device with effective dimensional motion. The
core protocol defines only one visible cursor, which tracks
whatever pointing device is attached as the
pointer.</small></p>
</td>
</table>
<p><small><b>POSIX</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Portable Operating System Interface, ISO/IEC
9945-1 (IEEE Std 1003.1).</small></p>
</td>
</table>
<p><small><b>POSIX Portable Filename Character
Set</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The set of 65 characters which can be used in
naming files on a POSIX-compliant host that are correctly
processed in all locales. The set is:</small></p>
<!-- INDENTATION -->
<pre><small>a..z A..Z 0..9 ._-
</small></pre>
</td>
</table>
<p><small><b>Property</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Windows can have associated properties that
consist of a name, a type, a data format, and some data. The
protocol places no interpretation on properties. They are
intended as a general-purpose naming mechanism for clients.
For example, clients might use properties to share
information such as resize hints, program names, and icon
formats with a window manager.</small></p>
</td>
</table>
<p><small><b>Property list</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The property list of a window is the list of
properties that have been defined for the
window.</small></p>
</td>
</table>
<p><small><b>PseudoColor</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small><i>PseudoColor</i> is a class of colormap in which
a pixel value indexes the colormap entry to produce an
independent RGB value; that is, the colormap is viewed as an
array of triples (RGB values). The RGB values can be changed
dynamically.</small></p>
</td>
</table>
<p><small><b>Rectangle</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A rectangle specified by [x,y,w,h] has an
infinitely thin outline path with corners at [x,y], [x+w,y],
[x+w,y+h], and [x, y+h]. When a rectangle is filled, the
lower-right edges are not drawn. For example, if w=h=0,
nothing would be drawn. For w=h=1, a single pixel would be
drawn.</small></p>
</td>
</table>
<p><small><b>Redirecting control</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Window managers (or client programs) may enforce
window layout policy in various ways. When a client attempts
to change the size or position of a window, the operation
may be redirected to a specified client rather than the
operation actually being performed.</small></p>
</td>
</table>
<p><small><b>Reply</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Information requested by a client program using
the X protocol is sent back to the client with a reply. Both
events and replies are multiplexed on the same connection.
Most requests do not generate replies, but some requests
generate multiple replies.</small></p>
</td>
</table>
<p><small><b>Request</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A command to the server is called a request. It is
a single block of data sent over a connection.</small></p>
</td>
</table>
<p><small><b>Resource</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Windows, pixmaps, cursors, fonts, graphics
contexts, and colormaps are known as resources. They all
have unique identifiers associated with them for naming
purposes. The lifetime of a resource usually is bounded by
the lifetime of the connection over which the resource was
created.</small></p>
</td>
</table>
<p><small><b>RGB values</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>RGB values are the red, green, and blue intensity
values that are used to define a color. These values are
always represented as 16-bit, unsigned numbers, with 0 the
minimum intensity and 65535 the maximum intensity. The X
server scales these values to match the display
hardware.</small></p>
</td>
</table>
<p><small><b>Root</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The root of a pixmap or graphics context is the
same as the root of whatever drawable was used when the
pixmap or GC was created. The root of a window is the root
window under which the window was created.</small></p>
</td>
</table>
<p><small><b>Root window</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Each screen has a root window covering it. The
root window cannot be reconfigured or unmapped, but
otherwise it acts as a full-fledged window. A root window
has no parent.</small></p>
</td>
</table>
<p><small><b>Save set</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The save set of a client is a list of other
clients’ windows that, if they are inferiors of one of
the client’s windows at connection close, should not
be destroyed and that should be remapped if currently
unmapped. Save sets are typically used by window managers to
avoid lost windows if the manager should terminate
abnormally.</small></p>
</td>
</table>
<p><small><b>Scanline</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A scanline is a list of pixel or bit values viewed
as a horizontal row (all values having the same y
coordinate) of an image, with the values ordered by
increasing the x coordinate.</small></p>
</td>
</table>
<p><small><b>Scanline order</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>An image represented in scanline order contains
scanlines ordered by increasing the y
coordinate.</small></p>
</td>
</table>
<p><small><b>Screen</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A server can provide several independent screens,
which typically have physically independent monitors. This
would be the expected configuration when there is only a
single keyboard and pointer shared among the screens. A
<i>Screen</i> structure contains the information about that
screen and is linked to the <i>Display</i>
structure.</small></p>
</td>
</table>
<p><small><b>Selection</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A selection can be thought of as an indirect
property with dynamic type. That is, rather than having the
property stored in the X server, it is maintained by some
client (the owner). A selection is global and is thought of
as belonging to the user and being maintained by clients,
rather than being private to a particular window
subhierarchy or a particular set of clients. When a client
asks for the contents of a selection, it specifies a
selection target type, which can be used to control the
transmitted representation of the contents. For example, if
the selection is ‘‘the last thing the user
clicked on,’’ and that is currently an image,
then the target type might specify whether the contents of
the image should be sent in XY format or Z
format.</small></p>
<!-- INDENTATION -->
<p><small>The target type can also be used to control the
class of contents transmitted; for example, asking for the
‘‘looks’’ (fonts, line spacing,
indentation, and so forth) of a paragraph selection, rather
than the text of the paragraph. The target type can also be
used for other purposes. The protocol does not constrain the
semantics.</small></p>
</td>
</table>
<p><small><b>Server</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The server, which is also referred to as the X
server, provides the basic windowing mechanism. It handles
IPC connections from clients, multiplexes graphics requests
onto the screens, and demultiplexes input back to the
appropriate clients.</small></p>
</td>
</table>
<p><small><b>Server grabbing</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The server can be grabbed by a single client for
exclusive use. This prevents processing of any requests from
other client connections until the grab is completed. This
is typically only a transient state for such things as
rubber-banding, pop-up menus, or executing requests
indivisibly.</small></p>
</td>
</table>
<p><small><b>Shift sequence</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>ISO2022 defines control characters and escape
sequences which temporarily (single shift) or permanently
(locking shift) cause a different character set to be in
effect (‘‘invoking’’ a character
set).</small></p>
</td>
</table>
<p><small><b>Sibling</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Children of the same parent window are known as
sibling windows.</small></p>
</td>
</table>
<p><small><b>Stacking order</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Sibling windows, similar to sheets of paper on a
desk, can stack on top of each other. Windows above both
obscure and occlude lower windows. The relationship between
sibling windows is known as the stacking order.</small></p>
</td>
</table>
<p><small><b>State-dependent encoding</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>An encoding in which an invocation of a charset
can apply to multiple characters in sequence. A
state-dependent encoding begins in an ‘‘initial
state’’ and enters other ‘‘shift
states’’ when specific ‘‘shift
sequences’’ are encountered in the byte
sequence. In ISO2022 terms, this means use of locking
shifts, not single shifts.</small></p>
</td>
</table>
<p><small><b>State-independent encoding</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Any encoding in which the invocations of the
charsets are fixed, or span only a single character. In
ISO2022 terms, this means use of at most single shifts, not
locking shifts.</small></p>
</td>
</table>
<p><small><b>StaticColor</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small><i>StaticColor</i> can be viewed as a degenerate
case of <i>PseudoColor</i> in which the RGB values are
predefined and read-only.</small></p>
</td>
</table>
<p><small><b>StaticGray</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small><i>StaticGray</i> can be viewed as a degenerate
case of <i>GrayScale</i> in which the gray values are
predefined and read-only. The values are typically linear or
near-linear increasing ramps.</small></p>
</td>
</table>
<p><small><b>Status</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Many Xlib functions return a success status. If
the function does not succeed, however, its arguments are
not disturbed.</small></p>
</td>
</table>
<p><small><b>Stipple</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A stipple pattern is a bitmap that is used to tile
a region to serve as an additional clip mask for a fill
operation with the foreground color.</small></p>
</td>
</table>
<p><small><b>STRING encoding</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Latin-1, plus tab and newline.</small></p>
</td>
</table>
<p><small><b>String Equivalence</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Two ISO Latin-1 STRING8 values are considered
equal if they are the same length and if corresponding bytes
are either equal or are equivalent as follows: decimal
values 65 to 90 inclusive (characters
‘‘A’’ to
‘‘Z’’) are pairwise equivalent to
decimal values 97 to 122 inclusive (characters
‘‘a’’ to
‘‘z’’), decimal values 192 to 214
inclusive (characters ‘‘A grave’’ to
‘‘O diaeresis’’) are pairwise
equivalent to decimal values 224 to 246 inclusive
(characters ‘‘a grave’’ to
‘‘o diaeresis’’), and decimal values
216 to 222 inclusive (characters ‘‘O
oblique’’ to ‘‘THORN’’)
are pairwise equivalent to decimal values 246 to 254
inclusive (characters ‘‘o oblique’’
to ‘‘thorn’’).</small></p>
</td>
</table>
<p><small><b>Tile</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A pixmap can be replicated in two dimensions to
tile a region. The pixmap itself is also known as a
tile.</small></p>
</td>
</table>
<p><small><b>Timestamp</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A timestamp is a time value expressed in
milliseconds. It is typically the time since the last server
reset. Timestamp values wrap around (after about 49.7 days).
The server, given its current time is represented by
timestamp T, always interprets timestamps from clients by
treating half of the timestamp space as being earlier in
time than T and half of the timestamp space as being later
in time than T. One timestamp value, represented by the
constant <i>CurrentTime</i>, is never generated by the
server. This value is reserved for use in requests to
represent the current server time.</small></p>
</td>
</table>
<p><small><b>TrueColor</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small><i>TrueColor</i> can be viewed as a degenerate
case of <i>DirectColor</i> in which the subfields in the
pixel value directly encode the corresponding RGB values.
That is, the colormap has predefined read-only RGB values.
The values are typically linear or near-linear increasing
ramps.</small></p>
</td>
</table>
<p><small><b>Type</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A type is an arbitrary atom used to identify the
interpretation of property data. Types are completely
uninterpreted by the server. They are solely for the benefit
of clients. X predefines type atoms for many frequently used
types, and clients also can define new types.</small></p>
</td>
</table>
<p><small><b>Viewable</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A window is viewable if it and all of its
ancestors are mapped. This does not imply that any portion
of the window is actually visible. Graphics requests can be
performed on a window when it is not viewable, but output
will not be retained unless the server is maintaining
backing store.</small></p>
</td>
</table>
<p><small><b>Visible</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A region of a window is visible if someone looking
at the screen can actually see it; that is, the window is
viewable and the region is not occluded by any other
window.</small></p>
</td>
</table>
<p><small><b>Whitespace</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Any spacing character. On implementations that
conform to the ANSI C library, whitespace is any character
for which <i>isspace</i> returns true.</small></p>
</td>
</table>
<p><small><b>Window gravity</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>When windows are resized, subwindows may be
repositioned automatically relative to some position in the
window. This attraction of a subwindow to some part of its
parent is known as window gravity.</small></p>
</td>
</table>
<p><small><b>Window manager</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>Manipulation of windows on the screen and much of
the user interface (policy) is typically provided by a
window manager client.</small></p>
</td>
</table>
<p><small><b>X Portable Character Set</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>A basic set of 97 characters which are assumed to
exist in all locales supported by Xlib. This set contains
the following characters:</small></p>
<!-- INDENTATION -->
<pre><small>a..z A..Z 0..9
!"#$%&’()*+,-./:;<=>?@[\]^_‘{|}~
<space>, <tab>, and <newline>
</small></pre>
<!-- INDENTATION -->
<p><small>This is the left/lower half (also called the G0
set) of the graphic character set of ISO8859-1 plus
<space>, <tab>, and <newline>. It is also
the set of graphic characters in 7-bit ASCII plus the same
three control characters. The actual encoding of these
characters on the host is system dependent; see the Host
Portable Character Encoding.</small></p>
</td>
</table>
<p><small><b>XLFD</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The X Logical Font Description Conventions that
define a standard syntax for structured font
names.</small></p>
</td>
</table>
<p><small><b>XY format</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The data for a pixmap is said to be in XY format
if it is organized as a set of bitmaps representing
individual bit planes with the planes appearing from
most-significant to least-significant bit order.</small></p>
</td>
</table>
<p><small><b>Z format</b></small></p>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="9%"></td>
<td width="90%">
<p><small>The data for a pixmap is said to be in Z format if
it is organized as a set of pixel values in scanline
order.</small></p>
</td>
</table>
<p><small><b>References</b></small></p>
<p><small>ANSI Programming Language - C: ANSI X3.159-1989,
December 14, 1989.</small></p>
<p><small>Draft Proposed Multibyte Extension of ANSI C,
Draft 1.1, November 30, 1989, SC22/C WG/SWG IPSJ/ITSCJ
Japan.</small></p>
<p><small>ISO2022: Information processing - ISO 7-bit and
8-bit coded character sets - Code extension
techniques.</small></p>
<p><small>ISO8859-1: Information processing - 8-bit
single-byte coded graphic character sets - Part 1: Latin
alphabet No. 1.</small></p>
<p><small>POSIX: Information Technology - Portable
Operating System Interface (POSIX) - Part 1: System
Application Program Interface (API) [C Language], ISO/IEC
9945-1.</small></p>
<p><small>Text of ISO/IEC/DIS 9541-1, Information
Processing - Font Information Interchange - Part 1:
Architecture.</small></p>
<p><small>X/Open Portability Guide, Issue 3, December 1988
(XPG3), X/Open Company, Ltd, Prentice-Hall, Inc. 1989. ISBN
0-13-685835-8. (See especially Volume 3: XSI Supplementary
Definitions.)</small></p>
<p><small><b>22</b></small></p>
<p><b><small>Xlib − C Library libX11
1.3.2</small></b></p>
<p align=center><b>Table of Contents</b></p>
<!-- TABS -->
<p><small>Table of Contents . . . . . . . . . . . . . . . .
. . . ii</small></p>
<p><small>Acknowledgments . . . . . . . . . . . . . . . . .
. . . iii</small></p>
<p><small>Chapter 1: Introduction to Xlib . . . . . . . . .
. . . 1</small></p>
<p><small>1.1. Overview of the X Window System . . . . . .
. . . . 1</small></p>
<p><small>1.2. Errors . . . . . . . . . . . . . . . . . . .
. . . 1</small></p>
<p><small>1.3. Standard Header Files . . . . . . . . . . .
. . . . 1</small></p>
<p><small>1.4. Generic Values and Types . . . . . . . . . .
. . . 1</small></p>
<p><small>1.5. Naming and Argument Conventions within Xlib
. . . . 1</small></p>
<p><small>1.6. Programming Considerations . . . . . . . . .
. . . 1</small></p>
<p><small>1.7. Character Sets and Encodings . . . . . . . .
. . . 1</small></p>
<p><small>1.8. Formatting Conventions . . . . . . . . . . .
. . . 1</small></p>
<p><small>Chapter 2: Display Functions . . . . . . . . . .
. . . . 2</small></p>
<p><small>2.1. Opening the Display . . . . . . . . . . . .
. . . . 2</small></p>
<p><small>2.2. Obtaining Information about the Display,
Image Formats, or Screens . . . . . . . . . . . . . . . . .
. 2</small></p>
<p><small>2.2.1. Display Macros . . . . . . . . . . . . . .
. . . 2</small></p>
<p><small>2.2.2. Image Format Functions and Macros . . . .
. . . . 2</small></p>
<p><small>2.2.3. Screen Information Macros . . . . . . . .
. . . . 2</small></p>
<p><small>2.3. Generating a NoOperation Protocol Request .
. . . . 2</small></p>
<p><small>2.4. Freeing Client-Created Data . . . . . . . .
. . . . 2</small></p>
<p><small>2.5. Closing the Display . . . . . . . . . . . .
. . . . 2</small></p>
<p><small>2.6. Using X Server Connection Close Operations .
. . . 2</small></p>
<p><small>2.7. Using Xlib with Threads . . . . . . . . . .
. . . . 2</small></p>
<p><small>2.8. Using Internal Connections . . . . . . . . .
. . . 2</small></p>
<p><small>Chapter 3: Window Functions . . . . . . . . . . .
. . . 3</small></p>
<p><small>3.1. Visual Types . . . . . . . . . . . . . . . .
. . . 3</small></p>
<p><small>3.2. Window Attributes . . . . . . . . . . . . .
. . . . 3</small></p>
<p><small>3.2.1. Background Attribute . . . . . . . . . . .
. . . 3</small></p>
<p><small>3.2.2. Border Attribute . . . . . . . . . . . . .
. . . 3</small></p>
<p><small>3.2.3. Gravity Attributes . . . . . . . . . . . .
. . . 3</small></p>
<p><small>3.2.4. Backing Store Attribute . . . . . . . . .
. . . . 3</small></p>
<p><small>3.2.5. Save Under Flag . . . . . . . . . . . . .
. . . . 3</small></p>
<p><small>3.2.6. Backing Planes and Backing Pixel
Attributes . . . 3</small></p>
<p><small>3.2.7. Event Mask and Do Not Propagate Mask
Attributes . . . . . . . . . . . . . . . . . . . . . . .
3</small></p>
<p><small>3.2.8. Override Redirect Flag . . . . . . . . . .
. . . 3</small></p>
<p><small>3.2.9. Colormap Attribute . . . . . . . . . . . .
. . . 3</small></p>
<p><small>3.2.10. Cursor Attribute . . . . . . . . . . . .
. . . . 3</small></p>
<p><small>3.3. Creating Windows . . . . . . . . . . . . . .
. . . 3</small></p>
<p><small>3.4. Destroying Windows . . . . . . . . . . . . .
. . . 3</small></p>
<p><small>3.5. Mapping Windows . . . . . . . . . . . . . .
. . . . 3</small></p>
<p><small>3.6. Unmapping Windows . . . . . . . . . . . . .
. . . . 3</small></p>
<p><small>3.7. Configuring Windows . . . . . . . . . . . .
. . . . 3</small></p>
<p><small>3.8. Changing Window Stacking Order . . . . . . .
. . . 3</small></p>
<p><small>3.9. Changing Window Attributes . . . . . . . . .
. . . 3</small></p>
<p><small>Chapter 4: Window Information Functions . . . . .
. . . 4</small></p>
<p><small>4.1. Obtaining Window Information . . . . . . . .
. . . 4</small></p>
<p><small>4.2. Translating Screen Coordinates . . . . . . .
. . . 4</small></p>
<p><small>4.3. Properties and Atoms . . . . . . . . . . . .
. . . 4</small></p>
<p><small>4.4. Obtaining and Changing Window Properties . .
. . . 4</small></p>
<p><small>4.5. Selections . . . . . . . . . . . . . . . . .
. . . 4</small></p>
<p><small>Chapter 5: Pixmap and Cursor Functions . . . . .
. . . . 5</small></p>
<p><small>5.1. Creating and Freeing Pixmaps . . . . . . . .
. . . 5</small></p>
<p><small>5.2. Creating, Recoloring, and Freeing Cursors .
. . . . 5</small></p>
<p><small>Chapter 6: Color Management Functions . . . . . .
. . . 6</small></p>
<p><small>6.1. Color Structures . . . . . . . . . . . . . .
. . . 6</small></p>
<p><small>6.2. Color Strings . . . . . . . . . . . . . . .
. . . . 6</small></p>
<p><small>6.2.1. RGB Device String Specification . . . . .
. . . . 6</small></p>
<p><small>6.2.2. RGB Intensity String Specification . . . .
. . . 6</small></p>
<p><small>6.2.3. Device-Independent String Specifications .
. . . 6</small></p>
<p><small>6.3. Color Conversion Contexts and Gamut Mapping
. . . . 6</small></p>
<p><small>6.4. Creating, Copying, and Destroying Colormaps
. . . . 6</small></p>
<p><small>6.5. Mapping Color Names to Values . . . . . . .
. . . . 6</small></p>
<p><small>6.6. Allocating and Freeing Color Cells . . . . .
. . . 6</small></p>
<p><small>6.7. Modifying and Querying Colormap Cells . . .
. . . . 6</small></p>
<p><small>6.8. Color Conversion Context Functions . . . . .
. . . 6</small></p>
<p><small>6.8.1. Getting and Setting the Color Conversion
Context of a Colormap . . . . . . . . . . . . . . . . .
6</small></p>
<p><small>6.8.2. Obtaining the Default Color Conversion
Context . . . . . . . . . . . . . . . . . . . . . . . .
6</small></p>
<p><small>6.8.3. Color Conversion Context Macros . . . . .
. . . . 6</small></p>
<p><small>6.8.4. Modifying Attributes of a Color Conversion
Context . . . . . . . . . . . . . . . . . . . . . . . .
6</small></p>
<p><small>6.8.5. Creating and Freeing a Color Conversion
Context . . . . . . . . . . . . . . . . . . . . . . . .
6</small></p>
<p><small>6.9. Converting between Color Spaces . . . . . .
. . . . 6</small></p>
<p><small>6.10. Callback Functions . . . . . . . . . . . .
. . . . 6</small></p>
<p><small>6.10.1. Prototype Gamut Compression Procedure . .
. . . 6</small></p>
<p><small>6.10.2. Supplied Gamut Compression Procedures . .
. . . 6</small></p>
<p><small>6.10.3. Prototype White Point Adjustment
Procedure . . . 6</small></p>
<p><small>6.10.4. Supplied White Point Adjustment
Procedures . . . 6</small></p>
<p><small>6.11. Gamut Querying Functions . . . . . . . . .
. . . . 6</small></p>
<p><small>6.11.1. Red, Green, and Blue Queries . . . . . .
. . . . 6</small></p>
<p><small>6.11.2. CIELab Queries . . . . . . . . . . . . .
. . . . 6</small></p>
<p><small>6.11.3. CIELuv Queries . . . . . . . . . . . . .
. . . . 6</small></p>
<p><small>6.11.4. TekHVC Queries . . . . . . . . . . . . .
. . . . 6</small></p>
<p><small>6.12. Color Management Extensions . . . . . . . .
. . . 6</small></p>
<p><small>6.12.1. Color Spaces . . . . . . . . . . . . . .
. . . . 6</small></p>
<p><small>6.12.2. Adding Device-Independent Color Spaces .
. . . . 6</small></p>
<p><small>6.12.3. Querying Color Space Format and Prefix .
. . . . 6</small></p>
<p><small>6.12.4. Creating Additional Color Spaces . . . .
. . . . 6</small></p>
<p><small>6.12.5. Parse String Callback . . . . . . . . . .
. . . 6</small></p>
<p><small>6.12.6. Color Specification Conversion Callback .
. . . 6</small></p>
<p><small>6.12.7. Function Sets . . . . . . . . . . . . . .
. . . 6</small></p>
<p><small>6.12.8. Adding Function Sets . . . . . . . . . .
. . . . 6</small></p>
<p><small>6.12.9. Creating Additional Function Sets . . . .
. . . 6</small></p>
<p><small>Chapter 7: Graphics Context Functions . . . . . .
. . . 7</small></p>
<p><small>7.1. Manipulating Graphics Context/State . . . .
. . . . 7</small></p>
<p><small>7.2. Using Graphics Context Convenience Routines
. . . . 7</small></p>
<p><small>7.2.1. Setting the Foreground, Background,
Function, or Plane Mask . . . . . . . . . . . . . . . . . .
. . . 7</small></p>
<p><small>7.2.2. Setting the Line Attributes and Dashes . .
. . . 7</small></p>
<p><small>7.2.3. Setting the Fill Style and Fill Rule . . .
. . . 7</small></p>
<p><small>7.2.4. Setting the Fill Tile and Stipple . . . .
. . . . 7</small></p>
<p><small>7.2.5. Setting the Current Font . . . . . . . . .
. . . 7</small></p>
<p><small>7.2.6. Setting the Clip Region . . . . . . . . .
. . . . 7</small></p>
<p><small>7.2.7. Setting the Arc Mode, Subwindow Mode, and
Graphics Exposure . . . . . . . . . . . . . . . . . . .
7</small></p>
<p><small>Chapter 8: Graphics Functions . . . . . . . . . .
. . . 8</small></p>
<p><small>8.1. Clearing Areas . . . . . . . . . . . . . . .
. . . 8</small></p>
<p><small>8.2. Copying Areas . . . . . . . . . . . . . . .
. . . . 8</small></p>
<p><small>8.3. Drawing Points, Lines, Rectangles, and Arcs
. . . . 8</small></p>
<p><small>8.3.1. Drawing Single and Multiple Points . . . .
. . . 8</small></p>
<p><small>8.3.2. Drawing Single and Multiple Lines . . . .
. . . . 8</small></p>
<p><small>8.3.3. Drawing Single and Multiple Rectangles . .
. . . 8</small></p>
<p><small>8.3.4. Drawing Single and Multiple Arcs . . . . .
. . . 8</small></p>
<p><small>8.4. Filling Areas . . . . . . . . . . . . . . .
. . . . 8</small></p>
<p><small>8.4.1. Filling Single and Multiple Rectangles . .
. . . 8</small></p>
<p><small>8.4.2. Filling a Single Polygon . . . . . . . . .
. . . 8</small></p>
<p><small>8.4.3. Filling Single and Multiple Arcs . . . . .
. . . 8</small></p>
<p><small>8.5. Font Metrics . . . . . . . . . . . . . . . .
. . . 8</small></p>
<p><small>8.5.1. Loading and Freeing Fonts . . . . . . . .
. . . . 8</small></p>
<p><small>8.5.2. Obtaining and Freeing Font Names and
Information . . . . . . . . . . . . . . . . . . . . . .
8</small></p>
<p><small>8.5.3. Computing Character String Sizes . . . . .
. . . 8</small></p>
<p><small>8.5.4. Computing Logical Extents . . . . . . . .
. . . . 8</small></p>
<p><small>8.5.5. Querying Character String Sizes . . . . .
. . . . 8</small></p>
<p><small>8.6. Drawing Text . . . . . . . . . . . . . . . .
. . . 8</small></p>
<p><small>8.6.1. Drawing Complex Text . . . . . . . . . . .
. . . 8</small></p>
<p><small>8.6.2. Drawing Text Characters . . . . . . . . .
. . . . 8</small></p>
<p><small>8.6.3. Drawing Image Text Characters . . . . . .
. . . . 8</small></p>
<p><small>8.7. Transferring Images between Client and
Server . . . 8</small></p>
<p><small>Chapter 9: Window and Session Manager Functions .
. . . 9</small></p>
<p><small>9.1. Changing the Parent of a Window . . . . . .
. . . . 9</small></p>
<p><small>9.2. Controlling the Lifetime of a Window . . . .
. . . 9</small></p>
<p><small>9.3. Managing Installed Colormaps . . . . . . . .
. . . 9</small></p>
<p><small>9.4. Setting and Retrieving the Font Search Path
. . . . 9</small></p>
<p><small>9.5. Grabbing the Server . . . . . . . . . . . .
. . . . 9</small></p>
<p><small>9.6. Killing Clients . . . . . . . . . . . . . .
. . . . 9</small></p>
<p><small>9.7. Controlling the Screen Saver . . . . . . . .
. . . 9</small></p>
<p><small>9.8. Controlling Host Access . . . . . . . . . .
. . . . 9</small></p>
<p><small>9.8.1. Adding, Getting, or Removing Hosts . . . .
. . . 9</small></p>
<p><small>9.8.2. Changing, Enabling, or Disabling Access
Control . . . . . . . . . . . . . . . . . . . . . . . .
9</small></p>
<p><small>Chapter 10: Events . . . . . . . . . . . . . . .
. . . . 10</small></p>
<p><small>10.1. Event Types . . . . . . . . . . . . . . . .
. . . 10</small></p>
<p><small>10.2. Event Structures . . . . . . . . . . . . .
. . . . 10</small></p>
<p><small>10.3. Event Masks . . . . . . . . . . . . . . . .
. . . 10</small></p>
<p><small>10.4. Event Processing Overview . . . . . . . . .
. . . 10</small></p>
<p><small>10.5. Keyboard and Pointer Events . . . . . . . .
. . . 10</small></p>
<p><small>10.5.1. Pointer Button Events . . . . . . . . . .
. . . 10</small></p>
<p><small>10.5.2. Keyboard and Pointer Events . . . . . . .
. . . 10</small></p>
<p><small>10.6. Window Entry/Exit Events . . . . . . . . .
. . . . 10</small></p>
<p><small>10.6.1. Normal Entry/Exit Events . . . . . . . .
. . . . 10</small></p>
<p><small>10.6.2. Grab and Ungrab Entry/Exit Events . . . .
. . . 10</small></p>
<p><small>10.7. Input Focus Events . . . . . . . . . . . .
. . . . 10</small></p>
<p><small>10.7.1. Normal Focus Events and Focus Events
While Grabbed . . . . . . . . . . . . . . . . . . . . . . .
. 10</small></p>
<p><small>10.7.2. Focus Events Generated by Grabs . . . . .
. . . 10</small></p>
<p><small>10.8. Key Map State Notification Events . . . . .
. . . 10</small></p>
<p><small>10.9. Exposure Events . . . . . . . . . . . . . .
. . . 10</small></p>
<p><small>10.9.1. Expose Events . . . . . . . . . . . . . .
. . . 10</small></p>
<p><small>10.9.2. GraphicsExpose and NoExpose Events . . .
. . . . 10</small></p>
<p><small>10.10. Window State Change Events . . . . . . . .
. . . 10</small></p>
<p><small>10.10.1. CirculateNotify Events . . . . . . . . .
. . . 10</small></p>
<p><small>10.10.2. ConfigureNotify Events . . . . . . . . .
. . . 10</small></p>
<p><small>10.10.3. CreateNotify Events . . . . . . . . . .
. . . . 10</small></p>
<p><small>10.10.4. DestroyNotify Events . . . . . . . . . .
. . . 10</small></p>
<p><small>10.10.5. GravityNotify Events . . . . . . . . . .
. . . 10</small></p>
<p><small>10.10.6. MapNotify Events . . . . . . . . . . . .
. . . 10</small></p>
<p><small>10.10.7. MappingNotify Events . . . . . . . . . .
. . . 10</small></p>
<p><small>10.10.8. ReparentNotify Events . . . . . . . . .
. . . . 10</small></p>
<p><small>10.10.9. UnmapNotify Events . . . . . . . . . . .
. . . 10</small></p>
<p><small>10.10.10. VisibilityNotify Events . . . . . . . .
. . . 10</small></p>
<p><small>10.11. Structure Control Events . . . . . . . . .
. . . 10</small></p>
<p><small>10.11.1. CirculateRequest Events . . . . . . . .
. . . . 10</small></p>
<p><small>10.11.2. ConfigureRequest Events . . . . . . . .
. . . . 10</small></p>
<p><small>10.11.3. MapRequest Events . . . . . . . . . . .
. . . . 10</small></p>
<p><small>10.11.4. ResizeRequest Events . . . . . . . . . .
. . . 10</small></p>
<p><small>10.12. Colormap State Change Events . . . . . . .
. . . 10</small></p>
<p><small>10.13. Client Communication Events . . . . . . .
. . . . 10</small></p>
<p><small>10.13.1. ClientMessage Events . . . . . . . . . .
. . . 10</small></p>
<p><small>10.13.2. PropertyNotify Events . . . . . . . . .
. . . . 10</small></p>
<p><small>10.13.3. SelectionClear Events . . . . . . . . .
. . . . 10</small></p>
<p><small>10.13.4. SelectionRequest Events . . . . . . . .
. . . . 10</small></p>
<p><small>10.13.5. SelectionNotify Events . . . . . . . . .
. . . 10</small></p>
<p><small>Chapter 11: Event Handling Functions . . . . . .
. . . . 11</small></p>
<p><small>11.1. Selecting Events . . . . . . . . . . . . .
. . . . 11</small></p>
<p><small>11.2. Handling the Output Buffer . . . . . . . .
. . . . 11</small></p>
<p><small>11.3. Event Queue Management . . . . . . . . . .
. . . . 11</small></p>
<p><small>11.4. Manipulating the Event Queue . . . . . . .
. . . . 11</small></p>
<p><small>11.4.1. Returning the Next Event . . . . . . . .
. . . . 11</small></p>
<p><small>11.4.2. Selecting Events Using a Predicate
Procedure . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 11</small></p>
<p><small>11.4.3. Selecting Events Using a Window or Event
Mask . . . . . . . . . . . . . . . . . . . . . . . . . .
11</small></p>
<p><small>11.5. Putting an Event Back into the Queue . . .
. . . . 11</small></p>
<p><small>11.6. Sending Events to Other Applications . . .
. . . . 11</small></p>
<p><small>11.7. Getting Pointer Motion History . . . . . .
. . . . 11</small></p>
<p><small>11.8. Handling Protocol Errors . . . . . . . . .
. . . . 11</small></p>
<p><small>11.8.1. Enabling or Disabling Synchronization . .
. . . 11</small></p>
<p><small>11.8.2. Using the Default Error Handlers . . . .
. . . . 11</small></p>
<p><small>Chapter 12: Input Device Functions . . . . . . .
. . . . 12</small></p>
<p><small>12.1. Pointer Grabbing . . . . . . . . . . . . .
. . . . 12</small></p>
<p><small>12.2. Keyboard Grabbing . . . . . . . . . . . . .
. . . 12</small></p>
<p><small>12.3. Resuming Event Processing . . . . . . . . .
. . . 12</small></p>
<p><small>12.4. Moving the Pointer . . . . . . . . . . . .
. . . . 12</small></p>
<p><small>12.5. Controlling Input Focus . . . . . . . . . .
. . . 12</small></p>
<p><small>12.6. Manipulating the Keyboard and Pointer
Settings . . . . . . . . . . . . . . . . . . . . . . . . . .
. . 12</small></p>
<p><small>12.7. Manipulating the Keyboard Encoding . . . .
. . . . 12</small></p>
<p><small>Chapter 13: Locales and Internationalized Text
Functions . . . . . . . . . . . . . . . . . . . . . . .
13</small></p>
<p><small>13.1. X Locale Management . . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.2. Locale and Modifier Dependencies . . . . .
. . . . 13</small></p>
<p><small>13.3. Variable Argument Lists . . . . . . . . . .
. . . 13</small></p>
<p><small>13.4. Output Methods . . . . . . . . . . . . . .
. . . . 13</small></p>
<p><small>13.4.1. Output Method Overview . . . . . . . . .
. . . . 13</small></p>
<p><small>13.4.2. Output Method Functions . . . . . . . . .
. . . 13</small></p>
<p><small>13.4.3. X Output Method Values . . . . . . . . .
. . . . 13</small></p>
<p><small>13.4.3.1. Required Char Set . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.4.3.2. Query Orientation . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.4.3.3. Directional Dependent Drawing . . . . .
. . . 13</small></p>
<p><small>13.4.3.4. Context Dependent Drawing . . . . . . .
. . . 13</small></p>
<p><small>13.4.4. Output Context Functions . . . . . . . .
. . . . 13</small></p>
<p><small>13.4.5. Output Context Values . . . . . . . . . .
. . . 13</small></p>
<p><small>13.4.5.1. Base Font Name . . . . . . . . . . . .
. . . . 13</small></p>
<p><small>13.4.5.2. Missing CharSet . . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.4.5.3. Default String . . . . . . . . . . . .
. . . . 13</small></p>
<p><small>13.4.5.4. Orientation . . . . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.4.5.5. Resource Name and Class . . . . . . . .
. . . 13</small></p>
<p><small>13.4.5.6. Font Info . . . . . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.4.5.7. OM Automatic . . . . . . . . . . . . .
. . . . 13</small></p>
<p><small>13.4.6. Creating and Freeing a Font Set . . . . .
. . . 13</small></p>
<p><small>13.4.7. Obtaining Font Set Metrics . . . . . . .
. . . . 13</small></p>
<p><small>13.4.8. Drawing Text Using Font Sets . . . . . .
. . . . 13</small></p>
<p><small>13.5. Input Methods . . . . . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.1. Input Method Overview . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.1.1. Input Method Architecture . . . . . . .
. . . 13</small></p>
<p><small>13.5.1.2. Input Contexts . . . . . . . . . . . .
. . . . 13</small></p>
<p><small>13.5.1.3. Getting Keyboard Input . . . . . . . .
. . . . 13</small></p>
<p><small>13.5.1.4. Focus Management . . . . . . . . . . .
. . . . 13</small></p>
<p><small>13.5.1.5. Geometry Management . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.1.6. Event Filtering . . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.1.7. Callbacks . . . . . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.1.8. Visible Position Feedback Masks . . . .
. . . 13</small></p>
<p><small>13.5.1.9. Preedit String Management . . . . . . .
. . . 13</small></p>
<p><small>13.5.2. Input Method Management . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.2.1. Hot Keys . . . . . . . . . . . . . . .
. . . . 13</small></p>
<p><small>13.5.2.2. Preedit State Operation . . . . . . . .
. . . 13</small></p>
<p><small>13.5.3. Input Method Functions . . . . . . . . .
. . . . 13</small></p>
<p><small>13.5.4. Input Method Values . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.4.1. Query Input Style . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.4.2. Resource Name and Class . . . . . . . .
. . . 13</small></p>
<p><small>13.5.4.3. Destroy Callback . . . . . . . . . . .
. . . . 13</small></p>
<p><small>13.5.4.4. Query IM/IC Values List . . . . . . . .
. . . 13</small></p>
<p><small>13.5.4.5. Visible Position . . . . . . . . . . .
. . . . 13</small></p>
<p><small>13.5.4.6. Preedit Callback Behavior . . . . . . .
. . . 13</small></p>
<p><small>13.5.5. Input Context Functions . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.6. Input Context Values . . . . . . . . . .
. . . . 13</small></p>
<p><small>13.5.6.1. Input Style . . . . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.6.2. Client Window . . . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.6.3. Focus Window . . . . . . . . . . . . .
. . . . 13</small></p>
<p><small>13.5.6.4. Resource Name and Class . . . . . . . .
. . . 13</small></p>
<p><small>13.5.6.5. Geometry Callback . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.6.6. Filter Events . . . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.6.7. Destroy Callback . . . . . . . . . . .
. . . . 13</small></p>
<p><small>13.5.6.8. String Conversion Callback . . . . . .
. . . . 13</small></p>
<p><small>13.5.6.9. String Conversion . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.6.10. Reset State . . . . . . . . . . . . .
. . . . 13</small></p>
<p><small>13.5.6.11. Hot Keys . . . . . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.6.12. Hot Key State . . . . . . . . . . . .
. . . . 13</small></p>
<p><small>13.5.6.13. Preedit and Status Attributes . . . .
. . . . 13</small></p>
<p><small>13.5.6.13.1. Area . . . . . . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.6.13.2. Area Needed . . . . . . . . . . . .
. . . . 13</small></p>
<p><small>13.5.6.13.3. Spot Location . . . . . . . . . . .
. . . . 13</small></p>
<p><small>13.5.6.13.4. Colormap . . . . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.6.13.5. Foreground and Background . . . . .
. . . . 13</small></p>
<p><small>13.5.6.13.6. Background Pixmap . . . . . . . . .
. . . . 13</small></p>
<p><small>13.5.6.13.7. Font Set . . . . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.6.13.8. Line Spacing . . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.6.13.9. Cursor . . . . . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.6.13.10. Preedit State . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.6.13.11. Preedit State Notify Callback . . .
. . . 13</small></p>
<p><small>13.5.6.13.12. Preedit and Status Callbacks . . .
. . . . 13</small></p>
<p><small>13.5.7. Input Method Callback Semantics . . . . .
. . . 13</small></p>
<p><small>13.5.7.1. Geometry Callback . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.7.2. Destroy Callback . . . . . . . . . . .
. . . . 13</small></p>
<p><small>13.5.7.3. String Conversion Callback . . . . . .
. . . . 13</small></p>
<p><small>13.5.7.4. Preedit State Callbacks . . . . . . . .
. . . 13</small></p>
<p><small>13.5.7.5. Preedit Draw Callback . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.7.6. Preedit Caret Callback . . . . . . . .
. . . . 13</small></p>
<p><small>13.5.7.7. Status Callbacks . . . . . . . . . . .
. . . . 13</small></p>
<p><small>13.5.8. Event Filtering . . . . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.9. Getting Keyboard Input . . . . . . . . .
. . . . 13</small></p>
<p><small>13.5.10. Input Method Conventions . . . . . . . .
. . . 13</small></p>
<p><small>13.5.10.1. Client Conventions . . . . . . . . . .
. . . 13</small></p>
<p><small>13.5.10.2. Synchronization Conventions . . . . .
. . . . 13</small></p>
<p><small>13.6. String Constants . . . . . . . . . . . . .
. . . . 13</small></p>
<p><small>Chapter 14: Inter-Client Communication Functions
. . . . 14</small></p>
<p><small>14.1. Client to Window Manager Communication . .
. . . . 14</small></p>
<p><small>14.1.1. Manipulating Top-Level Windows . . . . .
. . . . 14</small></p>
<p><small>14.1.2. Converting String Lists . . . . . . . . .
. . . 14</small></p>
<p><small>14.1.3. Setting and Reading Text Properties . . .
. . . 14</small></p>
<p><small>14.1.4. Setting and Reading the WM_NAME Property
. . . . 14</small></p>
<p><small>14.1.5. Setting and Reading the WM_ICON_NAME
Property . . . . . . . . . . . . . . . . . . . . . . . .
14</small></p>
<p><small>14.1.6. Setting and Reading the WM_HINTS Property
. . . 14</small></p>
<p><small>14.1.7. Setting and Reading the WM_NORMAL_HINTS
Property . . . . . . . . . . . . . . . . . . . . . . . .
14</small></p>
<p><small>14.1.8. Setting and Reading the WM_CLASS Property
. . . 14</small></p>
<p><small>14.1.9. Setting and Reading the WM_TRANSIENT_FOR
Property . . . . . . . . . . . . . . . . . . . . . . . .
14</small></p>
<p><small>14.1.10. Setting and Reading the WM_PROTOCOLS
Property . . . . . . . . . . . . . . . . . . . . . . . .
14</small></p>
<p><small>14.1.11. Setting and Reading the
WM_COLORMAP_WINDOWS Property . . . . . . . . . . . . . . . .
. . . . . . . . 14</small></p>
<p><small>14.1.12. Setting and Reading the WM_ICON_SIZE
Property . . . . . . . . . . . . . . . . . . . . . . . .
14</small></p>
<p><small>14.1.13. Using Window Manager Convenience
Functions . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 14</small></p>
<p><small>14.2. Client to Session Manager Communication . .
. . . 14</small></p>
<p><small>14.2.1. Setting and Reading the WM_COMMAND
Property . . . . . . . . . . . . . . . . . . . . . . . . . .
. . 14</small></p>
<p><small>14.2.2. Setting and Reading the WM_CLIENT_MACHINE
Property . . . . . . . . . . . . . . . . . . . . . . . .
14</small></p>
<p><small>14.3. Standard Colormaps . . . . . . . . . . . .
. . . . 14</small></p>
<p><small>14.3.1. Standard Colormap Properties and Atoms .
. . . . 14</small></p>
<p><small>14.3.2. Setting and Obtaining Standard Colormaps
. . . . 14</small></p>
<p><small>Chapter 15: Resource Manager Functions . . . . .
. . . . 15</small></p>
<p><small>15.1. Resource File Syntax . . . . . . . . . . .
. . . . 15</small></p>
<p><small>15.2. Resource Manager Matching Rules . . . . . .
. . . 15</small></p>
<p><small>15.3. Quarks . . . . . . . . . . . . . . . . . .
. . . . 15</small></p>
<p><small>15.4. Creating and Storing Databases . . . . . .
. . . . 15</small></p>
<p><small>15.5. Merging Resource Databases . . . . . . . .
. . . . 15</small></p>
<p><small>15.6. Looking Up Resources . . . . . . . . . . .
. . . . 15</small></p>
<p><small>15.7. Storing into a Resource Database . . . . .
. . . . 15</small></p>
<p><small>15.8. Enumerating Database Entries . . . . . . .
. . . . 15</small></p>
<p><small>15.9. Parsing Command Line Options . . . . . . .
. . . . 15</small></p>
<p><small>Chapter 16: Application Utility Functions . . . .
. . . 16</small></p>
<p><small>16.1. Using Keyboard Utility Functions . . . . .
. . . . 16</small></p>
<p><small>16.1.1. KeySym Classification Macros . . . . . .
. . . . 16</small></p>
<p><small>16.2. Using Latin-1 Keyboard Event Functions . .
. . . . 16</small></p>
<p><small>16.3. Allocating Permanent Storage . . . . . . .
. . . . 16</small></p>
<p><small>16.4. Parsing the Window Geometry . . . . . . . .
. . . 16</small></p>
<p><small>16.5. Manipulating Regions . . . . . . . . . . .
. . . . 16</small></p>
<p><small>16.5.1. Creating, Copying, or Destroying Regions
. . . . 16</small></p>
<p><small>16.5.2. Moving or Shrinking Regions . . . . . . .
. . . 16</small></p>
<p><small>16.5.3. Computing with Regions . . . . . . . . .
. . . . 16</small></p>
<p><small>16.5.4. Determining if Regions Are Empty or Equal
. . . 16</small></p>
<p><small>16.5.5. Locating a Point or a Rectangle in a
Region . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 16</small></p>
<p><small>16.6. Using Cut Buffers . . . . . . . . . . . . .
. . . 16</small></p>
<p><small>16.7. Determining the Appropriate Visual Type . .
. . . 16</small></p>
<p><small>16.8. Manipulating Images . . . . . . . . . . . .
. . . 16</small></p>
<p><small>16.9. Manipulating Bitmaps . . . . . . . . . . .
. . . . 16</small></p>
<p><small>16.10. Using the Context Manager . . . . . . . .
. . . . 16</small></p>
<p><small>Appendix A: Xlib Functions and Protocol Requests
. . . . 17</small></p>
<p><small>Appendix B: X Font Cursors . . . . . . . . . . .
. . . 19</small></p>
<p><small>Appendix C: Extensions . . . . . . . . . . . . .
. . . . 20</small></p>
<p><small>Appendix D: Compatibility Functions . . . . . . .
. . . 21</small></p>
<p><small>Glossary . . . . . . . . . . . . . . . . . . . .
. . . . 22</small></p>
<p><small>Index . . . . . . . . . . . . . . . . . . . . . .
. . . 23</small></p>
<hr>
</body>
</html>
ACC SHELL 2018