/usr/share/doc/libx11-dev/libX11/libX11.html

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Xlib - C Language X Interface</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><style xmlns="" type="text/css">/*
 * Copyright (c) 2011 Gaetan Nadon
 * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
 *
 * 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:
 *
 * The above copyright notice and this permission notice (including the next
 * paragraph) shall be included in all copies or substantial portions of the
 * Software.
 *
 * 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 AUTHORS OR COPYRIGHT HOLDERS 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.
 */

/*
 * Shared stylesheet for X.Org documentation translated to HTML format
 * http://www.sagehill.net/docbookxsl/UsingCSS.html
 * http://www.w3schools.com/css/default.asp
 * https://addons.mozilla.org/en-US/firefox/addon/web-developer/developers
 * https://addons.mozilla.org/en-US/firefox/addon/font-finder/
 */

/*
 * The sans-serif fonts are considered more legible on a computer screen
 * http://dry.sailingissues.com/linux-equivalents-verdana-arial.html
 *
 */
body {
  font-family: "Bitstream Vera Sans", "DejaVu Sans", Tahoma, Geneva, Arial, Sans-serif;
  /* In support of using "em" font size unit, the w3c recommended method */
  font-size: 100%;
}

/*
 * Selection: all elements requiring mono spaced fonts.
 *
 * The family names attempt to match the proportionally spaced font
 * family names such that the same font name is used for both.
 * We'd like to use Bitstream, for example, in both proportionally and
 * mono spaced font text.
 */
.command,
.errorcode,
.errorname,
.errortype,
.filename,
.funcsynopsis,
.function,
.parameter,
.programlisting,
.property,
.screen,
.structname,
.symbol,
.synopsis,
.type
{
  font-family:  "Bitstream Vera Sans Mono", "DejaVu Sans Mono", Courier, "Liberation Mono", Monospace;
}

/*
 * Books have a title page, a preface, some chapters and appendices,
 * a glossary, an index and a bibliography, in that order.
 *
 * An Article has no preface and no chapters. It has sections, appendices,
 * a glossary, an index and a bibliography.
 */

/*
 * Selection: book main title and subtitle
 */
div.book>div.titlepage h1.title,
div.book>div.titlepage h2.subtitle {
  text-align: center;
}

/*
 * Selection: article main title and subtitle
 */
div.article>div.titlepage h2.title,
div.article>div.titlepage h3.subtitle,
div.article>div.sect1>div.titlepage h2.title,
div.article>div.section>div.titlepage h2.title {
  text-align: center;
}

/*
 * Selection: various types of authors and collaborators, individuals or corporate
 *
 * These authors are not always contained inside an authorgroup.
 * They can be contained inside a lot of different parent types where they might
 * not be centered.
 * Reducing the margin at the bottom makes a visual separation between authors
 * We specify here the ones on the title page, others may be added based on merit.
 */
div.titlepage .authorgroup,
div.titlepage .author,
div.titlepage .collab,
div.titlepage .corpauthor,
div.titlepage .corpcredit,
div.titlepage .editor,
div.titlepage .othercredit {
  text-align: center;
  margin-bottom: 0.25em;
}

/*
 * Selection: the affiliation of various types of authors and collaborators,
 * individuals or corporate.
 */
div.titlepage .affiliation {
  text-align: center;
}

/*
 * Selection: product release information (X Version 11, Release 7)
 *
 * The releaseinfo element can be contained inside a lot of different parent
 * types where it might not be centered.
 * We specify here the one on the title page, others may be added based on merit.
 */
div.titlepage p.releaseinfo {
  font-weight: bold;
  text-align: center;
}

/*
 * Selection: publishing date
 */
div.titlepage .pubdate {
  text-align: center;
}

/*
 * The legal notices are displayed in smaller sized fonts
 * Justification is only supported in IE and therefore not requested.
 *
 */
.legalnotice {
  font-size: small;
  font-style: italic;
}

/*
 * For documentation having multiple licenses, the copyright and legalnotice
 * elements sequence cannot instantiated multiple times.
 * The copyright notice and license text are therefore coded inside a legalnotice
 * element. The role attribute on the paragraph is used to allow styling of the
 * copyright notice text which should not be italicized.
 */
p.multiLicensing {
  font-style: normal;
  font-size: medium;
}

/*
 * Selection: book or article main ToC title
 * A paragraph is generated for the title rather than a level 2 heading.
 * We do not want to select chapters sub table of contents, only the main one
 */
div.book>div.toc>p,
div.article>div.toc>p {
  font-size: 1.5em;
  text-align: center;
}

/*
 * Selection: major sections of a book or an article
 *
 * Unlike books, articles do not have a titlepage element for appendix.
 * Using the selector "div.titlepage h2.title" would be too general.
 */
div.book>div.preface>div.titlepage h2.title,
div.book>div.chapter>div.titlepage h2.title,
div.article>div.sect1>div.titlepage h2.title,
div.article>div.section>div.titlepage h2.title,
div.book>div.appendix>div.titlepage h2.title,
div.article>div.appendix h2.title,
div.glossary>div.titlepage h2.title,
div.index>div.titlepage h2.title,
div.bibliography>div.titlepage h2.title {
   /* Add a border top over the major parts, just like printed books */
   /* The Gray color is already used for the ruler over the main ToC. */
  border-top-style: solid;
  border-top-width: 2px;
  border-top-color: Gray;
  /* Put some space between the border and the title */
  padding-top: 0.2em;
  text-align: center;
}

/*
 * A Screen is a verbatim environment for displaying text that the user might
 * see on a computer terminal. It is often used to display the results of a command.
 *
 * http://www.css3.info/preview/rounded-border/
 */
.screen {
  background: #e0ffff;
  border-width: 1px;
  border-style: solid;
  border-color: #B0C4DE;
  border-radius: 1.0em;
  /* Browser's vendor properties prior to CSS 3 */
  -moz-border-radius: 1.0em;
  -webkit-border-radius: 1.0em;
  -khtml-border-radius: 1.0em;
  margin-left: 1.0em;
  margin-right: 1.0em;
  padding: 0.5em;
}

/*
 * Emphasis program listings with a light shade of gray similar to what
 * DocBook XSL guide does: http://www.sagehill.net/docbookxsl/ProgramListings.html
 * Found many C API docs on the web using like shades of gray.
 */
.programlisting {
  background: #F4F4F4;
  border-width: 1px;
  border-style: solid;
  border-color: Gray;
  padding: 0.5em;
}

/*
 * Emphasis functions synopsis using a darker shade of gray.
 * Add a border such that it stands out more.
 * Set the padding so the text does not touch the border.
 */
.funcsynopsis, .synopsis {
  background: #e6e6fa;
  border-width: 1px;
  border-style: solid;
  border-color: Gray;
  clear: both;
  margin: 0.5em;
  padding: 0.25em;
}

/*
 * Selection: paragraphs inside synopsis
 *
 * Removes the default browser margin, let the container set the padding.
 * Paragraphs are not always used in synopsis
 */
.funcsynopsis p,
.synopsis p {
  margin: 0;
  padding: 0;
}

/*
 * Selection: variable lists, informal tables and tables
 *
 * Note the parameter name "variablelist.as.table" in xorg-xhtml.xsl
 * A table with rows and columns is constructed inside div.variablelist
 *
 * Set the left margin so it is indented to the right
 * Display informal tables with single line borders
 */
table {
  margin-left: 0.5em;
  border-collapse: collapse;
}

/*
 * Selection: paragraphs inside tables
 *
 * Removes the default browser margin, let the container set the padding.
 * Paragraphs are not always used in tables
 */
td p {
  margin: 0;
  padding: 0;
}

/*
 * Add some space between the left and right column.
 * The vertical alignment helps the reader associate a term
 * with a multi-line definition.
 */
td, th {
  padding-left: 1.0em;
  padding-right: 1.0em;
  vertical-align: top;
}

.warning {
  border: 1px solid red;
  background: #FFFF66;
  padding-left: 0.5em;
}
</style></head><body><div xml:lang="en" class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="libX11"></a>Xlib - C Language X Interface</h1></div><div><h2 class="subtitle">X Consortium Standard</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">James</span> <span class="surname">Gettys</span></h3><div class="affiliation"><span class="orgname">Digital Equipment Corporation<br /></span> <span class="orgdiv">Cambridge Research Laboratory<br /></span></div></div><div class="author"><h3 class="author"><span class="firstname">Robert</span> <span class="othername">W.</span> <span class="surname">Scheifler</span></h3><div class="affiliation"><span class="orgname">Massachusetts Institute of Technology<br /></span> <span class="orgdiv">Laboratory for Computer Science<br /></span></div></div><div class="othercredit"><h3 class="othercredit"><span class="firstname">Chuck</span> <span class="surname">Adams</span></h3><div class="affiliation"><span class="orgname">Tektronix, Inc.<br /></span></div></div><div class="othercredit"><h3 class="othercredit"><span class="firstname">Vania</span> <span class="surname">Joloboff</span></h3><div class="affiliation"><span class="orgname">Open Software Foundation<br /></span></div></div><div class="othercredit"><h3 class="othercredit"><span class="firstname">Hideki</span> <span class="surname">Hiura</span></h3><div class="affiliation"><span class="orgname">Sun Microsystems, Inc.<br /></span></div></div><div class="othercredit"><h3 class="othercredit"><span class="firstname">Bill</span> <span class="surname">McMahon</span></h3><div class="affiliation"><span class="orgname">Hewlett-Packard Company<br /></span></div></div><div class="othercredit"><h3 class="othercredit"><span class="firstname">Ron</span> <span class="surname">Newman</span></h3><div class="affiliation"><span class="orgname">Massachusetts Institute of Technology<br /></span></div></div><div class="othercredit"><h3 class="othercredit"><span class="firstname">Al</span> <span class="surname">Tabayoyon</span></h3><div class="affiliation"><span class="orgname">Tektronix, Inc.<br /></span></div></div><div class="othercredit"><h3 class="othercredit"><span class="firstname">Glenn</span> <span class="surname">Widener</span></h3><div class="affiliation"><span class="orgname">Tektronix, Inc.<br /></span></div></div><div class="othercredit"><h3 class="othercredit"><span class="firstname">Shigeru</span> <span class="surname">Yamada</span></h3><div class="affiliation"><span class="orgname">Fujitsu OSSI<br /></span></div></div></div></div><div><p class="releaseinfo">X Version 11, Release 7.7</p></div><div><p class="copyright">Copyright © 1985, 1986, 1987, 1988, 1989, 1991, 1994, 1996, 2002 The Open Group</p></div><div><div class="legalnotice"><a id="idp37061988"></a><p>
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:
</p><p>
The above copyright notice and this permission notice shall be included in all 
copies or substantial portions of the Software.
</p><p>
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
OPEN GROUP 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.
</p><p>
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.
</p></div></div><div><div class="legalnotice"><a id="idp38503508"></a><p class="multiLicensing">Copyright © 1985, 1986, 1987, 1988, 1989, 1991 Digital Equipment Corporation</p><p>
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 supporting documentation, and that the names of
Digital and Tetronix not be used in in advertising or publicity pertaining
to distribution of the software without specific, written prior permission.
Digital and Tetronix make no representations about the suitability of the
software described herein for any purpose.
It is provided “as is” without express or implied warranty.
</p><p>TekHVC is a trademark of Tektronix, Inc.</p></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="preface"><a href="#acknowledgments">Acknowledgments</a></span></dt><dt><span class="chapter"><a href="#Introduction_to_Xlib">1. Introduction to Xlib</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Overview_of_the_X_Window_System">Overview of the X Window System</a></span></dt><dt><span class="sect1"><a href="#Errors">Errors</a></span></dt><dt><span class="sect1"><a href="#Standard_Header_Files">Standard Header Files</a></span></dt><dt><span class="sect1"><a href="#Generic_Values_and_Types">Generic Values and Types</a></span></dt><dt><span class="sect1"><a href="#Naming_and_Argument_Conventions_within_Xlib">Naming and Argument Conventions within Xlib</a></span></dt><dt><span class="sect1"><a href="#Programming_Considerations">Programming Considerations</a></span></dt><dt><span class="sect1"><a href="#Character_Sets_and_Encodings">Character Sets and Encodings</a></span></dt><dt><span class="sect1"><a href="#Formatting_Conventions">Formatting Conventions</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Display_Functions">2. Display Functions</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Opening_the_Display">Opening the Display</a></span></dt><dt><span class="sect1"><a href="#Obtaining_Information_about_the_Display_Image_Formats_or_Screens">Obtaining Information about the Display, Image Formats, or Screens</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Display_Macros">Display Macros</a></span></dt><dt><span class="sect2"><a href="#Image_Format_Functions_and_Macros">Image Format Functions and Macros</a></span></dt><dt><span class="sect2"><a href="#Screen_Information_Macros">Screen Information Macros</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Generating_a_NoOperation_Protocol_Request">Generating a NoOperation Protocol Request</a></span></dt><dt><span class="sect1"><a href="#Freeing_Client_Created_Data">Freeing Client-Created Data</a></span></dt><dt><span class="sect1"><a href="#Closing_the_Display">Closing the Display</a></span></dt><dt><span class="sect1"><a href="#Using_X_Server_Connection_Close_Operations">Using X Server Connection Close Operations</a></span></dt><dt><span class="sect1"><a href="#Using_Xlib_with_Threads">Using Xlib with Threads</a></span></dt><dt><span class="sect1"><a href="#Using_Internal_Connections">Using Internal Connections</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Window_Functions">3. Window Functions</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Visual_Types">Visual Types</a></span></dt><dt><span class="sect1"><a href="#Window_Attributes">Window Attributes</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Background_Attribute">Background Attribute</a></span></dt><dt><span class="sect2"><a href="#Border_Attribute">Border Attribute</a></span></dt><dt><span class="sect2"><a href="#Gravity_Attributes">Gravity Attributes</a></span></dt><dt><span class="sect2"><a href="#Backing_Store_Attribute">Backing Store Attribute</a></span></dt><dt><span class="sect2"><a href="#Save_Under_Flag">Save Under Flag</a></span></dt><dt><span class="sect2"><a href="#Backing_Planes_and_Backing_Pixel_Attributes">Backing Planes and Backing Pixel Attributes</a></span></dt><dt><span class="sect2"><a href="#Event_Mask_and_Do_Not_Propagate_Mask_Attributes">Event Mask and Do Not Propagate Mask Attributes</a></span></dt><dt><span class="sect2"><a href="#Override_Redirect_Flag">Override Redirect Flag</a></span></dt><dt><span class="sect2"><a href="#Colormap_Attribute">Colormap Attribute</a></span></dt><dt><span class="sect2"><a href="#Cursor_Attribute">Cursor Attribute</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Creating_Windows">Creating Windows</a></span></dt><dt><span class="sect1"><a href="#Destroying_Windows">Destroying Windows</a></span></dt><dt><span class="sect1"><a href="#Mapping_Windows">Mapping Windows</a></span></dt><dt><span class="sect1"><a href="#Unmapping_Windows">Unmapping Windows</a></span></dt><dt><span class="sect1"><a href="#Configuring_Windows">Configuring Windows</a></span></dt><dt><span class="sect1"><a href="#Changing_Window_Stacking_Order">Changing Window Stacking Order</a></span></dt><dt><span class="sect1"><a href="#Changing_Window_Attributes">Changing Window Attributes</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Window_Information_Functions">4. Window Information Functions</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Obtaining_Window_Information">Obtaining Window Information</a></span></dt><dt><span class="sect1"><a href="#Translating_Screen_Coordinates">Translating Screen Coordinates</a></span></dt><dt><span class="sect1"><a href="#Properties_and_Atoms">Properties and Atoms</a></span></dt><dt><span class="sect1"><a href="#Obtaining_and_Changing_Window_Properties">Obtaining and Changing Window Properties</a></span></dt><dt><span class="sect1"><a href="#Selections">Selections</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Pixmap_and_Cursor_Functions">5. Pixmap and Cursor Functions</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Creating_and_Freeing_Pixmaps">Creating and Freeing Pixmaps</a></span></dt><dt><span class="sect1"><a href="#Creating_Recoloring_and_Freeing_Cursors">Creating, Recoloring, and Freeing Cursors</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Color_Management_Functions">6. Color Management Functions</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Color_Structures">Color Structures</a></span></dt><dt><span class="sect1"><a href="#Color_Strings">Color Strings</a></span></dt><dd><dl><dt><span class="sect2"><a href="#RGB_Device_String_Specification"><acronym class="acronym">RGB</acronym> Device String Specification</a></span></dt><dt><span class="sect2"><a href="#RGB_Intensity_String_Specification"><acronym class="acronym">RGB</acronym> Intensity String Specification</a></span></dt><dt><span class="sect2"><a href="#Device_Independent_String_Specifications">Device-Independent String Specifications</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Color_Conversion_Contexts_and_Gamut_Mapping">Color Conversion Contexts and Gamut Mapping</a></span></dt><dt><span class="sect1"><a href="#Creating_Copying_and_Destroying_Colormaps">Creating, Copying, and Destroying Colormaps</a></span></dt><dt><span class="sect1"><a href="#Mapping_Color_Names_to_Values">Mapping Color Names to Values</a></span></dt><dt><span class="sect1"><a href="#Allocating_and_Freeing_Color_Cells">Allocating and Freeing Color Cells</a></span></dt><dt><span class="sect1"><a href="#Modifying_and_Querying_Colormap_Cells">Modifying and Querying Colormap Cells</a></span></dt><dt><span class="sect1"><a href="#Color_Conversion_Context_Functions">Color Conversion Context Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Getting_and_Setting_the_Color_Conversion_Context_of_a_Colormap">Getting and Setting the Color Conversion Context of a Colormap</a></span></dt><dt><span class="sect2"><a href="#Obtaining_the_Default_Color_Conversion_Context">Obtaining the Default Color Conversion Context</a></span></dt><dt><span class="sect2"><a href="#Color_Conversion_Context_Macros">Color Conversion Context Macros</a></span></dt><dt><span class="sect2"><a href="#Modifying_Attributes_of_a_Color_Conversion_Context">Modifying Attributes of a Color Conversion Context</a></span></dt><dt><span class="sect2"><a href="#Creating_and_Freeing_a_Color_Conversion_Context">Creating and Freeing a Color Conversion Context</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Converting_between_Color_Spaces">Converting between Color Spaces</a></span></dt><dt><span class="sect1"><a href="#Callback_Functions">Callback Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Prototype_Gamut_Compression_Procedure">Prototype Gamut Compression Procedure</a></span></dt><dt><span class="sect2"><a href="#Supplied_Gamut_Compression_Procedures">Supplied Gamut Compression Procedures</a></span></dt><dt><span class="sect2"><a href="#Prototype_White_Point_Adjustment_Procedure">Prototype White Point Adjustment Procedure</a></span></dt><dt><span class="sect2"><a href="#Supplied_White_Point_Adjustment_Procedures">Supplied White Point Adjustment Procedures</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Gamut_Querying_Functions">Gamut Querying Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Red_Green_and_Blue_Queries">Red, Green, and Blue Queries</a></span></dt><dt><span class="sect2"><a href="#CIELab_Queries">CIELab Queries</a></span></dt><dt><span class="sect2"><a href="#CIELuv_Queries">CIELuv Queries</a></span></dt><dt><span class="sect2"><a href="#TekHVC_Queries">TekHVC Queries</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Color_Management_Extensions">Color Management Extensions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Color_Spaces">Color Spaces</a></span></dt><dt><span class="sect2"><a href="#Adding_Device_Independent_Color_Spaces">Adding Device-Independent Color Spaces</a></span></dt><dt><span class="sect2"><a href="#Querying_Color_Space_Format_and_Prefix">Querying Color Space Format and Prefix</a></span></dt><dt><span class="sect2"><a href="#Creating_Additional_Color_Spaces">Creating Additional Color Spaces</a></span></dt><dt><span class="sect2"><a href="#Parse_String_Callback">Parse String Callback</a></span></dt><dt><span class="sect2"><a href="#Color_Specification_Conversion_Callback">Color Specification Conversion Callback</a></span></dt><dt><span class="sect2"><a href="#Function_Sets">Function Sets</a></span></dt><dt><span class="sect2"><a href="#Adding_Function_Sets">Adding Function Sets</a></span></dt><dt><span class="sect2"><a href="#Creating_Additional_Function_Sets">Creating Additional Function Sets</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#Graphics_Context_Functions">7. Graphics Context Functions</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Manipulating_Graphics_ContextState">Manipulating Graphics Context/State</a></span></dt><dt><span class="sect1"><a href="#Using_Graphics_Context_Convenience_Routines">Using Graphics Context Convenience Routines</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Setting_the_Foreground_Background_Function_or_Plane_Mask">Setting the Foreground, Background, Function, or Plane Mask</a></span></dt><dt><span class="sect2"><a href="#Setting_the_Line_Attributes_and_Dashes">Setting the Line Attributes and Dashes</a></span></dt><dt><span class="sect2"><a href="#Setting_the_Fill_Style_and_Fill_Rule">Setting the Fill Style and Fill Rule</a></span></dt><dt><span class="sect2"><a href="#Setting_the_Fill_Tile_and_Stipple">Setting the Fill Tile and Stipple</a></span></dt><dt><span class="sect2"><a href="#Setting_the_Current_Font">Setting the Current Font</a></span></dt><dt><span class="sect2"><a href="#Setting_the_Clip_Region">Setting the Clip Region</a></span></dt><dt><span class="sect2"><a href="#Setting_the_Arc_Mode_Subwindow_Mode_and_Graphics_Exposure">Setting the Arc Mode, Subwindow Mode, and Graphics Exposure</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#Graphics_Functions">8. Graphics Functions</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Clearing_Areas">Clearing Areas</a></span></dt><dt><span class="sect1"><a href="#Copying_Areas">Copying Areas</a></span></dt><dt><span class="sect1"><a href="#Drawing_Points_Lines_Rectangles_and_Arcs">Drawing Points, Lines, Rectangles, and Arcs</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Drawing_Single_and_Multiple_Points">Drawing Single and Multiple Points</a></span></dt><dt><span class="sect2"><a href="#Drawing_Single_and_Multiple_Lines">Drawing Single and Multiple Lines</a></span></dt><dt><span class="sect2"><a href="#Drawing_Single_and_Multiple_Rectangles">Drawing Single and Multiple Rectangles</a></span></dt><dt><span class="sect2"><a href="#Drawing_Single_and_Multiple_Arcs">Drawing Single and Multiple Arcs</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Filling_Areas">Filling Areas</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Filling_Single_and_Multiple_Rectangles">Filling Single and Multiple Rectangles</a></span></dt><dt><span class="sect2"><a href="#Filling_a_Single_Polygon">Filling a Single Polygon</a></span></dt><dt><span class="sect2"><a href="#Filling_Single_and_Multiple_Arcs">Filling Single and Multiple Arcs</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Font_Metrics">Font Metrics</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Loading_and_Freeing_Fonts">Loading and Freeing Fonts</a></span></dt><dt><span class="sect2"><a href="#Obtaining_and_Freeing_Font_Names_and_Information">Obtaining and Freeing Font Names and Information</a></span></dt><dt><span class="sect2"><a href="#Computing_Character_String_Sizes">Computing Character String Sizes</a></span></dt><dt><span class="sect2"><a href="#Computing_Logical_Extents">Computing Logical Extents</a></span></dt><dt><span class="sect2"><a href="#Querying_Character_String_Sizes">Querying Character String Sizes</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Drawing_Text">Drawing Text</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Drawing_Complex_Text">Drawing Complex Text</a></span></dt><dt><span class="sect2"><a href="#Drawing_Text_Characters">Drawing Text Characters</a></span></dt><dt><span class="sect2"><a href="#Drawing_Image_Text_Characters">Drawing Image Text Characters</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Transferring_Images_between_Client_and_Server">Transferring Images between Client and Server</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Window_and_Session_Manager_Functions">9. Window and Session Manager Functions</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Changing_the_Parent_of_a_Window">Changing the Parent of a Window</a></span></dt><dt><span class="sect1"><a href="#Controlling_the_Lifetime_of_a_Window">Controlling the Lifetime of a Window</a></span></dt><dt><span class="sect1"><a href="#Managing_Installed_Colormaps">Managing Installed Colormaps</a></span></dt><dt><span class="sect1"><a href="#Setting_and_Retrieving_the_Font_Search_Path">Setting and Retrieving the Font Search Path</a></span></dt><dt><span class="sect1"><a href="#Grabbing_the_Server">Grabbing the Server</a></span></dt><dt><span class="sect1"><a href="#Killing_Clients">Killing Clients</a></span></dt><dt><span class="sect1"><a href="#Controlling_the_Screen_Saver">Controlling the Screen Saver</a></span></dt><dt><span class="sect1"><a href="#Controlling_Host_Access">Controlling Host Access</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Adding_Getting_or_Removing_Hosts">Adding, Getting, or Removing Hosts</a></span></dt><dt><span class="sect2"><a href="#Changing_Enabling_or_Disabling_Access_Control">Changing, Enabling, or Disabling Access Control</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#Events">10. Events</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Event_Types">Event Types</a></span></dt><dt><span class="sect1"><a href="#Event_Structures">Event Structures</a></span></dt><dt><span class="sect1"><a href="#Event_Masks">Event Masks</a></span></dt><dt><span class="sect1"><a href="#Event_Processing_Overview">Event Processing Overview</a></span></dt><dt><span class="sect1"><a href="#Keyboard_and_Pointer_Events">Keyboard and Pointer Events</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Pointer_Button_Events">Pointer Button Events</a></span></dt><dt><span class="sect2"><a href="#Keyboard_and_Pointer_Events_b">Keyboard and Pointer Events</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Window_EntryExit_Events">Window Entry/Exit Events</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Normal_EntryExit_Events">Normal Entry/Exit Events</a></span></dt><dt><span class="sect2"><a href="#Grab_and_Ungrab_EntryExit_Events">Grab and Ungrab Entry/Exit Events</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Input_Focus_Events">Input Focus Events</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Normal_Focus_Events_and_Focus_Events_While_Grabbed">Normal Focus Events and Focus Events While Grabbed</a></span></dt><dt><span class="sect2"><a href="#Focus_Events_Generated_by_Grabs">Focus Events Generated by Grabs</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Key_Map_State_Notification_Events">Key Map State Notification Events</a></span></dt><dt><span class="sect1"><a href="#Exposure_Events">Exposure Events</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Expose_Events">Expose Events</a></span></dt><dt><span class="sect2"><a href="#GraphicsExpose_and_NoExpose_Events">GraphicsExpose and NoExpose Events</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Window_State_Change_Events">Window State Change Events</a></span></dt><dd><dl><dt><span class="sect2"><a href="#CirculateNotify_Events">CirculateNotify Events</a></span></dt><dt><span class="sect2"><a href="#ConfigureNotify_Events">ConfigureNotify Events</a></span></dt><dt><span class="sect2"><a href="#CreateNotify_Events">CreateNotify Events</a></span></dt><dt><span class="sect2"><a href="#DestroyNotify_Events">DestroyNotify Events</a></span></dt><dt><span class="sect2"><a href="#GravityNotify_Events">GravityNotify Events</a></span></dt><dt><span class="sect2"><a href="#MapNotify_Events">MapNotify Events</a></span></dt><dt><span class="sect2"><a href="#MappingNotify_Events">MappingNotify Events</a></span></dt><dt><span class="sect2"><a href="#ReparentNotify_Events">ReparentNotify Events</a></span></dt><dt><span class="sect2"><a href="#UnmapNotify_Events">UnmapNotify Events</a></span></dt><dt><span class="sect2"><a href="#VisibilityNotify_Events">VisibilityNotify Events</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Structure_Control_Events">Structure Control Events</a></span></dt><dd><dl><dt><span class="sect2"><a href="#CirculateRequest_Events">CirculateRequest Events</a></span></dt><dt><span class="sect2"><a href="#ConfigureRequest_Events">ConfigureRequest Events</a></span></dt><dt><span class="sect2"><a href="#MapRequest_Events">MapRequest Events</a></span></dt><dt><span class="sect2"><a href="#ResizeRequest_Events">ResizeRequest Events</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Colormap_State_Change_Events">Colormap State Change Events</a></span></dt><dt><span class="sect1"><a href="#Client_Communication_Events">Client Communication Events</a></span></dt><dd><dl><dt><span class="sect2"><a href="#ClientMessage_Events">ClientMessage Events</a></span></dt><dt><span class="sect2"><a href="#PropertyNotify_Events">PropertyNotify Events</a></span></dt><dt><span class="sect2"><a href="#SelectionClear_Events">SelectionClear Events</a></span></dt><dt><span class="sect2"><a href="#SelectionRequest_Events">SelectionRequest Events</a></span></dt><dt><span class="sect2"><a href="#SelectionNotify_Events">SelectionNotify Events</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#Event_Handling_Functions">11. Event Handling Functions</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Selecting_Events">Selecting Events</a></span></dt><dt><span class="sect1"><a href="#Handling_the_Output_Buffer">Handling the Output Buffer</a></span></dt><dt><span class="sect1"><a href="#Event_Queue_Management">Event Queue Management</a></span></dt><dt><span class="sect1"><a href="#Manipulating_the_Event_Queue">Manipulating the Event Queue</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Returning_the_Next_Event">Returning the Next Event</a></span></dt><dt><span class="sect2"><a href="#Selecting_Events_Using_a_Predicate_Procedure">Selecting Events Using a Predicate Procedure</a></span></dt><dt><span class="sect2"><a href="#Selecting_Events_Using_a_Window_or_Event_Mask">Selecting Events Using a Window or Event Mask</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Putting_an_Event_Back_into_the_Queue">Putting an Event Back into the Queue</a></span></dt><dt><span class="sect1"><a href="#Sending_Events_to_Other_Applications">Sending Events to Other Applications</a></span></dt><dt><span class="sect1"><a href="#Getting_Pointer_Motion_History">Getting Pointer Motion History</a></span></dt><dt><span class="sect1"><a href="#Handling_Protocol_Errors">Handling Protocol Errors</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Enabling_or_Disabling_Synchronization">Enabling or Disabling Synchronization</a></span></dt><dt><span class="sect2"><a href="#Using_the_Default_Error_Handlers">Using the Default Error Handlers</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#Input_Device_Functions">12. Input Device Functions</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Pointer_Grabbing">Pointer Grabbing</a></span></dt><dt><span class="sect1"><a href="#Keyboard_Grabbing">Keyboard Grabbing</a></span></dt><dt><span class="sect1"><a href="#Resuming_Event_Processing">Resuming Event Processing</a></span></dt><dt><span class="sect1"><a href="#Moving_the_Pointer">Moving the Pointer</a></span></dt><dt><span class="sect1"><a href="#Controlling_Input_Focus">Controlling Input Focus</a></span></dt><dt><span class="sect1"><a href="#Manipulating_the_Keyboard_and_Pointer_Settings">Manipulating the Keyboard and Pointer Settings</a></span></dt><dt><span class="sect1"><a href="#Manipulating_the_Keyboard_Encoding">Manipulating the Keyboard Encoding</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Locales_and_Internationalized_Text_Functions">13. Locales and Internationalized Text Functions</a></span></dt><dd><dl><dt><span class="sect1"><a href="#X_Locale_Management">X Locale Management</a></span></dt><dt><span class="sect1"><a href="#Locale_and_Modifier_Dependencies">Locale and Modifier Dependencies</a></span></dt><dt><span class="sect1"><a href="#Variable_Argument_Lists">Variable Argument Lists</a></span></dt><dt><span class="sect1"><a href="#Output_Methods">Output Methods</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Output_Method_Overview">Output Method Overview</a></span></dt><dt><span class="sect2"><a href="#Output_Method_Functions">Output Method Functions</a></span></dt><dt><span class="sect2"><a href="#X_Output_Method_Values">X Output Method Values</a></span></dt><dt><span class="sect2"><a href="#Output_Context_Functions">Output Context Functions</a></span></dt><dt><span class="sect2"><a href="#Output_Context_Values">Output Context Values</a></span></dt><dt><span class="sect2"><a href="#Creating_and_Freeing_a_Font_Set">Creating and Freeing a Font Set</a></span></dt><dt><span class="sect2"><a href="#Obtaining_Font_Set_Metrics">Obtaining Font Set Metrics</a></span></dt><dt><span class="sect2"><a href="#Drawing_Text_Using_Font_Sets">Drawing Text Using Font Sets</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Input_Methods">Input Methods</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Input_Method_Overview">Input Method Overview</a></span></dt><dt><span class="sect2"><a href="#Input_Method_Management">Input Method Management</a></span></dt><dt><span class="sect2"><a href="#Input_Method_Functions">Input Method Functions</a></span></dt><dt><span class="sect2"><a href="#Input_Method_Values">Input Method Values</a></span></dt><dt><span class="sect2"><a href="#Input_Context_Functions">Input Context Functions</a></span></dt><dt><span class="sect2"><a href="#Input_Context_Values">Input Context Values</a></span></dt><dt><span class="sect2"><a href="#Input_Method_Callback_Semantics">Input Method Callback Semantics</a></span></dt><dt><span class="sect2"><a href="#Event_Filtering_b">Event Filtering</a></span></dt><dt><span class="sect2"><a href="#Getting_Keyboard_Input_b">Getting Keyboard Input</a></span></dt><dt><span class="sect2"><a href="#Input_Method_Conventions">Input Method Conventions</a></span></dt></dl></dd><dt><span class="sect1"><a href="#String_Constants">String Constants</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Inter_Client_Communication_Functions">14. Inter-Client Communication Functions</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Client_to_Window_Manager_Communication">Client to Window Manager Communication</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Manipulating_Top_Level_Windows">Manipulating Top-Level Windows</a></span></dt><dt><span class="sect2"><a href="#Converting_String_Lists">Converting String Lists</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_Text_Properties">Setting and Reading Text Properties</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_NAME_Property">Setting and Reading the WM_NAME Property</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_ICON_NAME_Property">Setting and Reading the WM_ICON_NAME Property</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_HINTS_Property">Setting and Reading the WM_HINTS Property</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_NORMAL_HINTS_Property">Setting and Reading the WM_NORMAL_HINTS Property</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_CLASS_Property">Setting and Reading the WM_CLASS Property</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_TRANSIENT_FOR_Property">Setting and Reading the WM_TRANSIENT_FOR Property</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_PROTOCOLS_Property">Setting and Reading the WM_PROTOCOLS Property</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_COLORMAP_WINDOWS_Property">Setting and Reading the WM_COLORMAP_WINDOWS Property</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_ICON_SIZE_Property">Setting and Reading the WM_ICON_SIZE Property</a></span></dt><dt><span class="sect2"><a href="#Using_Window_Manager_Convenience_Functions">Using Window Manager Convenience Functions</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Client_to_Session_Manager_Communication">Client to Session Manager Communication</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_COMMAND_Property">Setting and Reading the WM_COMMAND Property</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_CLIENT_MACHINE_Property">Setting and Reading the WM_CLIENT_MACHINE Property</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Standard_Colormaps">Standard Colormaps</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Standard_Colormap_Properties_and_Atoms">Standard Colormap Properties and Atoms</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Obtaining_Standard_Colormaps">Setting and Obtaining Standard Colormaps</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#Resource_Manager_Functions">15. Resource Manager Functions</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Resource_File_Syntax">Resource File Syntax</a></span></dt><dt><span class="sect1"><a href="#Resource_Manager_Matching_Rules">Resource Manager Matching Rules</a></span></dt><dt><span class="sect1"><a href="#Quarks">Quarks</a></span></dt><dt><span class="sect1"><a href="#Creating_and_Storing_Databases">Creating and Storing Databases</a></span></dt><dt><span class="sect1"><a href="#Merging_Resource_Databases">Merging Resource Databases</a></span></dt><dt><span class="sect1"><a href="#Looking_Up_Resources">Looking Up Resources</a></span></dt><dt><span class="sect1"><a href="#Storing_into_a_Resource_Database">Storing into a Resource Database</a></span></dt><dt><span class="sect1"><a href="#Enumerating_Database_Entries">Enumerating Database Entries</a></span></dt><dt><span class="sect1"><a href="#Parsing_Command_Line_Options">Parsing Command Line Options</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Application_Utility_Functions">16. Application Utility Functions</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Using_Keyboard_Utility_Functions">Using Keyboard Utility Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#KeySym_Classification_Macros">KeySym Classification Macros</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Using_Latin_1_Keyboard_Event_Functions">Using Latin-1 Keyboard Event Functions</a></span></dt><dt><span class="sect1"><a href="#Allocating_Permanent_Storage">Allocating Permanent Storage</a></span></dt><dt><span class="sect1"><a href="#Parsing_the_Window_Geometry">Parsing the Window Geometry</a></span></dt><dt><span class="sect1"><a href="#Manipulating_Regions">Manipulating Regions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Creating_Copying_or_Destroying_Regions">Creating, Copying, or Destroying Regions</a></span></dt><dt><span class="sect2"><a href="#Moving_or_Shrinking_Regions">Moving or Shrinking Regions</a></span></dt><dt><span class="sect2"><a href="#Computing_with_Regions">Computing with Regions</a></span></dt><dt><span class="sect2"><a href="#Determining_if_Regions_Are_Empty_or_Equal">Determining if Regions Are Empty or Equal</a></span></dt><dt><span class="sect2"><a href="#Locating_a_Point_or_a_Rectangle_in_a_Region">Locating a Point or a Rectangle in a Region</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Using_Cut_Buffers">Using Cut Buffers</a></span></dt><dt><span class="sect1"><a href="#Determining_the_Appropriate_Visual_Type">Determining the Appropriate Visual Type</a></span></dt><dt><span class="sect1"><a href="#Manipulating_Images">Manipulating Images</a></span></dt><dt><span class="sect1"><a href="#Manipulating_Bitmaps">Manipulating Bitmaps</a></span></dt><dt><span class="sect1"><a href="#Using_the_Context_Manager">Using the Context Manager</a></span></dt></dl></dd><dt><span class="appendix"><a href="#xlib_functions_and_protocol_requests">A. Xlib Functions and Protocol Requests</a></span></dt><dt><span class="appendix"><a href="#x_font_cursors">B. X Font Cursors</a></span></dt><dt><span class="appendix"><a href="#extensions">C. Extensions</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Basic_Protocol_Support_Routines">Basic Protocol Support Routines</a></span></dt><dt><span class="sect1"><a href="#Hooking_into_Xlib">Hooking into Xlib</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Hooks_into_the_Library">Hooks into the Library</a></span></dt><dt><span class="sect2"><a href="#Hooks_onto_Xlib_Data_Structures">Hooks onto Xlib Data Structures</a></span></dt></dl></dd><dt><span class="sect1"><a href="#GC_Caching">GC Caching</a></span></dt><dt><span class="sect1"><a href="#Graphics_Batching">Graphics Batching</a></span></dt><dt><span class="sect1"><a href="#Writing_Extension_Stubs">Writing Extension Stubs</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Requests_Replies_and_Xproto.h">Requests, Replies, and Xproto.h</a></span></dt><dt><span class="sect2"><a href="#Request_Format">Request Format</a></span></dt><dt><span class="sect2"><a href="#Starting_to_Write_a_Stub_Procedure">Starting to Write a Stub Procedure</a></span></dt><dt><span class="sect2"><a href="#Locking_Data_Structures">Locking Data Structures</a></span></dt><dt><span class="sect2"><a href="#Sending_the_Protocol_Request_and_Arguments">Sending the Protocol Request and Arguments</a></span></dt><dt><span class="sect2"><a href="#Variable_Length_Arguments">Variable Length Arguments</a></span></dt><dt><span class="sect2"><a href="#Replies">Replies</a></span></dt><dt><span class="sect2"><a href="#Synchronous_Calling">Synchronous Calling</a></span></dt><dt><span class="sect2"><a href="#Allocating_and_Deallocating_Memory">Allocating and Deallocating Memory</a></span></dt><dt><span class="sect2"><a href="#Portability_Considerations">Portability Considerations</a></span></dt><dt><span class="sect2"><a href="#Deriving_the_Correct_Extension_Opcode">Deriving the Correct Extension Opcode</a></span></dt></dl></dd></dl></dd><dt><span class="appendix"><a href="#compatibility_functions">D. Compatibility Functions</a></span></dt><dd><dl><dt><span class="sect1"><a href="#X_Version_11_Compatibility_Functions">X Version 11 Compatibility Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Setting_Standard_Properties">Setting Standard Properties</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Getting_Window_Sizing_Hints">Setting and Getting Window Sizing Hints</a></span></dt><dt><span class="sect2"><a href="#Getting_and_Setting_an_XStandardColormap_Structure">Getting and Setting an XStandardColormap Structure</a></span></dt><dt><span class="sect2"><a href="#Parsing_Window_Geometry">Parsing Window Geometry</a></span></dt><dt><span class="sect2"><a href="#Getting_the_X_Environment_Defaults">Getting the X Environment Defaults</a></span></dt></dl></dd><dt><span class="sect1"><a href="#X_Version_10_Compatibility_Functions">X Version 10 Compatibility Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Drawing_and_Filling_Polygons_and_Curves">Drawing and Filling Polygons and Curves</a></span></dt><dt><span class="sect2"><a href="#Associating_User_Data_with_a_Value">Associating User Data with a Value</a></span></dt></dl></dd></dl></dd><dt><span class="glossary"><a href="#glossary">Glossary</a></span></dt><dt><span class="index"><a href="#idp37026124">Index</a></span></dt></dl></div><div class="list-of-tables"><p><strong>List of Tables</strong></p><dl><dt>A.1. <a href="#idp40218868">Protocol requests made by each Xlib function</a></dt><dt>A.2. <a href="#idp53027668">Xlib functions which use each Protocol Request</a></dt></dl></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a id="acknowledgments"></a>Acknowledgments</h1></div></div></div><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><div class="simplesect"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idp41654244"></a>Release 1</h2></div></div></div><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></div><div class="simplesect"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idp39758100"></a>Release 4</h2></div></div></div><p>
Our thanks go to Jim Fulton (MIT X Consortium) for designing and
specifying the new Xlib functions for Inter-Client Communication
Conventions (<acronym class="acronym">ICCCM</acronym>) 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></div><div class="simplesect"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idp39759548"></a>Release 5</h2></div></div></div><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&amp;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&amp;T),
Manish Sheth (AT&amp;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&amp;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></div><div class="simplesect"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idp42151436"></a>Release 6</h2></div></div></div><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><p>
</p><div class="literallayout"><p><br />
Jim Gettys<br />
Cambridge Research Laboratory<br />
Digital Equipment Corporation<br />
<br />
Robert W. Scheifler<br />
Laboratory for Computer Science<br />
Massachusetts Institute of Technology<br />
</p></div><p>
</p></div><div class="simplesect"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idp37029612"></a>Release 7</h2></div></div></div><p>
This document is made available to you in modern formats such as HTML and PDF
thanks to the efforts of Matt Dew, who converted the original troff sources to
DocBook/XML and edited them into shape; along with Gaetan Nadon and
Alan Coopersmith, who set up the formatting machinery in the libX11 builds and
performed further editing of the DocBook markup.
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Introduction_to_Xlib"></a>Chapter 1. Introduction to Xlib</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Overview_of_the_X_Window_System">Overview of the X Window System</a></span></dt><dt><span class="sect1"><a href="#Errors">Errors</a></span></dt><dt><span class="sect1"><a href="#Standard_Header_Files">Standard Header Files</a></span></dt><dt><span class="sect1"><a href="#Generic_Values_and_Types">Generic Values and Types</a></span></dt><dt><span class="sect1"><a href="#Naming_and_Argument_Conventions_within_Xlib">Naming and Argument Conventions within Xlib</a></span></dt><dt><span class="sect1"><a href="#Programming_Considerations">Programming Considerations</a></span></dt><dt><span class="sect1"><a href="#Character_Sets_and_Encodings">Character Sets and Encodings</a></span></dt><dt><span class="sect1"><a href="#Formatting_Conventions">Formatting Conventions</a></span></dt></dl></div><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>
<em class="citetitle">Xlib − C Language X Interface</em> 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. <em class="citetitle">Xlib − C Language X Interface</em>
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 <span class="olink"><em class="citetitle">X Window System Protocol</em></span> 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><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="link" href="#Overview_of_the_X_Window_System" title="Overview of the X Window System">Overview of the X Window System</a></p></li><li class="listitem"><p><a class="link" href="#Errors" title="Errors">Errors</a></p></li><li class="listitem"><p><a class="link" href="#Standard_Header_Files" title="Standard Header Files">Standard header files</a></p></li><li class="listitem"><p><a class="link" href="#Generic_Values_and_Types" title="Generic Values and Types">Generic values and types</a></p></li><li class="listitem"><p><a class="link" href="#Naming_and_Argument_Conventions_within_Xlib" title="Naming and Argument Conventions within Xlib">Naming and argument conventions within Xlib</a></p></li><li class="listitem"><p><a class="link" href="#Programming_Considerations" title="Programming Considerations">Programming considerations</a></p></li><li class="listitem"><p><a class="link" href="#Character_Sets_and_Encodings" title="Character Sets and Encodings">Character sets and encodings</a></p></li><li class="listitem"><p><a class="link" href="#Formatting_Conventions" title="Formatting Conventions">Formatting conventions</a></p></li></ul></div><p>
  </p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Overview_of_the_X_Window_System"></a>Overview of the X Window System</h2></div></div></div><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
<a class="link" href="#glossary" title="Glossary">the glossary</a>,
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 id="idp41228916" class="indexterm"></a>
A <em class="firstterm">screen</em> 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 <em class="firstterm">display</em>.
    </p><p>
All the windows in an X server are arranged in strict hierarchies.
At the top of each hierarchy is a <em class="firstterm">root window</em>,
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.
<a id="idp38653676" class="indexterm"></a>
<a id="idp38654028" class="indexterm"></a>
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.
<a id="idp38654988" class="indexterm"></a>
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 id="idp38656044" class="indexterm"></a>
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
<code class="systemitem">Expose</code>
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>
<a id="idp38658652" class="indexterm"></a>
<a id="idp38659076" class="indexterm"></a>
<a id="idp38659500" class="indexterm"></a>
<a id="idp42120620" class="indexterm"></a>
X also provides off-screen storage of graphics objects,
called <a class="firstterm" href="#glossary:Pixmap"><em class="firstterm">pixmaps</em></a>.
Single plane (depth 1) pixmaps are sometimes referred to as
<em class="firstterm">bitmaps</em>.
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>
<a id="idp42122748" class="indexterm"></a>
If a client does not want a request to execute asynchronously,
it can follow the request with a call to
<a class="xref" href="#XSync"><code class="function">XSync</code></a>,
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>
<a id="idp42124140" class="indexterm"></a>
<a id="idp42124548" class="indexterm"></a>
<a id="idp42125124" class="indexterm"></a>
<a id="idp42125700" class="indexterm"></a>
<a id="idp42126276" class="indexterm"></a>
<a id="idp42126852" class="indexterm"></a>
<a id="idp42127428" class="indexterm"></a>
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
<span class="type">Window</span>,
<span class="type">Font</span>,
<span class="type">Pixmap</span>,
<span class="type">Colormap</span>,
<span class="type">Cursor</span>,
and
<span class="type">GContext</span>,
as defined in the file
<code class="filename">&lt;X11/X.h&gt;</code>.
<a id="idp39764172" class="indexterm"></a>
<a id="idp39765068" class="indexterm"></a>
<a id="idp39765972" class="indexterm"></a>
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>
<a id="idp39767620" class="indexterm"></a>
Client programs are informed of events.
Events may either be side effects of a request (for example, restacking windows
generates
<code class="systemitem">Expose</code>
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,
<a class="xref" href="#XNextEvent"><code class="function">XNextEvent</code></a>
or
<a class="xref" href="#XWindowEvent"><code class="function">XWindowEvent</code></a>).
In addition, some library
functions (for example,
<a class="xref" href="#XRaiseWindow"><code class="function">XRaiseWindow</code></a>)
generate
<span class="symbol">Expose</span>
and
<span class="symbol">ConfigureRequest</span>
events.
These events also arrive asynchronously, but the client may
<a id="idp42292172" class="indexterm"></a>
wish to explicitly wait for them by calling
<a class="xref" href="#XSync"><code class="function">XSync</code></a>
after calling a function that can cause the server to generate events.
    </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Errors"></a>Errors</h2></div></div></div><p>
Some functions return
<span class="type">Status</span>,
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.
<a id="idp42294316" class="indexterm"></a>
Because C does not provide multiple return values,
many functions must return their results by writing into client-passed storage.
<a id="idp42294868" class="indexterm"></a>
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 <a class="link" href="#Enabling_or_Disabling_Synchronization" title="Enabling or Disabling Synchronization">section 11.8.1</a>).
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></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Standard_Header_Files"></a>Standard Header Files</h2></div></div></div><p>
The following include files are part of the Xlib standard:
<a id="idp42298148" class="indexterm"></a>

</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><a id="Standard_Header_Files:Xlib.h"></a><span class="term"><code class="filename">&lt;X11/Xlib.h&gt;</code></span></p></td><td><a id="idp42299812" class="indexterm"></a><a id="idp42300708" class="indexterm"></a><a id="idp42301284" class="indexterm"></a><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
<span class="symbol">XlibSpecificationRelease</span>.
<a id="idp42302364" class="indexterm"></a>
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></tr><tr><td><p><a id="Standard_Header_Files:X.h"></a><span class="term"><code class="filename">&lt;X11/X.h&gt;</code></span></p></td><td><a id="idp42304116" class="indexterm"></a><a id="idp42305012" class="indexterm"></a><a id="idp42305580" class="indexterm"></a><p>
This file declares types and constants for the X protocol that are
to be used by applications.  It is included automatically from
<code class="filename">&lt;X11/Xlib.h&gt;</code>
so application code should never need to
reference this file directly.
      </p></td></tr><tr><td><p><a id="Standard_Header_Files:Xcms.h"></a><span class="term"><code class="filename">&lt;X11/Xcms.h&gt;</code></span></p></td><td><a id="idp42308284" class="indexterm"></a><a id="idp41801772" class="indexterm"></a><a id="idp41802324" class="indexterm"></a><p>
This file contains symbols for much of the color management facilities
described in <a class="link" href="#Color_Management_Functions" title="Chapter 6. Color Management Functions">chapter 6</a>.
All functions, types, and symbols with the prefix "Xcms",
plus the Color Conversion Contexts macros, are declared in this file.
<code class="filename">&lt;X11/Xlib.h&gt;</code>
must be included before including this file.
      </p></td></tr><tr><td><p><a id="Standard_Header_Files:Xutil.h"></a><span class="term"><code class="filename">&lt;X11/Xutil.h&gt;</code></span></p></td><td><a id="idp41805436" class="indexterm"></a><a id="idp41806332" class="indexterm"></a><a id="idp41806908" class="indexterm"></a><p>
This file declares various functions, types, and symbols used for
inter-client communication and application utility functions,
which are described in chapters
<a class="link" href="#Inter_Client_Communication_Functions" title="Chapter 14. Inter-Client Communication Functions">14</a> and
<a class="link" href="#Application_Utility_Functions" title="Chapter 16. Application Utility Functions">16</a>.
<code class="filename">&lt;X11/Xlib.h&gt;</code> must be included before including this file.
      </p></td></tr><tr><td><p><a id="Standard_Header_Files:Xresource.h"></a><span class="term"><code class="filename">&lt;X11/Xresource.h&gt;</code></span></p></td><td><a id="idp41810356" class="indexterm"></a><a id="idp41811260" class="indexterm"></a><a id="idp41811836" class="indexterm"></a><p>
This file declares all functions, types, and symbols for the
resource manager facilities, which are described in
<a class="link" href="#Resource_Manager_Functions" title="Chapter 15. Resource Manager Functions">chapter 15</a>.
<code class="filename">&lt;X11/Xlib.h&gt;</code> 
must be included before including this file.
      </p></td></tr><tr><td><p><a id="Standard_Header_Files:Xatom.h"></a><span class="term"><code class="filename">&lt;X11/Xatom.h&gt;</code></span></p></td><td><a id="idp41815012" class="indexterm"></a><a id="idp41815908" class="indexterm"></a><a id="idp41816484" class="indexterm"></a><p>
This file declares all predefined atoms,
which are symbols with the prefix "XA_".
      </p></td></tr><tr><td><p><a id="Standard_Header_Files:cursorfont.h"></a><span class="term"><code class="filename">&lt;X11/cursorfont.h&gt;</code></span></p></td><td><a id="idp41818580" class="indexterm"></a><a id="idp41819484" class="indexterm"></a><a id="idp41820060" class="indexterm"></a><p>
This file declares the cursor symbols for the standard cursor font,
which are listed in <a class="link" href="#x_font_cursors" title="Appendix B. X Font Cursors">Appendix B</a>.
All cursor symbols have the prefix "XC_".
      </p></td></tr><tr><td><p><a id="Standard_Header_Files:keysymdef.h"></a><span class="term"><code class="filename">&lt;X11/keysymdef.h&gt;</code></span></p></td><td><a id="idp41822564" class="indexterm"></a><a id="idp41823468" class="indexterm"></a><a id="idp41824044" class="indexterm"></a><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
<span class="symbol">XK_MISCELLANY</span>,
<span class="symbol">XK_XKB_KEYS</span>,
<span class="symbol">XK_3270</span>,
<span class="symbol">XK_LATIN1</span>,
<span class="symbol">XK_LATIN2</span>,
<span class="symbol">XK_LATIN3</span>,
<span class="symbol">XK_LATIN4</span>,
<span class="symbol">XK_KATAKANA</span>,
<span class="symbol">XK_ARABIC</span>,
<span class="symbol">XK_CYRILLIC</span>,
<span class="symbol">XK_GREEK</span>,
<span class="symbol">XK_TECHNICAL</span>,
<span class="symbol">XK_SPECIAL</span>,
<span class="symbol">XK_PUBLISHING</span>,
<span class="symbol">XK_APL</span>,
<span class="symbol">XK_HEBREW</span>,
<span class="symbol">XK_THAI</span>, and
<span class="symbol">XK_KOREAN</span>.
      </p></td></tr><tr><td><p><a id="Standard_Header_Files:keysym.h"></a><span class="term"><code class="filename">&lt;X11/keysym.h&gt;</code></span></p></td><td><a id="idp41830428" class="indexterm"></a><a id="idp41831332" class="indexterm"></a><a id="idp41831908" class="indexterm"></a><p>
This file defines the preprocessor symbols
<span class="symbol">XK_MISCELLANY</span>,
<span class="symbol">XK_XKB_KEYS</span>,
<span class="symbol">XK_LATIN1</span>,
<span class="symbol">XK_LATIN2</span>,
<span class="symbol">XK_LATIN3</span>,
<span class="symbol">XK_LATIN4</span>, and
<span class="symbol">XK_GREEK</span>
and then includes <code class="filename">&lt;X11/keysymdef.h&gt;</code>.
      </p></td></tr><tr><td><p><a id="Standard_Header_Files:Xlibint.h"></a><span class="term"><code class="filename">&lt;X11/Xlibint.h&gt;</code></span></p></td><td><a id="idp41836052" class="indexterm"></a><a id="idp41836956" class="indexterm"></a><a id="idp41837532" class="indexterm"></a><p>
This file declares all the functions, types, and symbols used for
extensions, which are described in <a class="link" href="#extensions" title="Appendix C. Extensions">Appendix C</a>.
This file automatically includes
<code class="filename">&lt;X11/Xlib.h&gt;</code>.
      </p></td></tr><tr><td><p><a id="Standard_Header_Files:Xproto.h"></a><span class="term"><code class="filename">&lt;X11/Xproto.h&gt;</code></span></p></td><td><a id="idp41840532" class="indexterm"></a><a id="idp41841436" class="indexterm"></a><a id="idp41842012" class="indexterm"></a><p>
This file declares types and symbols for the basic X protocol,
for use in implementing extensions.
It is included automatically from
<code class="filename">&lt;X11/Xlibint.h&gt;</code>,
so application and extension code should never need to
reference this file directly.
      </p></td></tr><tr><td><p><a id="Standard_Header_Files:Xprotostr.h"></a><span class="term"><code class="filename">&lt;X11/Xprotostr.h&gt;</code></span></p></td><td><a id="idp41844748" class="indexterm"></a><a id="idp41845652" class="indexterm"></a><a id="idp41846228" class="indexterm"></a><p>
This file declares types and symbols for the basic X protocol,
for use in implementing extensions.
It is included automatically from
<code class="filename">&lt;X11/Xproto.h&gt;</code>,
so application and extension code should never need to
reference this file directly.
      </p></td></tr><tr><td><p><a id="Standard_Header_Files:X10.h"></a><span class="term"><code class="filename">&lt;X11/X10.h&gt;</code></span></p></td><td><a id="idp41848876" class="indexterm"></a><a id="idp41849772" class="indexterm"></a><a id="idp41850340" class="indexterm"></a><p>
This file declares all the functions, types, and symbols used for the
X10 compatibility functions, which are described in
<a class="link" href="#X_Version_10_Compatibility_Functions" title="X Version 10 Compatibility Functions">Appendix D</a>.
      </p></td></tr></tbody></table></div><p>
    </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Generic_Values_and_Types"></a>Generic Values and Types</h2></div></div></div><p>
The following symbols are defined by Xlib and used throughout the manual:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<a id="idp41853100" class="indexterm"></a>
<a id="idp41853524" class="indexterm"></a>
<a id="idp41853948" class="indexterm"></a>
Xlib defines the type
<span class="type">Bool</span>
and the Boolean values
<span class="symbol">True</span>
and
<span class="symbol">False</span>.
    </p></li><li class="listitem"><p>
<a id="idp41855460" class="indexterm"></a>
<span class="symbol">None</span>
is the universal null resource ID or atom.
    </p></li><li class="listitem"><p>
<a id="idp41856596" class="indexterm"></a>
The type
<span class="type">XID</span>
is used for generic resource IDs.
    </p></li><li class="listitem"><p>
<a id="idp41857676" class="indexterm"></a>
The type <span class="type">XPointer</span> is defined to be <span class="type">char *</span>
and is used as a generic opaque pointer to data.
    </p></li></ul></div><p>
    </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Naming_and_Argument_Conventions_within_Xlib"></a>Naming and Argument Conventions within Xlib</h2></div></div></div><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><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><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></li><li class="listitem"><p>
All Xlib functions begin with a capital X.
    </p></li><li class="listitem"><p>
The beginnings of all function names and symbols are capitalized.
    </p></li><li class="listitem"><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></li><li class="listitem"><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></li><li class="listitem"><p>
All elements  of or variables in a data structure are in lowercase.
Compound words, where needed, are constructed with underscores (_).
    </p></li><li class="listitem"><p>
The display argument, where used, is always first in the argument list.
    </p></li><li class="listitem"><p>
All resource objects, where used, occur at the beginning of the argument list
immediately after the display argument.
    </p></li><li class="listitem"><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></li><li class="listitem"><p>
Source arguments always precede the destination arguments in the argument list.
    </p></li><li class="listitem"><p>
The x argument always precedes the y argument in the argument list.
    </p></li><li class="listitem"><p>
The width argument always precedes the height argument in the argument list.
    </p></li><li class="listitem"><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></li><li class="listitem"><p>
Where a mask is accompanied with a structure,
the mask always precedes the pointer to the structure in the argument list.
    </p></li></ul></div><p>
    </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Programming_Considerations"></a>Programming Considerations</h2></div></div></div><p>
The major programming considerations are:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><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
<span class="type">int</span>
in the interface.
Values larger than 16 bits are truncated silently.
Sizes (width and height) are declared as unsigned quantities.
    </p></li><li class="listitem"><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></li><li class="listitem"><p>
Many display systems have limited amounts of off-screen memory.
If you can, you should minimize use of pixmaps and backing
store.
    </p></li><li class="listitem"><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 <a class="link" href="#Inter_Client_Communication_Functions" title="Chapter 14. Inter-Client Communication Functions">chapter 14</a>
and the <span class="olink"><em class="citetitle">Inter-Client Communication Conventions Manual</em></span>.
    </p></li></ul></div><p>
    </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Character_Sets_and_Encodings"></a>Character Sets and Encodings</h2></div></div></div><p>
Some of the Xlib functions make reference to specific character sets
and character encodings.
The following are the most common:

</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term"><em class="firstterm">X Portable Character Set</em></span></p></td><td><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><div class="literallayout"><p><br />
a..z A..Z 0..9 !"#$%&amp;'()*+,-./:;&lt;=&gt;?@[\\]^_`{|}~ &lt;space&gt;, &lt;tab&gt;, and &lt;newline&gt;<br />
</p></div><p>
      </p><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></tr><tr><td><p><span class="term"><em class="firstterm">Host Portable Character Encoding</em></span></p></td><td><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></tr><tr><td><p><span class="term"><em class="firstterm">Latin-1</em></span></p></td><td><p>
The coded character set defined by the ISO8859-1 standard.
      </p></td></tr><tr><td><p><span class="term"><em class="firstterm">Latin Portable Character Encoding</em></span></p></td><td><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></tr><tr><td><p><span class="term"><em class="firstterm">STRING Encoding</em></span></p></td><td><p>
Latin-1, plus tab and newline.
      </p></td></tr><tr><td><p><span class="term"><em class="firstterm"><acronym class="acronym">POSIX</acronym> Portable Filename Character Set</em></span></p></td><td><p>
The set of 65 characters,
which can be used in naming files on a <acronym class="acronym">POSIX</acronym>-compliant host,
that are correctly processed in all locales.
The set is:
</p><div class="literallayout"><p><br />
a..z A..Z 0..9 ._-<br />
</p></div><p>
      </p></td></tr></tbody></table></div><p>
    </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Formatting_Conventions"></a>Formatting Conventions</h2></div></div></div><p>
      <em class="citetitle">Xlib − C Language X Interface</em> uses the
      following conventions:

      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Global symbols are printed in
<code class="function">this</code>
<code class="function">special</code>
<code class="function">font</code>.
These can be either function names,
symbols defined in include files, or structure names.
When declared and defined,
function arguments are printed in <span class="emphasis"><em>italics</em></span>.
In the explanatory text that follows,
they usually are printed in regular type.
	  </p></li><li class="listitem"><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 <a class="link" href="#Using_the_Default_Error_Handlers" title="Using the Default Error Handlers">section 11.8.2</a>.
	  </p></li><li class="listitem"><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
<span class="emphasis"><em>specifies</em></span> or, in the case of multiple arguments, the word <span class="emphasis"><em>specify</em></span>.
The explanations for all arguments that are returned to you start with the
word <span class="emphasis"><em>returns</em></span> or, in the case of multiple arguments, the word <span class="emphasis"><em>return</em></span>.
The explanations for all arguments that you can pass and are returned start
with the words <span class="emphasis"><em>specifies and returns</em></span>.
	  </p></li><li class="listitem"><p>
Any pointer to a structure that is used to return a value is designated as
such by the <span class="emphasis"><em>_return</em></span> 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 <span class="emphasis"><em>_in_out</em></span> suffix.
	  </p></li></ul></div><p>
    </p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Display_Functions"></a>Chapter 2. Display Functions</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Opening_the_Display">Opening the Display</a></span></dt><dt><span class="sect1"><a href="#Obtaining_Information_about_the_Display_Image_Formats_or_Screens">Obtaining Information about the Display, Image Formats, or Screens</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Display_Macros">Display Macros</a></span></dt><dt><span class="sect2"><a href="#Image_Format_Functions_and_Macros">Image Format Functions and Macros</a></span></dt><dt><span class="sect2"><a href="#Screen_Information_Macros">Screen Information Macros</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Generating_a_NoOperation_Protocol_Request">Generating a NoOperation Protocol Request</a></span></dt><dt><span class="sect1"><a href="#Freeing_Client_Created_Data">Freeing Client-Created Data</a></span></dt><dt><span class="sect1"><a href="#Closing_the_Display">Closing the Display</a></span></dt><dt><span class="sect1"><a href="#Using_X_Server_Connection_Close_Operations">Using X Server Connection Close Operations</a></span></dt><dt><span class="sect1"><a href="#Using_Xlib_with_Threads">Using Xlib with Threads</a></span></dt><dt><span class="sect1"><a href="#Using_Internal_Connections">Using Internal Connections</a></span></dt></dl></div><p>
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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Open (connect to) the display
    </p></li><li class="listitem"><p>
Obtain information about the display, image formats, or screens
    </p></li><li class="listitem"><p>
Generate a
<code class="systemitem">NoOperation</code>
protocol request
    </p></li><li class="listitem"><p>
Free client-created data
    </p></li><li class="listitem"><p>
Close (disconnect from) a display
    </p></li><li class="listitem"><p>
Use X Server connection close operations
    </p></li><li class="listitem"><p>
Use Xlib with threads
    </p></li><li class="listitem"><p>
Use internal connections
    </p></li></ul></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Opening_the_Display"></a>Opening the Display</h2></div></div></div><p>

To open a connection to the X server that controls a display, use
<a class="xref" href="#XOpenDisplay"><code class="function">XOpenDisplay</code></a>.
<a id="idp42015420" class="indexterm"></a>
</p><div class="funcsynopsis"><a id="XOpenDisplay"></a><p><code class="funcdef">Display *<strong class="fsfunc">XOpenDisplay</strong>(</code>char *<var class="pdparam">display_name</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display_name</em></span>
    </span></p></td><td><p>
Specifies the hardware display name, which determines the display
and communications domain to be used.
On a <acronym class="acronym">POSIX</acronym>-conformant system, if the display_name is NULL, 
it defaults to the value of the DISPLAY environment variable. 
<a id="idp42947844" class="indexterm"></a>
    </p></td></tr></tbody></table></div><p>


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 <acronym class="acronym">POSIX</acronym>-conformant systems,
the display name or DISPLAY environment variable can be a string in the format:
</p><pre class="literallayout">


	<span class="emphasis"><em>protocol</em></span>/<span class="emphasis"><em>hostname</em></span>:<span class="emphasis"><em>number</em></span>.<span class="emphasis"><em>screen_number</em></span>
</pre><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>protocol</em></span>
    </span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hostname</em></span>
    </span></p></td><td><p>
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 (::).
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>number</em></span>
    </span></p></td><td><p>
Specifies the number of the display server on that host machine.
You may optionally follow this display number with a period (.).
A single <acronym class="acronym">CPU</acronym> can have more than one display.
Multiple displays are usually numbered starting with zero.
<a id="idp41181020" class="indexterm"></a>
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
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 
<code class="function">DefaultScreen</code>
macro or the 
<a class="xref" href="#XDefaultScreen"><code class="function">XDefaultScreen</code></a>
function if you are using languages other than C
(see <a class="link" href="#Display_Macros" title="Display Macros">section 2.2.1</a>).
    </p></td></tr></tbody></table></div><p>


For example, the following would specify screen 1 of display 0 on the 
machine named ``dual-headed'':
</p><p>

</p><pre class="literallayout">
dual-headed:0.1
</pre><p>
</p><p>

The
<a class="xref" href="#XOpenDisplay"><code class="function">XOpenDisplay</code></a>
function returns a 
<span class="type">Display</span>
structure that serves as the
connection to the X server and that contains all the information
about that X server.
<a class="xref" href="#XOpenDisplay"><code class="function">XOpenDisplay</code></a>
connects your application to the X server through <acronym class="acronym">TCP</acronym>
or DECnet communications protocols,
or through some local inter-process communication protocol.
<a id="idp43541844" class="indexterm"></a>
<a id="idp43542476" class="indexterm"></a>
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,
<a class="xref" href="#XOpenDisplay"><code class="function">XOpenDisplay</code></a>
connects using <acronym class="acronym">TCP</acronym> streams.  (If the protocol is specified as "inet", <acronym class="acronym">TCP</acronym> over
IPv4 is used.  If the protocol is specified as "inet6", <acronym class="acronym">TCP</acronym> over IPv6 is used.
Otherwise, the implementation determines which <acronym class="acronym">IP</acronym> 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,
<a class="xref" href="#XOpenDisplay"><code class="function">XOpenDisplay</code></a>
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.
</p><p>

<a id="idp43545964" class="indexterm"></a>
If successful, 
<a class="xref" href="#XOpenDisplay"><code class="function">XOpenDisplay</code></a>
returns a pointer to a 
<span class="type">Display</span>
structure,
which is defined in 
<code class="filename">&lt;X11/Xlib.h&gt;</code>.
<a id="idp43547524" class="indexterm"></a>
<a id="idp43548420" class="indexterm"></a>
<a id="idp43549332" class="indexterm"></a>
If 
<a class="xref" href="#XOpenDisplay"><code class="function">XOpenDisplay</code></a>
does not succeed, it returns NULL.
After a successful call to
<a class="xref" href="#XOpenDisplay"><code class="function">XOpenDisplay</code></a>,
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 
<code class="function">DefaultScreen</code>
macro (or the
<a class="xref" href="#XDefaultScreen"><code class="function">XDefaultScreen</code></a>
function).
You can access elements of the
<span class="type">Display</span>
and
<span class="type">Screen</span>
structures only by using the information macros or functions.
For information about using macros and functions to obtain information from 
the
<span class="type">Display</span>
structure,
see <a class="link" href="#Display_Macros" title="Display Macros">section 2.2.1</a>.
</p><p>

X servers may implement various types of access control mechanisms
(see <a class="link" href="#Controlling_Host_Access" title="Controlling Host Access">section 9.8</a>).
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Obtaining_Information_about_the_Display_Image_Formats_or_Screens"></a>Obtaining Information about the Display, Image Formats, or Screens</h2></div></div></div><p>

The Xlib library provides a number of useful macros 
and corresponding functions that return data from the 
<span class="type">Display</span>
structure.
The macros are used for C programming, 
and their corresponding function equivalents are for other language bindings.
This section discusses the:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Display macros
    </p></li><li class="listitem"><p>
Image format functions and macros
    </p></li><li class="listitem"><p>
Screen information macros
    </p></li></ul></div><p>

<a id="idp41670220" class="indexterm"></a>
All other members of the 
<span class="type">Display</span>
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 
<span class="type">Display</span>
structure.

The
<a class="xref" href="#XDisplayWidth"><code class="function">XDisplayWidth</code></a>,
<a class="xref" href="#XDisplayHeight"><code class="function">XDisplayHeight</code></a>,
<a class="xref" href="#XDisplayCells"><code class="function">XDisplayCells</code></a>,
<a class="xref" href="#XDisplayPlanes"><code class="function">XDisplayPlanes</code></a>,
<a class="xref" href="#XDisplayWidthMM"><code class="function">XDisplayWidthMM</code></a>,
and
<a class="xref" href="#XDisplayHeightMM"><code class="function">XDisplayHeightMM</code></a>
functions in the next sections are misnamed.
These functions really should be named Screen<span class="emphasis"><em>whatever</em></span> 
and XScreen<span class="emphasis"><em>whatever</em></span>, not Display<span class="emphasis"><em>whatever</em></span> or XDisplay<span class="emphasis"><em>whatever</em></span>.
Our apologies for the resulting confusion.

</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Display_Macros"></a>Display Macros</h3></div></div></div><p>

Applications should not directly modify any part of the
<span class="type">Display</span>
and
<span class="type">Screen</span>
structures.
The members should be considered read-only,
although they may change as the result of other operations on the display.
</p><p>

The following lists the C language macros,
their corresponding function equivalents that are for other language bindings,
and what data both can return.
</p><p>AllPlanes()</p><p>XAllPlanes()</p><p>


<a id="idp41679452" class="indexterm"></a>
<a id="idp41679876" class="indexterm"></a>
Both return a value with all bits set to 1 suitable for use in a plane argument to
a procedure.
</p><p>


Both 
<code class="function">BlackPixel</code>
and 
<code class="function">WhitePixel</code>
can be used in implementing a monochrome application.
These pixel values are for permanently allocated entries in the default
colormap.
The actual <acronym class="acronym">RGB</acronym> (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.

</p><p>
BlackPixel(<span class="emphasis"><em>display</em></span>, <span class="emphasis"><em>screen_number</em></span>)
</p><div class="funcsynopsis"><a id="XBlackPixel"></a><p><code class="funcdef">unsigned long <strong class="fsfunc">XBlackPixel</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen_number</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
    </p></td></tr></tbody></table></div><p>


<a id="idp42519484" class="indexterm"></a>
<a id="idp42519908" class="indexterm"></a>
Both return the black pixel value for the specified screen.
</p><p>



</p><p>
WhitePixel(<span class="emphasis"><em>display</em></span>, <span class="emphasis"><em>screen_number</em></span>)
</p><div class="funcsynopsis"><a id="XWhitePixel"></a><p><code class="funcdef">unsigned long <strong class="fsfunc">XWhitePixel</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen_number</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
    </p></td></tr></tbody></table></div><p>


<a id="idp42527724" class="indexterm"></a>
<a id="idp42528148" class="indexterm"></a>
Both return the white pixel value for the specified screen. 
</p><p>



</p><p>
ConnectionNumber(<span class="emphasis"><em>display</em></span>)
</p><div class="funcsynopsis"><a id="XConnectionNumber"></a><p><code class="funcdef">int <strong class="fsfunc">XConnectionNumber</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


<a id="idp42533780" class="indexterm"></a>
<a id="idp42534212" class="indexterm"></a>
Both return a connection number for the specified display.
On a <acronym class="acronym">POSIX</acronym>-conformant system,
this is the file descriptor of the connection.
</p><p>



</p><p>
DefaultColormap(<span class="emphasis"><em>display</em></span>, <span class="emphasis"><em>screen_number</em></span>)
</p><div class="funcsynopsis"><a id="XDefaultColormap"></a><p><code class="funcdef">Colormap <strong class="fsfunc">XDefaultColormap</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen_number</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
    </p></td></tr></tbody></table></div><p>


<a id="idp42542332" class="indexterm"></a>
<a id="idp42542764" class="indexterm"></a>
Both return the default colormap ID for allocation on the specified screen.
Most routine allocations of color should be made out of this colormap.
</p><p>



</p><p>
DefaultDepth(<span class="emphasis"><em>display</em></span>, <span class="emphasis"><em>screen_number</em></span>)
</p><div class="funcsynopsis"><a id="XDefaultDepth"></a><p><code class="funcdef">int <strong class="fsfunc">XDefaultDepth</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen_number</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
    </p></td></tr></tbody></table></div><p>


<a id="idp42550692" class="indexterm"></a>
<a id="idp42551124" class="indexterm"></a>
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
<a class="xref" href="#XMatchVisualInfo"><code class="function">XMatchVisualInfo</code></a>).
</p><p>


<a id="idp42552676" class="indexterm"></a>
To determine the number of depths that are available on a given screen, use
<code class="function">XListDepths</code>.

</p><p>
DefaultGC(<span class="emphasis"><em>display</em></span>, <span class="emphasis"><em>screen_number</em></span>)
</p><div class="funcsynopsis"><a id="XDefaultGC"></a><p><code class="funcdef">GC <strong class="fsfunc">XDefaultGC</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen_number</var>, int<var class="pdparam"> *count_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count_return</em></span>
    </span></p></td><td><p>
Returns the number of depths.
    </p></td></tr></tbody></table></div><p>


The
<code class="function">XListDepths</code>
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,
<code class="function">XListDepths</code>
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
<a class="xref" href="#XFree"></a>.
</p><p>



</p><p>
DefaultGC(<span class="emphasis"><em>display</em></span>, <span class="emphasis"><em>screen_number</em></span>)
</p><div class="funcsynopsis"><p><code class="funcdef">GC <strong class="fsfunc">XDefaultGC</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen_number</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
    </p></td></tr></tbody></table></div><p>


<a id="idp42570716" class="indexterm"></a>
<a id="idp42571140" class="indexterm"></a>
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.
</p><p>



</p><p>
DefaultRootWindow(<span class="emphasis"><em>display</em></span>)
</p><div class="funcsynopsis"><a id="XDefaultRootWindow"></a><p><code class="funcdef">Window <strong class="fsfunc">XDefaultRootWindow</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


<a id="idp42577132" class="indexterm"></a>
<a id="idp42577564" class="indexterm"></a>
Both return the root window for the default screen.
</p><p>



</p><p>
DefaultScreenOfDisplay(<span class="emphasis"><em>display</em></span>)
</p><div class="funcsynopsis"><a id="XDefaultScreenOfDisplay"></a><p><code class="funcdef">Screen *<strong class="fsfunc">XDefaultScreenOfDisplay</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


<a id="idp42583100" class="indexterm"></a>
<a id="idp42583508" class="indexterm"></a>
Both return a pointer to the default screen.
</p><p>



</p><p>
ScreenOfDisplay(<span class="emphasis"><em>display</em></span>, <span class="emphasis"><em>screen_number</em></span>)
</p><div class="funcsynopsis"><a id="XScreenOfDisplay"></a><p><code class="funcdef">Screen *<strong class="fsfunc">XScreenOfDisplay</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen_number</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
    </p></td></tr></tbody></table></div><p>


<a id="idp42591308" class="indexterm"></a>
<a id="idp42591740" class="indexterm"></a>
Both return a pointer to the indicated screen.
</p><p>



</p><p>
DefaultScreen(<span class="emphasis"><em>display</em></span>)
</p><div class="funcsynopsis"><a id="XDefaultScreen"></a><p><code class="funcdef">int <strong class="fsfunc">XDefaultScreen</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


<a id="idp42597364" class="indexterm"></a>
<a id="idp42597796" class="indexterm"></a>
Both return the default screen number referenced by the 
<a class="xref" href="#XOpenDisplay"><code class="function">XOpenDisplay</code></a>
function. 
This macro or function should be used to retrieve the screen number 
in applications that will use only a single screen.
</p><p>



</p><p>
DefaultVisual(<span class="emphasis"><em>display</em></span>, <span class="emphasis"><em>screen_number</em></span>)
</p><div class="funcsynopsis"><a id="XDefaultVisual"></a><p><code class="funcdef">Visual *<strong class="fsfunc">XDefaultVisual</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen_number</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
    </p></td></tr></tbody></table></div><p>


<a id="idp42606188" class="indexterm"></a>
<a id="idp42606620" class="indexterm"></a>
Both return the default visual type for the specified screen.
For further information about visual types,
see <a class="link" href="#Visual_Types" title="Visual Types">section 3.1</a>.
</p><p>



</p><p>
DisplayCells(<span class="emphasis"><em>display</em></span>, <span class="emphasis"><em>screen_number</em></span>)
</p><div class="funcsynopsis"><a id="XDisplayCells"></a><p><code class="funcdef">int <strong class="fsfunc">XDisplayCells</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen_number</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
    </p></td></tr></tbody></table></div><p>


<a id="idp42614876" class="indexterm"></a>
<a id="idp42615308" class="indexterm"></a>
Both return the number of entries in the default colormap.
</p><p>



</p><p>
DisplayPlanes(<span class="emphasis"><em>display</em></span>, <span class="emphasis"><em>screen_number</em></span>)
</p><div class="funcsynopsis"><a id="XDisplayPlanes"></a><p><code class="funcdef">int <strong class="fsfunc">XDisplayPlanes</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen_number</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
    </p></td></tr></tbody></table></div><p>


<a id="idp42623148" class="indexterm"></a>
<a id="idp42623580" class="indexterm"></a>
Both return the depth of the root window of the specified screen.
For an explanation of depth,
see the glossary.
</p><p>



</p><p>
DisplayString(<span class="emphasis"><em>display</em></span>)
</p><div class="funcsynopsis"><a id="XDisplayString"></a><p><code class="funcdef">char *<strong class="fsfunc">XDisplayString</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


<a id="idp42629268" class="indexterm"></a>
<a id="idp42629700" class="indexterm"></a>
Both return the string that was passed to 
<a class="xref" href="#XOpenDisplay"><code class="function">XOpenDisplay</code></a>
when the current display was opened. 
On <acronym class="acronym">POSIX</acronym>-conformant systems,
if the passed string was NULL, these return the value of
the DISPLAY environment variable when the current display was opened.
<a id="idp42630956" class="indexterm"></a>
These are useful to applications that invoke the 
<code class="function">fork</code>
system call and want to open a new connection to the same display from the 
child process as well as for printing error messages.
</p><p>



</p><p>
LastKnownRequestProcessed(<span class="emphasis"><em>display</em></span>)
</p><div class="funcsynopsis"><a id="XLastKnownRequestProcessed"></a><p><code class="funcdef">unsigned long <strong class="fsfunc">XLastKnownRequestProcessed</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


<a id="idp42637260" class="indexterm"></a>
The
<span class="olink"><code class="function">XExtendedMaxRequestSize</code></span>
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
<a class="xref" href="#XDrawLines"><code class="function">XDrawLines</code></a>,
<a class="xref" href="#XDrawArcs"><code class="function">XDrawArcs</code></a>,
<a class="xref" href="#XFillPolygon"><code class="function">XFillPolygon</code></a>,
<a class="xref" href="#XChangeProperty"><code class="function">XChangeProperty</code></a>,
<a class="xref" href="#XSetClipRectangles"><code class="function">XSetClipRectangles</code></a>,
and
<a class="xref" href="#XSetRegion"><code class="function">XSetRegion</code></a>
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,
<a class="xref" href="#XDrawPoints"><code class="function">XDrawPoints</code></a>,
<a class="xref" href="#XDrawRectangles"><code class="function">XDrawRectangles</code></a>,
<a class="xref" href="#XDrawSegments"><code class="function">XDrawSegments</code></a>,
<a class="xref" href="#XFillArcs"><code class="function">XFillArcs</code></a>,
<a class="xref" href="#XFillRectangles"><code class="function">XFillRectangles</code></a>,
<a class="xref" href="#XPutImage"><code class="function">XPutImage</code></a>)
is permitted but not required; an Xlib implementation may choose to
split the data across multiple smaller requests instead.
</p><p>



</p><p>
LastKnownRequestProcessed(<span class="emphasis"><em>display</em></span>)
</p><div class="funcsynopsis"><p><code class="funcdef">unsigned long <strong class="fsfunc">XLastKnownRequestProcessed</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


<a id="idp43612572" class="indexterm"></a>
The
<code class="function">XMaxRequestSize</code>
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:
<a class="xref" href="#XDrawPoints"><code class="function">XDrawPoints</code></a>,
<a class="xref" href="#XDrawRectangles"><code class="function">XDrawRectangles</code></a>,
<a class="xref" href="#XDrawSegments"><code class="function">XDrawSegments</code></a>,
<a class="xref" href="#XFillArcs"><code class="function">XFillArcs</code></a>,
<a class="xref" href="#XFillRectangles"><code class="function">XFillRectangles</code></a>,
and 
<a class="xref" href="#XPutImage"><code class="function">XPutImage</code></a>.
</p><p>



</p><p>
LastKnownRequestProcessed(<span class="emphasis"><em>display</em></span>)
</p><div class="funcsynopsis"><p><code class="funcdef">unsigned long <strong class="fsfunc">XLastKnownRequestProcessed</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


<a id="idp43620196" class="indexterm"></a>
<a id="idp43620572" class="indexterm"></a>
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.
</p><p>



</p><p>
NextRequest(<span class="emphasis"><em>display</em></span>)
</p><div class="funcsynopsis"><a id="XNextRequest"></a><p><code class="funcdef">unsigned long <strong class="fsfunc">XNextRequest</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


<a id="idp43625516" class="indexterm"></a>
<a id="idp43625892" class="indexterm"></a>
Both extract the full serial number that is to be used for the next
request.
Serial numbers are maintained separately for each display connection.
</p><p>



</p><p>
ProtocolVersion(<span class="emphasis"><em>display</em></span>)
</p><div class="funcsynopsis"><a id="XProtocolVersion"></a><p><code class="funcdef">int <strong class="fsfunc">XProtocolVersion</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


<a id="idp43630796" class="indexterm"></a>
<a id="idp43631172" class="indexterm"></a>
Both return the major version number (11) of the X protocol associated with 
the connected display.
</p><p>



</p><p>
ProtocolRevision(<span class="emphasis"><em>display</em></span>)
</p><div class="funcsynopsis"><a id="XProtocolRevision"></a><p><code class="funcdef">int <strong class="fsfunc">XProtocolRevision</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


<a id="idp43636028" class="indexterm"></a>
<a id="idp43636404" class="indexterm"></a>
Both return the minor protocol revision number of the X server.
</p><p>



</p><p>
QLength(<span class="emphasis"><em>display</em></span>)
</p><div class="funcsynopsis"><a id="XQLength"></a><p><code class="funcdef">int <strong class="fsfunc">XQLength</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


<a id="idp43641220" class="indexterm"></a>
<a id="idp43641596" class="indexterm"></a>
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
<a class="xref" href="#XEventsQueued"><code class="function">XEventsQueued</code></a>).
</p><p>



</p><p>
RootWindow(<span class="emphasis"><em>display</em></span>, <span class="emphasis"><em>screen_number</em></span>)
</p><div class="funcsynopsis"><a id="XRootWindow"></a><p><code class="funcdef">Window <strong class="fsfunc">XRootWindow</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen_number</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
    </p></td></tr></tbody></table></div><p>


<a id="idp43648772" class="indexterm"></a>
<a id="idp43649276" class="indexterm"></a>
<a id="idp43649652" class="indexterm"></a>
<a id="idp43650156" class="indexterm"></a>
Both return the root window.
These are useful with functions that need a drawable of a particular screen
and for creating top-level windows.
</p><p>



</p><p>
ScreenCount(<span class="emphasis"><em>display</em></span>)
</p><div class="funcsynopsis"><a id="XScreenCount"></a><p><code class="funcdef">int <strong class="fsfunc">XScreenCount</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


<a id="idp43655052" class="indexterm"></a>
<a id="idp43655428" class="indexterm"></a>
Both return the number of available screens.
</p><p>



</p><p>
ServerVendor(<span class="emphasis"><em>display</em></span>)
</p><div class="funcsynopsis"><a id="XServerVendor"></a><p><code class="funcdef">char *<strong class="fsfunc">XServerVendor</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


<a id="idp43660228" class="indexterm"></a>
<a id="idp43660604" class="indexterm"></a>
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.
</p><p>



</p><p>
VendorRelease(<span class="emphasis"><em>display</em></span>)
</p><div class="funcsynopsis"><a id="XVendorRelease"></a><p><code class="funcdef">int <strong class="fsfunc">XVendorRelease</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


<a id="idp43665692" class="indexterm"></a>
<a id="idp43666068" class="indexterm"></a>
Both return a number related to a vendor's release of the X server.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Image_Format_Functions_and_Macros"></a>Image Format Functions and Macros</h3></div></div></div><p>

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
<a class="link" href="#Transferring_Images_between_Client_and_Server" title="Transferring Images between Client and Server">8.7</a> and
<a class="link" href="#Manipulating_Images" title="Manipulating Images">16.8</a>).
</p><p>

The
<span class="structname">XPixmapFormatValues</span>
structure provides an interface to the pixmap format information
that is returned at the time of a connection setup.
It contains:
</p><p>


</p><pre class="literallayout">


typedef struct {
	int depth;
	int bits_per_pixel;
	int scanline_pad;
} XPixmapFormatValues;
</pre><p>
</p><p>



To obtain the pixmap format information for a given display, use
<code class="function">XListPixmapFormats</code>.
<a id="idp43671476" class="indexterm"></a>

</p><div class="funcsynopsis"><a id="XListPixmapFormats"></a><p><code class="funcdef">XPixmapFormatValues *<strong class="fsfunc">XListPixmapFormats</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> *count_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count_return</em></span>
    </span></p></td><td><p>
Returns the number of pixmap formats that are supported by the display.
    </p></td></tr></tbody></table></div><p>


The
<code class="function">XListPixmapFormats</code>
function returns an array of
<span class="structname">XPixmapFormatValues</span>
structures that describe the types of Z format images supported
by the specified display.
If insufficient memory is available,
<code class="function">XListPixmapFormats</code>
returns NULL.
To free the allocated storage for the
<span class="structname">XPixmapFormatValues</span>
structures, use
<a class="xref" href="#XFree"></a>.
</p><p>

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.
</p><p>



</p><p>
ImageByteOrder(<span class="emphasis"><em>display</em></span>)
</p><div class="funcsynopsis"><a id="XImageByteOrder"></a><p><code class="funcdef">int <strong class="fsfunc">XImageByteOrder</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


<a id="idp43683404" class="indexterm"></a>
<a id="idp43683780" class="indexterm"></a>
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
<span class="symbol">LSBFirst</span>
or 
<span class="symbol">MSBFirst</span>.
</p><p>



</p><p>
BitmapUnit(<span class="emphasis"><em>display</em></span>)
</p><div class="funcsynopsis"><a id="XBitmapUnit"></a><p><code class="funcdef">int <strong class="fsfunc">XBitmapUnit</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


<a id="idp43689092" class="indexterm"></a>
<a id="idp43689468" class="indexterm"></a>
Both return the size of a bitmap's scanline unit in bits.
The scanline is calculated in multiples of this value.
</p><p>



</p><p>
BitmapBitOrder(<span class="emphasis"><em>display</em></span>)
</p><div class="funcsynopsis"><a id="XBitmapBitOrder"></a><p><code class="funcdef">int <strong class="fsfunc">XBitmapBitOrder</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


<a id="idp43694332" class="indexterm"></a>
<a id="idp43694708" class="indexterm"></a>
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 
<span class="symbol">LSBFirst</span>
or 
<span class="symbol">MSBFirst</span>.
</p><p>



</p><p>
BitmapPad(<span class="emphasis"><em>display</em></span>)
</p><div class="funcsynopsis"><a id="XBitmapPad"></a><p><code class="funcdef">int <strong class="fsfunc">XBitmapPad</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


<a id="idp43700036" class="indexterm"></a>
<a id="idp43700412" class="indexterm"></a>
Each scanline must be padded to a multiple of bits returned
by this macro or function.
</p><p>



</p><p>
DisplayHeight(<span class="emphasis"><em>display</em></span>, <span class="emphasis"><em>screen_number</em></span>)
</p><div class="funcsynopsis"><a id="XDisplayHeight"></a><p><code class="funcdef">int <strong class="fsfunc">XDisplayHeight</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen_number</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
    </p></td></tr></tbody></table></div><p>


<a id="idp43707156" class="indexterm"></a>
<a id="idp43707532" class="indexterm"></a>
Both return an integer that describes the height of the screen
in pixels.
</p><p>



</p><p>
DisplayHeightMM(<span class="emphasis"><em>display</em></span>, <span class="emphasis"><em>screen_number</em></span>)
</p><div class="funcsynopsis"><a id="XDisplayHeightMM"></a><p><code class="funcdef">int <strong class="fsfunc">XDisplayHeightMM</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen_number</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
    </p></td></tr></tbody></table></div><p>


<a id="idp43714260" class="indexterm"></a>
<a id="idp43714636" class="indexterm"></a>
Both return the height of the specified screen in millimeters.
</p><p>



</p><p>
DisplayWidth(<span class="emphasis"><em>display</em></span>, <span class="emphasis"><em>screen_number</em></span>)
</p><div class="funcsynopsis"><a id="XDisplayWidth"></a><p><code class="funcdef">int <strong class="fsfunc">XDisplayWidth</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen_number</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
    </p></td></tr></tbody></table></div><p>


<a id="idp43721356" class="indexterm"></a>
<a id="idp43721732" class="indexterm"></a>
Both return the width of the screen in pixels.
</p><p>



</p><p>
DisplayWidthMM(<span class="emphasis"><em>display</em></span>, <span class="emphasis"><em>screen_number</em></span>)
</p><div class="funcsynopsis"><a id="XDisplayWidthMM"></a><p><code class="funcdef">int <strong class="fsfunc">XDisplayWidthMM</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen_number</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
    </p></td></tr></tbody></table></div><p>


<a id="idp43728436" class="indexterm"></a>
<a id="idp43728812" class="indexterm"></a>
Both return the width of the specified screen in millimeters.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Screen_Information_Macros"></a>Screen Information Macros</h3></div></div></div><p>

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.
</p><p>



</p><p>
BlackPixelOfScreen(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><a id="XBlackPixelOfScreen"></a><p><code class="funcdef">unsigned long <strong class="fsfunc">XBlackPixelOfScreen</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


<a id="idp43735220" class="indexterm"></a>
<a id="idp43735596" class="indexterm"></a>
Both return the black pixel value of the specified screen.
</p><p>



</p><p>
WhitePixelOfScreen(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><a id="XWhitePixelOfScreen"></a><p><code class="funcdef">unsigned long <strong class="fsfunc">XWhitePixelOfScreen</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


<a id="idp43740548" class="indexterm"></a>
<a id="idp43740924" class="indexterm"></a>
Both return the white pixel value of the specified screen.
</p><p>



</p><p>
CellsOfScreen(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><a id="XCellsOfScreen"></a><p><code class="funcdef">int <strong class="fsfunc">XCellsOfScreen</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


<a id="idp43745876" class="indexterm"></a>
<a id="idp43746252" class="indexterm"></a>
Both return the number of colormap cells in the default colormap 
of the specified screen.
</p><p>



</p><p>
DefaultColormapOfScreen(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><a id="XDefaultColormapOfScreen"></a><p><code class="funcdef">Colormap <strong class="fsfunc">XDefaultColormapOfScreen</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


<a id="idp43751236" class="indexterm"></a>
<a id="idp43751612" class="indexterm"></a>
Both return the default colormap of the specified screen.
</p><p>



</p><p>
DefaultDepthOfScreen(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><a id="XDefaultDepthOfScreen"></a><p><code class="funcdef">int <strong class="fsfunc">XDefaultDepthOfScreen</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


<a id="idp43756556" class="indexterm"></a>
<a id="idp43756932" class="indexterm"></a>
Both return the depth of the root window.
</p><p>



</p><p>
DefaultGCOfScreen(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><a id="XDefaultGCOfScreen"></a><p><code class="funcdef">GC <strong class="fsfunc">XDefaultGCOfScreen</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


<a id="idp43761812" class="indexterm"></a>
<a id="idp43762188" class="indexterm"></a>
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.
</p><p>



</p><p>
DefaultVisualOfScreen(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><a id="XDefaultVisualOfScreen"></a><p><code class="funcdef">Visual *<strong class="fsfunc">XDefaultVisualOfScreen</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


<a id="idp43767276" class="indexterm"></a>
<a id="idp43767652" class="indexterm"></a>
Both return the default visual of the specified screen.
For information on visual types,
see <a class="link" href="#Visual_Types" title="Visual Types">section 3.1</a>.
</p><p>



</p><p>
DoesBackingStore(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><a id="XDoesBackingStore"></a><p><code class="funcdef">int <strong class="fsfunc">XDoesBackingStore</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


<a id="idp43772988" class="indexterm"></a>
<a id="idp43773364" class="indexterm"></a>
Both return a value indicating whether the screen supports backing
stores.
The value returned can be one of 
<span class="symbol">WhenMapped</span>,
<span class="symbol">NotUseful</span>,
or
<span class="symbol">Always</span>
(see <a class="link" href="#Backing_Store_Attribute" title="Backing Store Attribute">section 3.2.4</a>).
</p><p>



</p><p>
DoesSaveUnders(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><a id="XDoesSaveUnders"></a><p><code class="funcdef">Bool <strong class="fsfunc">XDoesSaveUnders</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


<a id="idp43779292" class="indexterm"></a>
<a id="idp43779668" class="indexterm"></a>
Both return a Boolean value indicating whether the
screen supports save unders.
If
<span class="symbol">True</span>,
the screen supports save unders.
If
<span class="symbol">False</span>,
the screen does not support save unders
(see <a class="link" href="#Save_Under_Flag" title="Save Under Flag">section 3.2.5</a>).
</p><p>



</p><p>
DisplayOfScreen(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><a id="XDisplayOfScreen"></a><p><code class="funcdef">Display *<strong class="fsfunc">XDisplayOfScreen</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


<a id="idp43785484" class="indexterm"></a>
<a id="idp43785860" class="indexterm"></a>
Both return the display of the specified screen.
</p><p>



<a id="idp43786868" class="indexterm"></a>
</p><p>
EventMaskOfScreen(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><a id="XEventMaskOfScreen"></a><p><code class="funcdef">long <strong class="fsfunc">XEventMaskOfScreen</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


The
<code class="function">XScreenNumberOfScreen</code>
function returns the screen index number of the specified screen.
</p><p>



</p><p>
EventMaskOfScreen(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><p><code class="funcdef">long <strong class="fsfunc">XEventMaskOfScreen</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


<a id="idp43796020" class="indexterm"></a>
<a id="idp43796396" class="indexterm"></a>
Both return the event mask of the root window for the specified screen
at connection setup time.
</p><p>



</p><p>
WidthOfScreen(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><a id="XWidthOfScreen"></a><p><code class="funcdef">int <strong class="fsfunc">XWidthOfScreen</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


<a id="idp43801420" class="indexterm"></a>
<a id="idp43801796" class="indexterm"></a>
Both return the width of the specified screen in pixels.
</p><p>



</p><p>
HeightOfScreen(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><a id="XHeightOfScreen"></a><p><code class="funcdef">int <strong class="fsfunc">XHeightOfScreen</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


<a id="idp43806780" class="indexterm"></a>
<a id="idp43807156" class="indexterm"></a>
Both return the height of the specified screen in pixels.
</p><p>



</p><p>
WidthMMOfScreen(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><a id="XWidthMMOfScreen"></a><p><code class="funcdef">int <strong class="fsfunc">XWidthMMOfScreen</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


<a id="idp43812140" class="indexterm"></a>
<a id="idp43812516" class="indexterm"></a>
Both return the width of the specified screen in millimeters.
</p><p>



</p><p>
HeightMMOfScreen(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><a id="XHeightMMOfScreen"></a><p><code class="funcdef">int <strong class="fsfunc">XHeightMMOfScreen</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


<a id="idp43817508" class="indexterm"></a>
<a id="idp43817884" class="indexterm"></a>
Both return the height of the specified screen in millimeters.
</p><p>



</p><p>
MaxCmapsOfScreen(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><a id="XMaxCmapsOfScreen"></a><p><code class="funcdef">int <strong class="fsfunc">XMaxCmapsOfScreen</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


<a id="idp43822876" class="indexterm"></a>
<a id="idp43823252" class="indexterm"></a>
Both return the maximum number of installed colormaps supported 
by the specified screen
(see <a class="link" href="#Managing_Installed_Colormaps" title="Managing Installed Colormaps">section 9.3</a>).
</p><p>



</p><p>
MinCmapsOfScreen(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><a id="XMinCmapsOfScreen"></a><p><code class="funcdef">int <strong class="fsfunc">XMinCmapsOfScreen</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


<a id="idp43828628" class="indexterm"></a>
<a id="idp43829004" class="indexterm"></a>
Both return the minimum number of installed colormaps supported 
by the specified screen
(see <a class="link" href="#Managing_Installed_Colormaps" title="Managing Installed Colormaps">section 9.3</a>).
</p><p>



</p><p>
PlanesOfScreen(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><a id="XPlanesOfScreen"></a><p><code class="funcdef">int <strong class="fsfunc">XPlanesOfScreen</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


<a id="idp43834380" class="indexterm"></a>
<a id="idp43834756" class="indexterm"></a>
Both return the depth of the root window.
</p><p>



</p><p>
RootWindowOfScreen(<span class="emphasis"><em>screen</em></span>)
</p><div class="funcsynopsis"><a id="XRootWindowOfScreen"></a><p><code class="funcdef">Window <strong class="fsfunc">XRootWindowOfScreen</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the appropriate 
<span class="type">Screen</span>
structure.
    </p></td></tr></tbody></table></div><p>


<a id="idp43839724" class="indexterm"></a>
<a id="idp43840100" class="indexterm"></a>
Both return the root window of the specified screen.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Generating_a_NoOperation_Protocol_Request"></a>Generating a NoOperation Protocol Request</h2></div></div></div><p>

To execute a 
<code class="systemitem">NoOperation</code>
protocol request, use
<a class="xref" href="#XNoOp"><code class="function">XNoOp</code></a>.
<a id="idp43842692" class="indexterm"></a>

</p><div class="funcsynopsis"><a id="XNoOp"></a><p><code class="funcdef"><strong class="fsfunc">XNoOp</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term"><span class="emphasis"><em>display</em></span></span></p></td><td><p>Specifies the connection to the X server.</p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XNoOp"><code class="function">XNoOp</code></a>
function sends a 
<code class="systemitem">NoOperation</code>
protocol request to the X server,
thereby exercising the connection.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Freeing_Client_Created_Data"></a>Freeing Client-Created Data</h2></div></div></div><p>

To free in-memory data that was created by an Xlib function, use
<a class="xref" href="#XFree"></a>.
<a id="idp43848604" class="indexterm"></a>

</p><div class="funcsynopsis"><a id="XFree"></a><p><code class="funcdef">XFree(</code>void<var class="pdparam"> *data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>data</em></span>
    </span></p></td><td><p>
Specifies the data that is to be freed.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFree"></a>
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.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Closing_the_Display"></a>Closing the Display</h2></div></div></div><p>

To close a display or disconnect from the X server, use
<code class="function">XCloseDisplay</code>.
<a id="idp43854364" class="indexterm"></a>
</p><p>


</p><div class="funcsynopsis"><a id="xclosedisplay"></a><p><code class="funcdef">XCloseDisplay(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


The
<code class="function">XCloseDisplay</code>
function closes the connection to the X server for the display specified in the
<span class="type">Display</span>
structure and destroys all windows, resource IDs
(<span class="type">Window</span>,
<span class="type">Font</span>,
<span class="type">Pixmap</span>,
<span class="type">Colormap</span>,
<span class="type">Cursor</span>,
and
<span class="type">GContext</span>),
or other resources that the client has created
on this display, unless the close-down mode of the resource has been changed
(see
<a class="xref" href="#XSetCloseDownMode"></a>).
Therefore, these windows, resource IDs, and other resources should never be 
referenced again or an error will be generated.
Before exiting, you should call
<code class="function">XCloseDisplay</code>
explicitly so that any pending errors are reported as
<code class="function">XCloseDisplay</code>
performs a final
<a class="xref" href="#XSync"><code class="function">XSync</code></a>
operation.
<a id="idp43861764" class="indexterm"></a>
<a id="idp43862140" class="indexterm"></a>
</p><p>

<code class="function">XCloseDisplay</code>
can generate a
<span class="errorname">BadGC</span>
error.

</p><p>

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
<a class="xref" href="#XSetCloseDownMode"></a>.
<a id="idp43864324" class="indexterm"></a>

</p><div class="funcsynopsis"><a id="XSetCloseDownMode"></a><p><code class="funcdef">XSetCloseDownMode(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> close_mode</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>close_mode</em></span>
    </span></p></td><td><p>
Specifies the client close-down mode.
You can pass 
<span class="symbol">DestroyAll</span>,
<span class="symbol">RetainPermanent</span>,
or
<span class="symbol">RetainTemporary</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetCloseDownMode"></a>
defines what will happen to the client's resources at connection close.
A connection starts in
<span class="symbol">DestroyAll</span>
mode.
For information on what happens to the client's resources when the
close_mode argument is
<span class="symbol">RetainPermanent</span>
or
<span class="symbol">RetainTemporary</span>,
see <a class="link" href="#Using_X_Server_Connection_Close_Operations" title="Using X Server Connection Close Operations">section 2.6</a>.
</p><p>

<a class="xref" href="#XSetCloseDownMode"></a>
can generate a
<span class="errorname">BadValue</span>
error.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Using_X_Server_Connection_Close_Operations"></a>Using X Server Connection Close Operations</h2></div></div></div><p>

When the X server's connection to a client is closed
either by an explicit call to
<code class="function">XCloseDisplay</code>
or by a process that exits, the X server performs the following
automatic operations:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
It disowns all selections owned by the client
(see 
<a class="xref" href="#XSetSelectionOwner"><code class="function">XSetSelectionOwner</code></a>).
    </p></li><li class="listitem"><p>
It performs an
<a class="xref" href="#XUngrabPointer"><code class="function">XUngrabPointer</code></a>
and
<a class="xref" href="#XUngrabKeyboard"><code class="function">XUngrabKeyboard</code></a>
if the client has actively grabbed the pointer 
or the keyboard.
    </p></li><li class="listitem"><p>
It performs an
<a class="xref" href="#XUngrabServer"><code class="function">XUngrabServer</code></a>
if the client has grabbed the server.
    </p></li><li class="listitem"><p>
It releases all passive grabs made by the client.  
    </p></li><li class="listitem"><p>
It marks all resources (including colormap entries) allocated 
by the client either as permanent or temporary, 
depending on whether the close-down mode is 
<span class="symbol">RetainPermanent</span>
or
<span class="symbol">RetainTemporary</span>.
However, this does not prevent other client applications from explicitly
destroying the resources (see 
<a class="xref" href="#XSetCloseDownMode"></a>).
    </p></li></ul></div><p>

When the close-down mode is
<span class="symbol">DestroyAll</span>,
the X server destroys all of a client's resources as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
It performs a
<code class="systemitem">MapWindow</code>
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.
    </p></li><li class="listitem"><p>
It destroys all windows created by the client.
    </p></li><li class="listitem"><p>
It performs the appropriate free request on each nonwindow resource created by
the client in the server (for example, 
<span class="type">Font</span>,
<span class="type">Pixmap</span>,
<span class="type">Cursor</span>,
<span class="type">Colormap</span>,
and 
<span class="type">GContext</span>).
    </p></li><li class="listitem"><p>
It frees all colors and colormap entries allocated by a client application.
    </p></li></ul></div><p>

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
<span class="symbol">DestroyAll</span>,
the X server does the following: 
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
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 
<span class="symbol">RetainPermanent</span>
or
<span class="symbol">RetainTemporary</span>
mode.
    </p></li><li class="listitem"><p>
It deletes all but the predefined atom identifiers.
    </p></li><li class="listitem"><p>
It deletes all properties on all root windows
(see <a class="link" href="#Properties_and_Atoms" title="Properties and Atoms">section 4.3</a>).
    </p></li><li class="listitem"><p>
It resets all device maps and attributes 
(for example, key click, bell volume, and acceleration) 
as well as the access control list.
    </p></li><li class="listitem"><p>
It restores the standard root tiles and cursors.
    </p></li><li class="listitem"><p>
It restores the default font path.
    </p></li><li class="listitem"><p>
It restores the input focus to state
<span class="symbol">PointerRoot</span>.
    </p></li></ul></div><p>

However, the X server does not reset if you close a connection with a close-down
mode set to
<span class="symbol">RetainPermanent</span>
or
<span class="symbol">RetainTemporary</span>.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Using_Xlib_with_Threads"></a>Using Xlib with Threads</h2></div></div></div><p>

On systems that have threads, support may be provided to permit
multiple threads to use Xlib concurrently.
</p><p>


To initialize support for concurrent threads, use
<code class="function">XInitThreads</code>.
<a id="idp43892412" class="indexterm"></a>

</p><p>Status XInitThreads();</p><p>


The
<code class="function">XInitThreads</code>
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.
</p><p>

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.

</p><p>


To lock a display across several Xlib calls, use
<code class="function">XLockDisplay</code>.
<a id="idp43895892" class="indexterm"></a>

</p><div class="funcsynopsis"><a id="xlockdisplay"></a><p><code class="funcdef">XLockDisplay(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


The
<code class="function">XLockDisplay</code>
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
<code class="function">XLockDisplay</code>
work correctly; the display will not actually be unlocked until
<a class="xref" href="#XUnlockDisplay"></a>
has been called the same number of times as
<code class="function">XLockDisplay</code>.
This function has no effect unless Xlib was successfully initialized
for threads using
<code class="function">XInitThreads</code>.
</p><p>


To unlock a display, use
<a class="xref" href="#XUnlockDisplay"></a>.
<a id="idp43902164" class="indexterm"></a>

</p><div class="funcsynopsis"><a id="XUnlockDisplay"></a><p><code class="funcdef">XUnlockDisplay(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XUnlockDisplay"></a>
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
<code class="function">XLockDisplay</code>
has been called multiple times by a thread, then
<a class="xref" href="#XUnlockDisplay"></a>
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
<code class="function">XInitThreads</code>.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Using_Internal_Connections"></a>Using Internal Connections</h2></div></div></div><p>

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
<a class="link" href="#Locales_and_Internationalized_Text_Functions" title="Chapter 13. Locales and Internationalized Text Functions">chapter 13</a>).
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.
</p><p>

To track internal connections for a display, use
<a class="xref" href="#XAddConnectionWatch"></a>.
</p><div class="funcsynopsis"><a id="xconnectionwatch"></a><p><code class="funcdef">type void XConnectionWatchProc(</code>Display<var class="pdparam"> *display</var>, XPointer<var class="pdparam"> client_data</var>, int<var class="pdparam"> fd</var>, Bool<var class="pdparam"> opening</var>, XPointer<var class="pdparam"> *watch_data</var><code>)</code>;</p></div><div class="funcsynopsis"><a id="XAddConnectionWatch"></a><p><code class="funcdef">Status XAddConnectionWatch(</code>Display<var class="pdparam"> *display</var>, XWatchProc<var class="pdparam"> procedure</var>, XPointer<var class="pdparam"> client_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>procedure</em></span>
    </span></p></td><td><p>
Specifies the procedure to be called.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies the additional client data.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XAddConnectionWatch"></a>
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
<span class="symbol">True</span>,
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
<span class="symbol">False</span>,
the location pointed to by watch_data will hold this same private data pointer.
</p><p>

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
<a class="xref" href="#XAddConnectionWatch"></a>
returns.
<a class="xref" href="#XAddConnectionWatch"></a>
returns a nonzero status if the procedure is successfully registered;
otherwise, it returns zero.
</p><p>

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
<code class="function">XLockDisplay</code>.
</p><p>


To stop tracking internal connections for a display, use
<code class="function">XRemoveConnectionWatch</code>.
<a id="idp43924076" class="indexterm"></a>

</p><p>
()
</p><div class="funcsynopsis"><a id="xremoveconnectionwatch"></a><p><code class="funcdef">Status <strong class="fsfunc">XRemoveConnectionWatch</strong>(</code>Display<var class="pdparam"> *display</var>, XWatchProc<var class="pdparam"> procedure</var>, XPointer<var class="pdparam"> client_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>procedure</em></span>
    </span></p></td><td><p>
Specifies the procedure to be called.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies the additional client data.
    </p></td></tr></tbody></table></div><p>


The
<code class="function">XRemoveConnectionWatch</code>
function removes a previously registered connection watch procedure.
The client_data must match the client_data used when the procedure
was initially registered.

</p><p>


To process input on an internal connection, use
<a class="xref" href="#XProcessInternalConnection"><code class="function">XProcessInternalConnection</code></a>.
<a id="idp43932564" class="indexterm"></a>

</p><p>
()
</p><div class="funcsynopsis"><a id="XProcessInternalConnection"></a><p><code class="funcdef">void <strong class="fsfunc">XProcessInternalConnection</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> fd</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>fd</em></span>
    </span></p></td><td><p>
Specifies the file descriptor.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XProcessInternalConnection"><code class="function">XProcessInternalConnection</code></a>
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,
<code class="function">select</code>
or
<code class="function">poll</code>)
has indicated that input is available; otherwise,
the effect is not defined.
</p><p>


To obtain all of the current internal connections for a display, use
<a class="xref" href="#XInternalConnectionNumbers"><code class="function">XInternalConnectionNumbers</code></a>.
<a id="idp43940276" class="indexterm"></a>

</p><p>
()
</p><div class="funcsynopsis"><a id="XInternalConnectionNumbers"></a><p><code class="funcdef">Status <strong class="fsfunc">XInternalConnectionNumbers</strong>(</code>Display<var class="pdparam"> *display</var>, int **<var class="pdparam"> fd</var>, int *<var class="pdparam"> count_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>fd_return</em></span>
    </span></p></td><td><p>
Returns the file descriptors.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count_return</em></span>
    </span></p></td><td><p>
Returns the number of file descriptors.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XInternalConnectionNumbers"><code class="function">XInternalConnectionNumbers</code></a>
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
<a class="xref" href="#XFree"></a>.
This functions returns a nonzero status if the list is successfully allocated;
otherwise, it returns zero.
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Window_Functions"></a>Chapter 3. Window Functions</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Visual_Types">Visual Types</a></span></dt><dt><span class="sect1"><a href="#Window_Attributes">Window Attributes</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Background_Attribute">Background Attribute</a></span></dt><dt><span class="sect2"><a href="#Border_Attribute">Border Attribute</a></span></dt><dt><span class="sect2"><a href="#Gravity_Attributes">Gravity Attributes</a></span></dt><dt><span class="sect2"><a href="#Backing_Store_Attribute">Backing Store Attribute</a></span></dt><dt><span class="sect2"><a href="#Save_Under_Flag">Save Under Flag</a></span></dt><dt><span class="sect2"><a href="#Backing_Planes_and_Backing_Pixel_Attributes">Backing Planes and Backing Pixel Attributes</a></span></dt><dt><span class="sect2"><a href="#Event_Mask_and_Do_Not_Propagate_Mask_Attributes">Event Mask and Do Not Propagate Mask Attributes</a></span></dt><dt><span class="sect2"><a href="#Override_Redirect_Flag">Override Redirect Flag</a></span></dt><dt><span class="sect2"><a href="#Colormap_Attribute">Colormap Attribute</a></span></dt><dt><span class="sect2"><a href="#Cursor_Attribute">Cursor Attribute</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Creating_Windows">Creating Windows</a></span></dt><dt><span class="sect1"><a href="#Destroying_Windows">Destroying Windows</a></span></dt><dt><span class="sect1"><a href="#Mapping_Windows">Mapping Windows</a></span></dt><dt><span class="sect1"><a href="#Unmapping_Windows">Unmapping Windows</a></span></dt><dt><span class="sect1"><a href="#Configuring_Windows">Configuring Windows</a></span></dt><dt><span class="sect1"><a href="#Changing_Window_Stacking_Order">Changing Window Stacking Order</a></span></dt><dt><span class="sect1"><a href="#Changing_Window_Attributes">Changing Window Attributes</a></span></dt></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Visual_Types"></a>Visual Types</h2></div></div></div><p>

<a id="idp41430948" class="indexterm"></a>
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 <a class="link" href="#Display_Macros" title="Display Macros">2.2.1</a>
and <a class="link" href="#Determining_the_Appropriate_Visual_Type" title="Determining the Appropriate Visual Type">16.7</a>).
</p><p>

Xlib uses an opaque 
<span class="structname">Visual</span>
<a id="idp43020308" class="indexterm"></a>
structure that contains information about the possible color mapping.
The visual utility functions
(see <a class="link" href="#Determining_the_Appropriate_Visual_Type" title="Determining the Appropriate Visual Type">section 16.7</a>)
use an
<span class="structname">XVisualInfo</span>
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 
<a id="idp42641572" class="indexterm"></a>
<a id="idp41234268" class="indexterm"></a>
<a id="idp40415276" class="indexterm"></a>
<a id="idp40794932" class="indexterm"></a>
<a id="idp43019108" class="indexterm"></a>
<a id="idp42895284" class="indexterm"></a>
<span class="symbol">StaticGray</span>,
<span class="symbol">StaticColor</span>,
<span class="symbol">TrueColor</span>,
<span class="symbol">GrayScale</span>,
<span class="symbol">PseudoColor</span>,
or
<span class="symbol">DirectColor</span>.
</p><p>

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 
<acronym class="acronym">RGB</acronym> pieces, provided one is not on a grayscale screen.
This leads to the following diagram:
</p><pre class="literallayout">
                      Color        Gray-Scale
                   R/O    R/W      R/O   R/W
----------------------------------------------
 Undecomposed    Static  Pseudo   Static  Gray
   Colormap      Color   Color    Gray    Scale

 Decomposed       True   Direct
   Colormap       Color  Color
----------------------------------------------
</pre><p>

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 <acronym class="acronym">RGB</acronym> values in the following ways:
</p><p>

</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
For 
<span class="symbol">PseudoColor</span>,
a pixel value indexes a colormap to produce
independent <acronym class="acronym">RGB</acronym> values, and the <acronym class="acronym">RGB</acronym> values can be changed dynamically.
    </p></li><li class="listitem"><p>
<span class="symbol">GrayScale</span>
is treated the same way as 
<span class="symbol">PseudoColor</span>
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.  
    </p></li><li class="listitem"><p>
For 
<span class="symbol">DirectColor</span>,
a pixel value is decomposed into separate <acronym class="acronym">RGB</acronym> subfields, and each
subfield separately indexes the colormap for the corresponding value.
The <acronym class="acronym">RGB</acronym> values can be changed dynamically.
    </p></li><li class="listitem"><p>
<span class="symbol">TrueColor</span>
is treated the same way as 
<span class="symbol">DirectColor</span>
except that the colormap has predefined, read-only <acronym class="acronym">RGB</acronym> values.
These <acronym class="acronym">RGB</acronym> values are server dependent but provide linear or near-linear
ramps in each primary.  
    </p></li><li class="listitem"><p>
<span class="symbol">StaticColor</span>
is treated the same way as 
<span class="symbol">PseudoColor</span>
except that the colormap has predefined, 
read-only, server-dependent <acronym class="acronym">RGB</acronym> values.
    </p></li><li class="listitem"><p>
<span class="symbol">StaticGray</span>
is treated the same way as 
<span class="symbol">StaticColor</span>
except that the <acronym class="acronym">RGB</acronym> values are equal for any single pixel
value, thus resulting in shades of gray.  
<span class="symbol">StaticGray</span>
with a two-entry
colormap can be thought of as monochrome.
    </p></li></ul></div><p>

The red_mask, green_mask, and blue_mask members are only defined for
<span class="symbol">DirectColor</span>
and 
<span class="symbol">TrueColor</span>.
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 <acronym class="acronym">RGB</acronym> values are unsigned 16-bit numbers.
The colormap_size member defines the number of available colormap entries
in a newly created colormap.  
For 
<span class="symbol">DirectColor</span>
and 
<span class="symbol">TrueColor</span>,
this is the size of an individual pixel subfield.

</p><p>

To obtain the visual ID from a 
<span class="structname">Visual</span>,
use
<a class="xref" href="#XVisualIDFromVisual"><code class="function">XVisualIDFromVisual</code></a>.
<a id="idp42263196" class="indexterm"></a>
</p><div class="funcsynopsis"><a id="XVisualIDFromVisual"></a><p><code class="funcdef">VisualID <strong class="fsfunc">XVisualIDFromVisual</strong>(</code>Visual *<var class="pdparam">visual</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>visual</em></span>
    </span></p></td><td><p>
Specifies the visual type.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XVisualIDFromVisual"><code class="function">XVisualIDFromVisual</code></a>
function returns the visual ID for the specified visual type.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Window_Attributes"></a>Window Attributes</h2></div></div></div><p>

<a id="idp40341028" class="indexterm"></a>
<a id="idp40341452" class="indexterm"></a>
All 
<span class="symbol">InputOutput</span>
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 <a class="link" href="#Properties_and_Atoms" title="Properties and Atoms">section 4.3</a>).
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.
</p><p>

Windows also have associated property lists
(see <a class="link" href="#Properties_and_Atoms" title="Properties and Atoms">section 4.3</a>).
</p><p>

Both
<span class="symbol">InputOutput</span>
and
<span class="symbol">InputOnly</span>
windows have the following common attributes,
which are the only attributes of an
<span class="symbol">InputOnly</span>
window:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
win-gravity
    </p></li><li class="listitem"><p>
event-mask
    </p></li><li class="listitem"><p>
do-not-propagate-mask
    </p></li><li class="listitem"><p>
override-redirect
    </p></li><li class="listitem"><p>
cursor
    </p></li></ul></div><p>

If you specify any other attributes for an
<span class="symbol">InputOnly</span>
window,
a
<span class="errorname">BadMatch</span>
error results.
</p><p>

<span class="symbol">InputOnly</span>
windows are used for controlling input events in situations where
<span class="symbol">InputOutput</span>
windows are unnecessary.
<span class="symbol">InputOnly</span>
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
<span class="symbol">InputOnly</span>
windows cannot have
<span class="symbol">InputOutput</span>
windows as inferiors.
</p><p>

Windows have borders of a programmable width and pattern
as well as a background pattern or tile.
<a id="idp42673156" class="indexterm"></a>
Pixel values can be used for solid colors.
<a id="idp42673764" class="indexterm"></a>
<a id="idp42674340" class="indexterm"></a>
The background and border pixmaps can be destroyed immediately after
creating the window if no further explicit references to them
are to be made.
<a id="idp42675052" class="indexterm"></a>
The pattern can either be relative to the parent 
or absolute.
If
<span class="symbol">ParentRelative</span>,
the parent's background is used.
</p><p>

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.
<a id="idp42676508" class="indexterm"></a>
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
<a class="xref" href="#XMapWindow"><code class="function">XMapWindow</code></a>),
<a id="idp42677636" class="indexterm"></a>
the X server generates an 
<span class="symbol">Expose</span>
event for the window if backing store has not been maintained.
</p><p>

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.
</p><p>

To set an attribute of a window,
set the appropriate member of the
<span class="structname">XSetWindowAttributes</span>
structure and OR in the corresponding value bitmask in your subsequent calls to
<a class="xref" href="#XCreateWindow"><code class="function">XCreateWindow</code></a>
and
<a class="xref" href="#XChangeWindowAttributes"><code class="function">XChangeWindowAttributes</code></a>,
or use one of the other convenience functions that set the appropriate 
attribute.
The symbols for the value mask bits and the
<span class="structname">XSetWindowAttributes</span>
structure are:

</p><p>

/* Window attribute value mask bits */


</p><pre class="literallayout">
/* Window attribute value mask bits */
#define    CWBackPixmap                    (1L&lt;&lt;0)
#define    CWBackPixel                     (1L&lt;&lt;1)
#define    CWBorderPixmap                  (1L&lt;&lt;2)
#define    CWBorderPixel                   (1L&lt;&lt;3)
#define    CWBitGravity                    (1L&lt;&lt;4)
#define    CWWinGravity                    (1L&lt;&lt;5)
#define    CWBackingStore                  (1L&lt;&lt;6)
#define    CWBackingPlanes                 (1L&lt;&lt;7)
#define    CWBackingPixel                  (1L&lt;&lt;8)
#define    CWOverrideRedirect              (1L&lt;&lt;9)
#define    CWSaveUnder                     (1L&lt;&lt;10)
#define    CWEventMask                     (1L&lt;&lt;11)
#define    CWDontPropagate                 (1L&lt;&lt;12)
#define    CWColormap                      (1L&lt;&lt;13)
#define    CWCursor                        (1L&lt;&lt;14)
</pre><p>

<a id="idp42682220" class="indexterm"></a>
</p><pre class="literallayout">


/* Values */

typedef struct {
     Pixmap background_pixmap;     /* background, None, or ParentRelative */
     unsigned long background_pixel;     /* background pixel */
     Pixmap border_pixmap;          /* border of the window or CopyFromParent */
     unsigned long border_pixel;     /* border pixel value */
     int bit_gravity;     /* one of bit gravity values */
     int win_gravity;     /* one of the window gravity values */
     int backing_store;     /* NotUseful, WhenMapped, Always */
     unsigned long backing_planes;     /* planes to be preserved if possible */
     unsigned long backing_pixel;     /* value to use in restoring planes */
     Bool save_under;     /* should bits under be saved? (popups) */
     long event_mask;     /* set of events that should be saved */
     long do_not_propagate_mask;     /* set of events that should not propagate */
     Bool override_redirect;     /* boolean value for override_redirect */
     Colormap colormap;     /* color map to be associated with window */
     Cursor cursor;          /* cursor to be displayed (or None) */
} XSetWindowAttributes;
</pre><p>
</p><p>


The following lists the defaults for each window attribute and indicates
whether the attribute is applicable to
<span class="symbol">InputOutput</span>
and
<span class="symbol">InputOnly</span>
windows:
</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">Attribute</th><th align="left">Default</th><th align="left">InputOutput</th><th align="left">InputOnly</th></tr></thead><tbody><tr><td align="left">background-pixmap</td><td align="left"><span class="symbol">None</span></td><td align="left">Yes</td><td align="left">No</td></tr><tr><td align="left">background-pixel</td><td align="left">Undefined</td><td align="left">Yes</td><td align="left">No</td></tr><tr><td align="left">border-pixmap</td><td align="left"><span class="symbol">CopyFromParent</span></td><td align="left">Yes</td><td align="left">No</td></tr><tr><td align="left">border-pixel</td><td align="left">Undefined</td><td align="left">Yes</td><td align="left">No</td></tr><tr><td align="left">bit-gravity</td><td align="left"><span class="symbol">ForgetGravity</span></td><td align="left">Yes</td><td align="left">No</td></tr><tr><td align="left">win-gravity</td><td align="left"><span class="symbol">NorthWestGravity</span></td><td align="left">Yes</td><td align="left">Yes</td></tr><tr><td align="left">backing-store</td><td align="left"><span class="symbol">NotUseful</span></td><td align="left">Yes</td><td align="left">No</td></tr><tr><td align="left">backing-planes</td><td align="left">All ones</td><td align="left">Yes</td><td align="left">No</td></tr><tr><td align="left">backing-pixel</td><td align="left">zero</td><td align="left">Yes</td><td align="left">No</td></tr><tr><td align="left">save-under</td><td align="left"><span class="symbol">False</span></td><td align="left">Yes</td><td align="left">No</td></tr><tr><td align="left">event-mask</td><td align="left">empty set</td><td align="left">Yes</td><td align="left">Yes</td></tr><tr><td align="left">do-not-propagate-mask</td><td align="left">empty set</td><td align="left">Yes</td><td align="left">Yes</td></tr><tr><td align="left">override-redirect</td><td align="left"><span class="symbol">False</span></td><td align="left">Yes</td><td align="left">Yes</td></tr><tr><td align="left">colormap</td><td align="left"><span class="symbol">CopyFromParent</span></td><td align="left">Yes</td><td align="left">No</td></tr><tr><td align="left">cursor</td><td align="left"><span class="symbol">None</span></td><td align="left">Yes</td><td align="left">Yes</td></tr></tbody></table></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Background_Attribute"></a>Background Attribute</h3></div></div></div><p>

Only
<span class="symbol">InputOutput</span>
windows can have a background.
You can set the background of an
<span class="symbol">InputOutput</span>
window by using a pixel or a pixmap.
</p><p>

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.
</p><p>

You can set the background-pixmap to a pixmap,  
<span class="symbol">None</span>
(default), or 
<span class="symbol">ParentRelative</span>.
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.
</p><p>

If you set the background-pixmap,
it overrides the default.
The background-pixmap and the window must have the same depth,
or a
<span class="errorname">BadMatch</span>
error results.
If you set background-pixmap to
<span class="symbol">None</span>,
the window has no defined background.  
If you set the background-pixmap to
<span class="symbol">ParentRelative</span>:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The parent window's background-pixmap is used. 
The child window, however, must have the same depth as 
its parent,
or a
<span class="errorname">BadMatch</span>
error results.
    </p></li><li class="listitem"><p>
If the parent window has a background-pixmap of
<span class="symbol">None</span>,
the window also has a background-pixmap of
<span class="symbol">None</span>.
    </p></li><li class="listitem"><p>
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.  
    </p></li><li class="listitem"><p>
The background tile origin always aligns with the parent window's
background tile origin. 
If the background-pixmap is not
<span class="symbol">ParentRelative</span>,
the background tile origin is the child window's origin.
    </p></li></ul></div><p>

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.
</p><p>

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
<span class="symbol">None</span>.
If the background is
<span class="symbol">None</span>,
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.
<span class="symbol">Expose</span>
events are then generated for the regions, even if the background-pixmap
is
<span class="symbol">None</span>
(see <a class="link" href="#Exposure_Events" title="Exposure Events">section 10.9</a>).
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Border_Attribute"></a>Border Attribute</h3></div></div></div><p>

Only
<span class="symbol">InputOutput</span>
windows can have a border.
You can set the border of an
<span class="symbol">InputOutput</span>
window by using a pixel or a pixmap.
</p><p>

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.
</p><p>

You can also set the border-pixmap to a pixmap of any size (some may be faster
than others) or to
<span class="symbol">CopyFromParent</span>
(default).
You can set the border-pixel to any pixel value (no default).
</p><p>

If you set a border-pixmap, 
it overrides the default.
The border-pixmap and the window must have the same depth,
or a
<span class="errorname">BadMatch</span>
error results.
If you set the border-pixmap to 
<span class="symbol">CopyFromParent</span>,
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
<span class="errorname">BadMatch</span>
error results.
</p><p>

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.
</p><p>

Output to a window is always clipped to the inside of the window. 
Therefore, graphics operations never affect the window border.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Gravity_Attributes"></a>Gravity Attributes</h3></div></div></div><p>

The bit gravity of a window defines which region of the window should be 
retained when an
<span class="symbol">InputOutput</span>
window is resized. 
The default value for the bit-gravity attribute is 
<span class="symbol">ForgetGravity</span>.
The window gravity of a window allows you to define how the 
<span class="symbol">InputOutput</span>
or
<span class="symbol">InputOnly</span>
window should be repositioned if its parent is resized.  
The default value for the win-gravity attribute is 
<span class="symbol">NorthWestGravity</span>.
</p><p>

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:
</p><p>

</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Gravity Direction</th><th align="left">Coordinates</th></tr></thead><tbody><tr><td align="left"><span class="symbol">NorthWestGravity</span></td><td align="left">(0, 0)</td></tr><tr><td align="left"><span class="symbol">NorthGravity</span></td><td align="left">(Width/2, 0)</td></tr><tr><td align="left"><span class="symbol">NorthEastGravity</span></td><td align="left">(Width, 0)</td></tr><tr><td align="left"><span class="symbol">WestGravity</span></td><td align="left">(0, Height/2)</td></tr><tr><td align="left"><span class="symbol">CenterGravity</span></td><td align="left">(Width/2, Height/2)</td></tr><tr><td align="left"><span class="symbol">EastGravity</span></td><td align="left">(Width, Height/2)</td></tr><tr><td align="left"><span class="symbol">SouthWestGravity</span></td><td align="left">(0, Height)</td></tr><tr><td align="left"><span class="symbol">SouthGravity</span></td><td align="left">(Width/2, Height)</td></tr><tr><td align="left"><span class="symbol">SouthEastGravity</span></td><td align="left">(Width, Height)</td></tr></tbody></table></div><p>
</p><p>

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
<span class="symbol">GravityNotify</span>
event is generated
(see <a class="link" href="#GravityNotify_Events" title="GravityNotify Events">section 10.10.5</a>).
</p><p>

A bit-gravity of
<span class="symbol">StaticGravity</span>
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
<span class="symbol">StaticGravity</span>
still only takes effect when the width or height of the window is changed, 
not when the window is moved.
</p><p>

A bit-gravity of 
<span class="symbol">ForgetGravity</span>
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 
<span class="symbol">Expose</span>
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 
<span class="symbol">Expose</span>
events.
</p><p>

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
<span class="symbol">Forget</span>
instead.
</p><p>

A win-gravity of 
<span class="symbol">UnmapGravity</span>
is like 
<span class="symbol">NorthWestGravity</span>
(the window is not moved),
except the child is also
unmapped when the parent is resized,
and an 
<span class="symbol">UnmapNotify</span>
event is
generated.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Backing_Store_Attribute"></a>Backing Store Attribute</h3></div></div></div><p>

Some implementations of the X server may choose to maintain the contents of 
<span class="symbol">InputOutput</span>
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
<span class="symbol">NotUseful</span>
(default),
<span class="symbol">WhenMapped</span>,
or
<span class="symbol">Always</span>.
</p><p>

A backing-store attribute of 
<span class="symbol">NotUseful</span>
advises the X server that 
maintaining contents is unnecessary, 
although some X implementations may
still choose to maintain contents and, therefore, not generate 
<span class="symbol">Expose</span>
events.
A backing-store attribute of 
<span class="symbol">WhenMapped</span>
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 
<span class="symbol">Expose</span>
event when the window is created.
A backing-store attribute of 
<span class="symbol">Always</span>
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, 
<span class="symbol">Expose</span>
events normally are not generated, 
but the X server may stop maintaining 
contents at any time.  
</p><p>

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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Save_Under_Flag"></a>Save Under Flag</h3></div></div></div><a id="idp44020156" class="indexterm"></a><p>

Some server implementations may preserve contents of 
<span class="symbol">InputOutput</span>
windows under other 
<span class="symbol">InputOutput</span>
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.
</p><p>

You can set the save-under flag to
<span class="symbol">True</span>
or
<span class="symbol">False</span>
(default).
If save-under is 
<span class="symbol">True</span>,
the X server is advised that, when this window is mapped, 
saving the contents of windows it obscures would be beneficial.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Backing_Planes_and_Backing_Pixel_Attributes"></a>Backing Planes and Backing Pixel Attributes</h3></div></div></div><p>

You can set backing planes to indicate (with bits set to 1) 
which bit planes of an
<span class="symbol">InputOutput</span>
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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Event_Mask_and_Do_Not_Propagate_Mask_Attributes"></a>Event Mask and Do Not Propagate Mask Attributes</h3></div></div></div><p>

The event mask defines which events the client is interested in for this 
<span class="symbol">InputOutput</span>
or
<span class="symbol">InputOnly</span>
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 
<span class="symbol">NoEventMask</span>
(default).
</p><p>

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 
<span class="symbol">InputOutput</span>
or
<span class="symbol">InputOnly</span>
window.
The do-not-propagate-mask is the bitwise inclusive OR of zero or more
of the following masks:
<span class="symbol">KeyPress</span>,
<span class="symbol">KeyRelease</span>,
<span class="symbol">ButtonPress</span>,
<span class="symbol">ButtonRelease</span>,
<span class="symbol">PointerMotion</span>,
<span class="symbol">Button1Motion</span>,
<span class="symbol">Button2Motion</span>,
<span class="symbol">Button3Motion</span>,
<span class="symbol">Button4Motion</span>,
<span class="symbol">Button5Motion</span>,
and
<span class="symbol">ButtonMotion</span>.
You can specify that all events are propagated by setting 
<span class="symbol">NoEventMask</span>
(default).
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Override_Redirect_Flag"></a>Override Redirect Flag</h3></div></div></div><p>

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
<span class="symbol">InputOutput</span>
or
<span class="symbol">InputOnly</span>
window is to ignore these structure control facilities,
use the override-redirect flag.
</p><p>

The override-redirect flag specifies whether map and configure requests 
on this window should override a 
<span class="symbol">SubstructureRedirectMask</span>
on the parent.
You can set the override-redirect flag to
<span class="symbol">True</span>
or
<span class="symbol">False</span>
(default).
Window managers use this information to avoid tampering with pop-up windows
(see also <a class="link" href="#Inter_Client_Communication_Functions" title="Chapter 14. Inter-Client Communication Functions">chapter 14</a>).
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Colormap_Attribute"></a>Colormap Attribute</h3></div></div></div><p>

The colormap attribute specifies which colormap best reflects the true
colors of the 
<span class="symbol">InputOutput</span>
window.  
The colormap must have the same visual type as the window,
or a 
<span class="errorname">BadMatch</span>
error results.  
X servers capable of supporting multiple 
hardware colormaps can use this information, 
and window managers can use it for calls to
<a class="xref" href="#XInstallColormap"><code class="function">XInstallColormap</code></a>.
You can set the colormap attribute to a colormap or to
<span class="symbol">CopyFromParent</span>
(default).
</p><p>

If you set the colormap to
<span class="symbol">CopyFromParent</span>,
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 
<span class="errorname">BadMatch</span>
error results. 
The parent window must not have a colormap of 
<span class="symbol">None</span>,
or a 
<span class="errorname">BadMatch</span>
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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Cursor_Attribute"></a>Cursor Attribute</h3></div></div></div><p>

The cursor attribute specifies which cursor is to be used when the pointer is
in the 
<span class="symbol">InputOutput</span>
or
<span class="symbol">InputOnly</span>
window.
You can set the cursor to a cursor or
<span class="symbol">None</span>
(default).
</p><p>

If you set the cursor to
<span class="symbol">None</span>,
the parent's cursor is used when the 
pointer is in the 
<span class="symbol">InputOutput</span>
or
<span class="symbol">InputOnly</span>
window, and any change in the parent's cursor will cause an
immediate change in the displayed cursor.
By calling
<a class="xref" href="#XFreeCursor"><code class="function">XFreeCursor</code></a>,
the cursor can be freed immediately as long as no further explicit reference 
to it is made.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Creating_Windows"></a>Creating Windows</h2></div></div></div><p>

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 <a class="link" href="#Inter_Client_Communication_Functions" title="Chapter 14. Inter-Client Communication Functions">chapter 14</a>).
</p><p>

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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
You must never fight with the window manager for the size or
placement of your top-level window.
    </p></li><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
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.)
    </p></li><li class="listitem"><p>
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.
    </p></li></ul></div><p>

For further information,
see <a class="link" href="#Inter_Client_Communication_Functions" title="Chapter 14. Inter-Client Communication Functions">chapter 14</a> and
the <span class="olink"><em class="citetitle">Inter-Client Communication Conventions Manual</em></span>.
</p><p>

<a class="xref" href="#XCreateWindow"><code class="function">XCreateWindow</code></a>
is the more general function that allows you to set specific window attributes 
when you create a window.
<a class="xref" href="#XCreateSimpleWindow"><code class="function">XCreateSimpleWindow</code></a>
creates a window that inherits its attributes from its parent window.
</p><p>

<a id="idp44053140" class="indexterm"></a>
The X server acts as if 
<span class="symbol">InputOnly</span>
windows do not exist for
the purposes of graphics requests, exposure processing, and
<span class="symbol">VisibilityNotify</span>
events.
An 
<span class="symbol">InputOnly</span>
window cannot be used as a
drawable (that is, as a source or destination for graphics requests).
<span class="symbol">InputOnly</span>
and 
<span class="symbol">InputOutput</span>
windows act identically in other respects (properties,
grabs, input control, and so on).
Extension packages can define other classes of windows.
</p><p>

To create an unmapped window and set its window attributes, use
<a class="xref" href="#XCreateWindow"><code class="function">XCreateWindow</code></a>.
</p><a id="idp44056084" class="indexterm"></a><div class="funcsynopsis"><a id="XCreateWindow"></a><p><code class="funcdef">Window <strong class="fsfunc">XCreateWindow</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> parent</var>, intx,<var class="pdparam"> y</var>, unsignedintwidth,<var class="pdparam"> height</var>, unsignedint<var class="pdparam"> border_width</var>, int<var class="pdparam"> depth</var>, unsignedint<var class="pdparam"> class</var>, Visual<var class="pdparam"> *visual</var>, unsignedlong<var class="pdparam"> valuemask</var>, XSetWindowAttributes<var class="pdparam"> *attributes</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>parent</em></span>
    </span></p></td><td><p>
Specifies the parent window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
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
<span class="errorname">BadValue</span>
error results.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>border_width</em></span>
    </span></p></td><td><p>
Specifies the width of the created window's border in pixels.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>depth</em></span>
    </span></p></td><td><p>
Specifies the window's depth.
A depth of 
<span class="symbol">CopyFromParent</span>
means the depth is taken from the parent.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>class</em></span>
    </span></p></td><td><p>
Specifies the created window's class.
You can pass
<span class="symbol">InputOutput</span>,
<span class="symbol">InputOnly</span>,
or 
<span class="symbol">CopyFromParent</span>.
A class of 
<span class="symbol">CopyFromParent</span>
means the class
is taken from the parent.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>visual</em></span>
    </span></p></td><td><p>
Specifies the visual type.
A visual of 
<span class="symbol">CopyFromParent</span>
means the visual type is taken from the 
parent.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>valuemask</em></span>
    </span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>attributes</em></span>
    </span></p></td><td><p>
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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCreateWindow"><code class="function">XCreateWindow</code></a>
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
<span class="symbol">CreateNotify</span>
event.
The created window is placed on top in the stacking order 
with respect to siblings.
</p><p>

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.
</p><p>

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

The created window is not yet displayed (mapped) on the user's display.
To display the window, call
<a class="xref" href="#XMapWindow"><code class="function">XMapWindow</code></a>.
The new window initially uses the same cursor as
its parent. 
A new cursor can be defined for the new window by calling
<a class="xref" href="#XDefineCursor"><code class="function">XDefineCursor</code></a>.
<a id="idp44607340" class="indexterm"></a>
<a id="idp44607844" class="indexterm"></a>
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.
</p><p>

<a class="xref" href="#XCreateWindow"><code class="function">XCreateWindow</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadColor</span>,
<span class="errorname">BadCursor</span>,
<span class="errorname">BadMatch</span>,
<span class="errorname">BadPixmap</span>,
<span class="errorname">BadValue</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To create an unmapped 
<span class="symbol">InputOutput</span>
subwindow of a given parent window, use
<a class="xref" href="#XCreateSimpleWindow"><code class="function">XCreateSimpleWindow</code></a>.
</p><a id="idp44611524" class="indexterm"></a><div class="funcsynopsis"><a id="XCreateSimpleWindow"></a><p><code class="funcdef">Window <strong class="fsfunc">XCreateSimpleWindow</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> parent</var>, intx,<var class="pdparam"> y</var>, unsignedintwidth,<var class="pdparam"> height</var>, unsignedint<var class="pdparam"> border_width</var>, unsignedlong<var class="pdparam"> border</var>, unsignedlong<var class="pdparam"> background</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>parent</em></span>
    </span></p></td><td><p>
Specifies the parent window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
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
<span class="errorname">BadValue</span>
error results.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>border_width</em></span>
    </span></p></td><td><p>
Specifies the width of the created window's border in pixels.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>border</em></span>
    </span></p></td><td><p>
Specifies the border pixel value of the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>background</em></span>
    </span></p></td><td><p>
Specifies the background pixel value of the window.

    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCreateSimpleWindow"><code class="function">XCreateSimpleWindow</code></a>
function creates an unmapped
<span class="symbol">InputOutput</span>
subwindow for a specified parent window, returns the
window ID of the created window, and causes the X server to generate a
<span class="symbol">CreateNotify</span>
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
<span class="symbol">InputOnly</span>
window must be zero, or a
<span class="errorname">BadMatch</span>
error results.
<a class="xref" href="#XCreateSimpleWindow"><code class="function">XCreateSimpleWindow</code></a>
inherits its depth, class, and visual from its parent.
All other window attributes, except background and border, 
have their default values.
</p><p>

<a class="xref" href="#XCreateSimpleWindow"><code class="function">XCreateSimpleWindow</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadMatch</span>,
<span class="errorname">BadValue</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Destroying_Windows"></a>Destroying Windows</h2></div></div></div><p>

Xlib provides functions that you can use to destroy a window or destroy all
subwindows of a window.
</p><p>


To destroy a window and all of its subwindows, use
<a class="xref" href="#XDestroyWindow"><code class="function">XDestroyWindow</code></a>.
</p><a id="idp44633596" class="indexterm"></a><div class="funcsynopsis"><a id="XDestroyWindow"></a><p><code class="funcdef"><strong class="fsfunc">XDestroyWindow</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDestroyWindow"><code class="function">XDestroyWindow</code></a>
function destroys the specified window as well as all of its subwindows and causes
the X server to generate a
<span class="symbol">DestroyNotify</span>
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
<span class="symbol">DestroyNotify</span>
events is such that for any given window being destroyed,
<span class="symbol">DestroyNotify</span>
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 
<span class="symbol">Expose</span>
events on other windows that were obscured by the window being destroyed.
</p><p>

<a class="xref" href="#XDestroyWindow"><code class="function">XDestroyWindow</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p><p>


To destroy all subwindows of a specified window, use 
<a class="xref" href="#XDestroySubwindows"><code class="function">XDestroySubwindows</code></a>.
</p><a id="idp44642484" class="indexterm"></a><div class="funcsynopsis"><a id="XDestroySubwindows"></a><p><code class="funcdef"><strong class="fsfunc">XDestroySubwindows</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDestroySubwindows"><code class="function">XDestroySubwindows</code></a>
function destroys all inferior windows of the specified window, 
in bottom-to-top stacking order.
It causes the X server to generate a
<span class="symbol">DestroyNotify</span>
event for each window.
If any mapped
subwindows were actually destroyed,
<a class="xref" href="#XDestroySubwindows"><code class="function">XDestroySubwindows</code></a>
causes the X server to generate 
<span class="symbol">Expose</span>
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.  
</p><p>

<a class="xref" href="#XDestroySubwindows"><code class="function">XDestroySubwindows</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Mapping_Windows"></a>Mapping Windows</h2></div></div></div><p>

A window is considered mapped if an 
<a class="xref" href="#XMapWindow"><code class="function">XMapWindow</code></a>
call has been made on it.
It may not be visible on the screen for one of the following reasons:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
It is obscured by another opaque window.
    </p></li><li class="listitem"><p>
One of its ancestors is not mapped.
    </p></li><li class="listitem"><p>
It is entirely clipped by an ancestor.
    </p></li></ul></div><p>

<span class="symbol">Expose</span>
events are generated for the window when part or all of
it becomes visible on the screen. 
A client receives the
<span class="symbol">Expose</span>
events only if it has asked for them.
Windows retain their position in the stacking order when they are unmapped.
</p><p>

A window manager may want to control the placement of subwindows.
If 
<span class="symbol">SubstructureRedirectMask</span>
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 
<span class="symbol">MapRequest</span>
event.
However, if the override-redirect flag on the child had been set to
<span class="symbol">True</span>
(usually only on pop-up menus),
the map request is performed.
</p><p>

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 <a class="link" href="#Override_Redirect_Flag" title="Override Redirect Flag">sections 3.2.8</a>
and <a class="link" href="#Window_State_Change_Events" title="Window State Change Events">10.10</a>.
Only a single client at a time can select for 
<span class="symbol">SubstructureRedirectMask</span>.
</p><p>

Similarly, a single client can select for 
<span class="symbol">ResizeRedirectMask</span>
on a parent window.
Then, any attempt to resize the window by another client is suppressed, and
the client receives a 
<span class="symbol">ResizeRequest</span>
event.
</p><p>


To map a given window, use 
<a class="xref" href="#XMapWindow"><code class="function">XMapWindow</code></a>.
</p><a id="idp44658988" class="indexterm"></a><div class="funcsynopsis"><a id="XMapWindow"></a><p><code class="funcdef"><strong class="fsfunc">XMapWindow</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XMapWindow"><code class="function">XMapWindow</code></a>
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.
</p><p>

If the override-redirect of the window is
<span class="symbol">False</span>
and if some other client has selected
<span class="symbol">SubstructureRedirectMask</span>
on the parent window, then the X server generates a
<span class="symbol">MapRequest</span>
event, and the
<a class="xref" href="#XMapWindow"><code class="function">XMapWindow</code></a>
function does not map the window.
Otherwise, the window is mapped, and the X server generates a
<span class="symbol">MapNotify</span>
event.
</p><p>

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 
<span class="symbol">Expose</span>
events.
If backing-store was maintained while the window was unmapped, no 
<span class="symbol">Expose</span>
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.
</p><p>

<a id="idp44668348" class="indexterm"></a>
If the window is an
<span class="symbol">InputOutput</span>
window,
<a class="xref" href="#XMapWindow"><code class="function">XMapWindow</code></a>
generates 
<span class="symbol">Expose</span>
events on each 
<span class="symbol">InputOutput</span>
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 
<span class="symbol">Expose</span>
events and then map the window,
so the client processes input events as usual.
The event list will include 
<span class="symbol">Expose</span>
for each
window that has appeared on the screen. 
The client's normal response to
an 
<span class="symbol">Expose</span>
event should be to repaint the window.
This method usually leads to simpler programs and to proper interaction
with window managers.
</p><p>

<a class="xref" href="#XMapWindow"><code class="function">XMapWindow</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p><p>


To map and raise a window, use
<a class="xref" href="#XMapRaised"><code class="function">XMapRaised</code></a>.
</p><a id="idp44672596" class="indexterm"></a><div class="funcsynopsis"><a id="XMapRaised"></a><p><code class="funcdef"><strong class="fsfunc">XMapRaised</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XMapRaised"><code class="function">XMapRaised</code></a>
function
essentially is similar to
<a class="xref" href="#XMapWindow"><code class="function">XMapWindow</code></a>
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 
<a class="xref" href="#XMapWindow"><code class="function">XMapWindow</code></a>.
</p><p>

<a class="xref" href="#XMapRaised"><code class="function">XMapRaised</code></a>
can generate multiple
<span class="errorname">BadWindow</span>
errors.
</p><p>


To map all subwindows for a specified window, use 
<a class="xref" href="#XMapSubwindows"><code class="function">XMapSubwindows</code></a>.
</p><a id="idp44680948" class="indexterm"></a><div class="funcsynopsis"><a id="XMapSubwindows"></a><p><code class="funcdef"><strong class="fsfunc">XMapSubwindows</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XMapSubwindows"><code class="function">XMapSubwindows</code></a>
<a id="idp44686500" class="indexterm"></a>
function maps all subwindows for a specified window in top-to-bottom stacking 
order.
The X server generates
<span class="symbol">Expose</span>
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.
</p><p>

<a class="xref" href="#XMapSubwindows"><code class="function">XMapSubwindows</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Unmapping_Windows"></a>Unmapping Windows</h2></div></div></div><p>

Xlib provides functions that you can use to unmap a window or all subwindows.
</p><p>


To unmap a window, use 
<a class="xref" href="#XUnmapWindow"><code class="function">XUnmapWindow</code></a>.
</p><a id="idp44690484" class="indexterm"></a><div class="funcsynopsis"><a id="XUnmapWindow"></a><p><code class="funcdef"><strong class="fsfunc">XUnmapWindow</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XUnmapWindow"><code class="function">XUnmapWindow</code></a>
function unmaps the specified window and causes the X server to generate an
<span class="symbol">UnmapNotify</span>
<a id="idp44696316" class="indexterm"></a>
<a id="idp44696692" class="indexterm"></a>
event.
If the specified window is already unmapped, 
<a class="xref" href="#XUnmapWindow"><code class="function">XUnmapWindow</code></a>
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 
<span class="symbol">Expose</span>
events on windows that were formerly obscured by it.
</p><p>

<a class="xref" href="#XUnmapWindow"><code class="function">XUnmapWindow</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p><p>


To unmap all subwindows for a specified window, use 
<a class="xref" href="#XUnmapSubwindows"><code class="function">XUnmapSubwindows</code></a>.
</p><a id="idp44699892" class="indexterm"></a><div class="funcsynopsis"><a id="XUnmapSubwindows"></a><p><code class="funcdef"><strong class="fsfunc">XUnmapSubwindows</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XUnmapSubwindows"><code class="function">XUnmapSubwindows</code></a>
function unmaps all subwindows for the specified window in bottom-to-top
stacking order.
It causes the X server to generate an
<span class="symbol">UnmapNotify</span>
event on each subwindow and 
<span class="symbol">Expose</span>
events on formerly obscured windows.
<a id="idp44706052" class="indexterm"></a>
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.
</p><p>

<a class="xref" href="#XUnmapSubwindows"><code class="function">XUnmapSubwindows</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Configuring_Windows"></a>Configuring Windows</h2></div></div></div><p>

</p><p>

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
<span class="structname">XWindowChanges</span>
structure and OR in the corresponding value mask in subsequent calls to
<a class="xref" href="#XConfigureWindow"><code class="function">XConfigureWindow</code></a>.
The symbols for the value mask bits and the
<span class="structname">XWindowChanges</span>
structure are:

</p><p>


</p><pre class="literallayout">
/* Configure window value mask bits */
#define      CWX              (1&lt;&lt;0)
#define      CWY              (1&lt;&lt;1)
#define      CWWidth          (1&lt;&lt;2)
#define      CWHeight         (1&lt;&lt;3)
#define      CWBorderWidth    (1&lt;&lt;4)
#define      CWSibling        (1&lt;&lt;5)
#define      CWStackMode      (1&lt;&lt;6)
</pre><p>

<a id="idp44711340" class="indexterm"></a>
</p><pre class="literallayout">
/* Values */

typedef struct {
     int x, y;
     int width, height;
     int border_width;
     Window sibling;
     int stack_mode;
} XWindowChanges;
</pre><p>
</p><p>


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
<span class="errorname">BadValue</span>
error results.
Attempts to configure a root window have no effect.
</p><p>

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
<span class="symbol">InputOnly</span>
window nonzero, a
<span class="errorname">BadMatch</span>
error results. 
</p><p>

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
<span class="symbol">Above</span>,
<span class="symbol">Below</span>,
<span class="symbol">TopIf</span>,
<span class="symbol">BottomIf</span>,
or 
<span class="symbol">Opposite</span>.
</p><p>

If the override-redirect flag of the window is
<span class="symbol">False</span>
and if some other client has selected
<span class="symbol">SubstructureRedirectMask</span>
on the parent, the X server generates a
<span class="symbol">ConfigureRequest</span>
event, and no further processing is performed.
Otherwise, 
if some other client has selected 
<span class="symbol">ResizeRedirectMask</span>
on the window and the inside
width or height of the window is being changed,
a 
<span class="symbol">ResizeRequest</span>
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
<span class="symbol">ResizeRedirectMask</span>
and that
<span class="symbol">SubstructureRedirectMask</span>
on the parent has precedence over
<span class="symbol">ResizeRedirectMask</span>
on the window.
</p><p>

When the geometry of the window is changed as specified, 
the window is restacked among siblings, and a
<span class="symbol">ConfigureNotify</span>
event is generated if the state of the window actually changes.
<span class="symbol">GravityNotify</span>
events are generated after 
<span class="symbol">ConfigureNotify</span>
events.
If the inside width or height of the window has actually changed, 
children of the window are affected as specified.
</p><p>

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 <a class="link" href="#Gravity_Attributes" title="Gravity Attributes">section 3.2.3</a>).
</p><p>

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.
</p><p>

The restack check (specifically, the computation for 
<span class="symbol">BottomIf</span>,
<span class="symbol">TopIf</span>,
and 
<span class="symbol">Opposite</span>)
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
<span class="errorname">BadMatch</span>
error results.
</p><p>

If a sibling and a stack_mode are specified, 
the window is restacked as follows:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left"><span class="symbol">Above</span></td><td align="left">The window is placed just above the sibling.</td></tr><tr><td align="left"><span class="symbol">Below</span></td><td align="left">The window is placed just below the sibling.</td></tr><tr><td align="left"><span class="symbol">TopIf</span></td><td align="left">If the sibling occludes the window, the window is placed at the top of the stack.</td></tr><tr><td align="left"><span class="symbol">BottomIf</span></td><td align="left">If the window occludes the sibling, the window is placed at the bottom of the stack.</td></tr><tr><td align="left"><span class="symbol">Opposite</span></td><td align="left">
If the sibling occludes the window, the window is placed at the top of the stack.
If the window occludes the sibling,
the window is placed at the bottom of the stack.
      </td></tr></tbody></table></div><p>

If a stack_mode is specified but no sibling is specified,
the window is restacked as follows:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left"><span class="symbol">Above</span></td><td align="left">The window is placed at the top of the stack.</td></tr><tr><td align="left"><span class="symbol">Below</span></td><td align="left">The window is placed at the bottom of the stack.</td></tr><tr><td align="left"><span class="symbol">TopIf</span></td><td align="left">
If any sibling occludes the window, the window is placed at
the top of the stack.
      </td></tr><tr><td align="left"><span class="symbol">BottomIf</span></td><td align="left">
If the window occludes any sibling, the window is placed at
the bottom of the stack.
      </td></tr><tr><td align="left"><span class="symbol">Opposite</span></td><td align="left">
If any sibling occludes the window, the window
is placed at the top of the stack.
If the window occludes any sibling,
the window is placed at the bottom of the stack.
      </td></tr></tbody></table></div><p>

Attempts to configure a root window have no effect.
</p><p>


To configure a window's size, location, stacking, or border, use
<a class="xref" href="#XConfigureWindow"><code class="function">XConfigureWindow</code></a>.
</p><a id="idp44735940" class="indexterm"></a><div class="funcsynopsis"><a id="XConfigureWindow"></a><p><code class="funcdef"><strong class="fsfunc">XConfigureWindow</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, unsignedint<var class="pdparam"> value_mask</var>, XWindowChanges<var class="pdparam"> *values</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window to be reconfigured.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>value_mask</em></span>
    </span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>values</em></span>
    </span></p></td><td><p>
Specifies the 
<span class="structname">XWindowChanges</span>
structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XConfigureWindow"><code class="function">XConfigureWindow</code></a>
function uses the values specified in the
<span class="structname">XWindowChanges</span>
structure to reconfigure a window's size, position, border, and stacking order.
Values not specified are taken from the existing geometry of the window.
</p><p>

If a sibling is specified without a stack_mode or if the window
is not actually a sibling,
a
<span class="errorname">BadMatch</span>
error results. 
Note that the computations for
<span class="symbol">BottomIf</span>,
<span class="symbol">TopIf</span>,
and
<span class="symbol">Opposite</span>
are performed with respect to the window's final geometry (as controlled by the
other arguments passed to
<a class="xref" href="#XConfigureWindow"><code class="function">XConfigureWindow</code></a>),
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).
</p><p>

<a class="xref" href="#XConfigureWindow"><code class="function">XConfigureWindow</code></a>
can generate
<span class="errorname">BadMatch</span>,
<span class="errorname">BadValue</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To move a window without changing its size, use 
<a class="xref" href="#XMoveWindow"><code class="function">XMoveWindow</code></a>.
</p><a id="idp44749516" class="indexterm"></a><div class="funcsynopsis"><a id="XMoveWindow"></a><p><code class="funcdef"><strong class="fsfunc">XMoveWindow</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, intx,<var class="pdparam"> y</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window to be moved.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XMoveWindow"><code class="function">XMoveWindow</code></a>
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
<span class="symbol">Expose</span>
events.
Moving a mapped window generates
<span class="symbol">Expose</span>
events on any formerly obscured windows. 
</p><p>

If the override-redirect flag of the window is 
<span class="symbol">False</span>
and some
other client has selected 
<span class="symbol">SubstructureRedirectMask</span>
on the parent, the X server generates a
<span class="symbol">ConfigureRequest</span>
event, and no further processing is
performed.  
Otherwise, the window is moved.
</p><p>

<a class="xref" href="#XMoveWindow"><code class="function">XMoveWindow</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p><p>


To change a window's size without changing the upper-left coordinate, use 
<a class="xref" href="#XResizeWindow"><code class="function">XResizeWindow</code></a>.
</p><a id="idp44761996" class="indexterm"></a><div class="funcsynopsis"><a id="XResizeWindow"></a><p><code class="funcdef"><strong class="fsfunc">XResizeWindow</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, unsignedintwidth,<var class="pdparam"> height</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height, which are the interior dimensions of the
window after the call completes.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XResizeWindow"><code class="function">XResizeWindow</code></a>
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
<span class="symbol">Expose</span>
events.
If a mapped window is made smaller, 
changing its size generates
<span class="symbol">Expose</span>
events on windows that the mapped window formerly obscured.
</p><p>

If the override-redirect flag of the window is 
<span class="symbol">False</span>
and some
other client has selected 
<span class="symbol">SubstructureRedirectMask</span>
on the parent, the X server generates a
<span class="symbol">ConfigureRequest</span>
event, and no further processing is performed.  
If either width or height is zero,
a
<span class="errorname">BadValue</span>
error results.
</p><p>

<a class="xref" href="#XResizeWindow"><code class="function">XResizeWindow</code></a>
can generate
<span class="errorname">BadValue</span>
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To change the size and location of a window, use 
<a class="xref" href="#XMoveResizeWindow"><code class="function">XMoveResizeWindow</code></a>.
</p><a id="idp44774732" class="indexterm"></a><div class="funcsynopsis"><a id="XMoveResizeWindow"></a><p><code class="funcdef"><strong class="fsfunc">XMoveResizeWindow</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, intx,<var class="pdparam"> y</var>, unsignedintwidth,<var class="pdparam"> height</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window to be reconfigured.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, which define the new position of the
window relative to its parent.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height, which define the interior size of the window.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XMoveResizeWindow"><code class="function">XMoveResizeWindow</code></a>
function changes the size and location of the specified window 
without raising it.
Moving and resizing a mapped window may generate an
<span class="symbol">Expose</span>
event on the window.
Depending on the new size and location parameters,
moving and resizing a window may generate 
<span class="symbol">Expose</span>
events on windows that the window formerly obscured. 
</p><p>

If the override-redirect flag of the window is 
<span class="symbol">False</span>
and some
other client has selected 
<span class="symbol">SubstructureRedirectMask</span>
on the parent, the X server generates a
<span class="symbol">ConfigureRequest</span>
event, and no further processing is performed.  
Otherwise, the window size and location are changed.
</p><p>

<a class="xref" href="#XMoveResizeWindow"><code class="function">XMoveResizeWindow</code></a>
can generate
<span class="errorname">BadValue</span>
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To change the border width of a given window, use
<a class="xref" href="#XSetWindowBorderWidth"><code class="function">XSetWindowBorderWidth</code></a>.
</p><a id="idp44790148" class="indexterm"></a><div class="funcsynopsis"><a id="XSetWindowBorderWidth"></a><p><code class="funcdef"><strong class="fsfunc">XSetWindowBorderWidth</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, unsignedint<var class="pdparam"> width</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>
Specifies the width of the window border.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetWindowBorderWidth"><code class="function">XSetWindowBorderWidth</code></a>
function sets the specified window's border width to the specified width.
</p><p>

<a class="xref" href="#XSetWindowBorderWidth"><code class="function">XSetWindowBorderWidth</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Changing_Window_Stacking_Order"></a>Changing Window Stacking Order</h2></div></div></div><p>

</p><p>

Xlib provides functions that you can use to raise, lower, circulate,
or restack windows.
</p><p>


To raise a window so that no sibling window obscures it, use 
<a class="xref" href="#XRaiseWindow"><code class="function">XRaiseWindow</code></a>.
</p><a id="idp44801020" class="indexterm"></a><div class="funcsynopsis"><a id="XRaiseWindow"></a><p><code class="funcdef"><strong class="fsfunc">XRaiseWindow</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XRaiseWindow"><code class="function">XRaiseWindow</code></a>
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 
<span class="symbol">Expose</span>
events for the window and any mapped subwindows that were formerly obscured.  
</p><p>

If the override-redirect attribute of the window is 
<span class="symbol">False</span>
and some
other client has selected 
<span class="symbol">SubstructureRedirectMask</span>
on the parent, the X server generates a
<span class="symbol">ConfigureRequest</span>
event, and no processing is performed.
Otherwise, the window is raised.
</p><p>

<a class="xref" href="#XRaiseWindow"><code class="function">XRaiseWindow</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p><p>


To lower a window so that it does not obscure any sibling windows, use 
<a class="xref" href="#XLowerWindow"><code class="function">XLowerWindow</code></a>.
</p><a id="idp44810188" class="indexterm"></a><div class="funcsynopsis"><a id="XLowerWindow"></a><p><code class="funcdef"><strong class="fsfunc">XLowerWindow</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XLowerWindow"><code class="function">XLowerWindow</code></a>
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 
<span class="symbol">Expose</span>
events on any windows it formerly obscured.
</p><p>

If the override-redirect attribute of the window is 
<span class="symbol">False</span>
and some
other client has selected 
<span class="symbol">SubstructureRedirectMask</span>
on the parent, the X server generates a
<span class="symbol">ConfigureRequest</span>
event, and no processing is performed.  
Otherwise, the window is lowered to the bottom of the
stack.
</p><p>

<a class="xref" href="#XLowerWindow"><code class="function">XLowerWindow</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p><p>


To circulate a subwindow up or down, use
<a class="xref" href="#XCirculateSubwindows"><code class="function">XCirculateSubwindows</code></a>.
</p><a id="idp44819340" class="indexterm"></a><div class="funcsynopsis"><a id="XCirculateSubwindows"></a><p><code class="funcdef"><strong class="fsfunc">XCirculateSubwindows</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, int<var class="pdparam"> direction</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>direction</em></span>
    </span></p></td><td><p>
Specifies the direction (up or down) that you want to circulate
the window. 
You can pass 
<span class="symbol">RaiseLowest</span>
or
<span class="symbol">LowerHighest</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCirculateSubwindows"><code class="function">XCirculateSubwindows</code></a>
function circulates children of the specified window in the specified 
direction.
If you specify
<span class="symbol">RaiseLowest</span>,
<a class="xref" href="#XCirculateSubwindows"><code class="function">XCirculateSubwindows</code></a>
raises the lowest mapped child (if any) that is occluded 
by another child to the top of the stack.
If you specify
<span class="symbol">LowerHighest</span>,
<a class="xref" href="#XCirculateSubwindows"><code class="function">XCirculateSubwindows</code></a>
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 
<span class="symbol">SubstructureRedirectMask</span>
on the window, the X server generates a 
<span class="symbol">CirculateRequest</span>
event, and no further processing is performed.
If a child is actually restacked,
the X server generates a
<span class="symbol">CirculateNotify</span>
event. 
</p><p>

<a class="xref" href="#XCirculateSubwindows"><code class="function">XCirculateSubwindows</code></a>
can generate
<span class="errorname">BadValue</span>
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To raise the lowest mapped child of a window that is partially or completely
occluded by another child, use
<a class="xref" href="#XCirculateSubwindowsUp"><code class="function">XCirculateSubwindowsUp</code></a>.
</p><a id="idp44831308" class="indexterm"></a><div class="funcsynopsis"><a id="XCirculateSubwindowsUp"></a><p><code class="funcdef"><strong class="fsfunc">XCirculateSubwindowsUp</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCirculateSubwindowsUp"><code class="function">XCirculateSubwindowsUp</code></a>
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
<a class="xref" href="#XCirculateSubwindows"><code class="function">XCirculateSubwindows</code></a>
with
<span class="symbol">RaiseLowest</span>
specified.
</p><p>

<a class="xref" href="#XCirculateSubwindowsUp"><code class="function">XCirculateSubwindowsUp</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p><p>


To lower the highest mapped child of a window that partially or 
completely occludes another child, use 
<a class="xref" href="#XCirculateSubwindowsDown"><code class="function">XCirculateSubwindowsDown</code></a>.
</p><a id="idp44839516" class="indexterm"></a><div class="funcsynopsis"><a id="XCirculateSubwindowsDown"></a><p><code class="funcdef"><strong class="fsfunc">XCirculateSubwindowsDown</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCirculateSubwindowsDown"><code class="function">XCirculateSubwindowsDown</code></a>
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
<a class="xref" href="#XCirculateSubwindows"><code class="function">XCirculateSubwindows</code></a>
with
<span class="symbol">LowerHighest</span>
specified.
</p><p>

<a class="xref" href="#XCirculateSubwindowsDown"><code class="function">XCirculateSubwindowsDown</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p><p>


To restack a set of windows from top to bottom, use 
<a class="xref" href="#XRestackWindows"><code class="function">XRestackWindows</code></a>.
</p><a id="idp44847676" class="indexterm"></a><div class="funcsynopsis"><a id="XRestackWindows"></a><p><code class="funcdef"><strong class="fsfunc">XRestackWindows</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> windows[]</var>, int<var class="pdparam"> nwindows</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>windows</em></span>
    </span></p></td><td><p>
Specifies an array containing the windows to be restacked.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nwindows</em></span>
    </span></p></td><td><p>
Specifies the number of windows to be restacked.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XRestackWindows"><code class="function">XRestackWindows</code></a>
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
<span class="errorname">BadMatch</span>
error results.
</p><p>

If the override-redirect attribute of a window is 
<span class="symbol">False</span>
and some
other client has selected 
<span class="symbol">SubstructureRedirectMask</span>
on the parent, the X server generates 
<span class="symbol">ConfigureRequest</span>
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.
</p><p>

<a class="xref" href="#XRestackWindows"><code class="function">XRestackWindows</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Changing_Window_Attributes"></a>Changing Window Attributes</h2></div></div></div><p>

</p><p>

Xlib provides functions that you can use to set window attributes.
<a class="xref" href="#XChangeWindowAttributes"><code class="function">XChangeWindowAttributes</code></a>
is the more general function that allows you to set one or more window
attributes provided by the
<span class="structname">XSetWindowAttributes</span>
structure.
The other functions described in this section allow you to set one specific
window attribute, such as a window's background.
</p><p>


To change one or more attributes for a given window, use
<a class="xref" href="#XChangeWindowAttributes"><code class="function">XChangeWindowAttributes</code></a>.
</p><a id="idp44860988" class="indexterm"></a><div class="funcsynopsis"><a id="XChangeWindowAttributes"></a><p><code class="funcdef"><strong class="fsfunc">XChangeWindowAttributes</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, unsignedlong<var class="pdparam"> valuemask</var>, XSetWindowAttributes<var class="pdparam"> *attributes</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>valuemask</em></span>
    </span></p></td><td><p>
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
<a class="xref" href="#XCreateWindow"><code class="function">XCreateWindow</code></a>.
      </p></td></tr><tr><td><p><span class="term">
      
    </span></p></td><td><p>
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>attributes</em></span>
    </span></p></td><td><p>
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 <a class="link" href="#Window_Attributes" title="Window Attributes">section 3.2</a>).
    </p></td></tr></tbody></table></div><p>


Depending on the valuemask,
the
<a class="xref" href="#XChangeWindowAttributes"><code class="function">XChangeWindowAttributes</code></a>
function uses the window attributes in the
<span class="structname">XSetWindowAttributes</span>
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 
<a class="xref" href="#XClearWindow"><code class="function">XClearWindow</code></a>.
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 
<span class="symbol">None</span>
or 
<span class="symbol">ParentRelative</span>
restores the default background pixmap.
Changing the border of a root window to
<span class="symbol">CopyFromParent</span>
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 
<span class="symbol">WhenMapped</span>
or
<span class="symbol">Always</span>,
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 
<span class="symbol">ColormapNotify</span>
event.
Changing the colormap of a visible window may have no
immediate effect on the screen because the map may not be installed
(see
<a class="xref" href="#XInstallColormap"><code class="function">XInstallColormap</code></a>).
Changing the cursor of a root window to 
<span class="symbol">None</span>
restores the default
cursor.
Whenever possible, you are encouraged to share colormaps.
</p><p>

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 
<span class="symbol">SubstructureRedirectMask</span>,
<span class="symbol">ResizeRedirectMask</span>,
and
<span class="symbol">ButtonPressMask</span>.
If a client attempts to select any of these event masks 
and some other client has already selected one, 
a
<span class="errorname">BadAccess</span>
error results.
There is only one do-not-propagate-mask for a window, 
not one per client.
</p><p>

<a class="xref" href="#XChangeWindowAttributes"><code class="function">XChangeWindowAttributes</code></a>
can generate
<span class="errorname">BadAccess</span>,
<span class="errorname">BadColor</span>,
<span class="errorname">BadCursor</span>,
<span class="errorname">BadMatch</span>,
<span class="errorname">BadPixmap</span>,
<span class="errorname">BadValue</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To set the background of a window to a given pixel, use 
<a class="xref" href="#XSetWindowBackground"><code class="function">XSetWindowBackground</code></a>.
</p><a id="idp44879620" class="indexterm"></a><div class="funcsynopsis"><a id="XSetWindowBackground"></a><p><code class="funcdef"><strong class="fsfunc">XSetWindowBackground</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, unsignedlong<var class="pdparam"> background_pixel</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>background_pixel</em></span>
    </span></p></td><td><p>
Specifies the pixel that is to be used for the background.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetWindowBackground"><code class="function">XSetWindowBackground</code></a>
function sets the background of the window to the specified pixel value.
Changing the background does not cause the window contents to be changed.
<a class="xref" href="#XSetWindowBackground"><code class="function">XSetWindowBackground</code></a>
uses a pixmap of undefined size filled with the pixel value you passed.
If you try to change the background of an 
<span class="symbol">InputOnly</span>
window, a
<span class="errorname">BadMatch</span>
error results.
</p><p>

<a class="xref" href="#XSetWindowBackground"><code class="function">XSetWindowBackground</code></a>
can generate
<span class="errorname">BadMatch</span>
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


</p><p>

To set the background of a window to a given pixmap, use 
<a class="xref" href="#XSetWindowBackgroundPixmap"><code class="function">XSetWindowBackgroundPixmap</code></a>.
</p><a id="idp44890180" class="indexterm"></a><a id="idp44890684" class="indexterm"></a><div class="funcsynopsis"><a id="XSetWindowBackgroundPixmap"></a><p><code class="funcdef"><strong class="fsfunc">XSetWindowBackgroundPixmap</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, Pixmap<var class="pdparam"> background_pixmap</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>background_pixmap</em></span>
    </span></p></td><td><p>
Specifies the background pixmap,
<span class="symbol">ParentRelative</span>,
or
<span class="symbol">None</span>.
    </p></td></tr></tbody></table></div><p>


<a id="idp44897852" class="indexterm"></a>
<a id="idp44898356" class="indexterm"></a>
The
<a class="xref" href="#XSetWindowBackgroundPixmap"><code class="function">XSetWindowBackgroundPixmap</code></a>
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 
<span class="symbol">ParentRelative</span>
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 
<span class="symbol">InputOnly</span>
window, a
<span class="errorname">BadMatch</span>
error results.
If the background is set to
<span class="symbol">None</span>,
the window has no defined background.
</p><p>

<a class="xref" href="#XSetWindowBackgroundPixmap"><code class="function">XSetWindowBackgroundPixmap</code></a>
can generate
<span class="errorname">BadMatch</span>,
<span class="errorname">BadPixmap</span>,
and 
<span class="errorname">BadWindow</span>
errors.

<a class="xref" href="#XSetWindowBackground"><code class="function">XSetWindowBackground</code></a>
and
<a class="xref" href="#XSetWindowBackgroundPixmap"><code class="function">XSetWindowBackgroundPixmap</code></a>
do not change the current contents of the window.

</p><p>


To change and repaint a window's border to a given pixel, use 
<a class="xref" href="#XSetWindowBorder"><code class="function">XSetWindowBorder</code></a>.
</p><a id="idp44903740" class="indexterm"></a><div class="funcsynopsis"><a id="XSetWindowBorder"></a><p><code class="funcdef"><strong class="fsfunc">XSetWindowBorder</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, unsignedlong<var class="pdparam"> border_pixel</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>border_pixel</em></span>
    </span></p></td><td><p>
Specifies the entry in the colormap. 
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetWindowBorder"><code class="function">XSetWindowBorder</code></a>
function sets the border of the window to the pixel value you specify.
If you attempt to perform this on an
<span class="symbol">InputOnly</span>
window, a
<span class="errorname">BadMatch</span>
error results.
</p><p>

<a class="xref" href="#XSetWindowBorder"><code class="function">XSetWindowBorder</code></a>
can generate
<span class="errorname">BadMatch</span>
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To change and repaint the border tile of a given window, use 
<a class="xref" href="#XSetWindowBorderPixmap"><code class="function">XSetWindowBorderPixmap</code></a>.
</p><a id="idp44913428" class="indexterm"></a><div class="funcsynopsis"><a id="XSetWindowBorderPixmap"></a><p><code class="funcdef"><strong class="fsfunc">XSetWindowBorderPixmap</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, Pixmap<var class="pdparam"> border_pixmap</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>border_pixmap</em></span>
    </span></p></td><td><p>
Specifies the border pixmap or
<span class="symbol">CopyFromParent</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetWindowBorderPixmap"><code class="function">XSetWindowBorderPixmap</code></a>
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
<span class="symbol">CopyFromParent</span>,
a copy of the parent window's border pixmap is used.
If you attempt to perform this on an
<span class="symbol">InputOnly</span>
window, a
<span class="errorname">BadMatch</span>
error results.
<a id="idp44921652" class="indexterm"></a>
<a id="idp44922156" class="indexterm"></a>
</p><p>

<a class="xref" href="#XSetWindowBorderPixmap"><code class="function">XSetWindowBorderPixmap</code></a>
can generate
<span class="errorname">BadMatch</span>,
<span class="errorname">BadPixmap</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To set the colormap of a given window, use
<a class="xref" href="#XSetWindowColormap"><code class="function">XSetWindowColormap</code></a>.
</p><a id="idp44924860" class="indexterm"></a><div class="funcsynopsis"><a id="XSetWindowColormap"></a><p><code class="funcdef"><strong class="fsfunc">XSetWindowColormap</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, Colormap<var class="pdparam"> colormap</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetWindowColormap"><code class="function">XSetWindowColormap</code></a>
function sets the specified colormap of the specified window.
The colormap must have the same visual type as the window,
or a
<span class="errorname">BadMatch</span>
error results.
</p><p>

<a class="xref" href="#XSetWindowColormap"><code class="function">XSetWindowColormap</code></a>
can generate
<span class="errorname">BadColor</span>,
<span class="errorname">BadMatch</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To define which cursor will be used in a window, use
<a class="xref" href="#XDefineCursor"><code class="function">XDefineCursor</code></a>.
</p><a id="idp44934548" class="indexterm"></a><a id="idp44935052" class="indexterm"></a><div class="funcsynopsis"><a id="XDefineCursor"></a><p><code class="funcdef"><strong class="fsfunc">XDefineCursor</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, Cursor<var class="pdparam"> cursor</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>cursor</em></span>
    </span></p></td><td><p>
Specifies the cursor that is to be displayed or
<span class="symbol">None</span>.
    </p></td></tr></tbody></table></div><p>


If a cursor is set, it will be used when the pointer is in the window.
If the cursor is
<span class="symbol">None</span>,
it is equivalent to
<a class="xref" href="#XUndefineCursor"><code class="function">XUndefineCursor</code></a>.
</p><p>

<a class="xref" href="#XDefineCursor"><code class="function">XDefineCursor</code></a>
can generate
<span class="errorname">BadCursor</span>
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To undefine the cursor in a given window, use
<a class="xref" href="#XUndefineCursor"><code class="function">XUndefineCursor</code></a>.
</p><a id="idp44944708" class="indexterm"></a><a id="idp44945212" class="indexterm"></a><div class="funcsynopsis"><a id="XUndefineCursor"></a><p><code class="funcdef"><strong class="fsfunc">XUndefineCursor</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XUndefineCursor"><code class="function">XUndefineCursor</code></a>
function undoes the effect of a previous
<a class="xref" href="#XDefineCursor"><code class="function">XDefineCursor</code></a>
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.
</p><p>

<a class="xref" href="#XUndefineCursor"><code class="function">XUndefineCursor</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.


</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Window_Information_Functions"></a>Chapter 4. Window Information Functions</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Obtaining_Window_Information">Obtaining Window Information</a></span></dt><dt><span class="sect1"><a href="#Translating_Screen_Coordinates">Translating Screen Coordinates</a></span></dt><dt><span class="sect1"><a href="#Properties_and_Atoms">Properties and Atoms</a></span></dt><dt><span class="sect1"><a href="#Obtaining_and_Changing_Window_Properties">Obtaining and Changing Window Properties</a></span></dt><dt><span class="sect1"><a href="#Selections">Selections</a></span></dt></dl></div><p>
After you connect the display to the X server and create a window, you can use the Xlib window
information functions to:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Obtain information about a window</p></li><li class="listitem"><p>Translate screen coordinates</p></li><li class="listitem"><p>Manipulate property lists</p></li><li class="listitem"><p>Obtain and change window properties</p></li><li class="listitem"><p>Manipulate selections</p></li></ul></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Obtaining_Window_Information"></a>Obtaining Window Information</h2></div></div></div><p>

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.
</p><p>


To obtain the parent, a list of children, and number of children for 
a given window, use 
<a class="xref" href="#XQueryTree"><code class="function">XQueryTree</code></a>.
</p><a id="idp42684300" class="indexterm"></a><a id="idp40502284" class="indexterm"></a><a id="idp41664652" class="indexterm"></a><div class="funcsynopsis"><a id="XQueryTree"></a><p><code class="funcdef">Status <strong class="fsfunc">XQueryTree</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, Window<var class="pdparam"> *root_return</var>, Window<var class="pdparam"> *parent_return</var>, Window<var class="pdparam"> **children_return</var>, unsignedint<var class="pdparam"> *nchildren_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window whose list of children, root, parent, and number of
children you want to obtain.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>root_return</em></span>
    </span></p></td><td><p>
Returns the root window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>parent_return</em></span>
    </span></p></td><td><p>
Returns the parent window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>children_return</em></span>
    </span></p></td><td><p>
Returns the list of children.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nchildren_return</em></span>
    </span></p></td><td><p>
Returns the number of children.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XQueryTree"><code class="function">XQueryTree</code></a>
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).
<a class="xref" href="#XQueryTree"><code class="function">XQueryTree</code></a>
returns zero if it fails and nonzero if it succeeds.
To free a non-NULL children list when it is no longer needed, use 
<a class="xref" href="#XFree"></a>.
</p><p>

<a class="xref" href="#XQueryTree"><code class="function">XQueryTree</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p><p>


To obtain the current attributes of a given window, use 
<a class="xref" href="#XGetWindowAttributes"><code class="function">XGetWindowAttributes</code></a>.
</p><a id="idp40672940" class="indexterm"></a><div class="funcsynopsis"><a id="XGetWindowAttributes"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetWindowAttributes</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XWindowAttributes<var class="pdparam"> *window_attributes_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window whose current attributes you want to obtain.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>window_attributes_return</em></span>
    </span></p></td><td><p>
Returns the specified window's attributes in the
<span class="structname">XWindowAttributes</span>
structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetWindowAttributes"><code class="function">XGetWindowAttributes</code></a>
function returns the current attributes for the specified window to an
<span class="structname">XWindowAttributes</span>
structure.
</p><p>

<a id="idp44417292" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int x, y;                     /* location of window */
     int width, height;            /* width and height of window */
     int border_width;             /* border width of window */
     int depth;                    /* depth of window */
     Visual *visual;               /* the associated visual structure */
     Window root;                  /* root of screen containing window */
     int class;                    /* InputOutput, InputOnly*/
     int bit_gravity;              /* one of the bit gravity values */
     int win_gravity;              /* one of the window gravity values */
     int backing_store;            /* NotUseful, WhenMapped, Always */
     unsigned long backing_planes; /* planes to be preserved if possible */
     unsigned long backing_pixel;  /* value to be used when restoring planes */
     Bool save_under;              /* boolean, should bits under be saved? */
     Colormap colormap;            /* color map to be associated with window */
     Bool map_installed;           /* boolean, is color map currently installed*/
     int map_state;                /* IsUnmapped, IsUnviewable, IsViewable */
     long all_event_masks;         /* set of events all people have interest in*/
     long your_event_mask;         /* my event mask */
     long do_not_propagate_mask;   /* set of events that should not propagate */
     Bool override_redirect;       /* boolean value for override-redirect */
     Screen *screen;               /* back pointer to correct screen */
} XWindowAttributes;
</pre><p>
</p><p>


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
<span class="structname">Visual</span>
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
<span class="symbol">InputOutput</span>
or
<span class="symbol">InputOnly</span>.
</p><p>

The bit_gravity member is set to the window's bit gravity
and can be one of the following:
  </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="symbol">ForgetGravity</span></td><td><span class="symbol">EastGravity</span></td></tr><tr><td><span class="symbol">NorthWestGravity</span></td><td><span class="symbol">SouthWestGravity</span></td></tr><tr><td><span class="symbol">NorthGravity</span></td><td><span class="symbol">SouthGravity</span></td></tr><tr><td><span class="symbol">NorthEastGravity</span></td><td><span class="symbol">SouthEastGravity</span></td></tr><tr><td><span class="symbol">WestGravity</span></td><td><span class="symbol">StaticGravity</span></td></tr></table><p>
</p><p>
The win_gravity member is set to the window's window gravity
and can be one of the following:
  </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="symbol">UnmapGravity</span></td><td><span class="symbol">SouthWestGravity</span></td></tr><tr><td><span class="symbol">NorthWestGravity</span></td><td><span class="symbol">SouthGravity</span></td></tr><tr><td><span class="symbol">NorthGravity</span></td><td><span class="symbol">SouthEastGravity</span></td></tr><tr><td><span class="symbol">NorthEastGravity</span></td><td><span class="symbol">StaticGravity</span></td></tr><tr><td><span class="symbol">WestGravity</span></td><td><span class="symbol">CenterGravity</span></td></tr><tr><td><span class="symbol">EastGravity</span></td><td> </td></tr></table><p>
</p><p>

For additional information on gravity,
see <a class="link" href="#Gravity_Attributes" title="Gravity Attributes">section 3.2.3</a>.
</p><p>

The backing_store member is set to indicate how the X server should maintain
the contents of a window 
and can be 
<span class="symbol">WhenMapped</span>,
<span class="symbol">Always</span>,
or
<span class="symbol">NotUseful</span>.
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.
</p><p>

The save_under member is set to 
<span class="symbol">True</span>
or
<span class="symbol">False</span>.
The colormap member is set to the colormap for the specified window and can be
a colormap ID or 
<span class="symbol">None</span>.
The map_installed member is set to indicate whether the colormap is 
currently installed and can be 
<span class="symbol">True</span>
or
<span class="symbol">False</span>.
The map_state member is set to indicate the state of the window and can be
<span class="symbol">IsUnmapped</span>,
<span class="symbol">IsUnviewable</span>,
or
<span class="symbol">IsViewable</span>.
<span class="symbol">IsUnviewable</span>
is used if the window is mapped but some ancestor is unmapped.
</p><p>

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.
</p><p>

The override_redirect member is set to indicate whether this window overrides
structure control facilities and can be 
<span class="symbol">True</span>
or
<span class="symbol">False</span>.
Window manager clients should ignore the window if this member is
<span class="symbol">True</span>.
</p><p>

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.
</p><p>

<a class="xref" href="#XGetWindowAttributes"><code class="function">XGetWindowAttributes</code></a>
can generate
<span class="errorname">BadDrawable</span>
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To obtain the current geometry of a given drawable, use 
<a class="xref" href="#XGetGeometry"><code class="function">XGetGeometry</code></a>.
</p><a id="idp42813700" class="indexterm"></a><div class="funcsynopsis"><a id="XGetGeometry"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetGeometry</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, Window<var class="pdparam"> *root_return</var>, int*x_return,<var class="pdparam"> *y_return</var>, unsignedint*width_return,<var class="pdparam"> *height_return</var>, unsignedint<var class="pdparam"> *border_width_return</var>, unsignedint<var class="pdparam"> *depth_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable, which can be a window or a pixmap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>root_return</em></span>
    </span></p></td><td><p>
Returns the root window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y_return</em></span>
    </span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height_return</em></span>
    </span></p></td><td><p>
Return the drawable's dimensions (width and height).
For a window, 
these dimensions specify the inside size, not including the border.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>border_width_return</em></span>
    </span></p></td><td><p>
Returns the border width in pixels. 
If the drawable is a pixmap, it returns zero.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>depth_return</em></span>
    </span></p></td><td><p>
Returns the depth of the drawable (bits per pixel for the object).
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetGeometry"><code class="function">XGetGeometry</code></a>
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
<span class="symbol">InputOnly</span>.
</p><p>

<a class="xref" href="#XGetGeometry"><code class="function">XGetGeometry</code></a>
can generate a
<span class="errorname">BadDrawable</span>
error.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Translating_Screen_Coordinates"></a>Translating Screen Coordinates</h2></div></div></div><p>

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.
<a class="xref" href="#XTranslateCoordinates"><code class="function">XTranslateCoordinates</code></a>
and
<a class="xref" href="#XQueryPointer"><code class="function">XQueryPointer</code></a>
fulfill these needs (and avoid any race conditions) by
asking the X server to perform these operations.
</p><p>


To translate a coordinate in one window to the coordinate
space of another window, use
<a class="xref" href="#XTranslateCoordinates"><code class="function">XTranslateCoordinates</code></a>.
</p><a id="idp44487028" class="indexterm"></a><div class="funcsynopsis"><a id="XTranslateCoordinates"></a><p><code class="funcdef">Bool <strong class="fsfunc">XTranslateCoordinates</strong>(</code>Display<var class="pdparam"> *display</var>, Windowsrc_w,<var class="pdparam"> dest_w</var>, intsrc_x,<var class="pdparam"> src_y</var>, int*dest_x_return,<var class="pdparam"> *dest_y_return</var>, Window<var class="pdparam"> *child_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>src_w</em></span>
    </span></p></td><td><p>
Specifies the source window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dest_w</em></span>
    </span></p></td><td><p>
Specifies the destination window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>src_x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>src_y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates within the source window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dest_x_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dest_y_return</em></span>
    </span></p></td><td><p>
Return the x and y coordinates within the destination window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>child_return</em></span>
    </span></p></td><td><p>
Returns the child if the coordinates are contained in a mapped child of the
destination window.
    </p></td></tr></tbody></table></div><p>


If
<a class="xref" href="#XTranslateCoordinates"><code class="function">XTranslateCoordinates</code></a>
returns
<span class="symbol">True</span>,
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
<a class="xref" href="#XTranslateCoordinates"><code class="function">XTranslateCoordinates</code></a>
returns 
<span class="symbol">False</span>,
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
<span class="symbol">None</span>.
</p><p>

<a class="xref" href="#XTranslateCoordinates"><code class="function">XTranslateCoordinates</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p><p>


To obtain the screen coordinates of the pointer
or to determine the pointer coordinates relative to a specified window, use 
<a class="xref" href="#XQueryPointer"><code class="function">XQueryPointer</code></a>.
</p><a id="idp44507084" class="indexterm"></a><div class="funcsynopsis"><a id="XQueryPointer"></a><p><code class="funcdef">Bool <strong class="fsfunc">XQueryPointer</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, Window*root_return,<var class="pdparam"> *child_return</var>, int*root_x_return,<var class="pdparam"> *root_y_return</var>, int*win_x_return,<var class="pdparam"> *win_y_return</var>, unsignedint<var class="pdparam"> *mask_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>root_return</em></span>
    </span></p></td><td><p>
Returns the root window that the pointer is in.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>child_return</em></span>
    </span></p></td><td><p>
Returns the child window that the pointer is located in, if any.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>root_x_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>root_y_return</em></span>
    </span></p></td><td><p>
Return the pointer coordinates relative to the root window's origin.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>win_x_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>win_y_return</em></span>
    </span></p></td><td><p>
Return the pointer coordinates relative to the specified window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>mask_return</em></span>
    </span></p></td><td><p>
Returns the current state of the modifier keys and pointer buttons.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XQueryPointer"><code class="function">XQueryPointer</code></a>
function returns the root window the pointer is logically on and the pointer
coordinates relative to the root window's origin.
If
<a class="xref" href="#XQueryPointer"><code class="function">XQueryPointer</code></a>
returns 
<span class="symbol">False</span>,
the pointer is not on the same screen as the specified window, and
<a class="xref" href="#XQueryPointer"><code class="function">XQueryPointer</code></a>
returns 
<span class="symbol">None</span>
to child_return and zero to win_x_return and win_y_return.
If 
<a class="xref" href="#XQueryPointer"><code class="function">XQueryPointer</code></a>
returns 
<span class="symbol">True</span>,
the pointer coordinates returned to win_x_return and win_y_return
are relative to the origin of the specified window.
In this case, 
<a class="xref" href="#XQueryPointer"><code class="function">XQueryPointer</code></a>
returns the child that contains the pointer, if any,
or else
<span class="symbol">None</span>
to child_return.
</p><p>

<a class="xref" href="#XQueryPointer"><code class="function">XQueryPointer</code></a>
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.
</p><p>

Note that the logical state of a device (as seen through Xlib)
may lag the physical state if device event processing is frozen
(see <a class="link" href="#Pointer_Grabbing" title="Pointer Grabbing">section 12.1</a>).
</p><p>

<a class="xref" href="#XQueryPointer"><code class="function">XQueryPointer</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Properties_and_Atoms"></a>Properties and Atoms</h2></div></div></div><p>

A property is a collection of named, typed data.
The window system has a set of predefined properties
<a id="idp44533092" class="indexterm"></a>
(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.
<a class="xref" href="#XInternAtom"><code class="function">XInternAtom</code></a>
can be used to obtain the atom for property names.
<a id="idp44534756" class="indexterm"></a>
</p><p>

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.

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 <a class="link" href="#extensions" title="Appendix C. Extensions">appendix C</a>.

The type of a property is defined by an atom, which allows for
arbitrary extension in this type scheme.
<a id="idp44536812" class="indexterm"></a>
</p><p>

Certain property names are
predefined in the server for commonly used functions.
The atoms for these properties are defined in 
<code class="filename">&lt;X11/Xatom.h&gt;</code>.
<a id="idp44538244" class="indexterm"></a>
<a id="idp44539140" class="indexterm"></a>
<a id="idp44540052" class="indexterm"></a>
To avoid name clashes with user symbols, the 
<code class="code">#define</code>
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 <a class="link" href="#Inter_Client_Communication_Functions" title="Chapter 14. Inter-Client Communication Functions">chapter 14</a>.
</p><p>

The core protocol imposes no semantics on these property names,
but semantics are specified in other X Consortium standards,
such as the <span class="olink"><em class="citetitle">Inter-Client Communication Conventions Manual</em></span>
and the <span class="olink"><em class="citetitle">X Logical Font Description Conventions</em></span>.
</p><p>

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.
</p><p>

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: 
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Selections
    </p></li><li class="listitem"><p>
Property names
    </p></li><li class="listitem"><p>
Property types
    </p></li><li class="listitem"><p>
Font properties 
    </p></li><li class="listitem"><p>
Type of a 
<span class="symbol">ClientMessage</span>
event (none are built into the X server)
    </p></li></ul></div><p>

</p><p>

The built-in selection property names are:
</p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="property">PRIMARY</span></td><td><span class="property">SECONDARY</span></td></tr></table><p>
</p><p>

The built-in property names are: 
  </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="property">CUT_BUFFER0</span></td><td><span class="property">RESOURCE_MANAGER</span></td></tr><tr><td><span class="property">CUT_BUFFER1</span></td><td><span class="property">WM_CLASS</span></td></tr><tr><td><span class="property">CUT_BUFFER2</span></td><td><span class="property">WM_CLIENT_MACHINE</span></td></tr><tr><td><span class="property">CUT_BUFFER3</span></td><td><span class="property">WM_COLORMAP_WINDOWS</span></td></tr><tr><td><span class="property">CUT_BUFFER4</span></td><td><span class="property">WM_COMMAND</span></td></tr><tr><td><span class="property">CUT_BUFFER5</span></td><td><span class="property">WM_HINTS</span></td></tr><tr><td><span class="property">CUT_BUFFER6</span></td><td><span class="property">WM_ICON_NAME</span></td></tr><tr><td><span class="property">CUT_BUFFER7</span></td><td><span class="property">WM_ICON_SIZE</span></td></tr><tr><td><span class="property">RGB_BEST_MAP</span></td><td><span class="property">WM_NAME</span></td></tr><tr><td><span class="property">RGB_BLUE_MAP</span></td><td><span class="property">WM_NORMAL_HINTS</span></td></tr><tr><td><span class="property">RGB_DEFAULT_MAP</span></td><td><span class="property">WM_PROTOCOLS</span></td></tr><tr><td><span class="property">RGB_GRAY_MAP</span></td><td><span class="property">WM_STATE</span></td></tr><tr><td><span class="property">RGB_GREEN_MAP</span></td><td><span class="property">WM_TRANSIENT_FOR</span></td></tr><tr><td><span class="property">RGB_RED_MAP</span></td><td><span class="property">WM_ZOOM_HINTS</span></td></tr></table><p>
</p><p>
The built-in property types are: 
  </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="property">ARC</span></td><td><span class="property">PIXMAP</span></td></tr><tr><td><span class="property">ATOM</span></td><td><span class="property">POINT</span></td></tr><tr><td><span class="property">BITMAP</span></td><td><span class="property">RGB_COLOR_MAP</span></td></tr><tr><td><span class="property">CARDINAL</span></td><td><span class="property">RECTANGLE</span></td></tr><tr><td><span class="property">COLORMAP</span></td><td><span class="property">STRING</span></td></tr><tr><td><span class="property">CURSOR</span></td><td><span class="property">VISUALID</span></td></tr><tr><td><span class="property">DRAWABLE</span></td><td><span class="property">WINDOW</span></td></tr><tr><td><span class="property">FONT</span></td><td><span class="property">WM_HINTS</span></td></tr><tr><td><span class="property">INTEGER</span></td><td><span class="property">WM_SIZE_HINTS</span></td></tr></table><p>
</p><p>
The built-in font property names are: 
  </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="property">MIN_SPACE</span></td><td><span class="property">STRIKEOUT_DESCENT</span></td></tr><tr><td><span class="property">NORM_SPACE</span></td><td><span class="property">STRIKEOUT_ASCENT</span></td></tr><tr><td><span class="property">MAX_SPACE</span></td><td><span class="property">ITALIC_ANGLE</span></td></tr><tr><td><span class="property">END_SPACE</span></td><td><span class="property">X_HEIGHT</span></td></tr><tr><td><span class="property">SUPERSCRIPT_X</span></td><td><span class="property">QUAD_WIDTH</span></td></tr><tr><td><span class="property">SUPERSCRIPT_Y</span></td><td><span class="property">WEIGHT</span></td></tr><tr><td><span class="property">SUBSCRIPT_X</span></td><td><span class="property">POINT_SIZE</span></td></tr><tr><td><span class="property">SUBSCRIPT_Y</span></td><td><span class="property">RESOLUTION</span></td></tr><tr><td><span class="property">UNDERLINE_POSITION</span></td><td><span class="property">COPYRIGHT</span></td></tr><tr><td><span class="property">UNDERLINE_THICKNESS</span></td><td><span class="property">NOTICE</span></td></tr><tr><td><span class="property">FONT_NAME</span></td><td><span class="property">FAMILY_NAME</span></td></tr><tr><td><span class="property">FULL_NAME</span></td><td><span class="property">CAP_HEIGHT</span></td></tr></table><p>
</p><p>

For further information about font properties,
see <a class="link" href="#Font_Metrics" title="Font Metrics">section 8.5</a>.
</p><p>


To return an atom for a given name, use 
<a class="xref" href="#XInternAtom"><code class="function">XInternAtom</code></a>.
</p><a id="idp44123612" class="indexterm"></a><a id="idp44124180" class="indexterm"></a><div class="funcsynopsis"><a id="XInternAtom"></a><p><code class="funcdef">Atom <strong class="fsfunc">XInternAtom</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> *atom_name</var>, Bool<var class="pdparam"> only_if_exists</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>atom_name</em></span>
    </span></p></td><td><p>
Specifies the name associated with the atom you want returned.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>only_if_exists</em></span>
    </span></p></td><td><p>
Specifies a Boolean value that indicates whether the atom must be created.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XInternAtom"><code class="function">XInternAtom</code></a>
function returns the atom identifier associated with the specified atom_name
string.
If only_if_exists is 
<span class="symbol">False</span>,
the atom is created if it does not exist.
Therefore,
<a class="xref" href="#XInternAtom"><code class="function">XInternAtom</code></a>
can return
<span class="symbol">None</span>.
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.
</p><p>

<a class="xref" href="#XInternAtom"><code class="function">XInternAtom</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To return atoms for an array of names, use 
<a class="xref" href="#XInternAtoms"><code class="function">XInternAtoms</code></a>.
</p><a id="idp44136372" class="indexterm"></a><a id="idp44136940" class="indexterm"></a><div class="funcsynopsis"><a id="XInternAtoms"></a><p><code class="funcdef">Status <strong class="fsfunc">XInternAtoms</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> **names</var>, int<var class="pdparam"> count</var>, Bool<var class="pdparam"> only_if_exists</var>, Atom<var class="pdparam"> *atoms_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>names</em></span>
    </span></p></td><td><p>
Specifies the array of atom names.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count</em></span>
    </span></p></td><td><p>
Specifies the number of atom names in the array.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>only_if_exists</em></span>
    </span></p></td><td><p>
Specifies a Boolean value that indicates whether the atom must be created.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>atoms_return</em></span>
    </span></p></td><td><p>
Returns the atoms.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XInternAtoms"><code class="function">XInternAtoms</code></a>
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
<a class="xref" href="#XInternAtom"><code class="function">XInternAtom</code></a>
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.
</p><p>

This function returns a nonzero status if atoms are returned for
all of the names;
otherwise, it returns zero.
</p><p>

<a class="xref" href="#XInternAtoms"><code class="function">XInternAtoms</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To return a name for a given atom identifier, use 
<a class="xref" href="#XGetAtomName"><code class="function">XGetAtomName</code></a>.
</p><a id="idp44152548" class="indexterm"></a><a id="idp44153124" class="indexterm"></a><div class="funcsynopsis"><a id="XGetAtomName"></a><p><code class="funcdef">char *<strong class="fsfunc">XGetAtomName</strong>(</code>Display<var class="pdparam"> *display</var>, Atom<var class="pdparam"> atom</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>atom</em></span>
    </span></p></td><td><p>
Specifies the atom for the property name you want returned.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetAtomName"><code class="function">XGetAtomName</code></a>
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
<a class="xref" href="#XFree"></a>.
</p><p>

<a class="xref" href="#XGetAtomName"><code class="function">XGetAtomName</code></a>
can generate a
<span class="errorname">BadAtom</span>
error.
</p><p>


To return the names for an array of atom identifiers, use 
<a class="xref" href="#XGetAtomNames"><code class="function">XGetAtomNames</code></a>.
</p><a id="idp44162612" class="indexterm"></a><a id="idp44163188" class="indexterm"></a><div class="funcsynopsis"><a id="XGetAtomNames"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetAtomNames</strong>(</code>Display<var class="pdparam"> *display</var>, Atom<var class="pdparam"> *atoms</var>, int<var class="pdparam"> count</var>, char<var class="pdparam"> **names_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>atoms</em></span>
    </span></p></td><td><p>
Specifies the array of atoms.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count</em></span>
    </span></p></td><td><p>
Specifies the number of atoms in the array.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>names_return</em></span>
    </span></p></td><td><p>
Returns the atom names.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetAtomNames"><code class="function">XGetAtomNames</code></a>
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
<a class="xref" href="#XGetAtomName"><code class="function">XGetAtomName</code></a>
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.
</p><p>

This function returns a nonzero status if names are returned for
all of the atoms;
otherwise, it returns zero.
</p><p>

<a class="xref" href="#XGetAtomNames"><code class="function">XGetAtomNames</code></a>
can generate a
<span class="errorname">BadAtom</span>
error.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Obtaining_and_Changing_Window_Properties"></a>Obtaining and Changing Window Properties</h2></div></div></div><p>

You can attach a property list to every window.
Each property has a name, a type, and a value
(see <a class="link" href="#Properties_and_Atoms" title="Properties and Atoms">section 4.3</a>).
The value is an array of 8-bit, 16-bit, or 32-bit quantities,
whose interpretation is left to the clients.  The type
<span class="type">char</span>
is used to represent 8-bit quantities, the type
<span class="type">short</span>
is used to represent 16-bit quantities, and the type
<span class="type">long</span>
is used to represent 32-bit quantities.
</p><p>

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 <a class="link" href="#Inter_Client_Communication_Functions" title="Chapter 14. Inter-Client Communication Functions">chapter 14</a>).
</p><p>


To obtain the type, format, and value of a property of a given window, use 
<a class="xref" href="#XGetWindowProperty"><code class="function">XGetWindowProperty</code></a>.
<a id="idp44180516" class="indexterm"></a>
</p><a id="idp44181324" class="indexterm"></a><div class="funcsynopsis"><a id="XGetWindowProperty"></a><p><code class="funcdef">int <strong class="fsfunc">XGetWindowProperty</strong>(</code><var class="pdparam"> display</var>, <var class="pdparam"> w</var>, <var class="pdparam"> property</var>, <var class="pdparam"> long_offset</var>, <var class="pdparam"> long_length</var>, <var class="pdparam"> delete</var>, <var class="pdparam"> req_type</var>, <var class="pdparam"> actual_type_return</var>, <var class="pdparam"> actual_format_return</var>, <var class="pdparam"> nitems_return</var>, <var class="pdparam"> bytes_after_return</var>, <var class="pdparam"> prop_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window whose property you want to obtain.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>property</em></span>
    </span></p></td><td><p>
Specifies the property name.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>long_offset</em></span>
    </span></p></td><td><p>
Specifies the offset in the specified property (in 32-bit quantities) 
where the data is to be retrieved.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>long_length</em></span>
    </span></p></td><td><p>
Specifies the length in 32-bit multiples of the data to be retrieved.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>delete</em></span>
    </span></p></td><td><p>
Specifies a Boolean value that determines whether the property is deleted.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>req_type</em></span>
    </span></p></td><td><p>
Specifies the atom identifier associated with the property type or
<span class="symbol">AnyPropertyType</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>actual_type_return</em></span>
    </span></p></td><td><p>
Returns the atom identifier  that defines the actual type of the property.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>actual_format_return</em></span>
    </span></p></td><td><p>
Returns the actual format of the property.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nitems_return</em></span>
    </span></p></td><td><p>
Returns the actual number of 8-bit, 16-bit, or 32-bit items 
stored in the prop_return data.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>bytes_after_return</em></span>
    </span></p></td><td><p>
Returns the number of bytes remaining to be read in the property if 
a partial read was performed.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>prop_return</em></span>
    </span></p></td><td><p>
Returns the data in the specified format.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetWindowProperty"><code class="function">XGetWindowProperty</code></a>
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.
<a class="xref" href="#XGetWindowProperty"><code class="function">XGetWindowProperty</code></a>
sets the return arguments as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If the specified property does not exist for the specified window,
<a class="xref" href="#XGetWindowProperty"><code class="function">XGetWindowProperty</code></a>
returns 
<span class="symbol">None</span>
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.
    </p></li><li class="listitem"><p>
If the specified property exists 
but its type does not match the specified type,
<a class="xref" href="#XGetWindowProperty"><code class="function">XGetWindowProperty</code></a>
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.
    </p></li><li class="listitem"><p>
If the specified property exists and either you assign 
<span class="symbol">AnyPropertyType</span>
to the req_type argument or the specified type matches the actual property type,
<a class="xref" href="#XGetWindowProperty"><code class="function">XGetWindowProperty</code></a>
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:
    </p></li><li class="listitem"><p>

     N = actual length of the stored property in bytes
          (even if the format is 16 or 32)
     I = 4 * long_offset
     T = N - I
     L = MINIMUM(T, 4 * long_length)
     A = N - (I + L)

    </p></li><li class="listitem"><p>
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
<span class="errorname">BadValue</span>
error results. 
The value of bytes_after_return is A, 
giving the number of trailing unread bytes in the stored property.
    </p></li></ul></div><p>

If the returned format is 8, the returned data is represented as a
<span class="type">char</span>
array.
If the returned format is 16, the returned data is represented as a
<span class="type">short</span>
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
<span class="type">long</span>
array and should be cast to that type to obtain the elements.
</p><p>

<a class="xref" href="#XGetWindowProperty"><code class="function">XGetWindowProperty</code></a>
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.
</p><p>

If delete is 
<span class="symbol">True</span>
and bytes_after_return is zero, 
<a class="xref" href="#XGetWindowProperty"><code class="function">XGetWindowProperty</code></a>
deletes the property 
from the window and generates a 
<span class="symbol">PropertyNotify</span>
event on the window.
</p><p>

The function returns
<span class="symbol">Success</span>
if it executes successfully.
To free the resulting data,
use
<a class="xref" href="#XFree"></a>.
</p><p>

<a class="xref" href="#XGetWindowProperty"><code class="function">XGetWindowProperty</code></a>
can generate
<span class="errorname">BadAtom</span>,
<span class="errorname">BadValue</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To obtain a given window's property list, use 
<a class="xref" href="#XListProperties"><code class="function">XListProperties</code></a>.
</p><a id="idp44219820" class="indexterm"></a><a id="idp44220388" class="indexterm"></a><div class="funcsynopsis"><a id="XListProperties"></a><p><code class="funcdef">Atom *<strong class="fsfunc">XListProperties</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, int<var class="pdparam"> *num_prop_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window whose property list you want to obtain.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>num_prop_return</em></span>
    </span></p></td><td><p>
Returns the length of the properties array.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XListProperties"><code class="function">XListProperties</code></a>
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
<a class="xref" href="#XFree"></a>.
</p><p>

<a class="xref" href="#XListProperties"><code class="function">XListProperties</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p><p>


To change a property of a given window, use
<a class="xref" href="#XChangeProperty"><code class="function">XChangeProperty</code></a>.
</p><a id="idp44231588" class="indexterm"></a><a id="idp44232156" class="indexterm"></a><a id="idp44232724" class="indexterm"></a><a id="idp44233292" class="indexterm"></a><a id="idp44233860" class="indexterm"></a><a id="idp44234428" class="indexterm"></a><a id="idp44234996" class="indexterm"></a><div class="funcsynopsis"><a id="XChangeProperty"></a><p><code class="funcdef"><strong class="fsfunc">XChangeProperty</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, Atomproperty,<var class="pdparam"> type</var>, int<var class="pdparam"> format</var>, int<var class="pdparam"> mode</var>, unsignedchar<var class="pdparam"> *data</var>, int<var class="pdparam"> nelements</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window whose property you want to change.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>property</em></span>
    </span></p></td><td><p>
Specifies the property name.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>type</em></span>
    </span></p></td><td><p>
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 
<a class="xref" href="#XGetWindowProperty"><code class="function">XGetWindowProperty</code></a>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>format</em></span>
    </span></p></td><td><p>
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 
<a class="xref" href="#XChangeProperty"><code class="function">XChangeProperty</code></a>.

      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>mode</em></span>
    </span></p></td><td><p>
Specifies the mode of the operation.
You can pass
<span class="symbol">PropModeReplace</span>,
<span class="symbol">PropModePrepend</span>,
or
<span class="symbol">PropModeAppend</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>data</em></span>
    </span></p></td><td><p>
Specifies the property data.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nelements</em></span>
    </span></p></td><td><p>
Specifies the number of elements of the specified data format.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XChangeProperty"><code class="function">XChangeProperty</code></a>
function alters the property for the specified window and
causes the X server to generate a
<span class="symbol">PropertyNotify</span>
event on that window.
<a class="xref" href="#XChangeProperty"><code class="function">XChangeProperty</code></a>
performs the following:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If mode is
<span class="symbol">PropModeReplace</span>,
<a class="xref" href="#XChangeProperty"><code class="function">XChangeProperty</code></a>
discards the previous property value and stores the new data.
    </p></li><li class="listitem"><p>
If mode is
<span class="symbol">PropModePrepend</span>
or
<span class="symbol">PropModeAppend</span>,
<a class="xref" href="#XChangeProperty"><code class="function">XChangeProperty</code></a>
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
<span class="errorname">BadMatch</span>
error results.
If the property is undefined, 
it is treated as defined with the correct type and
format with zero-length data.
    </p></li></ul></div><p>

If the specified format is 8, the property data must be a
<span class="type">char</span>
array.
If the specified format is 16, the property data must be a
<span class="type">short</span>
array.
If the specified format is 32, the property data must be a
<span class="type">long</span>
array.
</p><p>

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 <a class="link" href="#Using_X_Server_Connection_Close_Operations" title="Using X Server Connection Close Operations">section 2.6</a>.
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
<span class="errorname">BadAlloc</span>
error results.)
</p><p>

<a class="xref" href="#XChangeProperty"><code class="function">XChangeProperty</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadAtom</span>,
<span class="errorname">BadMatch</span>,
<span class="errorname">BadValue</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To rotate a window's property list, use
<a class="xref" href="#XRotateWindowProperties"><code class="function">XRotateWindowProperties</code></a>.
</p><a id="idp44970388" class="indexterm"></a><div class="funcsynopsis"><a id="XRotateWindowProperties"></a><p><code class="funcdef"><strong class="fsfunc">XRotateWindowProperties</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, Atom<var class="pdparam"> properties[]</var>, int<var class="pdparam"> num_prop</var>, int<var class="pdparam"> npositions</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>properties</em></span>
    </span></p></td><td><p>
Specifies the array of properties that are to be rotated.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>num_prop</em></span>
    </span></p></td><td><p>
Specifies the length of the properties array.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>npositions</em></span>
    </span></p></td><td><p>
Specifies the rotation amount.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XRotateWindowProperties"><code class="function">XRotateWindowProperties</code></a>
function allows you to rotate properties on a window and causes
the X server to generate
<span class="symbol">PropertyNotify</span>
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
<span class="symbol">PropertyNotify</span>
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 
<span class="errorname">BadMatch</span>
error results.
If a 
<span class="errorname">BadAtom</span>
or 
<span class="errorname">BadMatch</span>
error results,
no properties are changed.
</p><p>

<a class="xref" href="#XRotateWindowProperties"><code class="function">XRotateWindowProperties</code></a>
can generate
<span class="errorname">BadAtom</span>,
<span class="errorname">BadMatch</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To delete a property on a given window, use 
<a class="xref" href="#XDeleteProperty"><code class="function">XDeleteProperty</code></a>.
</p><a id="idp44984708" class="indexterm"></a><a id="idp44985212" class="indexterm"></a><div class="funcsynopsis"><a id="XDeleteProperty"></a><p><code class="funcdef"><strong class="fsfunc">XDeleteProperty</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, Atom<var class="pdparam"> property</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window whose property you want to delete.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>property</em></span>
    </span></p></td><td><p>
Specifies the property name.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDeleteProperty"><code class="function">XDeleteProperty</code></a>
function deletes the specified property only if the
property was defined on the specified window
and causes the X server to generate a
<span class="symbol">PropertyNotify</span>
event on the window unless the property does not exist.
</p><p>

<a class="xref" href="#XDeleteProperty"><code class="function">XDeleteProperty</code></a>
can generate
<span class="errorname">BadAtom</span>
and
<span class="errorname">BadWindow</span>
errors.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Selections"></a>Selections</h2></div></div></div><p>

<a id="idp44995076" class="indexterm"></a>
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.
</p><p>

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.
</p><p>

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.
</p><p>

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.
</p><p>


To set the selection owner, use 
<a class="xref" href="#XSetSelectionOwner"><code class="function">XSetSelectionOwner</code></a>.
</p><a id="idp44999116" class="indexterm"></a><a id="idp44999620" class="indexterm"></a><div class="funcsynopsis"><a id="XSetSelectionOwner"></a><p><code class="funcdef"><strong class="fsfunc">XSetSelectionOwner</strong>(</code>Display<var class="pdparam"> *display</var>, Atom<var class="pdparam"> selection</var>, Window<var class="pdparam"> owner</var>, Time<var class="pdparam"> time</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>selection</em></span>
    </span></p></td><td><p>
Specifies the selection atom.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>owner</em></span>
    </span></p></td><td><p>
Specifies the owner of the specified selection atom.
You can pass a window or
<span class="symbol">None</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>time</em></span>
    </span></p></td><td><p>
Specifies the time.
You can pass either a timestamp or
<span class="symbol">CurrentTime</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetSelectionOwner"><code class="function">XSetSelectionOwner</code></a>
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
<span class="symbol">CurrentTime</span>
replaced by the current server time.
If the owner window is specified as
<span class="symbol">None</span>,
then the owner of the selection becomes 
<span class="symbol">None</span>
(that is, no owner).
Otherwise, the owner of the selection becomes the client executing
the request.
</p><p>

If the new owner (whether a client or
<span class="symbol">None</span>)
is not
the same as the current owner of the selection and the current
owner is not
<span class="symbol">None</span>,
the current owner is sent a 
<span class="symbol">SelectionClear</span>
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
<span class="symbol">None</span>,
but the last-change time is not affected.
The selection atom is uninterpreted by the X server.
<a class="xref" href="#XGetSelectionOwner"><code class="function">XGetSelectionOwner</code></a>
returns the owner window, which is reported in 
<span class="symbol">SelectionRequest</span>
and
<span class="symbol">SelectionClear</span>
events.
Selections are global to the X server.
</p><p>

<a class="xref" href="#XSetSelectionOwner"><code class="function">XSetSelectionOwner</code></a>
can generate
<span class="errorname">BadAtom</span>
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To return the selection owner, use 
<a class="xref" href="#XGetSelectionOwner"><code class="function">XGetSelectionOwner</code></a>.
</p><a id="idp45014412" class="indexterm"></a><a id="idp45014916" class="indexterm"></a><div class="funcsynopsis"><a id="XGetSelectionOwner"></a><p><code class="funcdef">Window <strong class="fsfunc">XGetSelectionOwner</strong>(</code>Display<var class="pdparam"> *display</var>, Atom<var class="pdparam"> selection</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>selection</em></span>
    </span></p></td><td><p>
Specifies the selection atom whose owner you want returned.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetSelectionOwner"><code class="function">XGetSelectionOwner</code></a>
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
<span class="symbol">None</span>.
If
<span class="symbol">None</span>
is returned,
there is no owner for the selection.
</p><p>

<a class="xref" href="#XGetSelectionOwner"><code class="function">XGetSelectionOwner</code></a>
can generate a
<span class="errorname">BadAtom</span>
error.
</p><p>


To request conversion of a selection, use 
<a class="xref" href="#XConvertSelection"><code class="function">XConvertSelection</code></a>.
</p><a id="idp45023036" class="indexterm"></a><a id="idp45023540" class="indexterm"></a><div class="funcsynopsis"><a id="XConvertSelection"></a><p><code class="funcdef"><strong class="fsfunc">XConvertSelection</strong>(</code>Display<var class="pdparam"> *display</var>, Atom<var class="pdparam"> selection</var>, Atom<var class="pdparam"> target</var>, Atom<var class="pdparam"> property</var>, Window<var class="pdparam"> requestor</var>, Time<var class="pdparam"> time</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>selection</em></span>
    </span></p></td><td><p>
Specifies the selection atom.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>target</em></span>
    </span></p></td><td><p>
Specifies the target atom.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>property</em></span>
    </span></p></td><td><p>
Specifies the property name.
You also can pass 
<span class="symbol">None</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>requestor</em></span>
    </span></p></td><td><p>
Specifies the requestor.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>time</em></span>
    </span></p></td><td><p>
Specifies the time.
You can pass either a timestamp or
<span class="symbol">CurrentTime</span>.
    </p></td></tr></tbody></table></div><p>


<a class="xref" href="#XConvertSelection"><code class="function">XConvertSelection</code></a>
requests that the specified selection be converted to the specified target
type:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If the specified selection has an owner, the X server sends a
<span class="symbol">SelectionRequest</span>
event to that owner.
    </p></li><li class="listitem"><p>
If no owner for the specified
selection exists, the X server generates a
<span class="symbol">SelectionNotify</span>
event to the
requestor with property
<span class="symbol">None</span>.
    </p></li></ul></div><p>

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

<a class="xref" href="#XConvertSelection"><code class="function">XConvertSelection</code></a>
can generate
<span class="errorname">BadAtom</span>
and
<span class="errorname">BadWindow</span>
errors.



</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Pixmap_and_Cursor_Functions"></a>Chapter 5. Pixmap and Cursor Functions</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Creating_and_Freeing_Pixmaps">Creating and Freeing Pixmaps</a></span></dt><dt><span class="sect1"><a href="#Creating_Recoloring_and_Freeing_Cursors">Creating, Recoloring, and Freeing Cursors</a></span></dt></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Creating_and_Freeing_Pixmaps"></a>Creating and Freeing Pixmaps</h2></div></div></div><p>

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.
</p><p>


To create a pixmap of a given size, use
<a class="xref" href="#XCreatePixmap"><code class="function">XCreatePixmap</code></a>.
</p><a id="idp43456268" class="indexterm"></a><div class="funcsynopsis"><a id="XCreatePixmap"></a><p><code class="funcdef">Pixmap <strong class="fsfunc">XCreatePixmap</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, unsignedintwidth,<var class="pdparam"> height</var>, unsignedint<var class="pdparam"> depth</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies which screen the pixmap is created on. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height, which define the dimensions of the pixmap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>depth</em></span>
    </span></p></td><td><p>
Specifies the depth of the pixmap.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCreatePixmap"><code class="function">XCreatePixmap</code></a>
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 
<span class="symbol">InputOnly</span>
window to the drawable argument.
The width and height arguments must be nonzero,
or a 
<span class="errorname">BadValue</span>
error results.
The depth argument must be one of the depths supported by the screen
of the specified drawable,
or a
<span class="errorname">BadValue</span>
error results.
</p><p>

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
<a class="xref" href="#XCopyPlane"><code class="function">XCopyPlane</code></a>
for an exception to this rule).
The initial contents of the pixmap are undefined.
</p><p>

<a class="xref" href="#XCreatePixmap"><code class="function">XCreatePixmap</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadDrawable</span>,
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To free all storage associated with a specified pixmap, use
<a class="xref" href="#XFreePixmap"><code class="function">XFreePixmap</code></a>.
</p><a id="idp41419412" class="indexterm"></a><div class="funcsynopsis"><a id="XFreePixmap"></a><p><code class="funcdef"><strong class="fsfunc">XFreePixmap</strong>(</code>Display<var class="pdparam"> *display</var>, Pixmap<var class="pdparam"> pixmap</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>pixmap</em></span>
    </span></p></td><td><p>
Specifies the pixmap.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFreePixmap"><code class="function">XFreePixmap</code></a>
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.
</p><p>

<a class="xref" href="#XFreePixmap"><code class="function">XFreePixmap</code></a>
can generate a
<span class="errorname">BadPixmap</span>
error.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Creating_Recoloring_and_Freeing_Cursors"></a>Creating, Recoloring, and Freeing Cursors</h2></div></div></div><p>

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.
</p><p>

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. 
<a id="idp42654220" class="indexterm"></a>
<a class="xref" href="#XQueryBestCursor"><code class="function">XQueryBestCursor</code></a>
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.
</p><p>


To create a cursor from the standard cursor font, use
<a class="xref" href="#XCreateFontCursor"><code class="function">XCreateFontCursor</code></a>.
</p><p>
#include &lt;X11/cursorfont.h&gt;
</p><a id="idp43516460" class="indexterm"></a><div class="funcsynopsis"><a id="XCreateFontCursor"></a><p><code class="funcdef">Cursor <strong class="fsfunc">XCreateFontCursor</strong>(</code>Display<var class="pdparam"> *display</var>, unsignedint<var class="pdparam"> shape</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>shape</em></span>
    </span></p></td><td><p>
Specifies the shape of the cursor.
    </p></td></tr></tbody></table></div><p>


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.
</p><p>

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
<a class="xref" href="#XRecolorCursor"><code class="function">XRecolorCursor</code></a>).
For further information about cursor shapes,
see <a class="link" href="#x_font_cursors" title="Appendix B. X Font Cursors">appendix B</a>.
</p><p>

<a class="xref" href="#XCreateFontCursor"><code class="function">XCreateFontCursor</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To create a cursor from font glyphs, use
<a class="xref" href="#XCreateGlyphCursor"><code class="function">XCreateGlyphCursor</code></a>.
</p><a id="idp41908796" class="indexterm"></a><div class="funcsynopsis"><a id="XCreateGlyphCursor"></a><p><code class="funcdef">Cursor <strong class="fsfunc">XCreateGlyphCursor</strong>(</code>Display<var class="pdparam"> *display</var>, Fontsource_font,<var class="pdparam"> mask_font</var>, unsignedintsource_char,<var class="pdparam"> mask_char</var>, XColor<var class="pdparam"> *foreground_color</var>, XColor<var class="pdparam"> *background_color</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>source_font</em></span>
    </span></p></td><td><p>
Specifies the font for the source glyph.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>mask_font</em></span>
    </span></p></td><td><p>
Specifies the font for the mask glyph or
<span class="symbol">None</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>source_char</em></span>
    </span></p></td><td><p>
Specifies the character glyph for the source.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>mask_char</em></span>
    </span></p></td><td><p>
Specifies the glyph character for the mask. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>foreground_color</em></span>
    </span></p></td><td><p>
Specifies the <acronym class="acronym">RGB</acronym> values for the foreground of the source. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>background_color</em></span>
    </span></p></td><td><p>
Specifies the <acronym class="acronym">RGB</acronym> values for the background of the source.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCreateGlyphCursor"><code class="function">XCreateGlyphCursor</code></a>
function is similar to
<a class="xref" href="#XCreatePixmapCursor"><code class="function">XCreatePixmapCursor</code></a>
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
<span class="errorname">BadValue</span>
error results.
If mask_font is given, 
mask_char must be a defined glyph in mask_font,
or a
<span class="errorname">BadValue</span>
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
<a class="xref" href="#XFreeFont"><code class="function">XFreeFont</code></a>
if no further explicit references to them are to be made. 
</p><p>

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.
</p><p>

<a class="xref" href="#XCreateGlyphCursor"><code class="function">XCreateGlyphCursor</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadFont</span>,
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To create a cursor from two bitmaps,
use
<a class="xref" href="#XCreatePixmapCursor"><code class="function">XCreatePixmapCursor</code></a>.
</p><a id="idp42819972" class="indexterm"></a><div class="funcsynopsis"><a id="XCreatePixmapCursor"></a><p><code class="funcdef">Cursor <strong class="fsfunc">XCreatePixmapCursor</strong>(</code>Display<var class="pdparam"> *display</var>, Pixmap<var class="pdparam"> source</var>, Pixmap<var class="pdparam"> mask</var>, XColor<var class="pdparam"> *foreground_color</var>, XColor<var class="pdparam"> *background_color</var>, unsignedintx,<var class="pdparam"> y</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>source</em></span>
    </span></p></td><td><p>
Specifies the shape of the source cursor.

      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>mask</em></span>
    </span></p></td><td><p>
Specifies the cursor's source bits to be displayed or
<span class="symbol">None</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>foreground_color</em></span>
    </span></p></td><td><p>
Specifies the <acronym class="acronym">RGB</acronym> values for the foreground of the source. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>background_color</em></span>
    </span></p></td><td><p>
Specifies the <acronym class="acronym">RGB</acronym> values for the background of the source.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, which indicate the hotspot relative to the
source's origin.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCreatePixmapCursor"><code class="function">XCreatePixmapCursor</code></a>
function creates a cursor and returns the cursor ID associated with it.
The foreground and background <acronym class="acronym">RGB</acronym> values must be specified using
foreground_color and background_color,
even if the X server only has a
<span class="symbol">StaticGray</span>
or
<span class="symbol">GrayScale</span>
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 
<span class="errorname">BadMatch</span>
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
<span class="errorname">BadMatch</span>
error results.
The hotspot must be a point within the source,
or a
<span class="errorname">BadMatch</span>
error results.
</p><p>

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.
</p><p>

<a class="xref" href="#XCreatePixmapCursor"><code class="function">XCreatePixmapCursor</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadPixmap</span>
errors.
</p><p>


To determine useful cursor sizes, use
<a class="xref" href="#XQueryBestCursor"><code class="function">XQueryBestCursor</code></a>.
</p><a id="idp40447348" class="indexterm"></a><div class="funcsynopsis"><a id="XQueryBestCursor"></a><p><code class="funcdef">Status <strong class="fsfunc">XQueryBestCursor</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, unsignedintwidth,<var class="pdparam"> height</var>, unsignedint*width_return,<var class="pdparam"> *height_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable, which indicates the screen.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height of the cursor that you want the size
information for.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height_return</em></span>
    </span></p></td><td><p>
Return the best width and height that is closest to the specified width 
and height.
    </p></td></tr></tbody></table></div><p>


Some displays allow larger cursors than other displays.
The
<a class="xref" href="#XQueryBestCursor"><code class="function">XQueryBestCursor</code></a>
function provides a way to find out what size cursors are actually
possible on the display.
<a id="idp44582492" class="indexterm"></a>
It returns the largest size that can be displayed.
Applications should be prepared to use smaller cursors on displays that
cannot support large ones.
</p><p>

<a class="xref" href="#XQueryBestCursor"><code class="function">XQueryBestCursor</code></a>
can generate a
<span class="errorname">BadDrawable</span>
error.
</p><p>


To change the color of a given cursor, use
<a class="xref" href="#XRecolorCursor"><code class="function">XRecolorCursor</code></a>.
</p><a id="idp44585348" class="indexterm"></a><div class="funcsynopsis"><a id="XRecolorCursor"></a><p><code class="funcdef"><strong class="fsfunc">XRecolorCursor</strong>(</code>Display<var class="pdparam"> *display</var>, Cursor<var class="pdparam"> cursor</var>, XColor*foreground_color,<var class="pdparam"> *background_color</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>cursor</em></span>
    </span></p></td><td><p>
Specifies the cursor. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>foreground_color</em></span>
    </span></p></td><td><p>
Specifies the <acronym class="acronym">RGB</acronym> values for the foreground of the source. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>background_color</em></span>
    </span></p></td><td><p>
Specifies the <acronym class="acronym">RGB</acronym> values for the background of the source.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XRecolorCursor"><code class="function">XRecolorCursor</code></a>
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
<span class="structname">XColor</span>
structures are ignored; only the <acronym class="acronym">RGB</acronym> values are used.
</p><p>

<a class="xref" href="#XRecolorCursor"><code class="function">XRecolorCursor</code></a>
can generate a
<span class="errorname">BadCursor</span>
error.
</p><p>


To free (destroy) a given cursor, use
<a class="xref" href="#XFreeCursor"><code class="function">XFreeCursor</code></a>.
</p><a id="idp44401564" class="indexterm"></a><div class="funcsynopsis"><a id="XFreeCursor"></a><p><code class="funcdef"><strong class="fsfunc">XFreeCursor</strong>(</code>Display<var class="pdparam"> *display</var>, Cursor<var class="pdparam"> cursor</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>cursor</em></span>
    </span></p></td><td><p>
Specifies the cursor. 
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFreeCursor"><code class="function">XFreeCursor</code></a>
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.
</p><p>

<a class="xref" href="#XFreeCursor"><code class="function">XFreeCursor</code></a>
can generate a
<span class="errorname">BadCursor</span>
error.


</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Color_Management_Functions"></a>Chapter 6. Color Management Functions</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Color_Structures">Color Structures</a></span></dt><dt><span class="sect1"><a href="#Color_Strings">Color Strings</a></span></dt><dd><dl><dt><span class="sect2"><a href="#RGB_Device_String_Specification"><acronym class="acronym">RGB</acronym> Device String Specification</a></span></dt><dt><span class="sect2"><a href="#RGB_Intensity_String_Specification"><acronym class="acronym">RGB</acronym> Intensity String Specification</a></span></dt><dt><span class="sect2"><a href="#Device_Independent_String_Specifications">Device-Independent String Specifications</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Color_Conversion_Contexts_and_Gamut_Mapping">Color Conversion Contexts and Gamut Mapping</a></span></dt><dt><span class="sect1"><a href="#Creating_Copying_and_Destroying_Colormaps">Creating, Copying, and Destroying Colormaps</a></span></dt><dt><span class="sect1"><a href="#Mapping_Color_Names_to_Values">Mapping Color Names to Values</a></span></dt><dt><span class="sect1"><a href="#Allocating_and_Freeing_Color_Cells">Allocating and Freeing Color Cells</a></span></dt><dt><span class="sect1"><a href="#Modifying_and_Querying_Colormap_Cells">Modifying and Querying Colormap Cells</a></span></dt><dt><span class="sect1"><a href="#Color_Conversion_Context_Functions">Color Conversion Context Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Getting_and_Setting_the_Color_Conversion_Context_of_a_Colormap">Getting and Setting the Color Conversion Context of a Colormap</a></span></dt><dt><span class="sect2"><a href="#Obtaining_the_Default_Color_Conversion_Context">Obtaining the Default Color Conversion Context</a></span></dt><dt><span class="sect2"><a href="#Color_Conversion_Context_Macros">Color Conversion Context Macros</a></span></dt><dt><span class="sect2"><a href="#Modifying_Attributes_of_a_Color_Conversion_Context">Modifying Attributes of a Color Conversion Context</a></span></dt><dt><span class="sect2"><a href="#Creating_and_Freeing_a_Color_Conversion_Context">Creating and Freeing a Color Conversion Context</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Converting_between_Color_Spaces">Converting between Color Spaces</a></span></dt><dt><span class="sect1"><a href="#Callback_Functions">Callback Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Prototype_Gamut_Compression_Procedure">Prototype Gamut Compression Procedure</a></span></dt><dt><span class="sect2"><a href="#Supplied_Gamut_Compression_Procedures">Supplied Gamut Compression Procedures</a></span></dt><dt><span class="sect2"><a href="#Prototype_White_Point_Adjustment_Procedure">Prototype White Point Adjustment Procedure</a></span></dt><dt><span class="sect2"><a href="#Supplied_White_Point_Adjustment_Procedures">Supplied White Point Adjustment Procedures</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Gamut_Querying_Functions">Gamut Querying Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Red_Green_and_Blue_Queries">Red, Green, and Blue Queries</a></span></dt><dt><span class="sect2"><a href="#CIELab_Queries">CIELab Queries</a></span></dt><dt><span class="sect2"><a href="#CIELuv_Queries">CIELuv Queries</a></span></dt><dt><span class="sect2"><a href="#TekHVC_Queries">TekHVC Queries</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Color_Management_Extensions">Color Management Extensions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Color_Spaces">Color Spaces</a></span></dt><dt><span class="sect2"><a href="#Adding_Device_Independent_Color_Spaces">Adding Device-Independent Color Spaces</a></span></dt><dt><span class="sect2"><a href="#Querying_Color_Space_Format_and_Prefix">Querying Color Space Format and Prefix</a></span></dt><dt><span class="sect2"><a href="#Creating_Additional_Color_Spaces">Creating Additional Color Spaces</a></span></dt><dt><span class="sect2"><a href="#Parse_String_Callback">Parse String Callback</a></span></dt><dt><span class="sect2"><a href="#Color_Specification_Conversion_Callback">Color Specification Conversion Callback</a></span></dt><dt><span class="sect2"><a href="#Function_Sets">Function Sets</a></span></dt><dt><span class="sect2"><a href="#Adding_Function_Sets">Adding Function Sets</a></span></dt><dt><span class="sect2"><a href="#Creating_Additional_Function_Sets">Creating Additional Function Sets</a></span></dt></dl></dd></dl></div><p>




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 <acronym class="acronym">RGB</acronym> color space.
The <acronym class="acronym">RGB</acronym> color space is device dependent;
rendering an <acronym class="acronym">RGB</acronym> 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 <acronym class="acronym">CIE</acronym> XYZ
color space.
This includes the <acronym class="acronym">CIE</acronym> XYZ, xyY, L*u*v*, and L*a*b* color spaces as well as
the TekHVC color space.
</p><p>

This chapter discusses how to:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Create, copy, and destroy a colormap
    </p></li><li class="listitem"><p>
Specify colors by name or value
    </p></li><li class="listitem"><p>
Allocate, modify, and free color cells
    </p></li><li class="listitem"><p>
Read entries in a colormap
    </p></li><li class="listitem"><p>
Convert between color spaces
    </p></li><li class="listitem"><p>
Control aspects of color conversion
    </p></li><li class="listitem"><p>
Query the color gamut of a screen
    </p></li><li class="listitem"><p>
Add new color spaces
    </p></li></ul></div><p>

All functions, types, and symbols in this chapter with the prefix ``Xcms''
are defined in
<code class="filename">&lt;X11/Xcms.h&gt;</code>.
<a id="idp40503564" class="indexterm"></a>
<a id="idp40504404" class="indexterm"></a>
<a id="idp40505292" class="indexterm"></a>
The remaining functions and types are defined in
<code class="filename">&lt;X11/Xlib.h&gt;</code>.
<a id="idp40506700" class="indexterm"></a>
<a id="idp40507596" class="indexterm"></a>
<a id="idp40508508" class="indexterm"></a>
</p><p>

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 (<acronym class="acronym">RGB</acronym>) 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 <acronym class="acronym">RGB</acronym> 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.
</p><p>

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 <acronym class="acronym">RGB</acronym> 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 <acronym class="acronym">RGB</acronym> value)
by a client to obtain desired colors.
The use of pixel value for an
unallocated cell results in an undefined color.
</p><p>

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
<a class="xref" href="#XInstallColormap"><code class="function">XInstallColormap</code></a>
and
<a class="xref" href="#XUninstallColormap"><code class="function">XUninstallColormap</code></a>.
</p><p>

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.
</p><p>

The 
<code class="function">DefaultColormap</code>
macro returns the default colormap.
The 
<code class="function">DefaultVisual</code>
macro
returns the default visual type for the specified screen.
<a id="idp43530196" class="indexterm"></a>
Possible visual types are 
<span class="symbol">StaticGray</span>,
<span class="symbol">GrayScale</span>,
<span class="symbol">StaticColor</span>,
<span class="symbol">PseudoColor</span>,
<span class="symbol">TrueColor</span>,
or 
<span class="symbol">DirectColor</span>
(see <a class="link" href="#Visual_Types" title="Visual Types">section 3.1</a>).
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Color_Structures"></a>Color Structures</h2></div></div></div><p>

Functions that operate only on <acronym class="acronym">RGB</acronym> color space values use an
<span class="structname">XColor</span>
structure, which contains:
</p><p>

<a id="idp43558660" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
	unsigned long pixel;	/* pixel value */
	unsigned short red, green, blue;	/* rgb values */
	char flags;	/* DoRed, DoGreen, DoBlue */	
	char pad;
} XColor;
</pre><p>
</p><p>


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).
<a id="idp43561092" class="indexterm"></a>
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
<span class="symbol">DoRed</span>,
<span class="symbol">DoGreen</span>,
and 
<span class="symbol">DoBlue</span>.
</p><p>


Functions that operate on all color space values use an
<span class="structname">XcmsColor</span>
structure.
This structure contains a union of substructures,
each supporting color specification encoding for a particular color space.
Like the
<span class="structname">XColor</span>
structure, the
<span class="structname">XcmsColor</span>
structure contains pixel
and color specification information (the spec member in the 
<span class="structname">XcmsColor</span>
structure).
<a id="idp43564044" class="indexterm"></a>

</p><p>

</p><pre class="literallayout">


typedef unsigned long XcmsColorFormat;			/* Color Specification Format */

typedef struct {
	union {
		XcmsRGB RGB;
		XcmsRGBi RGBi;
		XcmsCIEXYZ CIEXYZ;
		XcmsCIEuvY CIEuvY;
		XcmsCIExyY CIExyY;
		XcmsCIELab CIELab;
		XcmsCIELuv CIELuv;
		XcmsTekHVC TekHVC;
		XcmsPad Pad;
	} spec;
	unsigned long pixel;
	XcmsColorFormat format;
} XcmsColor;			/* Xcms Color Structure */
</pre><p>
</p><p>


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
<span class="type">XcmsColorFormat</span>.
The following macros define standard formats.

</p><pre class="literallayout">
#define          XcmsUndefinedFormat   0x00000000
#define          XcmsCIEXYZFormat      0x00000001  /* CIE XYZ */
#define          XcmsCIEuvYFormat      0x00000002  /* CIE u'v'Y */
#define          XcmsCIExyYFormat      0x00000003  /* CIE xyY */
#define          XcmsCIELabFormat      0x00000004  /* CIE L*a*b* */
#define          XcmsCIELuvFormat      0x00000005  /* CIE L*u*v* */
#define          XcmsTekHVCFormat      0x00000006  /* TekHVC */
#define          XcmsRGBFormat         0x80000000  /* RGB Device */
#define          XcmsRGBiFormat        0x80000001  /* RGB Intensity */
</pre><p>


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 <a class="link" href="#Creating_Additional_Color_Spaces" title="Creating Additional Color Spaces">section 6.12.4</a>).
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 
<a class="xref" href="#XcmsFormatOfPrefix"><code class="function">XcmsFormatOfPrefix</code></a>
and
<a class="xref" href="#XcmsPrefixOfFormat"><code class="function">XcmsPrefixOfFormat</code></a>).
</p><p>

Data types that describe the color specification encoding for the various
color spaces are defined as follows:

<a id="idp42179580" class="indexterm"></a>
</p><p>

</p><pre class="literallayout">


typedef double XcmsFloat;

typedef struct {
	unsigned short red;	/* 0x0000 to 0xffff */
	unsigned short green;	/* 0x0000 to 0xffff */
	unsigned short blue;	/* 0x0000 to 0xffff */
} XcmsRGB;		/* RGB Device */
</pre><p>
<a id="idp42181428" class="indexterm"></a>
</p><p>

</p><pre class="literallayout">


typedef struct {
	XcmsFloat red;	/* 0.0 to 1.0 */
	XcmsFloat green;	/* 0.0 to 1.0 */
	XcmsFloat blue;	/* 0.0 to 1.0 */
} XcmsRGBi;		/* RGB Intensity */
</pre><p>
<a id="idp42183220" class="indexterm"></a>
</p><p>

</p><pre class="literallayout">


typedef struct {
	XcmsFloat X;
	XcmsFloat Y;	/* 0.0 to 1.0 */
	XcmsFloat Z;
} XcmsCIEXYZ;		/* CIE XYZ */
</pre><p>
<a id="idp42184964" class="indexterm"></a>
</p><p>

</p><pre class="literallayout">


typedef struct {
	XcmsFloat u_prime;	/* 0.0 to ~0.6 */
	XcmsFloat v_prime;	/* 0.0 to ~0.6 */
	XcmsFloat Y; 	/* 0.0 to 1.0 */
} XcmsCIEuvY;		/* CIE u'v'Y */
</pre><p>
<a id="idp42186764" class="indexterm"></a>
</p><p>

</p><pre class="literallayout">


typedef struct {
	XcmsFloat x; 	/* 0.0 to ~.75 */
	XcmsFloat y; 	/* 0.0 to ~.85 */
	XcmsFloat Y; 	/* 0.0 to 1.0 */
} XcmsCIExyY;		/* CIE xyY */
</pre><p>
<a id="idp42188548" class="indexterm"></a>
</p><p>

</p><pre class="literallayout">


typedef struct {
	XcmsFloat L_star; 	/* 0.0 to 100.0 */
	XcmsFloat a_star;
	XcmsFloat b_star;
} XcmsCIELab;		/* CIE L*a*b* */
</pre><p>
<a id="idp45041404" class="indexterm"></a>
</p><p>

</p><pre class="literallayout">


typedef struct {
	XcmsFloat L_star; 	/* 0.0 to 100.0 */
	XcmsFloat u_star;
	XcmsFloat v_star;
} XcmsCIELuv;		/* CIE L*u*v* */
</pre><p>
<a id="idp45043172" class="indexterm"></a>
</p><p>

</p><pre class="literallayout">


typedef struct {
	XcmsFloat H; 	/* 0.0 to 360.0 */
	XcmsFloat V; 	/* 0.0 to 100.0 */
	XcmsFloat C; 	/* 0.0 to 100.0 */
} XcmsTekHVC;		/* TekHVC */
</pre><p>
<a id="idp45044964" class="indexterm"></a>
</p><p>

</p><pre class="literallayout">


typedef struct {
	XcmsFloat pad0;
	XcmsFloat pad1;
	XcmsFloat pad2;
	XcmsFloat pad3;
} XcmsPad;		/* four doubles */
</pre><p>
</p><p>


The device-dependent formats provided allow color specification in:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<acronym class="acronym">RGB</acronym> Intensity
(<span class="structname">XcmsRGBi</span>)
    </p></li><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
<acronym class="acronym">RGB</acronym> Device
(<span class="structname">XcmsRGB</span>)
    </p></li><li class="listitem"><p>
Red, green, and blue values appropriate for the specified output device.
<span class="structname">XcmsRGB</span>
values are of type unsigned short,
scaled from 0 to 65535 inclusive,
and are interchangeable with the red, green, and blue values in an 
<span class="structname">XColor</span>
structure. 
    </p></li></ul></div><p>

It is important to note that <acronym class="acronym">RGB</acronym> Intensity values are not gamma corrected
values.
In contrast,
<acronym class="acronym">RGB</acronym> Device values generated as a result of converting color specifications 
are always gamma corrected, and
<acronym class="acronym">RGB</acronym> 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 <span class="emphasis"><em><acronym class="acronym">RGB</acronym> value</em></span> in this manual always refers to an <acronym class="acronym">RGB</acronym> Device value.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Color_Strings"></a>Color Strings</h2></div></div></div><p>

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.
</p><p>

Color strings are used in the following functions:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<a class="xref" href="#XAllocNamedColor"><code class="function">XAllocNamedColor</code></a>
    </p></li><li class="listitem"><p>
<a class="xref" href="#XcmsAllocNamedColor"><code class="function">XcmsAllocNamedColor</code></a>
    </p></li><li class="listitem"><p>
<a class="xref" href="#XLookupColor"><code class="function">XLookupColor</code></a>
    </p></li><li class="listitem"><p>
<a class="xref" href="#XcmsLookupColor"><code class="function">XcmsLookupColor</code></a>
    </p></li><li class="listitem"><p>
<a class="xref" href="#XParseColor"><code class="function">XParseColor</code></a>
    </p></li><li class="listitem"><p>
<a class="xref" href="#XStoreNamedColor"><code class="function">XStoreNamedColor</code></a>
    </p></li></ul></div><p>

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.
</p><p>

A numerical color specification
consists of a color space name and a set of values in the following syntax:
</p><p>


</p><pre class="literallayout">
<span class="emphasis"><em>&lt;color_space_name&gt;</em></span>:<span class="emphasis"><em>&lt;value&gt;/.../&lt;value&gt;</em></span>
</pre><p>
</p><p>


The following are examples of valid color strings.
</p><p>

</p><pre class="literallayout">
"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"
</pre><p>
The syntax and semantics of numerical specifications are given
for each standard color space in the following sections.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="RGB_Device_String_Specification"></a><acronym class="acronym">RGB</acronym> Device String Specification</h3></div></div></div><p>

An <acronym class="acronym">RGB</acronym> Device specification is identified by
the prefix ``rgb:'' and conforms to the following syntax:
</p><p>


</p><pre class="literallayout">
rgb:<span class="emphasis"><em>&lt;red&gt;/&lt;green&gt;/&lt;blue&gt;</em></span>

    <span class="emphasis"><em>&lt;red&gt;</em></span>, <span class="emphasis"><em>&lt;green&gt;</em></span>, <span class="emphasis"><em>&lt;blue&gt;</em></span> := <span class="emphasis"><em>h</em></span> | <span class="emphasis"><em>hh</em></span> | <span class="emphasis"><em>hhh</em></span> | <span class="emphasis"><em>hhhh</em></span>
    <span class="emphasis"><em>h</em></span> := single hexadecimal digits (case insignificant)
</pre><p>

</p><p>

Note that <span class="emphasis"><em>h</em></span> indicates the value scaled in 4 bits, 
<span class="emphasis"><em>hh</em></span> the value scaled in 8 bits,
<span class="emphasis"><em>hhh</em></span> the value scaled in 12 bits,
and <span class="emphasis"><em>hhhh</em></span> the value scaled in 16 bits, respectively.
</p><p>

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.
</p><p>

For backward compatibility, an older syntax for <acronym class="acronym">RGB</acronym> 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:
</p><p>


</p><pre class="literallayout">


#RGB	(4 bits each)
#RRGGBB	(8 bits each)
#RRRGGGBBB	(12 bits each)
#RRRRGGGGBBBB	(16 bits each)
</pre><p>

</p><p>

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''.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="RGB_Intensity_String_Specification"></a><acronym class="acronym">RGB</acronym> Intensity String Specification</h3></div></div></div><p>

An <acronym class="acronym">RGB</acronym> intensity specification is identified
by the prefix ``rgbi:'' and conforms to the following syntax:
</p><p>


</p><pre class="literallayout">
rgbi:<span class="emphasis"><em>&lt;red&gt;/&lt;green&gt;/&lt;blue&gt;</em></span>
</pre><p>

</p><p>

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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Device_Independent_String_Specifications"></a>Device-Independent String Specifications</h3></div></div></div><p>

The standard device-independent string specifications have
the following syntax:
</p><p>


</p><pre class="literallayout">
CIEXYZ:<span class="emphasis"><em>&lt;X&gt;/&lt;Y&gt;/&lt;Z&gt;</em></span>
CIEuvY:<span class="emphasis"><em>&lt;u&gt;/&lt;v&gt;/&lt;Y&gt;</em></span>
CIExyY:<span class="emphasis"><em>&lt;x&gt;/&lt;y&gt;/&lt;Y&gt;</em></span>
CIELab:<span class="emphasis"><em>&lt;L&gt;/&lt;a&gt;/&lt;b&gt;</em></span>
CIELuv:<span class="emphasis"><em>&lt;L&gt;/&lt;u&gt;/&lt;v&gt;</em></span>
TekHVC:<span class="emphasis"><em>&lt;H&gt;/&lt;V&gt;/&lt;C&gt;</em></span>
</pre><p>

</p><p>

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.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Color_Conversion_Contexts_and_Gamut_Mapping"></a>Color Conversion Contexts and Gamut Mapping</h2></div></div></div><p>

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,
<a id="idp45089476" class="indexterm"></a>
is available in a Color Conversion Context (CCC).
<a id="idp45089948" class="indexterm"></a>
<a id="idp45090356" class="indexterm"></a>
</p><p>

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:
<a id="idp45091420" class="indexterm"></a>
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
White adjustment occurs when the inherent white point of the screen
differs from the white point assumed by the client.
    </p></li></ul></div><p>

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).
<a id="idp45093948" class="indexterm"></a>
<a id="idp45094380" class="indexterm"></a>
<a id="idp45094812" class="indexterm"></a>
<a id="idp45095244" class="indexterm"></a>
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.
</p><p>

Associated with each colormap is an initial CCC transparently generated by
Xlib.
<a id="idp45096436" class="indexterm"></a>
Therefore,
when you specify a colormap as an argument to an Xlib function,
you are indirectly specifying a CCC.
<a id="idp45097092" class="indexterm"></a>
<a id="idp45097660" class="indexterm"></a>
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.
<a id="idp45098380" class="indexterm"></a>
<a id="idp45098948" class="indexterm"></a>
</p><p>

Xcms functions in which gamut mapping can occur return
<span class="type">Status</span>
and have specific status values defined for them, 
as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<span class="symbol">XcmsFailure</span>
indicates that the function failed.
    </p></li><li class="listitem"><p>
<span class="symbol">XcmsSuccess</span>
indicates that the function succeeded.
In addition,
if the function performed any color conversion,
the colors did not need to be compressed.
    </p></li><li class="listitem"><p>
<span class="symbol">XcmsSuccessWithCompression</span>
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.
    </p></li></ul></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Creating_Copying_and_Destroying_Colormaps"></a>Creating, Copying, and Destroying Colormaps</h2></div></div></div><p>

To create a colormap for a screen, use
<a class="xref" href="#XCreateColormap"><code class="function">XCreateColormap</code></a>.</p><a id="idp45105060" class="indexterm"></a><div class="funcsynopsis"><a id="XCreateColormap"></a><p><code class="funcdef">Colormap <strong class="fsfunc">XCreateColormap</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, Visual<var class="pdparam"> *visual</var>, int<var class="pdparam"> alloc</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window on whose screen you want to create a colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>visual</em></span>
    </span></p></td><td><p>
Specifies a visual type supported on the screen.
If the visual type is not one supported by the screen, 
a
<span class="errorname">BadMatch</span>
error results.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>alloc</em></span>
    </span></p></td><td><p>
Specifies the colormap entries to be allocated.
You can pass 
<span class="symbol">AllocNone</span>
or 
<span class="symbol">AllocAll</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCreateColormap"><code class="function">XCreateColormap</code></a>
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.
</p><p>

The initial values of the colormap entries are undefined for the 
visual classes
<span class="symbol">GrayScale</span>,
<span class="symbol">PseudoColor</span>,
and
<span class="symbol">DirectColor</span>.
For
<span class="symbol">StaticGray</span>,
<span class="symbol">StaticColor</span>,
and
<span class="symbol">TrueColor</span>,
the entries have defined values,
but those values are specific to the visual and are not defined by X.
For
<span class="symbol">StaticGray</span>,
<span class="symbol">StaticColor</span>,
and
<span class="symbol">TrueColor</span>,
alloc must be
<span class="symbol">AllocNone</span>,
or a
<span class="errorname">BadMatch</span>
error results.
For the other visual classes,
if alloc is
<span class="symbol">AllocNone</span>,
the colormap initially has no allocated entries,
and clients can allocate them.
For information about the visual types,
see <a class="link" href="#Visual_Types" title="Visual Types">section 3.1</a>.
</p><p>

If alloc is
<span class="symbol">AllocAll</span>,
the entire colormap is allocated writable.
The initial values of all allocated entries are undefined.
For
<span class="symbol">GrayScale</span>
and
<span class="symbol">PseudoColor</span>,
the effect is as if an
<a class="xref" href="#XAllocColorCells"><code class="function">XAllocColorCells</code></a>
call returned all pixel values from zero to N - 1,
where N is the colormap entries value in the specified visual.
For
<span class="symbol">DirectColor</span>,
the effect is as if an
<a class="xref" href="#XAllocColorPlanes"><code class="function">XAllocColorPlanes</code></a>
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
<a class="xref" href="#XFreeColors"><code class="function">XFreeColors</code></a>.
</p><p>

<a class="xref" href="#XCreateColormap"><code class="function">XCreateColormap</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadMatch</span>,
<span class="errorname">BadValue</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To create a new colormap when the allocation out of a previously
shared colormap has failed because of resource exhaustion, use
<a class="xref" href="#XCopyColormapAndFree"><code class="function">XCopyColormapAndFree</code></a>.
</p><a id="idp45125892" class="indexterm"></a><div class="funcsynopsis"><a id="XCopyColormapAndFree"></a><p><code class="funcdef">Colormap <strong class="fsfunc">XCopyColormapAndFree</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCopyColormapAndFree"><code class="function">XCopyColormapAndFree</code></a>
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
<span class="symbol">AllocAll</span>,
the new colormap is also created with 
<span class="symbol">AllocAll</span>,
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
<span class="symbol">AllocAll</span>,
the allocations to be moved are all those pixels and planes
that have been allocated by the client using
<a class="xref" href="#XAllocColor"><code class="function">XAllocColor</code></a>,
<a class="xref" href="#XAllocNamedColor"><code class="function">XAllocNamedColor</code></a>,
<a class="xref" href="#XAllocColorCells"><code class="function">XAllocColorCells</code></a>,
or
<a class="xref" href="#XAllocColorPlanes"><code class="function">XAllocColorPlanes</code></a>
and that have not been freed since they were allocated.
</p><p>

<a class="xref" href="#XCopyColormapAndFree"><code class="function">XCopyColormapAndFree</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadColor</span>
errors.
</p><p>


To destroy a colormap, use 
<a class="xref" href="#XFreeColormap"><code class="function">XFreeColormap</code></a>.
<a id="idp45137860" class="indexterm"></a>
</p><div class="funcsynopsis"><a id="XFreeColormap"></a><p><code class="funcdef"><strong class="fsfunc">XFreeColormap</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap that you want to destroy.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFreeColormap"><code class="function">XFreeColormap</code></a>
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
<a class="xref" href="#XUninstallColormap"><code class="function">XUninstallColormap</code></a>).
If the specified colormap is defined as the colormap for a window (by
<a class="xref" href="#XCreateWindow"><code class="function">XCreateWindow</code></a>,
<a class="xref" href="#XSetWindowColormap"><code class="function">XSetWindowColormap</code></a>,
or
<a class="xref" href="#XChangeWindowAttributes"><code class="function">XChangeWindowAttributes</code></a>),
<a class="xref" href="#XFreeColormap"><code class="function">XFreeColormap</code></a>
changes the colormap associated with the window to
<span class="symbol">None</span>
and generates a
<span class="symbol">ColormapNotify</span>
event.
X does not define the colors displayed for a window with a colormap of
<span class="symbol">None</span>.
</p><p>

<a class="xref" href="#XFreeColormap"><code class="function">XFreeColormap</code></a>
can generate a
<span class="errorname">BadColor</span>
error.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Mapping_Color_Names_to_Values"></a>Mapping Color Names to Values</h2></div></div></div><p>


To map a color name to an <acronym class="acronym">RGB</acronym> value, use
<a class="xref" href="#XLookupColor"><code class="function">XLookupColor</code></a>.
<a id="idp45151156" class="indexterm"></a>
<a id="idp45151724" class="indexterm"></a>

</p><div class="funcsynopsis"><a id="XLookupColor"></a><p><code class="funcdef">Status <strong class="fsfunc">XLookupColor</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, char<var class="pdparam"> *color_name</var>, XColor*exact_def_return,<var class="pdparam"> *screen_def_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_name</em></span>
    </span></p></td><td><p>
Specifies the color name string (for example, red) whose color 
definition structure you want returned.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>exact_def_return</em></span>
    </span></p></td><td><p>
Returns the exact <acronym class="acronym">RGB</acronym> values.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_def_return</em></span>
    </span></p></td><td><p>
Returns the closest <acronym class="acronym">RGB</acronym> values provided by the hardware.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XLookupColor"><code class="function">XLookupColor</code></a>
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.
<a class="xref" href="#XLookupColor"><code class="function">XLookupColor</code></a>
returns nonzero if the name is resolved;
otherwise, it returns zero.
</p><p>

<a class="xref" href="#XLookupColor"><code class="function">XLookupColor</code></a>
can generate a
<span class="errorname">BadColor</span>
error.
</p><p>


To map a color name to the exact <acronym class="acronym">RGB</acronym> value, use
<a class="xref" href="#XParseColor"><code class="function">XParseColor</code></a>.
</p><a id="idp46218772" class="indexterm"></a><a id="idp46219276" class="indexterm"></a><div class="funcsynopsis"><a id="XParseColor"></a><p><code class="funcdef">Status <strong class="fsfunc">XParseColor</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, char<var class="pdparam"> *spec</var>, XColor<var class="pdparam"> *exact_def_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>spec</em></span>
    </span></p></td><td><p>
Specifies the color name string;
case is ignored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>exact_def_return</em></span>
    </span></p></td><td><p>
Returns the exact color value for later use and sets the
<span class="symbol">DoRed</span>,
<span class="symbol">DoGreen</span>,
and
<span class="symbol">DoBlue</span>
flags.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XParseColor"><code class="function">XParseColor</code></a>
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.
<a class="xref" href="#XParseColor"><code class="function">XParseColor</code></a>
returns nonzero if the name is resolved;
otherwise, it returns zero.
</p><p>

<a class="xref" href="#XParseColor"><code class="function">XParseColor</code></a>
can generate a
<span class="errorname">BadColor</span>
error.
</p><p>


To map a color name to a value in an arbitrary color space, use
<a class="xref" href="#XcmsLookupColor"><code class="function">XcmsLookupColor</code></a>.
</p><a id="idp46231268" class="indexterm"></a><a id="idp46231772" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsLookupColor"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsLookupColor</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, char<var class="pdparam"> *color_string</var>, XcmsColor*color_exact_return,<var class="pdparam"> *color_screen_return</var>, XcmsColorFormat<var class="pdparam"> result_format</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.

      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_string</em></span>
    </span></p></td><td><p>
Specifies the color string(St.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_exact_return</em></span>
    </span></p></td><td><p>
Returns the color specification parsed from the color string
or parsed from the corresponding string found in a color-name database.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_screen_return</em></span>
    </span></p></td><td><p>
Returns the color that can be reproduced on the screen.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>result_format</em></span>
    </span></p></td><td><p>
Specifies the color format for the returned color
specifications (color_screen_return and color_exact_return arguments).
If the format is
<span class="symbol">XcmsUndefinedFormat</span>
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
<span class="symbol">XcmsUndefinedFormat</span>
and the color string contains a color name,
the specification is returned in the format used 
to store the color in the database.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsLookupColor"><code class="function">XcmsLookupColor</code></a>
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.
<a class="xref" href="#XcmsLookupColor"><code class="function">XcmsLookupColor</code></a>
returns
<span class="symbol">XcmsSuccess</span>
or
<span class="symbol">XcmsSuccessWithCompression</span>
if the name is resolved; otherwise, it returns
<span class="symbol">XcmsFailure</span>.
If
<span class="symbol">XcmsSuccessWithCompression</span>
is returned, the color specification returned in 
color_screen_return is the result of gamut compression.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Allocating_and_Freeing_Color_Cells"></a>Allocating and Freeing Color Cells</h2></div></div></div><p>

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 id="idp46247692" class="indexterm"></a>
A read-only cell has its <acronym class="acronym">RGB</acronym> value set by the server.
<a id="idp46248260" class="indexterm"></a>
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.
</p><p>

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.
</p><p>


To allocate a read-only color cell with an <acronym class="acronym">RGB</acronym> value, use
<a class="xref" href="#XAllocColor"><code class="function">XAllocColor</code></a>.
</p><a id="idp46250764" class="indexterm"></a><a id="idp46251268" class="indexterm"></a><a id="idp46251772" class="indexterm"></a><a id="idp46252276" class="indexterm"></a><div class="funcsynopsis"><a id="XAllocColor"></a><p><code class="funcdef">Status <strong class="fsfunc">XAllocColor</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, XColor<var class="pdparam"> *screen_in_out</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_in_out</em></span>
    </span></p></td><td><p>
Specifies and returns the values actually used in the colormap.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XAllocColor"><code class="function">XAllocColor</code></a>
function allocates a read-only colormap entry corresponding to the closest
<acronym class="acronym">RGB</acronym> value supported by the hardware.
<a class="xref" href="#XAllocColor"><code class="function">XAllocColor</code></a>
returns the pixel value of the color closest to the specified
<acronym class="acronym">RGB</acronym> elements supported by the hardware
and returns the <acronym class="acronym">RGB</acronym> value actually used.
The corresponding colormap cell is read-only.
In addition,
<a class="xref" href="#XAllocColor"><code class="function">XAllocColor</code></a>
returns nonzero if it succeeded or zero if it failed.
<a id="idp46261260" class="indexterm"></a>
<a id="idp46261636" class="indexterm"></a>
<a id="idp46262140" class="indexterm"></a>
<a id="idp46262644" class="indexterm"></a>
Multiple clients that request the same effective <acronym class="acronym">RGB</acronym> 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.
<a class="xref" href="#XAllocColor"><code class="function">XAllocColor</code></a>
does not use or affect the flags in the
<span class="structname">XColor</span>
structure.
</p><p>

<a class="xref" href="#XAllocColor"><code class="function">XAllocColor</code></a>
can generate a
<span class="errorname">BadColor</span>
error.

delim %%

</p><p>


To allocate a read-only color cell with a color in arbitrary format, use
<a class="xref" href="#XcmsAllocColor"><code class="function">XcmsAllocColor</code></a>.
</p><a id="idp46266132" class="indexterm"></a><a id="idp46266636" class="indexterm"></a><a id="idp46267140" class="indexterm"></a><a id="idp46267644" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsAllocColor"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsAllocColor</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, XcmsColor<var class="pdparam"> *color_in_out</var>, XcmsColorFormat<var class="pdparam"> result_format</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_in_out</em></span>
    </span></p></td><td><p>
Specifies the color to allocate and returns the pixel and color 
that is actually used in the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>result_format</em></span>
    </span></p></td><td><p>
Specifies the color format for the returned color specification.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsAllocColor"><code class="function">XcmsAllocColor</code></a>
function is similar to
<a class="xref" href="#XAllocColor"><code class="function">XAllocColor</code></a>
except the color can be specified in any format.
The
<a class="xref" href="#XcmsAllocColor"><code class="function">XcmsAllocColor</code></a>
function ultimately calls 
<a class="xref" href="#XAllocColor"><code class="function">XAllocColor</code></a>
to allocate a read-only color cell (colormap entry) with the specified color.
<a class="xref" href="#XcmsAllocColor"><code class="function">XcmsAllocColor</code></a>
first converts the color specified
to an <acronym class="acronym">RGB</acronym> value and then passes this to
<a class="xref" href="#XAllocColor"><code class="function">XAllocColor</code></a>.
<a class="xref" href="#XcmsAllocColor"><code class="function">XcmsAllocColor</code></a>
returns the pixel value of the color cell and the color specification
actually allocated.
This returned color specification is the result of converting the <acronym class="acronym">RGB</acronym> value
returned by 
<a class="xref" href="#XAllocColor"><code class="function">XAllocColor</code></a>
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
<span class="symbol">XcmsRGBFormat</span>.
The corresponding colormap cell is read-only.
If this routine returns 
<span class="symbol">XcmsFailure</span>,
the color_in_out color specification is left unchanged.
</p><p>

<a class="xref" href="#XcmsAllocColor"><code class="function">XcmsAllocColor</code></a>
can generate a
<span class="errorname">BadColor</span>
error.
</p><p>


To allocate a read-only color cell using a color name and return the closest
color supported by the hardware in <acronym class="acronym">RGB</acronym> format, use
<a class="xref" href="#XAllocNamedColor"><code class="function">XAllocNamedColor</code></a>.
</p><a id="idp46282740" class="indexterm"></a><a id="idp46283244" class="indexterm"></a><a id="idp46283748" class="indexterm"></a><a id="idp46284252" class="indexterm"></a><a id="idp46284756" class="indexterm"></a><div class="funcsynopsis"><a id="XAllocNamedColor"></a><p><code class="funcdef">Status <strong class="fsfunc">XAllocNamedColor</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, char<var class="pdparam"> *color_name</var>, XColor*screen_def_return,<var class="pdparam"> *exact_def_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_name</em></span>
    </span></p></td><td><p>
Specifies the color name string (for example, red) whose color 
definition structure you want returned.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_def_return</em></span>
    </span></p></td><td><p>
Returns the closest <acronym class="acronym">RGB</acronym> values provided by the hardware.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>exact_def_return</em></span>
    </span></p></td><td><p>
Returns the exact <acronym class="acronym">RGB</acronym> values.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XAllocNamedColor"><code class="function">XAllocNamedColor</code></a>
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.
<a class="xref" href="#XAllocNamedColor"><code class="function">XAllocNamedColor</code></a>
returns nonzero if a cell is allocated;
otherwise, it returns zero.
</p><p>

<a class="xref" href="#XAllocNamedColor"><code class="function">XAllocNamedColor</code></a>
can generate a
<span class="errorname">BadColor</span>
error. 
</p><p>


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
<a class="xref" href="#XcmsAllocNamedColor"><code class="function">XcmsAllocNamedColor</code></a>.
</p><a id="idp46298036" class="indexterm"></a><a id="idp46298540" class="indexterm"></a><a id="idp46299044" class="indexterm"></a><a id="idp46299548" class="indexterm"></a><a id="idp46300052" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsAllocNamedColor"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsAllocNamedColor</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, char<var class="pdparam"> *color_string</var>, XcmsColor<var class="pdparam"> *color_screen_return</var>, XcmsColor<var class="pdparam"> *color_exact_return</var>, XcmsColorFormat<var class="pdparam"> result_format</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_string</em></span>
    </span></p></td><td><p>
Specifies the color string whose color definition structure is to be
returned.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_screen_return</em></span>
    </span></p></td><td><p>
Returns the pixel value of the color cell and color specification 
that actually is stored for that cell.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_exact_return</em></span>
    </span></p></td><td><p>
Returns the color specification parsed from the color string
or parsed from the corresponding string found in a color-name database.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>result_format</em></span>
    </span></p></td><td><p>
Specifies the color format for the returned color
specifications (color_screen_return and color_exact_return arguments).
If the format is
<span class="symbol">XcmsUndefinedFormat</span>
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
<span class="symbol">XcmsUndefinedFormat</span>
and the color string contains a color name,
the specification is returned in the format used 
to store the color in the database.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsAllocNamedColor"><code class="function">XcmsAllocNamedColor</code></a>
function is similar to
<a class="xref" href="#XAllocNamedColor"><code class="function">XAllocNamedColor</code></a>
except that the color returned can be in any format specified.
This function
ultimately calls
<a class="xref" href="#XAllocColor"><code class="function">XAllocColor</code></a>
to allocate a read-only color cell with
the color specified by a color string.
The color string is parsed into an
<span class="structname">XcmsColor</span>
structure (see
<a class="xref" href="#XcmsLookupColor"><code class="function">XcmsLookupColor</code></a>),
converted
to an <acronym class="acronym">RGB</acronym> value, and finally passed to
<a class="xref" href="#XAllocColor"><code class="function">XAllocColor</code></a>.
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.
</p><p>

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 <acronym class="acronym">RGB</acronym> value
returned by
<a class="xref" href="#XAllocColor"><code class="function">XAllocColor</code></a>
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
<span class="symbol">XcmsRGBFormat</span>.
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.
</p><p>

<a class="xref" href="#XcmsAllocNamedColor"><code class="function">XcmsAllocNamedColor</code></a>
can generate a
<span class="errorname">BadColor</span>
error.
</p><p>


To allocate read/write color cell and color plane combinations for a
<span class="symbol">PseudoColor</span>
model, use
<a class="xref" href="#XAllocColorCells"><code class="function">XAllocColorCells</code></a>.
</p><a id="idp46319404" class="indexterm"></a><a id="idp46319988" class="indexterm"></a><a id="idp46320572" class="indexterm"></a><a id="idp46321140" class="indexterm"></a><div class="funcsynopsis"><a id="XAllocColorCells"></a><p><code class="funcdef">Status <strong class="fsfunc">XAllocColorCells</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, Bool<var class="pdparam"> contig</var>, unsignedlong<var class="pdparam"> plane_masks_return[]</var>, unsignedint<var class="pdparam"> nplanes</var>, unsignedlong<var class="pdparam"> pixels_return[]</var>, unsignedint<var class="pdparam"> npixels</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>contig</em></span>
    </span></p></td><td><p>
Specifies a Boolean value that indicates whether the planes must be contiguous.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>plane_mask_return</em></span>
    </span></p></td><td><p>
Returns an array of plane masks.

      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nplanes</em></span>
    </span></p></td><td><p>
Specifies the number of plane masks that are to be returned in the plane masks 
array. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>pixels_return</em></span>
    </span></p></td><td><p>
Returns an array of pixel values. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>npixels</em></span>
    </span></p></td><td><p>
Specifies the number of pixel values that are to be returned in the 
pixels_return array. 
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XAllocColorCells"><code class="function">XAllocColorCells</code></a>
function allocates read/write color cells.
The number of colors must be positive and the number of planes nonnegative,
or a
<span class="errorname">BadValue</span>
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 × 2<sup><span class="emphasis"><em>nplanes</em></span></sup>
distinct pixels can be produced.
All of these are
allocated writable by the request.
For 
<span class="symbol">GrayScale</span>
or 
<span class="symbol">PseudoColor</span>,
each mask has exactly one bit set to 1. 
For 
<span class="symbol">DirectColor</span>,
each has exactly three bits set to 1.
If contig is 
<span class="symbol">True</span>
and if all masks are ORed
together, a single contiguous set of bits set to 1 will be formed for 
<span class="symbol">GrayScale</span>
or 
<span class="symbol">PseudoColor</span>
and three contiguous sets of bits set to 1 (one within each
pixel subfield) for 
<span class="symbol">DirectColor</span>.
The <acronym class="acronym">RGB</acronym> values of the allocated
entries are undefined.
<a class="xref" href="#XAllocColorCells"><code class="function">XAllocColorCells</code></a>
returns nonzero if it succeeded or zero if it failed.
</p><p>

<a class="xref" href="#XAllocColorCells"><code class="function">XAllocColorCells</code></a>
can generate
<span class="errorname">BadColor</span>
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To allocate read/write color resources for a
<span class="symbol">DirectColor</span>
model, use
<a class="xref" href="#XAllocColorPlanes"><code class="function">XAllocColorPlanes</code></a>.
</p><a id="idp46343284" class="indexterm"></a><a id="idp46343868" class="indexterm"></a><a id="idp46344452" class="indexterm"></a><a id="idp46345020" class="indexterm"></a><div class="funcsynopsis"><a id="XAllocColorPlanes"></a><p><code class="funcdef">Status <strong class="fsfunc">XAllocColorPlanes</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, Bool<var class="pdparam"> contig</var>, unsignedlong<var class="pdparam"> pixels_return[]</var>, int<var class="pdparam"> ncolors</var>, intnreds,ngreens,<var class="pdparam"> nblues</var>, unsignedlong*rmask_return,*gmask_return,<var class="pdparam"> *bmask_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>contig</em></span>
    </span></p></td><td><p>
Specifies a Boolean value that indicates whether the planes must be contiguous.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>pixels_return</em></span>
    </span></p></td><td><p>
Returns an array of pixel values. 
<a class="xref" href="#XAllocColorPlanes"><code class="function">XAllocColorPlanes</code></a>
returns the pixel values in this array.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>ncolors</em></span>
    </span></p></td><td><p>
Specifies the number of pixel values that are to be returned in the 
pixels_return array. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nreds</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>ngreens</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nblues</em></span>
    </span></p></td><td><p>


Specify the number of red, green, and blue planes.
The value you pass must be nonnegative. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>rmask_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gmask_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>bmask_return</em></span>
    </span></p></td><td><p>
Return bit masks for the red, green, and blue planes.
    </p></td></tr></tbody></table></div><p>


The specified ncolors must be positive; 
and nreds, ngreens, and nblues must be nonnegative,
or a
<span class="errorname">BadValue</span>
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 
<span class="symbol">True</span>,
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 
<span class="symbol">DirectColor</span>,
each mask
will lie within the corresponding pixel subfield.
By ORing together
subsets of masks with each pixel value, 
ncolors × 2<sup><span class="emphasis"><em>(nreds+ngreens+nblues)</em></span></sup>
distinct pixel values can be produced.
All of these are allocated by the request.
However, in the
colormap, there are only
ncolors × 2<sup><span class="emphasis"><em>nreds</em></span></sup>
independent red entries,
ncolors × 2<sup><span class="emphasis"><em>ngreens</em></span></sup>
independent green entries, and
ncolors × 2<sup><span class="emphasis"><em>nblues</em></span></sup>
independent blue entries.
This is true even for 
<span class="symbol">PseudoColor</span>.
When the colormap entry of a pixel
value is changed (using 
<a class="xref" href="#XStoreColors"><code class="function">XStoreColors</code></a>,
<a class="xref" href="#XStoreColor"><code class="function">XStoreColor</code></a>,
or 
<a class="xref" href="#XStoreNamedColor"><code class="function">XStoreNamedColor</code></a>),
the pixel is decomposed according to the masks, 
and the corresponding independent entries are updated.
<a class="xref" href="#XAllocColorPlanes"><code class="function">XAllocColorPlanes</code></a>
returns nonzero if it succeeded or zero if it failed.
</p><p>

<a class="xref" href="#XAllocColorPlanes"><code class="function">XAllocColorPlanes</code></a>
can generate
<span class="errorname">BadColor</span>
and
<span class="errorname">BadValue</span>
errors.
</p><p>


<a id="idp46374140" class="indexterm"></a>
To free colormap cells, use
<a class="xref" href="#XFreeColors"><code class="function">XFreeColors</code></a>.
<a id="idp46375156" class="indexterm"></a>
<a id="idp46375580" class="indexterm"></a>

</p><div class="funcsynopsis"><a id="XFreeColors"></a><p><code class="funcdef"><strong class="fsfunc">XFreeColors</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, unsignedlong<var class="pdparam"> pixels[]</var>, int<var class="pdparam"> npixels</var>, unsignedlong<var class="pdparam"> planes</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>pixels</em></span>
    </span></p></td><td><p>
Specifies an array of pixel values that map to the cells in the specified
colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>npixels</em></span>
    </span></p></td><td><p>
Specifies the number of pixels. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>planes</em></span>
    </span></p></td><td><p>
Specifies the planes you want to free.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFreeColors"><code class="function">XFreeColors</code></a>
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 
<a id="idp46388100" class="indexterm"></a>
<a id="idp46388524" class="indexterm"></a>
<a id="idp46388956" class="indexterm"></a>
<a id="idp46389388" class="indexterm"></a>
<a class="xref" href="#XAllocColor"><code class="function">XAllocColor</code></a>,
<a class="xref" href="#XAllocNamedColor"><code class="function">XAllocNamedColor</code></a>,
<a class="xref" href="#XAllocColorCells"><code class="function">XAllocColorCells</code></a>,
and 
<a class="xref" href="#XAllocColorPlanes"><code class="function">XAllocColorPlanes</code></a>).
Note that freeing an
individual pixel obtained from 
<a class="xref" href="#XAllocColorPlanes"><code class="function">XAllocColorPlanes</code></a>
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.
</p><p>

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 
<span class="errorname">BadValue</span>
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
<span class="symbol">AllocAll</span>
to
<a class="xref" href="#XCreateColormap"><code class="function">XCreateColormap</code></a>),
a
<span class="errorname">BadAccess</span>
error results. 
If more than one pixel is in error, 
the one that gets reported is arbitrary.
</p><p>

<a class="xref" href="#XFreeColors"><code class="function">XFreeColors</code></a>
can generate
<span class="errorname">BadAccess</span>,
<span class="errorname">BadColor</span>,
and
<span class="errorname">BadValue</span>
errors.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Modifying_and_Querying_Colormap_Cells"></a>Modifying and Querying Colormap Cells</h2></div></div></div><p>


To store an <acronym class="acronym">RGB</acronym> value in a single colormap cell, use
<a class="xref" href="#XStoreColor"><code class="function">XStoreColor</code></a>.
</p><a id="idp46398332" class="indexterm"></a><a id="idp46398900" class="indexterm"></a><div class="funcsynopsis"><a id="XStoreColor"></a><p><code class="funcdef"><strong class="fsfunc">XStoreColor</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, XColor<var class="pdparam"> *color</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color</em></span>
    </span></p></td><td><p>
Specifies the pixel and <acronym class="acronym">RGB</acronym> values.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XStoreColor"><code class="function">XStoreColor</code></a>
function changes the colormap entry of the pixel value specified in the
pixel member of the
<span class="structname">XColor</span>
structure.
You specified this value in the
pixel member of the
<span class="structname">XColor</span>
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
<span class="errorname">BadValue</span>
error results.
<a class="xref" href="#XStoreColor"><code class="function">XStoreColor</code></a>
also changes the red, green, and/or blue color components.
You specify which color components are to be changed by setting
<span class="symbol">DoRed</span>,
<span class="symbol">DoGreen</span>,
and/or
<span class="symbol">DoBlue</span>
in the flags member of the
<span class="structname">XColor</span>
structure.
If the colormap is an installed map for its screen, 
the changes are visible immediately.
</p><p>

<a class="xref" href="#XStoreColor"><code class="function">XStoreColor</code></a>
can generate
<span class="errorname">BadAccess</span>,
<span class="errorname">BadColor</span>,
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To store multiple <acronym class="acronym">RGB</acronym> values in multiple colormap cells, use
<a class="xref" href="#XStoreColors"><code class="function">XStoreColors</code></a>.
</p><a id="idp46412740" class="indexterm"></a><a id="idp46413308" class="indexterm"></a><div class="funcsynopsis"><a id="XStoreColors"></a><p><code class="funcdef"><strong class="fsfunc">XStoreColors</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, XColor<var class="pdparam"> color[]</var>, int<var class="pdparam"> ncolors</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color</em></span>
    </span></p></td><td><p>
Specifies an array of color definition structures to be stored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>ncolors</em></span>
    </span></p></td><td><p>

Specifies the number of 
<span class="structname">XColor</span>
structures in the color definition array.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XStoreColors"><code class="function">XStoreColors</code></a>
function changes the colormap entries of the pixel values
specified in the pixel members of the
<span class="structname">XColor</span>
structures.
You specify which color components are to be changed by setting 
<span class="symbol">DoRed</span>,
<span class="symbol">DoGreen</span>,
and/or
<span class="symbol">DoBlue</span>
in the flags member of the
<span class="structname">XColor</span>
structures.
If the colormap is an installed map for its screen, the
changes are visible immediately.
<a class="xref" href="#XStoreColors"><code class="function">XStoreColors</code></a>
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
<span class="errorname">BadValue</span>
error results.
If a specified pixel either is unallocated or is allocated read-only, a
<span class="errorname">BadAccess</span>
error results.
If more than one pixel is in error, 
the one that gets reported is arbitrary.
</p><p>

<a class="xref" href="#XStoreColors"><code class="function">XStoreColors</code></a>
can generate
<span class="errorname">BadAccess</span>,
<span class="errorname">BadColor</span>,
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To store a color of arbitrary format in a single colormap cell, use
<a class="xref" href="#XcmsStoreColor"><code class="function">XcmsStoreColor</code></a>.
</p><a id="idp46429204" class="indexterm"></a><a id="idp46429772" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsStoreColor"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsStoreColor</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, XcmsColor<var class="pdparam"> *color</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color</em></span>
    </span></p></td><td><p>
Specifies the color cell and the color to store.
Values specified in this
<span class="structname">XcmsColor</span>
structure remain unchanged on return.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsStoreColor"><code class="function">XcmsStoreColor</code></a>
function converts the color specified in the
<span class="structname">XcmsColor</span>
structure into <acronym class="acronym">RGB</acronym> values.
It then uses this <acronym class="acronym">RGB</acronym> specification in an
<span class="structname">XColor</span>
structure, whose three flags 
(<span class="symbol">DoRed</span>,
<span class="symbol">DoGreen</span>,
and
<span class="symbol">DoBlue</span>)
are set, in a call to
<a class="xref" href="#XStoreColor"><code class="function">XStoreColor</code></a>
to change the color cell specified by the pixel member of the
<span class="structname">XcmsColor</span>
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
<span class="errorname">BadValue</span>
error results.
If the color cell is unallocated or is allocated read-only, a
<span class="errorname">BadAccess</span>
error results.
If the colormap is an installed map for its screen, 
the changes are visible immediately.
</p><p>

Note that 
<a class="xref" href="#XStoreColor"><code class="function">XStoreColor</code></a>
has no return value; therefore, an
<span class="symbol">XcmsSuccess</span>
return value from this function indicates that the conversion 
to <acronym class="acronym">RGB</acronym> succeeded and the call to
<a class="xref" href="#XStoreColor"><code class="function">XStoreColor</code></a>
was made.
To obtain the actual color stored, use
<a class="xref" href="#XcmsQueryColor"><code class="function">XcmsQueryColor</code></a>.
Because of the screen's hardware limitations or gamut compression,
the color stored in the colormap may not be identical
to the color specified.
</p><p>

<a class="xref" href="#XcmsStoreColor"><code class="function">XcmsStoreColor</code></a>
can generate
<span class="errorname">BadAccess</span>,
<span class="errorname">BadColor</span>,
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To store multiple colors of arbitrary format in multiple colormap cells, use
<a class="xref" href="#XcmsStoreColors"><code class="function">XcmsStoreColors</code></a>.
</p><a id="idp46446724" class="indexterm"></a><a id="idp46447292" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsStoreColors"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsStoreColors</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, XcmsColor<var class="pdparam"> colors[]</var>, int<var class="pdparam"> ncolors</var>, Bool<var class="pdparam"> compression_flags_return[]</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colors</em></span>
    </span></p></td><td><p>
Specifies the color specification array of
<span class="structname">XcmsColor</span>
structures, each specifying a color cell and the color to store in that
cell.
Values specified in the array remain unchanged upon return.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>ncolors</em></span>
    </span></p></td><td><p>
Specifies the number of 
<span class="structname">XcmsColor</span>
structures in the color-specification array.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>compression_flags_return</em></span>
    </span></p></td><td><p>
Returns an array of Boolean values indicating compression status.
If a non-NULL pointer is supplied,
each element of the array is set to
<span class="symbol">True</span>
if the corresponding color was compressed and
<span class="symbol">False</span>
otherwise.
Pass NULL if the compression status is not useful.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsStoreColors"><code class="function">XcmsStoreColors</code></a>
function converts the colors specified in the array of
<span class="structname">XcmsColor</span>
structures into <acronym class="acronym">RGB</acronym> values and then uses these <acronym class="acronym">RGB</acronym> specifications in
<span class="structname">XColor</span>
structures, whose three flags 
(<span class="symbol">DoRed</span>,
<span class="symbol">DoGreen</span>,
and
<span class="symbol">DoBlue</span>)
are set, in a call to
<a class="xref" href="#XStoreColors"><code class="function">XStoreColors</code></a>
to change the color cells specified by the pixel member of the corresponding
<span class="structname">XcmsColor</span>
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
<span class="errorname">BadValue</span>
error results.
If a color cell is unallocated or is allocated read-only, a
<span class="errorname">BadAccess</span>
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.
</p><p>

Note that 
<a class="xref" href="#XStoreColors"><code class="function">XStoreColors</code></a>
has no return value; therefore, an
<span class="symbol">XcmsSuccess</span>
return value from this function indicates that conversions 
to <acronym class="acronym">RGB</acronym> succeeded and the call to
<a class="xref" href="#XStoreColors"><code class="function">XStoreColors</code></a>
was made.
To obtain the actual colors stored, use
<a class="xref" href="#XcmsQueryColors"><code class="function">XcmsQueryColors</code></a>.
Because of the screen's hardware limitations or gamut compression,
the colors stored in the colormap may not be identical
to the colors specified.
</p><p>

<a class="xref" href="#XcmsStoreColors"><code class="function">XcmsStoreColors</code></a>
can generate
<span class="errorname">BadAccess</span>,
<span class="errorname">BadColor</span>,
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To store a color specified by name in a single colormap cell, use
<a class="xref" href="#XStoreNamedColor"><code class="function">XStoreNamedColor</code></a>.
</p><a id="idp46468924" class="indexterm"></a><a id="idp46469492" class="indexterm"></a><a id="idp46470060" class="indexterm"></a><div class="funcsynopsis"><a id="XStoreNamedColor"></a><p><code class="funcdef"><strong class="fsfunc">XStoreNamedColor</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, char<var class="pdparam"> *color</var>, unsignedlong<var class="pdparam"> pixel</var>, int<var class="pdparam"> flags</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color</em></span>
    </span></p></td><td><p>
Specifies the color name string (for example, red). 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>pixel</em></span>
    </span></p></td><td><p>
Specifies the entry in the colormap. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>flags</em></span>
    </span></p></td><td><p>
Specifies which red, green, and blue components are set.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XStoreNamedColor"><code class="function">XStoreNamedColor</code></a>
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 
<span class="symbol">DoRed</span>,
<span class="symbol">DoGreen</span>,
and 
<span class="symbol">DoBlue</span>.
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
<span class="errorname">BadValue</span>
error results.
If the specified pixel either is unallocated or is allocated read-only, a
<span class="errorname">BadAccess</span>
error results.
</p><p>

<a class="xref" href="#XStoreNamedColor"><code class="function">XStoreNamedColor</code></a>
can generate
<span class="errorname">BadAccess</span>,
<span class="errorname">BadColor</span>,
<span class="errorname">BadName</span>,
and 
<span class="errorname">BadValue</span>
errors.
</p><p>

The
<a class="xref" href="#XQueryColor"><code class="function">XQueryColor</code></a>
and
<a class="xref" href="#XQueryColors"><code class="function">XQueryColors</code></a>
functions take pixel values in the pixel member of
<span class="structname">XColor</span>
structures and store in the structures the <acronym class="acronym">RGB</acronym> 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
<span class="structname">XColor</span>
structure to all three colors.
If a pixel is not a valid index into the specified colormap, a
<span class="errorname">BadValue</span>
error results.
If more than one pixel is in error,
the one that gets reported is arbitrary.
</p><p>


To query the <acronym class="acronym">RGB</acronym> value of a single colormap cell, use
<a class="xref" href="#XQueryColor"><code class="function">XQueryColor</code></a>.
</p><a id="idp46489420" class="indexterm"></a><a id="idp46489988" class="indexterm"></a><div class="funcsynopsis"><a id="XQueryColor"></a><p><code class="funcdef"><strong class="fsfunc">XQueryColor</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, XColor<var class="pdparam"> *def_in_out</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>def_in_out</em></span>
    </span></p></td><td><p>
Specifies and returns the <acronym class="acronym">RGB</acronym> values for the pixel specified in the structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XQueryColor"><code class="function">XQueryColor</code></a>
function returns the current <acronym class="acronym">RGB</acronym> value for the pixel in the
<span class="structname">XColor</span>
structure and sets the
<span class="symbol">DoRed</span>,
<span class="symbol">DoGreen</span>,
and
<span class="symbol">DoBlue</span>
flags.
</p><p>

<a class="xref" href="#XQueryColor"><code class="function">XQueryColor</code></a>
can generate
<span class="errorname">BadColor</span>
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To query the <acronym class="acronym">RGB</acronym> values of multiple colormap cells, use
<a class="xref" href="#XQueryColors"><code class="function">XQueryColors</code></a>.
</p><a id="idp46502308" class="indexterm"></a><a id="idp46502876" class="indexterm"></a><div class="funcsynopsis"><a id="XQueryColors"></a><p><code class="funcdef"><strong class="fsfunc">XQueryColors</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, XColor<var class="pdparam"> defs_in_out[]</var>, int<var class="pdparam"> ncolors</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>defs_in_out</em></span>
    </span></p></td><td><p>
Specifies and returns an array of color definition structures for the pixel
specified in the structure.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>ncolors</em></span>
    </span></p></td><td><p>

Specifies the number of 
<span class="structname">XColor</span>
structures in the color definition array.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XQueryColors"><code class="function">XQueryColors</code></a>
function returns the <acronym class="acronym">RGB</acronym> value for each pixel in each
<span class="structname">XColor</span>
structure and sets the
<span class="symbol">DoRed</span>,
<span class="symbol">DoGreen</span>,
and
<span class="symbol">DoBlue</span>
flags in each structure.

</p><p>

<a class="xref" href="#XQueryColors"><code class="function">XQueryColors</code></a>
can generate
<span class="errorname">BadColor</span>
and
<span class="errorname">BadValue</span>
errors.

</p><p>

To query the color of a single colormap cell in an arbitrary format, use
<a class="xref" href="#XcmsQueryColor"><code class="function">XcmsQueryColor</code></a>.
</p><a id="idp46517116" class="indexterm"></a><a id="idp46517684" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsQueryColor"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsQueryColor</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, XcmsColor<var class="pdparam"> *color_in_out</var>, XcmsColorFormat<var class="pdparam"> result_format</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_in_out</em></span>
    </span></p></td><td><p>
Specifies the pixel member that indicates the color cell to query.
The color specification stored for the color cell is returned in this
<span class="structname">XcmsColor</span>
structure.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>result_format</em></span>
    </span></p></td><td><p>
Specifies the color format for the returned color specification.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsQueryColor"><code class="function">XcmsQueryColor</code></a>
function obtains the <acronym class="acronym">RGB</acronym> value
for the pixel value in the pixel member of the specified
<span class="structname">XcmsColor</span>
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
<span class="errorname">BadValue</span>
error results.
</p><p>

<a class="xref" href="#XcmsQueryColor"><code class="function">XcmsQueryColor</code></a>
can generate
<span class="errorname">BadColor</span>
and
<span class="errorname">BadValue</span>
errors.

</p><p>

To query the color of multiple colormap cells in an arbitrary format, use
<a class="xref" href="#XcmsQueryColors"><code class="function">XcmsQueryColors</code></a>.
</p><a id="idp46531588" class="indexterm"></a><a id="idp46532156" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsQueryColors"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsQueryColors</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, XcmsColor<var class="pdparam"> colors_in_out[]</var>, unsignedint<var class="pdparam"> ncolors</var>, XcmsColorFormat<var class="pdparam"> result_format</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colors_in_out</em></span>
    </span></p></td><td><p>
Specifies an array of
<span class="structname">XcmsColor</span>
structures, each pixel member indicating the color cell to query.
The color specifications for the color cells are returned in these structures.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>ncolors</em></span>
    </span></p></td><td><p>
Specifies the number of 
<span class="structname">XcmsColor</span>
structures in the color-specification array.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>result_format</em></span>
    </span></p></td><td><p>
Specifies the color format for the returned color specification.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsQueryColors"><code class="function">XcmsQueryColors</code></a>
function obtains the <acronym class="acronym">RGB</acronym> values
for pixel values in the pixel members of
<span class="structname">XcmsColor</span>
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
<span class="errorname">BadValue</span>
error results.
If more than one pixel is in error,
the one that gets reported is arbitrary.
</p><p>

<a class="xref" href="#XcmsQueryColors"><code class="function">XcmsQueryColors</code></a>
can generate
<span class="errorname">BadColor</span>
and
<span class="errorname">BadValue</span>
errors.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Color_Conversion_Context_Functions"></a>Color Conversion Context Functions</h2></div></div></div><p>

This section describes functions to create, modify,
and query Color Conversion Contexts (CCCs).
</p><p>

Associated with each colormap is an initial CCC transparently generated by
Xlib.
<a id="idp46549252" class="indexterm"></a>
Therefore, when you specify a colormap as an argument to a function,
you are indirectly specifying a CCC.
<a id="idp46549932" class="indexterm"></a>
<a id="idp46550500" class="indexterm"></a>
The CCC attributes that can be modified by the X client are:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Client White Point
    </p></li><li class="listitem"><p>
Gamut compression procedure and client data
    </p></li><li class="listitem"><p>
White point adjustment procedure and client data
    </p></li></ul></div><p>

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.
<a id="idp46553372" class="indexterm"></a>
<a id="idp46553940" class="indexterm"></a>
There is a default CCC associated with each screen.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Getting_and_Setting_the_Color_Conversion_Context_of_a_Colormap"></a>Getting and Setting the Color Conversion Context of a Colormap</h3></div></div></div><p>


To obtain the CCC associated with a colormap, use
<a class="xref" href="#XcmsCCCOfColormap"><code class="function">XcmsCCCOfColormap</code></a>.
</p><a id="idp46556940" class="indexterm"></a><a id="idp46557372" class="indexterm"></a><a id="idp46557940" class="indexterm"></a><a id="idp46558508" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsCCCOfColormap"></a><p><code class="funcdef">XcmsCCC <strong class="fsfunc">XcmsCCCOfColormap</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsCCCOfColormap"><code class="function">XcmsCCCOfColormap</code></a>
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
<a class="xref" href="#XcmsSetCCCOfColormap"><code class="function">XcmsSetCCCOfColormap</code></a>,
this CCC is used when the specified colormap is used as an argument 
to color functions.

</p><p>

To change the CCC associated with a colormap, use
<a class="xref" href="#XcmsSetCCCOfColormap"><code class="function">XcmsSetCCCOfColormap</code></a>.
</p><a id="idp46567124" class="indexterm"></a><a id="idp46567564" class="indexterm"></a><a id="idp46568132" class="indexterm"></a><a id="idp46568700" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsSetCCCOfColormap"></a><p><code class="funcdef">XcmsCCC <strong class="fsfunc">XcmsSetCCCOfColormap</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var>, XcmsCCC<var class="pdparam"> ccc</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsSetCCCOfColormap"><code class="function">XcmsSetCCCOfColormap</code></a>
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
<a class="xref" href="#XcmsFreeCCC"><code class="function">XcmsFreeCCC</code></a>.
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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Obtaining_the_Default_Color_Conversion_Context"></a>Obtaining the Default Color Conversion Context</h3></div></div></div><p>

You can change the default CCC attributes for subsequently created CCCs
by changing the CCC attributes of the default CCC.
<a id="idp46579892" class="indexterm"></a>
<a id="idp46580460" class="indexterm"></a>
A default CCC is associated with each screen.

</p><p>

To obtain the default CCC for a screen, use
<a class="xref" href="#XcmsDefaultCCC"><code class="function">XcmsDefaultCCC</code></a>.
</p><a id="idp46582180" class="indexterm"></a><a id="idp46582612" class="indexterm"></a><a id="idp46583196" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsDefaultCCC"></a><p><code class="funcdef">XcmsCCC <strong class="fsfunc">XcmsDefaultCCC</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen_number</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsDefaultCCC"><code class="function">XcmsDefaultCCC</code></a>
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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Color_Conversion_Context_Macros"></a>Color Conversion Context Macros</h3></div></div></div><p>

Applications should not directly modify any part of the
<span class="structname">XcmsCCC</span>.
The following lists the C language macros, their corresponding function
equivalents for other language bindings, and what data they both
can return.

</p><a id="idp46592708" class="indexterm"></a><a id="idp46593140" class="indexterm"></a><div class="funcsynopsis"><a id="DisplayOfCCC"></a><p><code class="funcdef"><strong class="fsfunc">DisplayOfCCC</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var><code>)</code>;</p></div><div class="funcsynopsis"><a id="XcmsDisplayOfCCC"></a><p><code class="funcdef">Display *<strong class="fsfunc">XcmsDisplayOfCCC</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
    </p></td></tr></tbody></table></div><p>


Both return the display associated with the specified CCC.
</p><a id="idp46599556" class="indexterm"></a><a id="idp46599980" class="indexterm"></a><div class="funcsynopsis"><a id="VisualOfCCC"></a><p><code class="funcdef"><strong class="fsfunc">VisualOfCCC</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var><code>)</code>;</p></div><div class="funcsynopsis"><a id="XcmsVisualOfCCC"></a><p><code class="funcdef">Visual *<strong class="fsfunc">XcmsVisualOfCCC</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
    </p></td></tr></tbody></table></div><p>


Both return the visual associated with the specified CCC.

</p><a id="idp46606268" class="indexterm"></a><a id="idp46606700" class="indexterm"></a><div class="funcsynopsis"><a id="ScreenNumberOfCCC"></a><p><code class="funcdef"><strong class="fsfunc">ScreenNumberOfCCC</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var><code>)</code>;</p></div><div class="funcsynopsis"><a id="XcmsScreenNumberOfCCC"></a><p><code class="funcdef">int <strong class="fsfunc">XcmsScreenNumberOfCCC</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
    </p></td></tr></tbody></table></div><p>


Both return the number of the screen associated with the specified CCC.

</p><a id="idp46613028" class="indexterm"></a><a id="idp46613468" class="indexterm"></a><div class="funcsynopsis"><a id="ScreenWhitePointOfCCC"></a><p><code class="funcdef"><strong class="fsfunc">ScreenWhitePointOfCCC</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var><code>)</code>;</p></div><div class="funcsynopsis"><a id="XcmsScreenWhitePointOfCCC"></a><p><code class="funcdef">XcmsColor <strong class="fsfunc">XcmsScreenWhitePointOfCCC</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
    </p></td></tr></tbody></table></div><p>


Both return the white point of the screen associated with the specified CCC.

</p><a id="idp46619860" class="indexterm"></a><a id="idp46620300" class="indexterm"></a><div class="funcsynopsis"><a id="ClientWhitePointOfCCC"></a><p><code class="funcdef"> <strong class="fsfunc">ClientWhitePointOfCCC</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var><code>)</code>;</p></div><div class="funcsynopsis"><a id="XcmsClientWhitePointOfCCC"></a><p><code class="funcdef">XcmsColor *<strong class="fsfunc">XcmsClientWhitePointOfCCC</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
    </p></td></tr></tbody></table></div><p>


Both return the Client White Point of the specified CCC.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Modifying_Attributes_of_a_Color_Conversion_Context"></a>Modifying Attributes of a Color Conversion Context</h3></div></div></div><p>

To set the Client White Point in the CCC, use
<a class="xref" href="#XcmsSetWhitePoint"><code class="function">XcmsSetWhitePoint</code></a>.
</p><a id="idp46628564" class="indexterm"></a><a id="idp46628996" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsSetWhitePoint"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsSetWhitePoint</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsColor<var class="pdparam"> *color</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color</em></span>
    </span></p></td><td><p>
Specifies the new Client White Point.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsSetWhitePoint"><code class="function">XcmsSetWhitePoint</code></a>
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
<span class="symbol">XcmsCIEXYZFormat</span>,
<span class="symbol">XcmsCIEuvYFormat</span>,
<span class="symbol">XcmsCIExyYFormat</span>,
or
<span class="symbol">XcmsUndefinedFormat</span>.
If the color argument is NULL, this function sets the format component of the
Client White Point specification to
<span class="symbol">XcmsUndefinedFormat</span>,
indicating that the Client White Point is assumed to be the same as the
Screen White Point.
</p><p>

This function returns nonzero status
if the format for the new white point is valid;
otherwise, it returns zero.


</p><p>

To set the gamut compression procedure and corresponding client data
in a specified CCC, use
<a class="xref" href="#XcmsSetCompressionProc"><code class="function">XcmsSetCompressionProc</code></a>.
</p><a id="idp46638988" class="indexterm"></a><a id="idp46639428" class="indexterm"></a><a id="idp46640028" class="indexterm"></a><a id="idp46640604" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsSetCompressionProc"></a><p><code class="funcdef">XcmsCompressionProc <strong class="fsfunc">XcmsSetCompressionProc</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsCompressionProc<var class="pdparam"> compression_proc</var>, XPointer<var class="pdparam"> client_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>compression_proc</em></span>
    </span></p></td><td><p>
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
<span class="symbol">XcmsFailure</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies client data for gamut compression procedure or NULL.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsSetCompressionProc"><code class="function">XcmsSetCompressionProc</code></a>
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.

</p><p>

To set the white point adjustment procedure and corresponding client data
in a specified CCC, use
<a class="xref" href="#XcmsSetWhiteAdjustProc"><code class="function">XcmsSetWhiteAdjustProc</code></a>.
</p><a id="idp46651084" class="indexterm"></a><a id="idp46651524" class="indexterm"></a><a id="idp46652132" class="indexterm"></a><a id="idp46652716" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsSetWhiteAdjustProc"></a><p><code class="funcdef">XcmsWhiteAdjustProc <strong class="fsfunc">XcmsSetWhiteAdjustProc</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsWhiteAdjustProc<var class="pdparam"> white_adjust_proc</var>, XPointer<var class="pdparam"> client_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>white_adjust_proc</em></span>
    </span></p></td><td><p>
Specifies the white point adjustment procedure.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies client data for white point adjustment procedure or NULL.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsSetWhiteAdjustProc"><code class="function">XcmsSetWhiteAdjustProc</code></a>
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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Creating_and_Freeing_a_Color_Conversion_Context"></a>Creating and Freeing a Color Conversion Context</h3></div></div></div><p>

You can explicitly create a CCC within your application by calling
<a class="xref" href="#XcmsCreateCCC"><code class="function">XcmsCreateCCC</code></a>.
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
<a class="xref" href="#XcmsFreeCCC"><code class="function">XcmsFreeCCC</code></a>.

</p><p>

To create a CCC, use
<a class="xref" href="#XcmsCreateCCC"><code class="function">XcmsCreateCCC</code></a>.
</p><a id="idp46665284" class="indexterm"></a><a id="idp46665716" class="indexterm"></a><a id="idp46666300" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsCreateCCC"></a><p><code class="funcdef">XcmsCCC <strong class="fsfunc">XcmsCreateCCC</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen_number</var>, Visual<var class="pdparam"> *visual</var>, XcmsColor<var class="pdparam"> *client_white_point</var>, XcmsCompressionProc<var class="pdparam"> compression_proc</var>, XPointer<var class="pdparam"> compression_client_data</var>, XcmsWhiteAdjustProc<var class="pdparam"> white_adjust_proc</var>, XPointer<var class="pdparam"> white_adjust_client_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>visual</em></span>
    </span></p></td><td><p>
Specifies the visual type.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_white_point</em></span>
    </span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>compression_proc</em></span>
    </span></p></td><td><p>
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
<span class="symbol">XcmsFailure</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>compression_client_data</em></span>
    </span></p></td><td><p>
Specifies client data for use by the gamut compression procedure or NULL.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>white_adjust_proc</em></span>
    </span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>white_adjust_client_data</em></span>
    </span></p></td><td><p>
Specifies client data for use with the white point adjustment procedure or NULL.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsCreateCCC"><code class="function">XcmsCreateCCC</code></a>
function creates a CCC for the specified display, screen, and visual.
</p><p>


To free a CCC, use
<a class="xref" href="#XcmsFreeCCC"><code class="function">XcmsFreeCCC</code></a>.
</p><a id="idp46686036" class="indexterm"></a><a id="idp46686460" class="indexterm"></a><a id="idp46687044" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsFreeCCC"></a><p><code class="funcdef">void <strong class="fsfunc">XcmsFreeCCC</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsFreeCCC"><code class="function">XcmsFreeCCC</code></a>
function frees the memory used for the specified CCC.
Note that default CCCs and those currently associated with colormaps
are ignored.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Converting_between_Color_Spaces"></a>Converting between Color Spaces</h2></div></div></div><p>


To convert an array of color specifications in arbitrary color formats
to a single destination format, use
<a class="xref" href="#XcmsConvertColors"><code class="function">XcmsConvertColors</code></a>.
</p><a id="idp46694412" class="indexterm"></a><a id="idp46694844" class="indexterm"></a><a id="idp46695412" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsConvertColors"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsConvertColors</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsColor<var class="pdparam"> colors_in_out[]</var>, unsignedint<var class="pdparam"> ncolors</var>, XcmsColorFormat<var class="pdparam"> target_format</var>, Bool<var class="pdparam"> compression_flags_return[]</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colors_in_out</em></span>
    </span></p></td><td><p>
Specifies an array of color specifications.
Pixel members are ignored and remain unchanged upon return.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>ncolors</em></span>
    </span></p></td><td><p>
Specifies the number of 
<span class="structname">XcmsColor</span>
structures in the color-specification array.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>target_format</em></span>
    </span></p></td><td><p>
Specifies the target color specification format.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>compression_flags_return</em></span>
    </span></p></td><td><p>
Returns an array of Boolean values indicating compression status.
If a non-NULL pointer is supplied,
each element of the array is set to
<span class="symbol">True</span>
if the corresponding color was compressed and
<span class="symbol">False</span>
otherwise.
Pass NULL if the compression status is not useful.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsConvertColors"><code class="function">XcmsConvertColors</code></a>
function converts the color specifications in the specified array of
<span class="structname">XcmsColor</span>
structures from their current format to a single target format,
using the specified CCC.
When the return value is
<span class="symbol">XcmsFailure</span>,
the contents of the color specification array are left unchanged.
</p><p>

The array may contain a mixture of color specification formats
(for example, 3 <acronym class="acronym">CIE</acronym> XYZ, 2 <acronym class="acronym">CIE</acronym> 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,
<span class="symbol">XcmsRGBiFormat</span>,
<span class="symbol">XcmsRGBFormat</span>),
all specifications are converted to <acronym class="acronym">CIE</acronym> XYZ format and then to the target
device-dependent format.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Callback_Functions"></a>Callback Functions</h2></div></div></div><p>

This section describes the gamut compression and white point
adjustment callbacks.
</p><p>

The gamut compression procedure specified in the CCC
is called when an attempt to convert a color specification from
<span class="structname">XcmsCIEXYZ</span>
to a device-dependent format (typically
<span class="structname">XcmsRGBi</span>)
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.
</p><p>

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.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Prototype_Gamut_Compression_Procedure"></a>Prototype Gamut Compression Procedure</h3></div></div></div><p>

The gamut compression callback interface must adhere to the
following:
</p><a id="idp46716348" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsCompressionProc"></a><p><code class="funcdef">typedef Status<strong class="fsfunc">(*XcmsCompressionProc</strong>)(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsColor<var class="pdparam"> colors_in_out[]</var>, unsignedint<var class="pdparam"> ncolors</var>, unsignedint<var class="pdparam"> index</var>, Bool<var class="pdparam"> compression_flags_return[]</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colors_in_out</em></span>
    </span></p></td><td><p>
Specifies an array of color specifications.
Pixel members should be ignored and must remain unchanged upon return.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>ncolors</em></span>
    </span></p></td><td><p>
Specifies the number of 
<span class="structname">XcmsColor</span>
structures in the color-specification array.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>index</em></span>
    </span></p></td><td><p>
Specifies the index into the array of
<span class="structname">XcmsColor</span>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>compression_flags_return</em></span>
    </span></p></td><td><p>
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
<span class="symbol">True</span>
should be stored at the corresponding index in this array;
otherwise, the array should not be modified.
    </p></td></tr></tbody></table></div><p>


When implementing a gamut compression procedure, consider the following
rules and assumptions:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The gamut compression procedure can attempt to compress one or multiple
specifications at a time.
    </p></li><li class="listitem"><p>
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
<span class="structname">XcmsRGBi</span>).
If any modifications are made to these color specifications,
they must be in their initial device-dependent format upon return.
    </p></li><li class="listitem"><p>
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
<span class="structname">XcmsCIEXYZ</span>.
Upon return, this color specification must be in
<span class="structname">XcmsCIEXYZ</span>.
    </p></li><li class="listitem"><p>
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
<span class="structname">XcmsCIEXYZ</span>.
If any modifications are made to these color specifications, 
they must be in
<span class="structname">XcmsCIEXYZ</span>
upon return.
    </p></li><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
If the gamut compression procedure uses a device-independent color space not
initially accessible for use in the color management system, use 
<a class="xref" href="#XcmsAddColorSpace"><code class="function">XcmsAddColorSpace</code></a>
to ensure that it is added.
    </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Supplied_Gamut_Compression_Procedures"></a>Supplied Gamut Compression Procedures</h3></div></div></div><p>

The following equations are useful in describing gamut compression
functions:

delim %%

</p><p>

</p><pre class="literallayout">
%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%

%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]%

%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%

%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]%
</pre><p>
</p><p>

The gamut compression callback procedures provided by Xlib are as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="function">XcmsCIELabClipL</code>
    </p></li><li class="listitem"><p>
This brings the encountered out-of-gamut color specification into the 
screen's color gamut by reducing or increasing <acronym class="acronym">CIE</acronym> metric lightness (L*) 
in the <acronym class="acronym">CIE</acronym> 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 <acronym class="acronym">CIE</acronym> L*a*b* coordinates of maximum
Psychometric Chroma.
See
<a class="xref" href="#XcmsCIELabQueryMaxC"><code class="function">XcmsCIELabQueryMaxC</code></a>.
No client data is necessary.
    </p></li><li class="listitem"><p>
<code class="function">XcmsCIELabClipab</code>
    </p></li><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
<code class="function">XcmsCIELabClipLab</code>
    </p></li><li class="listitem"><p>
This brings the encountered out-of-gamut color specification into the
screen's color gamut by replacing it with <acronym class="acronym">CIE</acronym> 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.
    </p></li><li class="listitem"><p>
<code class="function">XcmsCIELuvClipL</code>
    </p></li><li class="listitem"><p>
This brings the encountered out-of-gamut color specification into the 
screen's color gamut by reducing or increasing <acronym class="acronym">CIE</acronym> metric lightness (L*)
in the <acronym class="acronym">CIE</acronym> 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 <acronym class="acronym">CIE</acronym> L*u*v* coordinates of maximum
Psychometric Chroma.
See
<a class="xref" href="#XcmsCIELuvQueryMaxC"><code class="function">XcmsCIELuvQueryMaxC</code></a>.
No client data is necessary.
    </p></li><li class="listitem"><p>
<code class="function">XcmsCIELuvClipuv</code>
    </p></li><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
<code class="function">XcmsCIELuvClipLuv</code>
    </p></li><li class="listitem"><p>
This brings the encountered out-of-gamut color specification into the
screen's color gamut by replacing it with <acronym class="acronym">CIE</acronym> 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.
    </p></li><li class="listitem"><p>
<code class="function">XcmsTekHVCClipV</code>
    </p></li><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
<code class="function">XcmsTekHVCClipC</code>
    </p></li><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
<code class="function">XcmsTekHVCClipVC</code>
    </p></li><li class="listitem"><p>
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.
    </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Prototype_White_Point_Adjustment_Procedure"></a>Prototype White Point Adjustment Procedure</h3></div></div></div><p>

The white point adjustment procedure interface must adhere to the following:
</p><a id="idp46757860" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsWhiteAdjustProc"></a><p><code class="funcdef">typedef Status <strong class="fsfunc">(*XcmsWhiteAdjustProc</strong>)(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsColor<var class="pdparam"> *initial_white_point</var>, XcmsColor<var class="pdparam"> *target_white_point</var>, XcmsColorFormat<var class="pdparam"> target_format</var>, XcmsColor<var class="pdparam"> colors_in_out[]</var>, unsignedint<var class="pdparam"> ncolors</var>, Bool<var class="pdparam"> compression_flags_return[]</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>initial_white_point</em></span>
    </span></p></td><td><p>
Specifies the initial white point.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>target_white_point</em></span>
    </span></p></td><td><p>
Specifies the target white point.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>target_format</em></span>
    </span></p></td><td><p>
Specifies the target color specification format.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colors_in_out</em></span>
    </span></p></td><td><p>
Specifies an array of color specifications.
Pixel members should be ignored and must remain unchanged upon return.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>ncolors</em></span>
    </span></p></td><td><p>
Specifies the number of 
<span class="structname">XcmsColor</span>
structures in the color-specification array.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>compression_flags_return</em></span>
    </span></p></td><td><p>
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
<span class="symbol">True</span>
should be stored at the corresponding index in this array;
otherwise, the array should not be modified.
    </p></td></tr></tbody></table></div><p>


</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Supplied_White_Point_Adjustment_Procedures"></a>Supplied White Point Adjustment Procedures</h3></div></div></div><p>

White point adjustment procedures provided by Xlib are as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="function">XcmsCIELabWhiteShiftColors</code>
    </p></li><li class="listitem"><p>
This uses the <acronym class="acronym">CIE</acronym> 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 
<span class="structname">XcmsCIELab</span>
using the source white point and then converts to the target specification
format using the destination's white point.
No client data is necessary.
    </p></li><li class="listitem"><p>
<code class="function">XcmsCIELuvWhiteShiftColors</code>
    </p></li><li class="listitem"><p>
This uses the <acronym class="acronym">CIE</acronym> 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 
<span class="structname">XcmsCIELuv</span>
using the source white point and then converts to the target specification
format using the destination's white point.
No client data is necessary.
    </p></li><li class="listitem"><p>
<code class="function">XcmsTekHVCWhiteShiftColors</code>
    </p></li><li class="listitem"><p>
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
<span class="structname">XcmsTekHVC</span>
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.
    </p></li></ul></div><p>

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, <acronym class="acronym">CIE</acronym> L*u*v*, <acronym class="acronym">CIE</acronym> 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 <acronym class="acronym">CIE</acronym> color spaces that are assumed to be white-point-independent
are <acronym class="acronym">CIE</acronym> u'v'Y, <acronym class="acronym">CIE</acronym> XYZ, and <acronym class="acronym">CIE</acronym> 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
<a class="xref" href="#XcmsAddColorSpace"><code class="function">XcmsAddColorSpace</code></a>
to ensure that it is added.
</p><p>

As an example, 
if the CCC specifies a white point adjustment procedure
and if the Client White Point and Screen White Point differ, the
<a class="xref" href="#XcmsAllocColor"><code class="function">XcmsAllocColor</code></a>
function will use the white point adjustment
procedure twice: 
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Once to convert to
<span class="structname">XcmsRGB</span>
    </p></li><li class="listitem"><p>
A second time to convert from
<span class="structname">XcmsRGB</span>
    </p></li></ul></div><p>

For example, assume the specification is in
<span class="structname">XcmsCIEuvY</span>
and the adjustment procedure is
<code class="function">XcmsCIELuvWhiteShiftColors</code>.
During conversion to
<span class="structname">XcmsRGB</span>,
the call to 
<a class="xref" href="#XcmsAllocColor"><code class="function">XcmsAllocColor</code></a>
results in the following series of color specification conversions:

</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
From 
<span class="structname">XcmsCIEuvY</span>
to
<span class="structname">XcmsCIELuv</span>
using the Client White Point
    </p></li><li class="listitem"><p>
From 
<span class="structname">XcmsCIELuv</span>
to
<span class="structname">XcmsCIEuvY</span>
using the Screen White Point
    </p></li><li class="listitem"><p>
From
<span class="structname">XcmsCIEuvY</span>
to
<span class="structname">XcmsCIEXYZ</span>
(<acronym class="acronym">CIE</acronym> u'v'Y and XYZ are white-point-independent color spaces)
    </p></li><li class="listitem"><p>
From 
<span class="structname">XcmsCIEXYZ</span>
to 
<span class="structname">XcmsRGBi</span>
    </p></li><li class="listitem"><p>
From 
<span class="structname">XcmsRGBi</span>
to
<span class="structname">XcmsRGB</span>
    </p></li></ul></div><p>

The resulting <acronym class="acronym">RGB</acronym> specification is passed to
<a class="xref" href="#XAllocColor"><code class="function">XAllocColor</code></a>,
and the <acronym class="acronym">RGB</acronym>
specification returned by
<a class="xref" href="#XAllocColor"><code class="function">XAllocColor</code></a>
is converted back to 
<span class="structname">XcmsCIEuvY</span>
by reversing the color conversion sequence.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Gamut_Querying_Functions"></a>Gamut Querying Functions</h2></div></div></div><p>

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 <acronym class="acronym">CIE</acronym> L*a*b*, <acronym class="acronym">CIE</acronym> L*u*v*, 
and TekHVC color spaces.
<a id="idp46799012" class="indexterm"></a>
Functions are also provided that allow you to query 
the color specification of:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
White (full-intensity red, green, and blue)
    </p></li><li class="listitem"><p>
Red (full-intensity red while green and blue are zero)
    </p></li><li class="listitem"><p>
Green (full-intensity green while red and blue are zero)
    </p></li><li class="listitem"><p>
Blue (full-intensity blue while red and green are zero)
    </p></li><li class="listitem"><p>
Black (zero-intensity red, green, and blue)
    </p></li></ul></div><p>

The white point associated with color specifications passed to 
and returned from these gamut querying
functions is assumed to be the Screen White Point.
<a id="idp46802756" class="indexterm"></a>
This is a reasonable assumption,
because the client is trying to query the screen's color gamut.
</p><p>

The following naming convention is used for the Max and Min functions:
</p><p>

</p><pre class="literallayout">
Xcms<span class="emphasis"><em>&lt;color_space&gt;</em></span>QueryMax<span class="emphasis"><em>&lt;dimensions&gt;</em></span>

Xcms<span class="emphasis"><em>&lt;color_space&gt;</em></span>QueryMin<span class="emphasis"><em>&lt;dimensions&gt;</em></span>
</pre><p>
</p><p>

The &lt;dimensions&gt; consists of a letter or letters 
that identify the dimensions of the color space 
that are not fixed.
For example, 
<a class="xref" href="#XcmsTekHVCQueryMaxC"><code class="function">XcmsTekHVCQueryMaxC</code></a>
is given a fixed Hue and Value for which maximum Chroma is found.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Red_Green_and_Blue_Queries"></a>Red, Green, and Blue Queries</h3></div></div></div><p>

To obtain the color specification for black 
(zero-intensity red, green, and blue), use
<a class="xref" href="#XcmsQueryBlack"><code class="function">XcmsQueryBlack</code></a>.
</p><a id="idp46809204" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsQueryBlack"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsQueryBlack</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsColorFormat<var class="pdparam"> target_format</var>, XcmsColor<var class="pdparam"> *color_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>target_format</em></span>
    </span></p></td><td><p>
Specifies the target color specification format.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_return</em></span>
    </span></p></td><td><p>
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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsQueryBlack"><code class="function">XcmsQueryBlack</code></a>
function returns the color specification in the specified target format
for zero-intensity red, green, and blue.

</p><p>

To obtain the color specification for blue 
(full-intensity blue while red and green are zero), use
<a class="xref" href="#XcmsQueryBlue"><code class="function">XcmsQueryBlue</code></a>.
</p><a id="idp46819204" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsQueryBlue"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsQueryBlue</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsColorFormat<var class="pdparam"> target_format</var>, XcmsColor<var class="pdparam"> *color_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>target_format</em></span>
    </span></p></td><td><p>
Specifies the target color specification format.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_return</em></span>
    </span></p></td><td><p>
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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsQueryBlue"><code class="function">XcmsQueryBlue</code></a>
function returns the color specification in the specified target format
for full-intensity blue while red and green are zero.

</p><p>

To obtain the color specification for green
(full-intensity green while red and blue are zero), use
<a class="xref" href="#XcmsQueryGreen"><code class="function">XcmsQueryGreen</code></a>.
</p><a id="idp46829260" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsQueryGreen"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsQueryGreen</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsColorFormat<var class="pdparam"> target_format</var>, XcmsColor<var class="pdparam"> *color_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>target_format</em></span>
    </span></p></td><td><p>
Specifies the target color specification format.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_return</em></span>
    </span></p></td><td><p>
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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsQueryGreen"><code class="function">XcmsQueryGreen</code></a>
function returns the color specification in the specified target format
for full-intensity green while red and blue are zero.

</p><p>

To obtain the color specification for red
(full-intensity red while green and blue are zero), use
<a class="xref" href="#XcmsQueryRed"><code class="function">XcmsQueryRed</code></a>.
</p><a id="idp46839308" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsQueryRed"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsQueryRed</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsColorFormat<var class="pdparam"> target_format</var>, XcmsColor<var class="pdparam"> *color_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>target_format</em></span>
    </span></p></td><td><p>
Specifies the target color specification format.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_return</em></span>
    </span></p></td><td><p>
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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsQueryRed"><code class="function">XcmsQueryRed</code></a>
function returns the color specification in the specified target format
for full-intensity red while green and blue are zero.
</p><p>


To obtain the color specification for white
(full-intensity red, green, and blue), use
<a class="xref" href="#XcmsQueryWhite"><code class="function">XcmsQueryWhite</code></a>.
</p><a id="idp46849316" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsQueryWhite"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsQueryWhite</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsColorFormat<var class="pdparam"> target_format</var>, XcmsColor<var class="pdparam"> *color_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>target_format</em></span>
    </span></p></td><td><p>
Specifies the target color specification format.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_return</em></span>
    </span></p></td><td><p>
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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsQueryWhite"><code class="function">XcmsQueryWhite</code></a>
function returns the color specification in the specified target format
for full-intensity red, green, and blue.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="CIELab_Queries"></a>CIELab Queries</h3></div></div></div><p>

The following equations are useful in describing the CIELab query functions:

delim %%

</p><p>

<a id="idp46860540" class="indexterm"></a>
<a id="idp46860980" class="indexterm"></a>
<a id="idp46861556" class="indexterm"></a>
<a id="idp46861988" class="indexterm"></a>
</p><pre class="literallayout">
%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%

%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]%
</pre><p>

To obtain the <acronym class="acronym">CIE</acronym> L*a*b* coordinates of maximum Psychometric Chroma
for a given Psychometric Hue Angle and <acronym class="acronym">CIE</acronym> metric lightness (L*), use
<a class="xref" href="#XcmsCIELabQueryMaxC"><code class="function">XcmsCIELabQueryMaxC</code></a>.
</p><a id="idp46864436" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsCIELabQueryMaxC"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsCIELabQueryMaxC</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsFloat<var class="pdparam"> hue_angle</var>, XcmsFloat<var class="pdparam"> L_star</var>, XcmsColor<var class="pdparam"> *color_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hue_angle</em></span>
    </span></p></td><td><p>
Specifies the hue angle (in degrees) at which to find maximum chroma.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>L_star</em></span>
    </span></p></td><td><p>
Specifies the lightness (L*) at which to find maximum chroma.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_return</em></span>
    </span></p></td><td><p>
Returns the <acronym class="acronym">CIE</acronym> 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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsCIELabQueryMaxC"><code class="function">XcmsCIELabQueryMaxC</code></a>
function, given a hue angle and lightness,
finds the point of maximum chroma displayable by the screen.
It returns this point in <acronym class="acronym">CIE</acronym> L*a*b* coordinates.
</p><p>


To obtain the <acronym class="acronym">CIE</acronym> L*a*b* coordinates of maximum <acronym class="acronym">CIE</acronym> metric lightness (L*)
for a given Psychometric Hue Angle and Psychometric Chroma, use
<a class="xref" href="#XcmsCIELabQueryMaxL"><code class="function">XcmsCIELabQueryMaxL</code></a>.
</p><a id="idp46877212" class="indexterm"></a><a id="idp46877652" class="indexterm"></a><a id="idp46878228" class="indexterm"></a><a id="idp46878948" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsCIELabQueryMaxL"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsCIELabQueryMaxL</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsFloat<var class="pdparam"> hue_angle</var>, XcmsFloat<var class="pdparam"> chroma</var>, XcmsColor<var class="pdparam"> *color_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hue_angle</em></span>
    </span></p></td><td><p>
Specifies the hue angle (in degrees) at which to find maximum lightness.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>chroma</em></span>
    </span></p></td><td><p>
Specifies the chroma at which to find maximum lightness.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_return</em></span>
    </span></p></td><td><p>
Returns the <acronym class="acronym">CIE</acronym> 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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsCIELabQueryMaxL"><code class="function">XcmsCIELabQueryMaxL</code></a>
function, given a hue angle and chroma,
finds the point in <acronym class="acronym">CIE</acronym> L*a*b* color space of maximum 
lightness (L*) displayable by the screen.
It returns this point in <acronym class="acronym">CIE</acronym> L*a*b* coordinates.
An 
<span class="symbol">XcmsFailure</span>
return value usually indicates that the given chroma
is beyond maximum for the given hue angle.

</p><p>

To obtain the <acronym class="acronym">CIE</acronym> L*a*b* coordinates of maximum Psychometric Chroma
for a given Psychometric Hue Angle, use
<a class="xref" href="#XcmsCIELabQueryMaxLC"><code class="function">XcmsCIELabQueryMaxLC</code></a>.
</p><a id="idp46892068" class="indexterm"></a><a id="idp46892508" class="indexterm"></a><a id="idp46892940" class="indexterm"></a><a id="idp46893516" class="indexterm"></a><a id="idp46894092" class="indexterm"></a><a id="idp46894812" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsCIELabQueryMaxLC"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsCIELabQueryMaxLC</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsFloat<var class="pdparam"> hue_angle</var>, XcmsColor<var class="pdparam"> *color_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hue_angle</em></span>
    </span></p></td><td><p>
Specifies the hue angle (in degrees) at which to find maximum chroma.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_return</em></span>
    </span></p></td><td><p>
Returns the <acronym class="acronym">CIE</acronym> 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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsCIELabQueryMaxLC"><code class="function">XcmsCIELabQueryMaxLC</code></a>
function, given a hue angle,
finds the point of maximum chroma displayable by the screen.
It returns this point in <acronym class="acronym">CIE</acronym> L*a*b* coordinates.

</p><p>

To obtain the <acronym class="acronym">CIE</acronym> L*a*b* coordinates of minimum <acronym class="acronym">CIE</acronym> metric lightness (L*)
for a given Psychometric Hue Angle and Psychometric Chroma, use
<a class="xref" href="#XcmsCIELabQueryMinL"><code class="function">XcmsCIELabQueryMinL</code></a>.
</p><a id="idp46905812" class="indexterm"></a><a id="idp46906252" class="indexterm"></a><a id="idp46906828" class="indexterm"></a><a id="idp46907548" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsCIELabQueryMinL"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsCIELabQueryMinL</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsFloat<var class="pdparam"> hue_angle</var>, XcmsFloat<var class="pdparam"> chroma</var>, XcmsColor<var class="pdparam"> *color_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hue_angle</em></span>
    </span></p></td><td><p>
Specifies the hue angle (in degrees) at which to find minimum lightness.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>chroma</em></span>
    </span></p></td><td><p>
Specifies the chroma at which to find minimum lightness.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_return</em></span>
    </span></p></td><td><p>
Returns the <acronym class="acronym">CIE</acronym> 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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsCIELabQueryMinL"><code class="function">XcmsCIELabQueryMinL</code></a>
function, given a hue angle and chroma,
finds the point of minimum lightness (L*) displayable by the screen.
It returns this point in <acronym class="acronym">CIE</acronym> L*a*b* coordinates.
An 
<span class="symbol">XcmsFailure</span>
return value usually indicates that the given chroma
is beyond maximum for the given hue angle.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="CIELuv_Queries"></a>CIELuv Queries</h3></div></div></div><p>

The following equations are useful in describing the CIELuv query functions:

delim %%

</p><p>

<a id="idp46921364" class="indexterm"></a>
<a id="idp46921804" class="indexterm"></a>
<a id="idp46922380" class="indexterm"></a>
<a id="idp46922812" class="indexterm"></a>
</p><pre class="literallayout">
%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%

%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]%
</pre><p>

</p><p>

To obtain the <acronym class="acronym">CIE</acronym> L*u*v* coordinates of maximum Psychometric Chroma
for a given Psychometric Hue Angle and <acronym class="acronym">CIE</acronym> metric lightness (L*), use
<a class="xref" href="#XcmsCIELuvQueryMaxC"><code class="function">XcmsCIELuvQueryMaxC</code></a>.
</p><a id="idp46925644" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsCIELuvQueryMaxC"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsCIELuvQueryMaxC</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsFloat<var class="pdparam"> hue_angle</var>, XcmsFloat<var class="pdparam"> L_star</var>, XcmsColor<var class="pdparam"> *color_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hue_angle</em></span>
    </span></p></td><td><p>
Specifies the hue angle (in degrees) at which to find maximum chroma.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>L_star</em></span>
    </span></p></td><td><p>
Specifies the lightness (L*) at which to find maximum chroma.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_return</em></span>
    </span></p></td><td><p>
Returns the <acronym class="acronym">CIE</acronym> 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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsCIELuvQueryMaxC"><code class="function">XcmsCIELuvQueryMaxC</code></a>
function, given a hue angle and lightness,
finds the point of maximum chroma displayable by the screen.
It returns this point in <acronym class="acronym">CIE</acronym> L*u*v* coordinates.

</p><p>

To obtain the <acronym class="acronym">CIE</acronym> L*u*v* coordinates of maximum <acronym class="acronym">CIE</acronym> metric lightness (L*)
for a given Psychometric Hue Angle and Psychometric Chroma, use
<a class="xref" href="#XcmsCIELuvQueryMaxL"><code class="function">XcmsCIELuvQueryMaxL</code></a>.
</p><a id="idp46938452" class="indexterm"></a><a id="idp46938892" class="indexterm"></a><a id="idp46939468" class="indexterm"></a><a id="idp46940188" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsCIELuvQueryMaxL"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsCIELuvQueryMaxL</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsFloat<var class="pdparam"> hue_angle</var>, XcmsFloat<var class="pdparam"> chroma</var>, XcmsColor<var class="pdparam"> *color_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hue_angle</em></span>
    </span></p></td><td><p>
Specifies the hue angle (in degrees) at which to find maximum lightness.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>L_star</em></span>
    </span></p></td><td><p>
Specifies the lightness (L*) at which to find maximum lightness.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_return</em></span>
    </span></p></td><td><p>
Returns the <acronym class="acronym">CIE</acronym> 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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsCIELuvQueryMaxL"><code class="function">XcmsCIELuvQueryMaxL</code></a>
function, given a hue angle and chroma,
finds the point in <acronym class="acronym">CIE</acronym> L*u*v* color space of maximum 
lightness (L*) displayable by the screen.
It returns this point in <acronym class="acronym">CIE</acronym> L*u*v* coordinates.
An 
<span class="symbol">XcmsFailure</span>
return value usually indicates that the given chroma
is beyond maximum for the given hue angle.

</p><p>

To obtain the <acronym class="acronym">CIE</acronym> L*u*v* coordinates of maximum Psychometric Chroma
for a given Psychometric Hue Angle, use
<a class="xref" href="#XcmsCIELuvQueryMaxLC"><code class="function">XcmsCIELuvQueryMaxLC</code></a>.
</p><a id="idp46953284" class="indexterm"></a><a id="idp46953724" class="indexterm"></a><a id="idp46954156" class="indexterm"></a><a id="idp46954732" class="indexterm"></a><a id="idp46955308" class="indexterm"></a><a id="idp46956028" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsCIELuvQueryMaxLC"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsCIELuvQueryMaxLC</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsFloat<var class="pdparam"> hue_angle</var>, XcmsColor<var class="pdparam"> *color_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hue_angle</em></span>
    </span></p></td><td><p>
Specifies the hue angle (in degrees) at which to find maximum chroma.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_return</em></span>
    </span></p></td><td><p>
Returns the <acronym class="acronym">CIE</acronym> 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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsCIELuvQueryMaxLC"><code class="function">XcmsCIELuvQueryMaxLC</code></a>
function, given a hue angle,
finds the point of maximum chroma displayable by the screen.
It returns this point in <acronym class="acronym">CIE</acronym> L*u*v* coordinates.

</p><p>

To obtain the <acronym class="acronym">CIE</acronym> L*u*v* coordinates of minimum <acronym class="acronym">CIE</acronym> metric lightness (L*)
for a given Psychometric Hue Angle and Psychometric Chroma, use
<a class="xref" href="#XcmsCIELuvQueryMinL"><code class="function">XcmsCIELuvQueryMinL</code></a>.
</p><a id="idp46967028" class="indexterm"></a><a id="idp46967468" class="indexterm"></a><a id="idp46968044" class="indexterm"></a><a id="idp46968764" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsCIELuvQueryMinL"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsCIELuvQueryMinL</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsFloat<var class="pdparam"> hue_angle</var>, XcmsFloat<var class="pdparam"> chroma</var>, XcmsColor<var class="pdparam"> *color_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hue_angle</em></span>
    </span></p></td><td><p>
Specifies the hue angle (in degrees) at which to find minimum lightness.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>chroma</em></span>
    </span></p></td><td><p>
Specifies the chroma at which to find minimum lightness.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_return</em></span>
    </span></p></td><td><p>
Returns the <acronym class="acronym">CIE</acronym> 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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsCIELuvQueryMinL"><code class="function">XcmsCIELuvQueryMinL</code></a>
function, given a hue angle and chroma,
finds the point of minimum lightness (L*) displayable by the screen.
It returns this point in <acronym class="acronym">CIE</acronym> L*u*v* coordinates.
An 
<span class="symbol">XcmsFailure</span>
return value usually indicates that the given chroma
is beyond maximum for the given hue angle.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="TekHVC_Queries"></a>TekHVC Queries</h3></div></div></div><p>

To obtain the maximum Chroma for a given Hue and Value, use
<a class="xref" href="#XcmsTekHVCQueryMaxC"><code class="function">XcmsTekHVCQueryMaxC</code></a>.
</p><a id="idp46982404" class="indexterm"></a><a id="idp46982828" class="indexterm"></a><a id="idp46983396" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsTekHVCQueryMaxC"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsTekHVCQueryMaxC</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsFloat<var class="pdparam"> hue</var>, XcmsFloat<var class="pdparam"> value</var>, XcmsColor<var class="pdparam"> *color_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hue</em></span>
    </span></p></td><td><p>
Specifies the Hue in which to find the maximum Chroma.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>value</em></span>
    </span></p></td><td><p>
Specifies the Value in which to find the maximum Chroma.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_return</em></span>
    </span></p></td><td><p>
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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsTekHVCQueryMaxC"><code class="function">XcmsTekHVCQueryMaxC</code></a>
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.

</p><p>

To obtain the maximum Value for a given Hue and Chroma, use
<a class="xref" href="#XcmsTekHVCQueryMaxV"><code class="function">XcmsTekHVCQueryMaxV</code></a>.
</p><a id="idp46995292" class="indexterm"></a><a id="idp46995716" class="indexterm"></a><a id="idp46996284" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsTekHVCQueryMaxV"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsTekHVCQueryMaxV</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsFloat<var class="pdparam"> hue</var>, XcmsFloat<var class="pdparam"> chroma</var>, XcmsColor<var class="pdparam"> *color_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hue</em></span>
    </span></p></td><td><p>
Specifies the Hue in which to find the maximum Value.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>chroma</em></span>
    </span></p></td><td><p>
Specifies the chroma at which to find maximum Value.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_return</em></span>
    </span></p></td><td><p>
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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsTekHVCQueryMaxV"><code class="function">XcmsTekHVCQueryMaxV</code></a>
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.

</p><p>

To obtain the maximum Chroma and Value at which it is reached
for a specified Hue, use
<a class="xref" href="#XcmsTekHVCQueryMaxVC"><code class="function">XcmsTekHVCQueryMaxVC</code></a>.
</p><a id="idp47008196" class="indexterm"></a><a id="idp47008620" class="indexterm"></a><a id="idp47009044" class="indexterm"></a><a id="idp47009612" class="indexterm"></a><a id="idp47010180" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsTekHVCQueryMaxVC"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsTekHVCQueryMaxVC</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsFloat<var class="pdparam"> hue</var>, XcmsColor<var class="pdparam"> *color_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hue</em></span>
    </span></p></td><td><p>
Specifies the Hue in which to find the maximum Chroma.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_return</em></span>
    </span></p></td><td><p>
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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsTekHVCQueryMaxVC"><code class="function">XcmsTekHVCQueryMaxVC</code></a>
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.

</p><p>

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
<a class="xref" href="#XcmsTekHVCQueryMaxVSamples"><code class="function">XcmsTekHVCQueryMaxVSamples</code></a>.
</p><a id="idp47020540" class="indexterm"></a><a id="idp47020964" class="indexterm"></a><a id="idp47021388" class="indexterm"></a><a id="idp47021956" class="indexterm"></a><a id="idp47022524" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsTekHVCQueryMaxVSamples"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsTekHVCQueryMaxVSamples</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsFloat<var class="pdparam"> hue</var>, XcmsColor<var class="pdparam"> colors_return[]</var>, unsignedint<var class="pdparam"> nsamples</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hue</em></span>
    </span></p></td><td><p>
Specifies the Hue for maximum Chroma/Value samples.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nsamples</em></span>
    </span></p></td><td><p>
Specifies the number of samples.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colors_return</em></span>
    </span></p></td><td><p>
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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsTekHVCQueryMaxVSamples"><code class="function">XcmsTekHVCQueryMaxVSamples</code></a>
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.

</p><p>

To obtain the minimum Value for a given Hue and Chroma, use
<a class="xref" href="#XcmsTekHVCQueryMinV"><code class="function">XcmsTekHVCQueryMinV</code></a>.
</p><a id="idp47034524" class="indexterm"></a><a id="idp47034948" class="indexterm"></a><a id="idp47035516" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsTekHVCQueryMinV"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsTekHVCQueryMinV</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsFloat<var class="pdparam"> hue</var>, XcmsFloat<var class="pdparam"> chroma</var>, XcmsColor<var class="pdparam"> *color_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
The CCC's Client White Point and white point adjustment procedures
are ignored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hue</em></span>
    </span></p></td><td><p>
Specifies the Hue in which to find the minimum Value.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>value</em></span>
    </span></p></td><td><p>
Specifies the Value in which to find the minimum Value.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_return</em></span>
    </span></p></td><td><p>
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.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsTekHVCQueryMinV"><code class="function">XcmsTekHVCQueryMinV</code></a>
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.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Color_Management_Extensions"></a>Color Management Extensions</h2></div></div></div><p>

The Xlib color management facilities can be extended in two ways:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Device-Independent Color Spaces
    </p></li><li class="listitem"><p>
Device-independent color spaces that are derivable to <acronym class="acronym">CIE</acronym> XYZ
space can be added using the
<a class="xref" href="#XcmsAddColorSpace"><code class="function">XcmsAddColorSpace</code></a>
function.
    </p></li><li class="listitem"><p>
Color Characterization Function Set
    </p></li><li class="listitem"><p>
A Color Characterization Function Set consists of
device-dependent color spaces and their functions that
convert between these color spaces and the <acronym class="acronym">CIE</acronym> XYZ
color space, bundled together for a specific class of output devices.
A function set can be added using the
<a class="xref" href="#XcmsAddFunctionSet"><code class="function">XcmsAddFunctionSet</code></a>
function.
    </p></li></ul></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Color_Spaces"></a>Color Spaces</h3></div></div></div><p>

The <acronym class="acronym">CIE</acronym> XYZ color space serves as the hub for all
conversions between device-independent and device-dependent color spaces.
Therefore, the knowledge to convert an 
<span class="structname">XcmsColor</span>
structure to and from <acronym class="acronym">CIE</acronym> XYZ format is associated with each color space.
For example, conversion from <acronym class="acronym">CIE</acronym> L*u*v* to <acronym class="acronym">RGB</acronym> requires the knowledge
to convert from <acronym class="acronym">CIE</acronym> L*u*v* to <acronym class="acronym">CIE</acronym> XYZ and from <acronym class="acronym">CIE</acronym> XYZ to <acronym class="acronym">RGB</acronym>.
This knowledge is stored as an array of functions that,
when applied in series, will convert the 
<span class="structname">XcmsColor</span>
structure to or from <acronym class="acronym">CIE</acronym> XYZ format.
This color specification conversion mechanism facilitates
the addition of color spaces.
</p><p>

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 <acronym class="acronym">CIE</acronym> L*u*v* is performed 
by intermediate conversion to <acronym class="acronym">CIE</acronym> u*v*Y and then to <acronym class="acronym">CIE</acronym> L*u*v*, 
thus bypassing conversion between <acronym class="acronym">CIE</acronym> u*v*Y and <acronym class="acronym">CIE</acronym> XYZ.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Adding_Device_Independent_Color_Spaces"></a>Adding Device-Independent Color Spaces</h3></div></div></div><p>

To add a device-independent color space, use
<a class="xref" href="#XcmsAddColorSpace"><code class="function">XcmsAddColorSpace</code></a>.
</p><a id="idp47060148" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsAddColorSpace"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsAddColorSpace</strong>(</code>XcmsColorSpace<var class="pdparam"> *color_space</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>color_space</em></span>
    </span></p></td><td><p>
Specifies the device-independent color space to add.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsAddColorSpace"><code class="function">XcmsAddColorSpace</code></a>
function makes a device-independent color space (actually an
<span class="structname">XcmsColorSpace</span>
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
<a class="xref" href="#XcmsFormatOfPrefix"><code class="function">XcmsFormatOfPrefix</code></a>
and
<a class="xref" href="#XcmsPrefixOfFormat"><code class="function">XcmsPrefixOfFormat</code></a>).
</p><p>

If the 
<span class="structname">XcmsColorSpace</span>
structure is already accessible in the color management system, 
<a class="xref" href="#XcmsAddColorSpace"><code class="function">XcmsAddColorSpace</code></a>
returns 
<span class="symbol">XcmsSuccess</span>.
</p><p>

Note that added 
<span class="structname">XcmsColorSpace</span>s
must be retained for reference by Xlib.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Querying_Color_Space_Format_and_Prefix"></a>Querying Color Space Format and Prefix</h3></div></div></div><p>

To obtain the format associated with the color space
associated with a specified color string prefix, use
<a class="xref" href="#XcmsFormatOfPrefix"><code class="function">XcmsFormatOfPrefix</code></a>.
</p><a id="idp47070844" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsFormatOfPrefix"></a><p><code class="funcdef">XcmsColorFormat <strong class="fsfunc">XcmsFormatOfPrefix</strong>(</code>char<var class="pdparam"> *prefix</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>prefix</em></span>
    </span></p></td><td><p>
Specifies the string that contains the color space prefix.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsFormatOfPrefix"><code class="function">XcmsFormatOfPrefix</code></a>
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,
<a class="xref" href="#XcmsFormatOfPrefix"><code class="function">XcmsFormatOfPrefix</code></a>
returns 
<span class="symbol">XcmsUndefinedFormat</span>.
</p><p>


To obtain the color string prefix associated with the color space
specified by a color format, use
<a class="xref" href="#XcmsPrefixOfFormat"><code class="function">XcmsPrefixOfFormat</code></a>.
</p><a id="idp47077748" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsPrefixOfFormat"></a><p><code class="funcdef">char *<strong class="fsfunc">XcmsPrefixOfFormat</strong>(</code>XcmsColorFormat<var class="pdparam"> format</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>format</em></span>
    </span></p></td><td><p>
Specifies the color specification format.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsPrefixOfFormat"><code class="function">XcmsPrefixOfFormat</code></a>
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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Creating_Additional_Color_Spaces"></a>Creating Additional Color Spaces</h3></div></div></div><p>

Color space specific information necessary 
for color space conversion and color string parsing is stored in an
<span class="structname">XcmsColorSpace</span>
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
<a class="xref" href="#XcmsAddColorSpace"><code class="function">XcmsAddColorSpace</code></a>
function.
</p><p>

If a new 
<span class="structname">XcmsColorSpace</span>
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
<a class="xref" href="#XcmsFormatOfPrefix"><code class="function">XcmsFormatOfPrefix</code></a>
and
<a class="xref" href="#XcmsPrefixOfFormat"><code class="function">XcmsPrefixOfFormat</code></a>).

</p><p>

</p><pre class="literallayout">


typedef (*XcmsConversionProc)();
typedef XcmsConversionProc *XcmsFuncListPtr;
		/* A NULL terminated list of function pointers*/

typedef struct _XcmsColorSpace {
	char *prefix;
	XcmsColorFormat format;
	XcmsParseStringProc parseString;
	XcmsFuncListPtr to_CIEXYZ;
	XcmsFuncListPtr from_CIEXYZ;
	int inverse_flag;
} XcmsColorSpace;
</pre><p>
</p><p>


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 <acronym class="acronym">CIE</acronym> XYZ,
and ``rgb'' or ``<acronym class="acronym">RGB</acronym>'' for <acronym class="acronym">RGB</acronym>.
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 
<span class="structname">XcmsColor</span>
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 
<span class="structname">XcmsColor</span>
structure from/to the current color space format to/from the <acronym class="acronym">CIE</acronym> 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:
</p><p>

</p><pre class="literallayout">
Given:  n = number of functions in each list

for each i, such that 0 &lt;= i &lt; n
    from_CIEXYZ[n - i - 1] is the inverse of to_CIEXYZ[i].
</pre><p>
</p><p>

This allows Xlib to use the shortest conversion path,
thus bypassing <acronym class="acronym">CIE</acronym> XYZ if possible (for example, TekHVC to <acronym class="acronym">CIE</acronym> L*u*v*).
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Parse_String_Callback"></a>Parse String Callback</h3></div></div></div><p>

The callback in the
<span class="structname">XcmsColorSpace</span>
structure for parsing a color string for the particular color space must
adhere to the following software interface specification:
</p><a id="idp47096148" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsParseStringProc"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsParseStringProc</strong>(</code>char<var class="pdparam"> *color_string</var>, XcmsColor<var class="pdparam"> *color_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>color_string</em></span>
    </span></p></td><td><p>
Specifies the color string to parse.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>color_return</em></span>
    </span></p></td><td><p>
Returns the color specification in the color space's format.
    </p></td></tr></tbody></table></div><p>


</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Color_Specification_Conversion_Callback"></a>Color Specification Conversion Callback</h3></div></div></div><p>

Callback functions in the
<span class="structname">XcmsColorSpace</span>
structure for converting a color specification between device-independent
spaces must adhere to the
following software interface specification:
</p><div class="funcsynopsis"><a id="ConversionProc"></a><p><code class="funcdef">Status <strong class="fsfunc">ConversionProc</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsColor<var class="pdparam"> *white_point</var>, XcmsColor<var class="pdparam"> *colors_in_out</var>, unsignedint<var class="pdparam"> ncolors</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>white_point</em></span>
    </span></p></td><td><p>
Specifies the white point associated with color specifications.
The pixel member should be ignored,
and the entire structure remain unchanged upon return.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colors_in_out</em></span>
    </span></p></td><td><p>
Specifies an array of color specifications.
Pixel members should be ignored and must remain unchanged upon return.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>ncolors</em></span>
    </span></p></td><td><p>
Specifies the number of 
<span class="structname">XcmsColor</span>
structures in the color-specification array.
    </p></td></tr></tbody></table></div><p>



Callback functions in the
<span class="structname">XcmsColorSpace</span>
structure for converting a color specification to or from a device-dependent
space must adhere to the
following software interface specification:
</p><div class="funcsynopsis"><p><code class="funcdef">Status <strong class="fsfunc">ConversionProc</strong>(</code>XcmsCCC<var class="pdparam"> ccc</var>, XcmsColor<var class="pdparam"> *colors_in_out</var>, unsignedint<var class="pdparam"> ncolors</var>, Bool<var class="pdparam"> compression_flags_return[]</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ccc</em></span>
    </span></p></td><td><p>
Specifies the CCC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colors_in_out</em></span>
    </span></p></td><td><p>
Specifies an array of color specifications.
Pixel members should be ignored and must remain unchanged upon return.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>ncolors</em></span>
    </span></p></td><td><p>
Specifies the number of 
<span class="structname">XcmsColor</span>
structures in the color-specification array.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>compression_flags_return</em></span>
    </span></p></td><td><p>
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
<span class="symbol">True</span>
should be stored at the corresponding index in this array;
otherwise, the array should not be modified.
    </p></td></tr></tbody></table></div><p>


Conversion functions are available globally for use by other color
spaces.
The conversion functions provided by Xlib are:
</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">Function</th><th align="left">Converts from</th><th align="left">Converts to</th></tr></thead><tbody><tr><td align="left"><code class="function">XcmsCIELabToCIEXYZ</code></td><td align="left"><span class="symbol">XcmsCIELabFormat</span></td><td align="left"><span class="symbol">XcmsCIEXYZFormat</span></td></tr><tr><td align="left"><code class="function">XcmsCIELuvToCIEuvY</code></td><td align="left"><span class="symbol">XcmsCIELuvFormat</span></td><td align="left"><span class="symbol">XcmsCIEuvYFormat</span></td></tr><tr><td align="left"><code class="function">XcmsCIEXYZToCIELab</code></td><td align="left"><span class="symbol">XcmsCIEXYZFormat</span></td><td align="left"><span class="symbol">XcmsCIELabFormat</span></td></tr><tr><td align="left"><code class="function">XcmsCIEXYZToCIEuvY</code></td><td align="left"><span class="symbol">XcmsCIEXYZFormat</span></td><td align="left"><span class="symbol">XcmsCIEuvYFormat</span></td></tr><tr><td align="left"><code class="function">XcmsCIEXYZToCIExyY</code></td><td align="left"><span class="symbol">XcmsCIEXYZFormat</span></td><td align="left"><span class="symbol">XcmsCIExyYFormat</span></td></tr><tr><td align="left"><code class="function">XcmsCIEXYZToRGBi</code></td><td align="left"><span class="symbol">XcmsCIEXYZFormat</span></td><td align="left"><span class="symbol">XcmsRGBiFormat</span></td></tr><tr><td align="left"><code class="function">XcmsCIEuvYToCIELuv</code></td><td align="left"><span class="symbol">XcmsCIEuvYFormat</span></td><td align="left"><span class="symbol">XcmsCIELabFormat</span></td></tr><tr><td align="left"><code class="function">XcmsCIEuvYToCIEXYZ</code></td><td align="left"><span class="symbol">XcmsCIEuvYFormat</span></td><td align="left"><span class="symbol">XcmsCIEXYZFormat</span></td></tr><tr><td align="left"><code class="function">XcmsCIEuvYToTekHVC</code></td><td align="left"><span class="symbol">XcmsCIEuvYFormat</span></td><td align="left"><span class="symbol">XcmsTekHVCFormat</span></td></tr><tr><td align="left"><code class="function">XcmsCIExyYToCIEXYZ</code></td><td align="left"><span class="symbol">XcmsCIExyYFormat</span></td><td align="left"><span class="symbol">XcmsCIEXYZFormat</span></td></tr><tr><td align="left"><code class="function">XcmsRGBToRGBi</code></td><td align="left"><span class="symbol">XcmsRGBFormat</span></td><td align="left"><span class="symbol">XcmsRGBiFormat</span></td></tr><tr><td align="left"><code class="function">XcmsRGBiToCIEXYZ</code></td><td align="left"><span class="symbol">XcmsRGBiFormat</span></td><td align="left"><span class="symbol">XcmsCIEXYZFormat</span></td></tr><tr><td align="left"><code class="function">XcmsRGBiToRGB</code></td><td align="left"><span class="symbol">XcmsRGBiFormat</span></td><td align="left"><span class="symbol">XcmsRGBFormat</span></td></tr><tr><td align="left"><code class="function">XcmsTekHVCToCIEuvY</code></td><td align="left"><span class="symbol">XcmsTekHVCFormat</span></td><td align="left"><span class="symbol">XcmsCIEuvYFormat</span></td></tr></tbody></table></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Function_Sets"></a>Function Sets</h3></div></div></div><a id="idp47147956" class="indexterm"></a><a id="idp47148388" class="indexterm"></a><p>

Functions to convert between device-dependent color spaces
and <acronym class="acronym">CIE</acronym> 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 <acronym class="acronym">CIE</acronym> 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.
<a id="idp47150380" class="indexterm"></a>
For details about how color characterization data is
stored in root window properties,
see <span class="olink">the
section on Device Color Characterization in the
<em class="citetitle">Inter-Client Communication Conventions Manual</em></span>.
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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Adding_Function_Sets"></a>Adding Function Sets</h3></div></div></div><p>

To add a function set, use
<a class="xref" href="#XcmsAddFunctionSet"><code class="function">XcmsAddFunctionSet</code></a>.
</p><a id="idp47154060" class="indexterm"></a><div class="funcsynopsis"><a id="XcmsAddFunctionSet"></a><p><code class="funcdef">Status <strong class="fsfunc">XcmsAddFunctionSet</strong>(</code>XcmsFunctionSet<var class="pdparam"> *function_set</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>function_set</em></span>
    </span></p></td><td><p>
Specifies the function set to add.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XcmsAddFunctionSet"><code class="function">XcmsAddFunctionSet</code></a>
function adds a function set to the color management system.
If the function set uses device-dependent 
<span class="structname">XcmsColorSpace</span>
structures not accessible in the color management system,
<a class="xref" href="#XcmsAddFunctionSet"><code class="function">XcmsAddFunctionSet</code></a>
adds them.
If an added
<span class="structname">XcmsColorSpace</span>
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 
<a class="xref" href="#XcmsFormatOfPrefix"><code class="function">XcmsFormatOfPrefix</code></a>
and
<a class="xref" href="#XcmsPrefixOfFormat"><code class="function">XcmsPrefixOfFormat</code></a>).
</p><p>

Additional function sets should be added before any calls to other
Xlib routines are made.
If not, the 
<span class="structname">XcmsPerScrnInfo</span>
member of a previously created 
<span class="structname">XcmsCCC</span>
does not have the opportunity to initialize
with the added function set.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Creating_Additional_Function_Sets"></a>Creating Additional Function Sets</h3></div></div></div><p>

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
<span class="structname">XcmsColorSpace</span>
structures and a means to read and store a 
screen's color characterization data.
This data is stored in an
<span class="structname">XcmsFunctionSet</span>
structure.
A handle to this structure (that is, by means of global variable)
is usually made accessible to the client program for use with
<a class="xref" href="#XcmsAddFunctionSet"><code class="function">XcmsAddFunctionSet</code></a>.
</p><p>

If a function set uses new device-dependent 
<span class="structname">XcmsColorSpace</span>
structures,
they will be transparently processed into the color management system.
Function sets can share an 
<span class="structname">XcmsColorSpace</span>
structure for a device-dependent color space.
In addition, multiple 
<span class="structname">XcmsColorSpace</span>
structures are allowed for a device-dependent color space;
however, a function set can reference only one of them.
These 
<span class="structname">XcmsColorSpace</span>
structures will differ in the functions to convert to and from <acronym class="acronym">CIE</acronym> XYZ,
thus tailored for the specific function set.

</p><p>

</p><pre class="literallayout">


typedef struct _XcmsFunctionSet {
	XcmsColorSpace **DDColorSpaces;
	XcmsScreenInitProc screenInitProc;
	XcmsScreenFreeProc screenFreeProc;
} XcmsFunctionSet;
</pre><p>
</p><p>


The DDColorSpaces member is a pointer to a NULL terminated list
of pointers to 
<span class="structname">XcmsColorSpace</span>
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 
<span class="structname">XcmsPerScrnInfo</span>
structure for a particular screen.
</p><p>

The screen initialization callback must adhere to the following software
interface specification:
<a id="idp47170588" class="indexterm"></a>

</p><div class="funcsynopsis"><p><code class="funcdef">typedef Status <strong class="fsfunc">(*XcmsScreenInitProc</strong>)(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen_number</var>, ScmsPerScrnInfo<var class="pdparam"> *screen_info</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_info</em></span>
    </span></p></td><td><p>
Specifies the 
<span class="structname">XcmsPerScrnInfo</span>
structure, which contains the per screen information.
    </p></td></tr></tbody></table></div><p>


The screen initialization callback in the
<span class="structname">XcmsFunctionSet</span>
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
<span class="structname">XcmsPerScrnInfo</span>
structure.
<a id="idp47179540" class="indexterm"></a>
<a id="idp47179972" class="indexterm"></a>
If successful, the procedure fills in the 
<span class="structname">XcmsPerScrnInfo</span>
structure as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
It sets the screenData member to the address 
of the created device profile data structure 
(contents known only by the function set).
    </p></li><li class="listitem"><p>
It next sets the screenWhitePoint member.
    </p></li><li class="listitem"><p>
It next sets the functionSet member to the address of the
<span class="structname">XcmsFunctionSet</span>
structure.
    </p></li><li class="listitem"><p>
It then sets the state member to 
<span class="symbol">XcmsInitSuccess</span>
and finally returns
<span class="symbol">XcmsSuccess</span>.
    </p></li></ul></div><p>

If unsuccessful, the procedure sets the state member to 
<span class="symbol">XcmsInitFailure</span>
and returns
<span class="symbol">XcmsFailure</span>.
</p><p>

The
<span class="structname">XcmsPerScrnInfo</span>
structure contains:

</p><p>

</p><pre class="literallayout">


typedef struct _XcmsPerScrnInfo {
	XcmsColor screenWhitePoint;
	XPointer functionSet;
	XPointer screenData;
	unsigned char state;
	char pad[3];
} XcmsPerScrnInfo;
</pre><p>
</p><p>


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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<span class="symbol">XcmsInitNone</span>
indicates initialization has not been previously attempted.
    </p></li><li class="listitem"><p>
<span class="symbol">XcmsInitFailure</span>
indicates initialization has been previously attempted but failed.
    </p></li><li class="listitem"><p>
<span class="symbol">XcmsInitSuccess</span>
indicates initialization has been previously attempted and succeeded.
    </p></li></ul></div><p>

The screen free callback must adhere to the following software
interface specification:
</p><div class="funcsynopsis"><p><code class="funcdef">typedef void (*XcmsScreenFreeProc)(</code>XPointer<var class="pdparam"> screenData</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screenData</em></span>
    </span></p></td><td><p>
Specifies the data to be freed.
    </p></td></tr></tbody></table></div><p>


This function is called to free the screenData stored in an
<span class="structname">XcmsPerScrnInfo</span>
structure.


</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Graphics_Context_Functions"></a>Chapter 7. Graphics Context Functions</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Manipulating_Graphics_ContextState">Manipulating Graphics Context/State</a></span></dt><dt><span class="sect1"><a href="#Using_Graphics_Context_Convenience_Routines">Using Graphics Context Convenience Routines</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Setting_the_Foreground_Background_Function_or_Plane_Mask">Setting the Foreground, Background, Function, or Plane Mask</a></span></dt><dt><span class="sect2"><a href="#Setting_the_Line_Attributes_and_Dashes">Setting the Line Attributes and Dashes</a></span></dt><dt><span class="sect2"><a href="#Setting_the_Fill_Style_and_Fill_Rule">Setting the Fill Style and Fill Rule</a></span></dt><dt><span class="sect2"><a href="#Setting_the_Fill_Tile_and_Stipple">Setting the Fill Tile and Stipple</a></span></dt><dt><span class="sect2"><a href="#Setting_the_Current_Font">Setting the Current Font</a></span></dt><dt><span class="sect2"><a href="#Setting_the_Clip_Region">Setting the Clip Region</a></span></dt><dt><span class="sect2"><a href="#Setting_the_Arc_Mode_Subwindow_Mode_and_Graphics_Exposure">Setting the Arc Mode, Subwindow Mode, and Graphics Exposure</a></span></dt></dl></dd></dl></div><p>
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.
</p><p>
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.
</p><p>
This chapter discusses how to:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Manipulate graphics context/state</p></li><li class="listitem"><p>Use graphics context convenience functions</p></li></ul></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Manipulating_Graphics_ContextState"></a>Manipulating Graphics Context/State</h2></div></div></div><p>

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.
</p><p>

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
<a class="xref" href="#XSetForeground"><code class="function">XSetForeground</code></a>
of a GC followed by a call to
<a class="xref" href="#XSetLineAttributes"><code class="function">XSetLineAttributes</code></a>
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. 
</p><p>

To set an attribute of a GC,
set the appropriate member of the
<span class="structname">XGCValues</span>
structure and OR in the corresponding value bitmask in your subsequent calls to
<a class="xref" href="#XCreateGC"><code class="function">XCreateGC</code></a>.
The symbols for the value mask bits and the
<span class="structname">XGCValues</span>
structure are:

</p><pre class="literallayout">
/* GC attribute value mask bits */

#define     GCFunction              (1L&lt;&lt;0)
#define     GCPlaneMask             (1L&lt;&lt;1)
#define     GCForeground            (1L&lt;&lt;2)
#define     GCBackground            (1L&lt;&lt;3)
#define     GCLineWidth             (1L&lt;&lt;4)
#define     GCLineStyle             (1L&lt;&lt;5)
#define     GCCapStyle              (1L&lt;&lt;6)
#define     GCJoinStyle             (1L&lt;&lt;7)
#define     GCFillStyle             (1L&lt;&lt;8)
#define     GCFillRule              (1L&lt;&lt;9)
#define     GCTile                  (1L&lt;&lt;10)
#define     GCStipple               (1L&lt;&lt;11)
#define     GCTileStipXOrigin       (1L&lt;&lt;12)
#define     GCTileStipYOrigin       (1L&lt;&lt;13)
#define     GCFont                  (1L&lt;&lt;14)
#define     GCSubwindowMode         (1L&lt;&lt;15)
#define     GCGraphicsExposures     (1L&lt;&lt;16)
#define     GCClipXOrigin           (1L&lt;&lt;17)
#define     GCClipYOrigin           (1L&lt;&lt;18)
#define     GCClipMask              (1L&lt;&lt;19)
#define     GCDashOffset            (1L&lt;&lt;20)
#define     GCDashList              (1L&lt;&lt;21)
#define     GCArcMode               (1L&lt;&lt;22)
</pre><pre class="literallayout">


/* Values */

typedef struct {
     int function;                 /* logical operation */
     unsigned long plane_mask;     /* plane mask */
     unsigned long foreground;     /* foreground pixel */
     unsigned long background;     /* background pixel */
     int line_width;               /* line width (in pixels) */
     int line_style;               /* LineSolid, LineOnOffDash, LineDoubleDash */
     int cap_style;                /* CapNotLast, CapButt, CapRound, CapProjecting */
     int join_style;               /* JoinMiter, JoinRound, JoinBevel */
     int fill_style;               /* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/
     int fill_rule;                /* EvenOddRule, WindingRule */
     int arc_mode;                 /* ArcChord, ArcPieSlice */
     Pixmap tile;                  /* tile pixmap for tiling operations */
     Pixmap stipple;               /* stipple 1 plane pixmap for stippling */
     int ts_x_origin;              /* offset for tile or stipple operations */
     int ts_y_origin
     Font font;                    /* default text font for text operations */
     int subwindow_mode;           /* ClipByChildren, IncludeInferiors */
     Bool graphics_exposures;      /* boolean, should exposures be generated */
     int clip_x_origin;            /* origin for clipping */
     int clip_y_origin;
     Pixmap clip_mask;             /* bitmap clipping; other calls for rects */
     int dash_offset;              /* patterned/dashed line information */
     char dashes;
} XGCValues;
</pre><p>


The default GC values are:
</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Component</th><th align="left">Default</th></tr></thead><tbody><tr><td align="left">function</td><td align="left"><span class="symbol">GXcopy</span></td></tr><tr><td align="left">plane_mask</td><td align="left">All ones</td></tr><tr><td align="left">foreground</td><td align="left">0</td></tr><tr><td align="left">background</td><td align="left">1</td></tr><tr><td align="left">line_width</td><td align="left">0</td></tr><tr><td align="left">line_style</td><td align="left"><span class="symbol">LineSolid</span></td></tr><tr><td align="left">cap_style</td><td align="left"><span class="symbol">CapButt</span></td></tr><tr><td align="left">join_style</td><td align="left"><span class="symbol">JoinMiter</span></td></tr><tr><td align="left">fill_style</td><td align="left"><span class="symbol">FillSolid</span></td></tr><tr><td align="left">fill_rule</td><td align="left"><span class="symbol">EvenOddRule</span></td></tr><tr><td align="left">arc_mode</td><td align="left"><span class="symbol">ArcPieSlice</span></td></tr><tr><td align="left">tile</td><td align="left">
      <p>Pixmap of unspecified size filled with foreground pixel</p>
      <p>(that is, client specified pixel if any, else 0)</p>
      <p>(subsequent changes to foreground do not affect this pixmap)</p>
      </td></tr><tr><td align="left">stipple</td><td align="left">Pixmap of unspecified size filled with ones</td></tr><tr><td align="left">ts_x_origin</td><td align="left">0</td></tr><tr><td align="left">ts_y_origin</td><td align="left">0</td></tr><tr><td align="left">font</td><td align="left">&lt;implementation dependent&gt;</td></tr><tr><td align="left">subwindow_mode</td><td align="left"><span class="symbol">ClipByChildren</span></td></tr><tr><td align="left">graphics_exposures</td><td align="left"><span class="symbol">True</span></td></tr><tr><td align="left">clip_x_origin</td><td align="left">0</td></tr><tr><td align="left">clip_y_origin</td><td align="left">0</td></tr><tr><td align="left">clip_mask</td><td align="left"><span class="symbol">None</span></td></tr><tr><td align="left">dash_offset</td><td align="left">0</td></tr><tr><td align="left">dashes</td><td align="left">4 (that is, the list [4, 4])</td></tr></tbody></table></div><p>

Note that foreground and background are not set to any values likely
to be useful in a window.
</p><p>

<a id="idp44366260" class="indexterm"></a>
<a id="idp44366692" class="indexterm"></a>
<a id="idp44367116" class="indexterm"></a>
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.
<span class="symbol">GXcopy</span>
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 
<code class="filename">&lt;X11/X.h&gt;</code>,
<a id="idp44368740" class="indexterm"></a>
<a id="idp44369636" class="indexterm"></a>
<a id="idp44370540" class="indexterm"></a>
are:
</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">Function Name</th><th align="left">Value</th><th align="left">Operation</th></tr></thead><tbody><tr><td align="left"><span class="symbol">GXclear</span></td><td align="left">0x0</td><td align="left">0</td></tr><tr><td align="left"><span class="symbol">GXand</span></td><td align="left">0x1</td><td align="left">src AND dst</td></tr><tr><td align="left"><span class="symbol">GXandReverse</span></td><td align="left">0x2</td><td align="left">src AND NOT dst</td></tr><tr><td align="left"><span class="symbol">GXcopy</span></td><td align="left">0x3</td><td align="left">src</td></tr><tr><td align="left"><span class="symbol">GXandInverted</span></td><td align="left">0x4</td><td align="left">(NOT src) AND dst</td></tr><tr><td align="left"><span class="symbol">GXnoop</span></td><td align="left">0x5</td><td align="left">dst</td></tr><tr><td align="left"><span class="symbol">GXxor</span></td><td align="left">0x6</td><td align="left">src XOR dst</td></tr><tr><td align="left"><span class="symbol">GXor</span></td><td align="left">0x7</td><td align="left">src OR dst</td></tr><tr><td align="left"><span class="symbol">GXnor</span></td><td align="left">0x8</td><td align="left">(NOT src) AND (NOT dst)</td></tr><tr><td align="left"><span class="symbol">GXequiv</span></td><td align="left">0x9</td><td align="left">(NOT src) XOR dst</td></tr><tr><td align="left"><span class="symbol">GXinvert</span></td><td align="left">0xa</td><td align="left">NOT dst</td></tr><tr><td align="left"><span class="symbol">GXorReverse</span></td><td align="left">0xb</td><td align="left">src OR (NOT dst)</td></tr><tr><td align="left"><span class="symbol">GXcopyInverted</span></td><td align="left">0xc</td><td align="left">NOT src</td></tr><tr><td align="left"><span class="symbol">GXorInverted</span></td><td align="left">0xd</td><td align="left">(NOT src) OR dst</td></tr><tr><td align="left"><span class="symbol">GXnand</span></td><td align="left">0xe</td><td align="left">(NOT src) OR (NOT dst)</td></tr><tr><td align="left"><span class="symbol">GXset</span></td><td align="left">0xf</td><td align="left">1</td></tr></tbody></table></div><p>

Many graphics operations depend on either pixel values or planes in a GC.
<a id="idp45163556" class="indexterm"></a>
The planes attribute is of type long, and it specifies which planes of the
destination are to be modified, one bit per plane.
<a id="idp45164100" class="indexterm"></a>
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.
</p><p>

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
<span class="symbol">AllPlanes</span>
can be used to refer to all planes of the screen simultaneously.
The result is computed by the following:
</p><p>

</p><pre class="literallayout">
((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))
</pre><p>
</p><p>

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).
</p><p>

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:
</p><p>

</p><pre class="literallayout">


[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)]
</pre><p>
</p><p>

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).
</p><p>

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. 
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
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.
    </p></li></ul></div><p>

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.
</p><p>

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.
</p><p>

The line-style defines which sections of a line are drawn:
</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term"><span class="symbol">LineSolid</span></span></p></td><td><p>The full path of the line is drawn.</p></td></tr><tr><td><p><span class="term"><span class="symbol">LineDoubleDash</span></span></p></td><td><p>
The full path of the line is drawn,
but the even dashes are filled differently
from the odd dashes (see fill-style) with 
<span class="symbol">CapButt</span>
style used where even and odd dashes meet.
      </p></td></tr><tr><td><p><span class="term"><span class="symbol">LineOnOffDash</span></span></p></td><td><p>
Only the even dashes are drawn,
and cap-style applies to 
all internal ends of the individual dashes,
except
<span class="symbol">CapNotLast</span>
is treated as
<span class="symbol">CapButt</span>.
      </p></td></tr></tbody></table></div><p>
The cap-style defines how the endpoints of a path are drawn:
</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term"><span class="symbol">CapNotLast</span></span></p></td><td><p>
This is equivalent to
<span class="symbol">CapButt</span>
except that for a line-width of zero the final endpoint is not drawn.
     </p></td></tr><tr><td><p><span class="term"><span class="symbol">CapButt</span></span></p></td><td><p>
The line is square at the endpoint (perpendicular to the slope of the line)
with no projection beyond.
      </p></td></tr><tr><td><p><span class="term"><span class="symbol">CapRound</span></span></p></td><td><p>
The line has a circular arc with the diameter equal to the line-width,
centered on the endpoint.
(This is equivalent to 
<span class="symbol">CapButt</span>
for line-width of zero).
      </p></td></tr><tr><td><p><span class="term"><span class="symbol">CapProjecting</span></span></p></td><td><p>
The line is square at the end, but the path continues beyond the endpoint
for a distance equal to half the line-width.
(This is equivalent to
<span class="symbol">CapButt</span>
for line-width of zero).
      </p></td></tr></tbody></table></div><p>
The join-style defines how corners are drawn for wide lines:
</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term"><span class="symbol">JoinMiter</span></span></p></td><td><p>
The outer edges of two lines extend to meet at an angle.
However, if the angle is less than 11 degrees,
then a
<span class="symbol">JoinBevel</span>
join-style is used instead.
      </p></td></tr><tr><td><p><span class="term"><span class="symbol">JoinRound</span></span></p></td><td><p>
The corner is a circular arc with the diameter equal to the line-width,
centered on the joinpoint.
      </p></td></tr><tr><td><p><span class="term"><span class="symbol">JoinBevel</span></span></p></td><td><p>
The corner has
<span class="symbol">CapButt</span>
endpoint styles with the triangular notch filled.
      </p></td></tr></tbody></table></div><p>

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:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><tbody><tr><td align="left"><span class="symbol">CapNotLast</span></td><td align="left">thin</td><td align="left">The results are device dependent,
      but the desired effect is that nothing is drawn.</td></tr><tr><td align="left"><span class="symbol">CapButt</span></td><td align="left">thin</td><td align="left">The results are device dependent,
      but the desired effect is that a single pixel is drawn.</td></tr><tr><td align="left"><span class="symbol">CapRound</span></td><td align="left">thin</td><td align="left">The results are the same as for
      <span class="symbol">CapButt</span> /thin.</td></tr><tr><td align="left"><span class="symbol">CapProjecting</span></td><td align="left">thin</td><td align="left">The results are the same as for
      <span class="symbol">CapButt</span> /thin.</td></tr><tr><td align="left"><span class="symbol">CapButt</span></td><td align="left">wide</td><td align="left">Nothing is drawn.</td></tr><tr><td align="left"><span class="symbol">CapRound</span></td><td align="left">wide</td><td align="left">The closed path is a circle, centered at the endpoint, and
      with the diameter equal to the line-width.</td></tr><tr><td align="left"><span class="symbol">CapProjecting</span></td><td align="left">wide</td><td align="left">The closed path is a square, aligned with the coordinate axes, centered at the
      endpoint, and with the sides equal to the line-width.</td></tr></tbody></table></div><p>

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.
</p><p>

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
<span class="errorname">BadMatch</span>
error results.
The stipple pixmap must have depth one and must have the same root as the
GC, or a 
<span class="errorname">BadMatch</span>
error results.  
For stipple operations where the fill-style is
<span class="symbol">FillStippled</span>
but not 
<span class="symbol">FillOpaqueStippled</span>,
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.
</p><p>

The fill-style defines the contents of the source for line, text, and
fill requests.  
For all text and fill requests (for example,
<a class="xref" href="#XDrawText"><code class="function">XDrawText</code></a>,
<a class="xref" href="#XDrawText16"><code class="function">XDrawText16</code></a>,
<a class="xref" href="#XFillRectangle"><code class="function">XFillRectangle</code></a>,
<a class="xref" href="#XFillPolygon"><code class="function">XFillPolygon</code></a>,
and
<a class="xref" href="#XFillArc"><code class="function">XFillArc</code></a>);
for line requests 
with line-style 
<span class="symbol">LineSolid</span>
(for example,
<a class="xref" href="#XDrawLine"><code class="function">XDrawLine</code></a>,
<a class="xref" href="#XDrawSegments"><code class="function">XDrawSegments</code></a>,
<a class="xref" href="#XDrawRectangle"><code class="function">XDrawRectangle</code></a>,
<a class="xref" href="#XDrawArc"><code class="function">XDrawArc</code></a>);
and for the even dashes for line requests with line-style 
<span class="symbol">LineOnOffDash</span>
or 
<span class="symbol">LineDoubleDash</span>,
the following apply:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left"><span class="symbol">FillSolid</span></td><td align="left">Foreground</td></tr><tr><td align="left"><span class="symbol">FillTiled</span></td><td align="left">Tile</td></tr><tr><td align="left"><span class="symbol">FillOpaqueStippled</span></td><td align="left">A tile with the same width and height as stipple,
      but with background everywhere stipple has a zero
      and with foreground everywhere stipple has a one</td></tr><tr><td align="left"><span class="symbol">FillStippled</span></td><td align="left">Foreground masked by stipple</td></tr></tbody></table></div><p>

When drawing lines with line-style
<span class="symbol">LineDoubleDash</span>,
the odd dashes are controlled by the fill-style in the following manner:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left"><span class="symbol">FillSolid</span></td><td align="left">Background</td></tr><tr><td align="left"><span class="symbol">FillTiled</span></td><td align="left">Same as for even dashes</td></tr><tr><td align="left"><span class="symbol">FillOpaqueStippled</span></td><td align="left">Same as for even dashes</td></tr><tr><td align="left"><span class="symbol">FillStippled</span></td><td align="left">Background masked by stipple</td></tr></tbody></table></div><p>

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.
</p><p>

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.
</p><p>

The dashes value is actually a simplified form of the
more general patterns that can be set with 
<a class="xref" href="#XSetDashes"><code class="function">XSetDashes</code></a>.
Specifying a
value of N is equivalent to specifying the two-element list [N, N] in 
<a class="xref" href="#XSetDashes"><code class="function">XSetDashes</code></a>.
The value must be nonzero,
or a
<span class="errorname">BadValue</span>
error results.
</p><p>

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
<span class="errorname">BadMatch</span>
error results.
If clip-mask is set to
<span class="symbol">None</span>,
the pixels are always drawn regardless of the clip origin.
The clip-mask also can be set by calling the
<a class="xref" href="#XSetClipRectangles"><code class="function">XSetClipRectangles</code></a>
or
<a class="xref" href="#XSetRegion"><code class="function">XSetRegion</code></a>
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.
</p><p>

You can set the subwindow-mode to
<span class="symbol">ClipByChildren</span>
or
<span class="symbol">IncludeInferiors</span>.
For 
<span class="symbol">ClipByChildren</span>,
both source and destination windows are
additionally clipped by all viewable 
<span class="symbol">InputOutput</span>
children.  
For 
<span class="symbol">IncludeInferiors</span>,
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 
<span class="symbol">IncludeInferiors</span>
on a window of one depth with mapped
inferiors of differing depth is not illegal, but the semantics are
undefined by the core protocol.
</p><p>

The fill-rule defines what pixels are inside (drawn) for
paths given in 
<a class="xref" href="#XFillPolygon"><code class="function">XFillPolygon</code></a>
requests and can be set to 
<span class="symbol">EvenOddRule</span>
or
<span class="symbol">WindingRule</span>.
For
<span class="symbol">EvenOddRule</span>,
a point is inside if
an infinite ray with the point as origin crosses the path an odd number
of times.  
For 
<span class="symbol">WindingRule</span>,
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.
</p><p>

For both 
<span class="symbol">EvenOddRule</span>
and
<span class="symbol">WindingRule</span>,
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).
</p><p>

The arc-mode controls filling in the 
<a class="xref" href="#XFillArcs"><code class="function">XFillArcs</code></a>
function and can be set to
<span class="symbol">ArcPieSlice</span>
or
<span class="symbol">ArcChord</span>.
For
<span class="symbol">ArcPieSlice</span>,
the arcs are pie-slice filled.
For
<span class="symbol">ArcChord</span>,
the arcs are chord filled.
</p><p>

The graphics-exposure flag controls 
<span class="symbol">GraphicsExpose</span>
event generation
for 
<a class="xref" href="#XCopyArea"><code class="function">XCopyArea</code></a>
and 
<a class="xref" href="#XCopyPlane"><code class="function">XCopyPlane</code></a>
requests (and any similar requests defined by extensions).
</p><p>


To create a new GC that is usable on a given screen with a 
depth of drawable, use
<a class="xref" href="#XCreateGC"><code class="function">XCreateGC</code></a>.
</p><a id="idp45234020" class="indexterm"></a><a id="idp45234604" class="indexterm"></a><div class="funcsynopsis"><a id="XCreateGC"></a><p><code class="funcdef">GC <strong class="fsfunc">XCreateGC</strong>(</code>Display <var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, unsignedlong<var class="pdparam"> valuemask</var>, XGCValues *<var class="pdparam">values</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>valuemask</em></span>
    </span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>values</em></span>
    </span></p></td><td><p>
Specifies any values as specified by the valuemask.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCreateGC"><code class="function">XCreateGC</code></a>
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
<span class="errorname">BadMatch</span>
error.
</p><p>

<a class="xref" href="#XCreateGC"><code class="function">XCreateGC</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadFont</span>,
<span class="errorname">BadMatch</span>,
<span class="errorname">BadPixmap</span>,
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To copy components from a source GC to a destination GC, use
<a class="xref" href="#XCopyGC"><code class="function">XCopyGC</code></a>.
</p><a id="idp45248564" class="indexterm"></a><div class="funcsynopsis"><a id="XCopyGC"></a><p><code class="funcdef"><strong class="fsfunc">XCopyGC</strong>(</code>Display<var class="pdparam"> *display</var>, GCsrc,<var class="pdparam"> dest</var>, unsignedlong<var class="pdparam"> valuemask</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>src</em></span>
    </span></p></td><td><p>
Specifies the components of the source GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>valuemask</em></span>
    </span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dest</em></span>
    </span></p></td><td><p>
Specifies the destination GC.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCopyGC"><code class="function">XCopyGC</code></a>
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
<span class="errorname">BadMatch</span>
error results.
The valuemask specifies which component to copy, as for
<a class="xref" href="#XCreateGC"><code class="function">XCreateGC</code></a>.
</p><p>

<a class="xref" href="#XCopyGC"><code class="function">XCopyGC</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadMatch</span>
errors.
</p><p>


To change the components in a given GC, use
<a class="xref" href="#XChangeGC"><code class="function">XChangeGC</code></a>.
</p><a id="idp45261652" class="indexterm"></a><div class="funcsynopsis"><a id="XChangeGC"></a><p><code class="funcdef"><strong class="fsfunc">XChangeGC</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, unsignedlong<var class="pdparam"> valuemask</var>, XGCValues<var class="pdparam"> *values</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>valuemask</em></span>
    </span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>values</em></span>
    </span></p></td><td><p>
Specifies any values as specified by the valuemask.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XChangeGC"><code class="function">XChangeGC</code></a>
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 
<a class="xref" href="#XCreateGC"><code class="function">XCreateGC</code></a>.
Changing the clip-mask overrides any previous 
<a class="xref" href="#XSetClipRectangles"><code class="function">XSetClipRectangles</code></a>
request on the context. 
Changing the dash-offset or dash-list
overrides any previous 
<a class="xref" href="#XSetDashes"><code class="function">XSetDashes</code></a>
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.
</p><p>

<a class="xref" href="#XChangeGC"><code class="function">XChangeGC</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadFont</span>,
<span class="errorname">BadGC</span>,
<span class="errorname">BadMatch</span>,
<span class="errorname">BadPixmap</span>,
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To obtain components of a given GC, use
<a class="xref" href="#XGetGCValues"><code class="function">XGetGCValues</code></a>.
</p><a id="idp45276788" class="indexterm"></a><div class="funcsynopsis"><a id="XGetGCValues"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetGCValues</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, unsignedlong<var class="pdparam"> valuemask</var>, XGCValues<var class="pdparam"> *values_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>valuemask</em></span>
    </span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>values_return</em></span>
    </span></p></td><td><p>
Returns the GC values in the specified
<span class="structname">XGCValues</span>
structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetGCValues"><code class="function">XGetGCValues</code></a>
function returns the components specified by valuemask for the specified GC.
If the valuemask contains a valid set of GC mask bits
(<span class="symbol">GCFunction</span>,
<span class="symbol">GCPlaneMask</span>,
<span class="symbol">GCForeground</span>,
<span class="symbol">GCBackground</span>,
<span class="symbol">GCLineWidth</span>,
<span class="symbol">GCLineStyle</span>,
<span class="symbol">GCCapStyle</span>,
<span class="symbol">GCJoinStyle</span>,
<span class="symbol">GCFillStyle</span>,
<span class="symbol">GCFillRule</span>,
<span class="symbol">GCTile</span>,
<span class="symbol">GCStipple</span>,
<span class="symbol">GCTileStipXOrigin</span>,
<span class="symbol">GCTileStipYOrigin</span>,
<span class="symbol">GCFont</span>,
<span class="symbol">GCSubwindowMode</span>,
<span class="symbol">GCGraphicsExposures</span>,
<span class="symbol">GCClipXOrigin</span>,
<span class="symbol">GCClipYOrigin</span>,
<span class="symbol">GCDashOffset</span>,
or
<span class="symbol">GCArcMode</span>)
and no error occurs,
<a class="xref" href="#XGetGCValues"><code class="function">XGetGCValues</code></a>
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
<span class="symbol">GCClipMask</span>
and 
<span class="symbol">GCDashList</span>
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
<span class="symbol">GCFont</span>,
<span class="symbol">GCTile</span>,
and
<span class="symbol">GCStipple</span>
if the component has never been explicitly set by the client.
</p><p>


To free a given GC, use
<a class="xref" href="#XFreeGC"><code class="function">XFreeGC</code></a>.
</p><a id="idp45844660" class="indexterm"></a><div class="funcsynopsis"><a id="XFreeGC"></a><p><code class="funcdef"><strong class="fsfunc">XFreeGC</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFreeGC"><code class="function">XFreeGC</code></a>
function destroys the specified GC as well as all the associated storage.
</p><p>

<a class="xref" href="#XFreeGC"><code class="function">XFreeGC</code></a>
can generate a
<span class="errorname">BadGC</span>
error.
</p><p>


To obtain the 
<span class="type">GContext</span>
resource ID for a given GC, use 
<a class="xref" href="#XGContextFromGC"><code class="function">XGContextFromGC</code></a>.
</p><a id="idp45853460" class="indexterm"></a><div class="funcsynopsis"><a id="XGContextFromGC"></a><p><code class="funcdef">GContext <strong class="fsfunc">XGContextFromGC</strong>(</code>GC<var class="pdparam"> gc</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC for which you want the resource ID.
    </p></td></tr></tbody></table></div><p>



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
<a class="xref" href="#XFlushGC"><code class="function">XFlushGC</code></a>.
</p><a id="idp45859012" class="indexterm"></a><div class="funcsynopsis"><a id="XFlushGC"></a><p><code class="funcdef">void <strong class="fsfunc">XFlushGC</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
    </p></td></tr></tbody></table></div><p>


</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Using_Graphics_Context_Convenience_Routines"></a>Using Graphics Context Convenience Routines</h2></div></div></div><p>

This section discusses how to set the:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Foreground, background, plane mask, or function components
    </p></li><li class="listitem"><p>
Line attributes and dashes components
    </p></li><li class="listitem"><p>
Fill style and fill rule components
    </p></li><li class="listitem"><p>
Fill tile and stipple components
    </p></li><li class="listitem"><p>
Font component
    </p></li><li class="listitem"><p>
Clip region component
    </p></li><li class="listitem"><p>
Arc mode, subwindow mode, and graphics exposure components
    </p></li></ul></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_the_Foreground_Background_Function_or_Plane_Mask"></a>Setting the Foreground, Background, Function, or Plane Mask</h3></div></div></div><p>

To set the foreground, background, plane mask, and function components
for a given GC, use
<a class="xref" href="#XSetState"><code class="function">XSetState</code></a>.
</p><a id="idp45872436" class="indexterm"></a><div class="funcsynopsis"><a id="XSetState"></a><p><code class="funcdef"><strong class="fsfunc">XSetState</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, unsignedlongforeground,<var class="pdparam"> background</var>, int<var class="pdparam"> function</var>, unsignedlong<var class="pdparam"> plane_mask</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>foreground</em></span>
    </span></p></td><td><p>
Specifies the foreground you want to set for the specified GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>background</em></span>
    </span></p></td><td><p>
Specifies the background you want to set for the specified GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>function</em></span>
    </span></p></td><td><p>
Specifies the function you want to set for the specified GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>plane_mask</em></span>
    </span></p></td><td><p>
Specifies the plane mask.

    </p></td></tr></tbody></table></div><p>


<a class="xref" href="#XSetState"><code class="function">XSetState</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To set the foreground of a given GC, use
<a class="xref" href="#XSetForeground"><code class="function">XSetForeground</code></a>.
</p><a id="idp45887524" class="indexterm"></a><div class="funcsynopsis"><a id="XSetForeground"></a><p><code class="funcdef"><strong class="fsfunc">XSetForeground</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, unsignedlong<var class="pdparam"> foreground</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>foreground</em></span>
    </span></p></td><td><p>
Specifies the foreground you want to set for the specified GC.
    </p></td></tr></tbody></table></div><p>


<a class="xref" href="#XSetForeground"><code class="function">XSetForeground</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadGC</span>
errors.
</p><p>


To set the background of a given GC, use
<a class="xref" href="#XSetBackground"><code class="function">XSetBackground</code></a>.
</p><a id="idp45897364" class="indexterm"></a><div class="funcsynopsis"><a id="XSetBackground"></a><p><code class="funcdef"><strong class="fsfunc">XSetBackground</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, unsignedlong<var class="pdparam"> background</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>background</em></span>
    </span></p></td><td><p>
Specifies the background you want to set for the specified GC.
    </p></td></tr></tbody></table></div><p>


<a class="xref" href="#XSetBackground"><code class="function">XSetBackground</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadGC</span>
errors.
</p><p>


To set the display function in a given GC, use
<a class="xref" href="#XSetFunction"><code class="function">XSetFunction</code></a>.
</p><a id="idp45907212" class="indexterm"></a><div class="funcsynopsis"><a id="XSetFunction"></a><p><code class="funcdef"><strong class="fsfunc">XSetFunction</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, int<var class="pdparam"> function</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>function</em></span>
    </span></p></td><td><p>
Specifies the function you want to set for the specified GC.
    </p></td></tr></tbody></table></div><p>


<a class="xref" href="#XSetFunction"><code class="function">XSetFunction</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To set the plane mask of a given GC, use
<a class="xref" href="#XSetPlaneMask"><code class="function">XSetPlaneMask</code></a>.
</p><a id="idp45917260" class="indexterm"></a><div class="funcsynopsis"><a id="XSetPlaneMask"></a><p><code class="funcdef"><strong class="fsfunc">XSetPlaneMask</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, unsignedlong<var class="pdparam"> plane_mask</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>plane_mask</em></span>
    </span></p></td><td><p>
Specifies the plane mask.

    </p></td></tr></tbody></table></div><p>


<a class="xref" href="#XSetPlaneMask"><code class="function">XSetPlaneMask</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadGC</span>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_the_Line_Attributes_and_Dashes"></a>Setting the Line Attributes and Dashes</h3></div></div></div><p>

To set the line drawing components of a given GC, use
<a class="xref" href="#XSetLineAttributes"><code class="function">XSetLineAttributes</code></a>.
</p><a id="idp45928284" class="indexterm"></a><div class="funcsynopsis"><a id="XSetLineAttributes"></a><p><code class="funcdef"><strong class="fsfunc">XSetLineAttributes</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, unsignedint<var class="pdparam"> line_width</var>, int<var class="pdparam"> line_style</var>, int<var class="pdparam"> cap_style</var>, int<var class="pdparam"> join_style</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>line_width</em></span>
    </span></p></td><td><p>
Specifies the line-width you want to set for the specified GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>line_style</em></span>
    </span></p></td><td><p>
Specifies the line-style you want to set for the specified GC.
You can pass
<span class="symbol">LineSolid</span>,
<span class="symbol">LineOnOffDash</span>,
or
<span class="symbol">LineDoubleDash</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>cap_style</em></span>
    </span></p></td><td><p>
Specifies the line-style and cap-style you want to set for the specified GC.
You can pass
<span class="symbol">CapNotLast</span>,
<span class="symbol">CapButt</span>,
<span class="symbol">CapRound</span>,
or
<span class="symbol">CapProjecting</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>join_style</em></span>
    </span></p></td><td><p>
Specifies the line join-style you want to set for the specified GC.
You can pass
<span class="symbol">JoinMiter</span>,
<span class="symbol">JoinRound</span>,
or
<span class="symbol">JoinBevel</span>.
    </p></td></tr></tbody></table></div><p>


<a class="xref" href="#XSetLineAttributes"><code class="function">XSetLineAttributes</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To set the dash-offset and dash-list for dashed line styles of a given GC, use
<a class="xref" href="#XSetDashes"><code class="function">XSetDashes</code></a>.
</p><a id="idp45946140" class="indexterm"></a><div class="funcsynopsis"><a id="XSetDashes"></a><p><code class="funcdef"><strong class="fsfunc">XSetDashes</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, int<var class="pdparam"> dash_offset</var>, char<var class="pdparam"> dash_list[]</var>, int<var class="pdparam"> n</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dash_offset</em></span>
    </span></p></td><td><p>
Specifies the phase of the pattern for the dashed line-style you want to set
for the specified GC. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dash_list</em></span>
    </span></p></td><td><p>
Specifies the dash-list for the dashed line-style
you want to set for the specified GC. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>n</em></span>
    </span></p></td><td><p>
Specifies the number of elements in dash_list. 
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetDashes"><code class="function">XSetDashes</code></a>
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
<span class="errorname">BadValue</span>
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
<span class="errorname">BadValue</span>
error results.
Specifying an odd-length list is equivalent to specifying the same list
concatenated with itself to produce an even-length list.
</p><p>

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.
</p><p>

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.
</p><p>

<a class="xref" href="#XSetDashes"><code class="function">XSetDashes</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadValue</span>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_the_Fill_Style_and_Fill_Rule"></a>Setting the Fill Style and Fill Rule</h3></div></div></div><p>

To set the fill-style of a given GC, use
<a class="xref" href="#XSetFillStyle"><code class="function">XSetFillStyle</code></a>.
</p><a id="idp45964300" class="indexterm"></a><div class="funcsynopsis"><a id="XSetFillStyle"></a><p><code class="funcdef"><strong class="fsfunc">XSetFillStyle</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, int<var class="pdparam"> fill_style</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>fill_style</em></span>
    </span></p></td><td><p>
Specifies the fill-style you want to set for the specified GC.
You can pass
<span class="symbol">FillSolid</span>,
<span class="symbol">FillTiled</span>,
<span class="symbol">FillStippled</span>,
or
<span class="symbol">FillOpaqueStippled</span>.
    </p></td></tr></tbody></table></div><p>


<a class="xref" href="#XSetFillStyle"><code class="function">XSetFillStyle</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To set the fill-rule of a given GC, use
<a class="xref" href="#XSetFillRule"><code class="function">XSetFillRule</code></a>.
</p><a id="idp45975276" class="indexterm"></a><div class="funcsynopsis"><a id="XSetFillRule"></a><p><code class="funcdef"><strong class="fsfunc">XSetFillRule</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, int<var class="pdparam"> fill_rule</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>fill_rule</em></span>
    </span></p></td><td><p>
Specifies the fill-rule you want to set for the specified GC.
You can pass 
<span class="symbol">EvenOddRule</span>
or
<span class="symbol">WindingRule</span>.
    </p></td></tr></tbody></table></div><p>


<a class="xref" href="#XSetFillRule"><code class="function">XSetFillRule</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadValue</span>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_the_Fill_Tile_and_Stipple"></a>Setting the Fill Tile and Stipple</h3></div></div></div><p>

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.
</p><p>


To obtain the best size of a tile, stipple, or cursor, use
<a class="xref" href="#XQueryBestSize"><code class="function">XQueryBestSize</code></a>.
</p><a id="idp45987676" class="indexterm"></a><div class="funcsynopsis"><a id="XQueryBestSize"></a><p><code class="funcdef">Status <strong class="fsfunc">XQueryBestSize</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> class</var>, Drawable<var class="pdparam"> which_screen</var>, unsignedintwidth,<var class="pdparam"> height</var>, unsignedint*width_return,<var class="pdparam"> *height_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>class</em></span>
    </span></p></td><td><p>
Specifies the class that you are interested in.
You can pass 
<span class="symbol">TileShape</span>,
<span class="symbol">CursorShape</span>,
or 
<span class="symbol">StippleShape</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>which_screen</em></span>
    </span></p></td><td><p>
Specifies any drawable on the screen.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height_return</em></span>
    </span></p></td><td><p>
Return the width and height of the object best supported 
by the display hardware.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XQueryBestSize"><code class="function">XQueryBestSize</code></a>
function returns the best or closest size to the specified size.
For 
<span class="symbol">CursorShape</span>,
this is the largest size that can be fully displayed on the screen specified by
which_screen.
For 
<span class="symbol">TileShape</span>,
this is the size that can be tiled fastest.
For 
<span class="symbol">StippleShape</span>,
this is the size that can be stippled fastest.
For 
<span class="symbol">CursorShape</span>,
the drawable indicates the desired screen.
For 
<span class="symbol">TileShape</span>
and 
<span class="symbol">StippleShape</span>,
the drawable indicates the screen and possibly the window class and depth.
An 
<span class="symbol">InputOnly</span>
window cannot be used as the drawable for 
<span class="symbol">TileShape</span>
or 
<span class="symbol">StippleShape</span>,
or a
<span class="errorname">BadMatch</span>
error results.
</p><p>

<a class="xref" href="#XQueryBestSize"><code class="function">XQueryBestSize</code></a>
can generate
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadMatch</span>,
and 
<span class="errorname">BadValue</span>
errors.
</p><p>


To obtain the best fill tile shape, use
<a class="xref" href="#XQueryBestTile"><code class="function">XQueryBestTile</code></a>.
</p><a id="idp46008844" class="indexterm"></a><div class="funcsynopsis"><a id="XQueryBestTile"></a><p><code class="funcdef">Status <strong class="fsfunc">XQueryBestTile</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> which_screen</var>, unsignedintwidth,<var class="pdparam"> height</var>, unsignedint*width_return,<var class="pdparam"> *height_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>which_screen</em></span>
    </span></p></td><td><p>
Specifies any drawable on the screen.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height_return</em></span>
    </span></p></td><td><p>
Return the width and height of the object best supported 
by the display hardware.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XQueryBestTile"><code class="function">XQueryBestTile</code></a>
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 
<span class="symbol">InputOnly</span>
window is used as the drawable, a 
<span class="errorname">BadMatch</span>
error results.
</p><p>

<a class="xref" href="#XQueryBestTile"><code class="function">XQueryBestTile</code></a>
can generate
<span class="errorname">BadDrawable</span>
and
<span class="errorname">BadMatch</span>
errors.
</p><p>


To obtain the best stipple shape, use
<a class="xref" href="#XQueryBestStipple"><code class="function">XQueryBestStipple</code></a>.
</p><a id="idp46025308" class="indexterm"></a><div class="funcsynopsis"><a id="XQueryBestStipple"></a><p><code class="funcdef">Status <strong class="fsfunc">XQueryBestStipple</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> which_screen</var>, unsignedintwidth,<var class="pdparam"> height</var>, unsignedint*width_return,<var class="pdparam"> *height_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>which_screen</em></span>
    </span></p></td><td><p>
Specifies any drawable on the screen.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height_return</em></span>
    </span></p></td><td><p>
Return the width and height of the object best supported 
by the display hardware.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XQueryBestStipple"><code class="function">XQueryBestStipple</code></a>
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
<span class="symbol">InputOnly</span>
window is used as the drawable, a
<span class="errorname">BadMatch</span>
error results.
</p><p>

<a class="xref" href="#XQueryBestStipple"><code class="function">XQueryBestStipple</code></a>
can generate
<span class="errorname">BadDrawable</span>
and
<span class="errorname">BadMatch</span>
errors.
</p><p>


To set the fill tile of a given GC, use
<a class="xref" href="#XSetTile"><code class="function">XSetTile</code></a>.
</p><a id="idp46041724" class="indexterm"></a><div class="funcsynopsis"><a id="XSetTile"></a><p><code class="funcdef"><strong class="fsfunc">XSetTile</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, Pixmap<var class="pdparam"> tile</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>tile</em></span>
    </span></p></td><td><p>
Specifies the fill tile you want to set for the specified GC. 
    </p></td></tr></tbody></table></div><p>


The tile and GC must have the same depth,
or a
<span class="errorname">BadMatch</span>
error results.
</p><p>

<a class="xref" href="#XSetTile"><code class="function">XSetTile</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadGC</span>,
<span class="errorname">BadMatch</span>,
and
<span class="errorname">BadPixmap</span>
errors.
</p><p>


To set the stipple of a given GC, use
<a class="xref" href="#XSetStipple"><code class="function">XSetStipple</code></a>.
</p><a id="idp46052612" class="indexterm"></a><div class="funcsynopsis"><a id="XSetStipple"></a><p><code class="funcdef"><strong class="fsfunc">XSetStipple</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, Pixmap<var class="pdparam"> stipple</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>stipple</em></span>
    </span></p></td><td><p>
Specifies the stipple you want to set for the specified GC.
    </p></td></tr></tbody></table></div><p>


The stipple must have a depth of one,
or a
<span class="errorname">BadMatch</span>
error results.
</p><p>

<a class="xref" href="#XSetStipple"><code class="function">XSetStipple</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadGC</span>,
<span class="errorname">BadMatch</span>,
and
<span class="errorname">BadPixmap</span>
errors.
</p><p>


To set the tile or stipple origin of a given GC, use
<a class="xref" href="#XSetTSOrigin"><code class="function">XSetTSOrigin</code></a>.
</p><a id="idp46063516" class="indexterm"></a><div class="funcsynopsis"><a id="XSetTSOrigin"></a><p><code class="funcdef"><strong class="fsfunc">XSetTSOrigin</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, intts_x_origin,<var class="pdparam"> ts_y_origin</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>ts_x_origin</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>ts_y_origin</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates of the tile and stipple origin.
    </p></td></tr></tbody></table></div><p>


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.
</p><p>

<a class="xref" href="#XSetTSOrigin"><code class="function">XSetTSOrigin</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadGC</span>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_the_Current_Font"></a>Setting the Current Font</h3></div></div></div><p>

To set the current font of a given GC, use
<a class="xref" href="#XSetFont"><code class="function">XSetFont</code></a>.
</p><a id="idp46076348" class="indexterm"></a><div class="funcsynopsis"><a id="XSetFont"></a><p><code class="funcdef"><strong class="fsfunc">XSetFont</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, Font<var class="pdparam"> font</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>font</em></span>
    </span></p></td><td><p>
Specifies the font.
    </p></td></tr></tbody></table></div><p>


<a class="xref" href="#XSetFont"><code class="function">XSetFont</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadFont</span>,
and 
<span class="errorname">BadGC</span>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_the_Clip_Region"></a>Setting the Clip Region</h3></div></div></div><p>

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.
</p><p>


To set the clip-origin of a given GC, use
<a class="xref" href="#XSetClipOrigin"><code class="function">XSetClipOrigin</code></a>.
</p><a id="idp46087804" class="indexterm"></a><div class="funcsynopsis"><a id="XSetClipOrigin"></a><p><code class="funcdef"><strong class="fsfunc">XSetClipOrigin</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, intclip_x_origin,<var class="pdparam"> clip_y_origin</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>clip_x_origin</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>clip_y_origin</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates of the clip-mask origin.
    </p></td></tr></tbody></table></div><p>


The clip-mask origin is interpreted relative to the origin of whatever 
destination drawable is specified in the graphics request.
</p><p>

<a class="xref" href="#XSetClipOrigin"><code class="function">XSetClipOrigin</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadGC</span>
errors.
</p><p>


To set the clip-mask of a given GC to the specified pixmap, use
<a class="xref" href="#XSetClipMask"><code class="function">XSetClipMask</code></a>.
</p><a id="idp46099772" class="indexterm"></a><div class="funcsynopsis"><a id="XSetClipMask"></a><p><code class="funcdef"><strong class="fsfunc">XSetClipMask</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, Pixmap<var class="pdparam"> pixmap</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>pixmap</em></span>
    </span></p></td><td><p>
Specifies the pixmap or
<span class="symbol">None</span>.
    </p></td></tr></tbody></table></div><p>


If the clip-mask is set to
<span class="symbol">None</span>,
the pixels are always drawn (regardless of the clip-origin).
</p><p>

<a class="xref" href="#XSetClipMask"><code class="function">XSetClipMask</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadGC</span>,
<span class="errorname">BadMatch</span>,
and
<span class="errorname">BadPixmap</span>
errors.
</p><p>


To set the clip-mask of a given GC to the specified list of rectangles, use
<a class="xref" href="#XSetClipRectangles"><code class="function">XSetClipRectangles</code></a>.
</p><a id="idp46110884" class="indexterm"></a><div class="funcsynopsis"><a id="XSetClipRectangles"></a><p><code class="funcdef"><strong class="fsfunc">XSetClipRectangles</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, intclip_x_origin,<var class="pdparam"> clip_y_origin</var>, XRectangle<var class="pdparam"> rectangles[]</var>, int<var class="pdparam"> n</var>, int<var class="pdparam"> ordering</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>clip_x_origin</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>clip_y_origin</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates of the clip-mask origin.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>rectangles</em></span>
    </span></p></td><td><p>
Specifies an array of rectangles that define the clip-mask.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>n</em></span>
    </span></p></td><td><p>
Specifies the number of rectangles. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>ordering</em></span>
    </span></p></td><td><p>
Specifies the ordering relations on the rectangles.
You can pass
<span class="symbol">Unsorted</span>,
<span class="symbol">YSorted</span>,
<span class="symbol">YXSorted</span>,
or
<span class="symbol">YXBanded</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetClipRectangles"><code class="function">XSetClipRectangles</code></a>
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
<span class="symbol">None</span>
as the clip-mask in
<a class="xref" href="#XCreateGC"><code class="function">XCreateGC</code></a>,
<a class="xref" href="#XChangeGC"><code class="function">XChangeGC</code></a>,
and
<a class="xref" href="#XSetClipMask"><code class="function">XSetClipMask</code></a>.
</p><p>

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
<span class="errorname">BadMatch</span>
error, but it is not required to do so.
If no error is generated, the graphics
results are undefined.
<span class="symbol">Unsorted</span>
means the rectangles are in arbitrary order.
<span class="symbol">YSorted</span>
means that the rectangles are nondecreasing in their Y origin.
<span class="symbol">YXSorted</span>
additionally constrains 
<span class="symbol">YSorted</span>
order in that all
rectangles with an equal Y origin are nondecreasing in their X
origin.  
<span class="symbol">YXBanded</span>
additionally constrains 
<span class="symbol">YXSorted</span>
by requiring that,
for every possible Y scanline, all rectangles that include that
scanline have an identical Y origins and Y extents.
</p><p>

<a class="xref" href="#XSetClipRectangles"><code class="function">XSetClipRectangles</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadGC</span>,
<span class="errorname">BadMatch</span>,
and
<span class="errorname">BadValue</span>
errors.
</p><p>

Xlib provides a set of basic functions for performing
region arithmetic.
For information about these functions,
see <a class="link" href="#Manipulating_Regions" title="Manipulating Regions">section 16.5</a>.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_the_Arc_Mode_Subwindow_Mode_and_Graphics_Exposure"></a>Setting the Arc Mode, Subwindow Mode, and Graphics Exposure</h3></div></div></div><p>

To set the arc mode of a given GC, use
<a class="xref" href="#XSetArcMode"><code class="function">XSetArcMode</code></a>.
</p><a id="idp46136476" class="indexterm"></a><div class="funcsynopsis"><a id="XSetArcMode"></a><p><code class="funcdef"><strong class="fsfunc">XSetArcMode</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, int<var class="pdparam"> arc_mode</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>arc_mode</em></span>
    </span></p></td><td><p>
Specifies the arc mode.
You can pass
<span class="symbol">ArcChord</span>
or
<span class="symbol">ArcPieSlice</span>.
    </p></td></tr></tbody></table></div><p>


<a class="xref" href="#XSetArcMode"><code class="function">XSetArcMode</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To set the subwindow mode of a given GC, use
<a class="xref" href="#XSetSubwindowMode"><code class="function">XSetSubwindowMode</code></a>.
</p><a id="idp46146916" class="indexterm"></a><div class="funcsynopsis"><a id="XSetSubwindowMode"></a><p><code class="funcdef"><strong class="fsfunc">XSetSubwindowMode</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, int<var class="pdparam"> subwindow_mode</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>subwindow_mode</em></span>
    </span></p></td><td><p>
Specifies the subwindow mode.
You can pass
<span class="symbol">ClipByChildren</span>
or
<span class="symbol">IncludeInferiors</span>.
    </p></td></tr></tbody></table></div><p>


<a class="xref" href="#XSetSubwindowMode"><code class="function">XSetSubwindowMode</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To set the graphics-exposures flag of a given GC, use
<a class="xref" href="#XSetGraphicsExposures"><code class="function">XSetGraphicsExposures</code></a>.
</p><a id="idp46157420" class="indexterm"></a><div class="funcsynopsis"><a id="XSetGraphicsExposures"></a><p><code class="funcdef"><strong class="fsfunc">XSetGraphicsExposures</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, Bool<var class="pdparam"> graphics_exposures</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>graphics_exposures</em></span>
    </span></p></td><td><p>
Specifies a Boolean value that indicates whether you want
<span class="symbol">GraphicsExpose</span>
and
<span class="symbol">NoExpose</span>
events to be reported when calling
<a class="xref" href="#XCopyArea"><code class="function">XCopyArea</code></a>
and
<a class="xref" href="#XCopyPlane"><code class="function">XCopyPlane</code></a>
with this GC.
    </p></td></tr></tbody></table></div><p>


<a class="xref" href="#XSetGraphicsExposures"><code class="function">XSetGraphicsExposures</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadValue</span>
errors.


</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Graphics_Functions"></a>Chapter 8. Graphics Functions</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Clearing_Areas">Clearing Areas</a></span></dt><dt><span class="sect1"><a href="#Copying_Areas">Copying Areas</a></span></dt><dt><span class="sect1"><a href="#Drawing_Points_Lines_Rectangles_and_Arcs">Drawing Points, Lines, Rectangles, and Arcs</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Drawing_Single_and_Multiple_Points">Drawing Single and Multiple Points</a></span></dt><dt><span class="sect2"><a href="#Drawing_Single_and_Multiple_Lines">Drawing Single and Multiple Lines</a></span></dt><dt><span class="sect2"><a href="#Drawing_Single_and_Multiple_Rectangles">Drawing Single and Multiple Rectangles</a></span></dt><dt><span class="sect2"><a href="#Drawing_Single_and_Multiple_Arcs">Drawing Single and Multiple Arcs</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Filling_Areas">Filling Areas</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Filling_Single_and_Multiple_Rectangles">Filling Single and Multiple Rectangles</a></span></dt><dt><span class="sect2"><a href="#Filling_a_Single_Polygon">Filling a Single Polygon</a></span></dt><dt><span class="sect2"><a href="#Filling_Single_and_Multiple_Arcs">Filling Single and Multiple Arcs</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Font_Metrics">Font Metrics</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Loading_and_Freeing_Fonts">Loading and Freeing Fonts</a></span></dt><dt><span class="sect2"><a href="#Obtaining_and_Freeing_Font_Names_and_Information">Obtaining and Freeing Font Names and Information</a></span></dt><dt><span class="sect2"><a href="#Computing_Character_String_Sizes">Computing Character String Sizes</a></span></dt><dt><span class="sect2"><a href="#Computing_Logical_Extents">Computing Logical Extents</a></span></dt><dt><span class="sect2"><a href="#Querying_Character_String_Sizes">Querying Character String Sizes</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Drawing_Text">Drawing Text</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Drawing_Complex_Text">Drawing Complex Text</a></span></dt><dt><span class="sect2"><a href="#Drawing_Text_Characters">Drawing Text Characters</a></span></dt><dt><span class="sect2"><a href="#Drawing_Image_Text_Characters">Drawing Image Text Characters</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Transferring_Images_between_Client_and_Server">Transferring Images between Client and Server</a></span></dt></dl></div><p>
Once you have established a connection to a display, you can use the Xlib graphics functions to:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Clear and copy areas</p></li><li class="listitem"><p>Draw points, lines, rectangles, and arcs</p></li><li class="listitem"><p>Fill areas</p></li><li class="listitem"><p>Manipulate fonts</p></li><li class="listitem"><p>Draw text</p></li><li class="listitem"><p>Transfer images between clients and the server</p></li></ul></div><p>
If the same drawable and GC is used for each call, Xlib batches back-to-back
calls to XDrawPoint, XDrawLine, XDrawRectangle, XFillArc, and XFillRectangle.
Note that this reduces the total number of requests sent to the server.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Clearing_Areas"></a>Clearing Areas</h2></div></div></div><p>

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 
<a class="xref" href="#XFillRectangle"><code class="function">XFillRectangle</code></a>,
which sets the pixmap to a known value.
</p><p>


To clear a rectangular area of a given window, use
<a class="xref" href="#XClearArea"><code class="function">XClearArea</code></a>.
</p><a id="idp43384652" class="indexterm"></a><a id="idp40873052" class="indexterm"></a><a id="idp43072036" class="indexterm"></a><div class="funcsynopsis"><a id="XClearArea"></a><p><code class="funcdef"><strong class="fsfunc">XClearArea</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, intx,<var class="pdparam"> y</var>, unsignedintwidth,<var class="pdparam"> height</var>, Bool<var class="pdparam"> exposures</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, which are relative to the origin of the
window and specify the upper-left corner of the rectangle.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height, which are the dimensions of the rectangle.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>exposures</em></span>
    </span></p></td><td><p>
Specifies a Boolean value that indicates if
<span class="symbol">Expose</span>
events are to be generated.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XClearArea"><code class="function">XClearArea</code></a>
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
<span class="symbol">ClipByChildren</span>.
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 
<span class="symbol">None</span>,
the contents of the window are not changed.  
In either
case, if exposures is 
<span class="symbol">True</span>,
one or more 
<span class="symbol">Expose</span>
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
<span class="symbol">InputOnly</span>,
a
<span class="errorname">BadMatch</span>
error results.
</p><p>

<a class="xref" href="#XClearArea"><code class="function">XClearArea</code></a>
can generate
<span class="errorname">BadMatch</span>,
<span class="errorname">BadValue</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To clear the entire area in a given window, use
<a class="xref" href="#XClearWindow"><code class="function">XClearWindow</code></a>.
</p><a id="idp46184412" class="indexterm"></a><a id="idp46184980" class="indexterm"></a><a id="idp46185548" class="indexterm"></a><div class="funcsynopsis"><a id="XClearWindow"></a><p><code class="funcdef"><strong class="fsfunc">XClearWindow</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XClearWindow"><code class="function">XClearWindow</code></a>
function clears the entire area in the specified window and is
equivalent to
<a class="xref" href="#XClearArea"><code class="function">XClearArea</code></a>
(display, w, 0, 0, 0, 0, 
<span class="symbol">False</span>).
If the window has a defined background tile, the rectangle is tiled with a
plane-mask of all ones and 
<span class="symbol">GXcopy</span>
function.
If the window has
background 
<span class="symbol">None</span>,
the contents of the window are not changed.  
If you specify a window whose class is
<span class="symbol">InputOnly</span>,
a
<span class="errorname">BadMatch</span>
error results. 
</p><p>

<a class="xref" href="#XClearWindow"><code class="function">XClearWindow</code></a>
can generate
<span class="errorname">BadMatch</span>
and
<span class="errorname">BadWindow</span>
errors.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Copying_Areas"></a>Copying Areas</h2></div></div></div><p>

Xlib provides functions that you can use to copy an area or a bit plane.
</p><p>


To copy an area between drawables of the same
root and depth, use
<a class="xref" href="#XCopyArea"><code class="function">XCopyArea</code></a>.
</p><a id="idp46197692" class="indexterm"></a><a id="idp46198260" class="indexterm"></a><a id="idp46198828" class="indexterm"></a><div class="funcsynopsis"><a id="XCopyArea"></a><p><code class="funcdef"><strong class="fsfunc">XCopyArea</strong>(</code>Display<var class="pdparam"> *display</var>, Drawablesrc,<var class="pdparam"> dest</var>, GC<var class="pdparam"> gc</var>, intsrc_x,<var class="pdparam"> src_y</var>, unsignedintwidth,<var class="pdparam"> height</var>, intdest_x,<var class="pdparam"> dest_y</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>src</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dest</em></span>
    </span></p></td><td><p>
Specify the source and destination rectangles to be combined. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>src_x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>src_y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, 
which are relative to the origin of the source rectangle
and specify its upper-left corner.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height, which are the dimensions of both the source
and destination rectangles.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dest_x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dest_y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, which are relative to the origin of the
destination rectangle and specify its upper-left corner.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCopyArea"><code class="function">XCopyArea</code></a>
function combines the specified rectangle of src with the specified rectangle 
of dest.
The drawables must have the same root and depth,
or a
<span class="errorname">BadMatch</span>
error results.
</p><p>

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 
<span class="symbol">None</span>,
corresponding regions
of the destination are tiled with that background
(with plane-mask of all ones and
<span class="symbol">GXcopy</span>
function).
Regardless of tiling or whether the destination is a window or a pixmap,
if graphics-exposures is 
<span class="symbol">True</span>,
then
<span class="symbol">GraphicsExpose</span>
events for all corresponding destination regions are generated.
If graphics-exposures is 
<span class="symbol">True</span>
but no
<span class="symbol">GraphicsExpose</span>
events are generated, a
<span class="symbol">NoExpose</span>
event is generated.
Note that by default graphics-exposures is
<span class="symbol">True</span>
in new GCs.
</p><p>

This function uses these GC components: function, plane-mask, 
subwindow-mode, graphics-exposures, clip-x-origin,
clip-y-origin, and clip-mask.
</p><p>

<a class="xref" href="#XCopyArea"><code class="function">XCopyArea</code></a>
can generate
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadMatch</span>
errors.

</p><p>

To copy a single bit plane of a given drawable, use
<a class="xref" href="#XCopyPlane"><code class="function">XCopyPlane</code></a>.
</p><a id="idp45295604" class="indexterm"></a><a id="idp45296172" class="indexterm"></a><a id="idp45296740" class="indexterm"></a><div class="funcsynopsis"><a id="XCopyPlane"></a><p><code class="funcdef"><strong class="fsfunc">XCopyPlane</strong>(</code>Display<var class="pdparam"> *display</var>, Drawablesrc,<var class="pdparam"> dest</var>, GC<var class="pdparam"> gc</var>, intsrc_x,<var class="pdparam"> src_y</var>, unsignedintwidth,<var class="pdparam"> height</var>, intdest_x,<var class="pdparam"> dest_y</var>, unsignedlong<var class="pdparam"> plane</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>src</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dest</em></span>
    </span></p></td><td><p>
Specify the source and destination rectangles to be combined. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>src_x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>src_y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, 
which are relative to the origin of the source rectangle
and specify its upper-left corner.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height, which are the dimensions of both the source
and destination rectangles.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dest_x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dest_y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, which are relative to the origin of the
destination rectangle and specify its upper-left corner.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>plane</em></span>
    </span></p></td><td><p>
Specifies the bit plane.
You must set exactly one bit to 1.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCopyPlane"><code class="function">XCopyPlane</code></a>
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
<span class="errorname">BadMatch</span>
error results.
If plane does not have exactly one bit set to 1 and the value of plane
is not less than %2 sup n%, where <span class="emphasis"><em>n</em></span> is the depth of src, a
<span class="errorname">BadValue</span>
error results.
</p><p>

Effectively, 
<a class="xref" href="#XCopyPlane"><code class="function">XCopyPlane</code></a>
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 
<code class="systemitem">CopyArea</code>
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
<span class="symbol">FillOpaqueStippled</span>
for filling a rectangular area of the destination.
</p><p>

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

<a class="xref" href="#XCopyPlane"><code class="function">XCopyPlane</code></a>
can generate
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadGC</span>,
<span class="errorname">BadMatch</span>,
and 
<span class="errorname">BadValue</span>
errors.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Drawing_Points_Lines_Rectangles_and_Arcs"></a>Drawing Points, Lines, Rectangles, and Arcs</h2></div></div></div><p>

Xlib provides functions that you can use to draw:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
A single point or multiple points
    </p></li><li class="listitem"><p>
A single line or multiple lines
    </p></li><li class="listitem"><p>
A single rectangle or multiple rectangles
    </p></li><li class="listitem"><p>
A single arc or multiple arcs
    </p></li></ul></div><p>

Some of the functions described in the following sections
use these structures:
</p><p>

<a id="idp45328484" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     short x1, y1, x2, y2;
} XSegment;
</pre><p>
</p><p>


<a id="idp45330484" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     short x, y;
} XPoint;
</pre><p>
</p><p>


<a id="idp45332476" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     short x, y;
     unsigned short width, height;
} XRectangle;
</pre><p>
</p><p>


<a id="idp45334508" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     short x, y;
     unsigned short width, height;
     short angle1, angle2;             /* Degrees * 64 */
} XArc;
</pre><p>
</p><p>


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.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Drawing_Single_and_Multiple_Points"></a>Drawing Single and Multiple Points</h3></div></div></div><p>

<a id="idp45338164" class="indexterm"></a>
<a id="idp45338732" class="indexterm"></a>
<a id="idp45339300" class="indexterm"></a>
<a id="idp45339724" class="indexterm"></a>
</p><p>

To draw a single point in a given drawable, use
<a class="xref" href="#XDrawPoint"><code class="function">XDrawPoint</code></a>.
</p><a id="idp45341076" class="indexterm"></a><div class="funcsynopsis"><a id="XDrawPoint"></a><p><code class="funcdef"><strong class="fsfunc">XDrawPoint</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, intx,<var class="pdparam"> y</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates where you want the point drawn.
    </p></td></tr></tbody></table></div><p>



To draw multiple points in a given drawable, use
<a class="xref" href="#XDrawPoints"><code class="function">XDrawPoints</code></a>.
</p><a id="idp45352964" class="indexterm"></a><div class="funcsynopsis"><a id="XDrawPoints"></a><p><code class="funcdef"><strong class="fsfunc">XDrawPoints</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, XPoint<var class="pdparam"> *points</var>, int<var class="pdparam"> npoints</var>, int<var class="pdparam"> mode</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>points</em></span>
    </span></p></td><td><p>
Specifies an array of points.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>npoints</em></span>
    </span></p></td><td><p>
Specifies the number of points in the array.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>mode</em></span>
    </span></p></td><td><p>
Specifies the coordinate mode. 
You can pass
<span class="symbol">CoordModeOrigin</span>
or
<span class="symbol">CoordModePrevious</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDrawPoint"><code class="function">XDrawPoint</code></a>
function uses the foreground pixel and function components of the
GC to draw a single point into the specified drawable; 
<a class="xref" href="#XDrawPoints"><code class="function">XDrawPoints</code></a>
draws multiple points this way.
<span class="symbol">CoordModeOrigin</span>
treats all coordinates as relative to the origin,
and
<span class="symbol">CoordModePrevious</span>
treats all coordinates after the first as relative to the previous point.
<a class="xref" href="#XDrawPoints"><code class="function">XDrawPoints</code></a>
draws the points in the order listed in the array.
</p><p>

Both functions use these GC components: function, plane-mask,
foreground, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
</p><p>

<a class="xref" href="#XDrawPoint"><code class="function">XDrawPoint</code></a>
can generate
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadGC</span>,
and 
<span class="errorname">BadMatch</span>
errors.
<a class="xref" href="#XDrawPoints"><code class="function">XDrawPoints</code></a>
can generate
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadGC</span>,
<span class="errorname">BadMatch</span>,
and
<span class="errorname">BadValue</span>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Drawing_Single_and_Multiple_Lines"></a>Drawing Single and Multiple Lines</h3></div></div></div><p>

<a id="idp45373444" class="indexterm"></a>
<a id="idp45374012" class="indexterm"></a>
<a id="idp45374580" class="indexterm"></a>
<a id="idp45375004" class="indexterm"></a>
<a id="idp45375428" class="indexterm"></a>
<a id="idp45375996" class="indexterm"></a>
<a id="idp45376564" class="indexterm"></a>
</p><p>

To draw a single line between two points in a given drawable, use
<a class="xref" href="#XDrawLine"><code class="function">XDrawLine</code></a>.
</p><a id="idp45377940" class="indexterm"></a><div class="funcsynopsis"><a id="XDrawLine"></a><p><code class="funcdef"><strong class="fsfunc">XDrawLine</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, intx1,y1,x2,<var class="pdparam"> y2</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x1</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y1</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x2</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y2</em></span>
    </span></p></td><td><p>
Specify the points (x1, y1) and (x2, y2) to be connected.
    </p></td></tr></tbody></table></div><p>



To draw multiple lines in a given drawable, use
<a class="xref" href="#XDrawLines"><code class="function">XDrawLines</code></a>.
</p><a id="idp45392980" class="indexterm"></a><div class="funcsynopsis"><a id="XDrawLines"></a><p><code class="funcdef"><strong class="fsfunc">XDrawLines</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, XPoint<var class="pdparam"> *points</var>, int<var class="pdparam"> npoints</var>, int<var class="pdparam"> mode</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>points</em></span>
    </span></p></td><td><p>
Specifies an array of points.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>npoints</em></span>
    </span></p></td><td><p>
Specifies the number of points in the array.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>mode</em></span>
    </span></p></td><td><p>
Specifies the coordinate mode. 
You can pass
<span class="symbol">CoordModeOrigin</span>
or
<span class="symbol">CoordModePrevious</span>.
    </p></td></tr></tbody></table></div><p>



To draw multiple, unconnected lines in a given drawable,
use
<a class="xref" href="#XDrawSegments"><code class="function">XDrawSegments</code></a>.
</p><a id="idp45407308" class="indexterm"></a><div class="funcsynopsis"><a id="XDrawSegments"></a><p><code class="funcdef"><strong class="fsfunc">XDrawSegments</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, XSegment<var class="pdparam"> *segments</var>, int<var class="pdparam"> nsegments</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>segments</em></span>
    </span></p></td><td><p>
Specifies an array of segments.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nsegments</em></span>
    </span></p></td><td><p>
Specifies the number of segments in the array.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDrawLine"><code class="function">XDrawLine</code></a>
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, 
<a class="xref" href="#XDrawLine"><code class="function">XDrawLine</code></a>
does not draw a pixel more than once.
If lines intersect, the intersecting pixels are drawn multiple times.  
</p><p>

The
<a class="xref" href="#XDrawLines"><code class="function">XDrawLines</code></a>
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
<span class="structname">XPoint</span>
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, 
<a class="xref" href="#XDrawLines"><code class="function">XDrawLines</code></a>
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 
<code class="systemitem">PolyLine</code>
protocol request were a single, filled shape.
<span class="symbol">CoordModeOrigin</span>
treats all coordinates as relative to the origin,
and
<span class="symbol">CoordModePrevious</span>
treats all coordinates after the first as relative to the previous point.
</p><p>

The
<a class="xref" href="#XDrawSegments"><code class="function">XDrawSegments</code></a>
function draws multiple, unconnected lines. 
For each segment, 
<a class="xref" href="#XDrawSegments"><code class="function">XDrawSegments</code></a>
draws a
line between (x1, y1) and (x2, y2).
It draws the lines in the order listed in the array of
<span class="structname">XSegment</span>
structures and does not perform joining at coincident endpoints.
For any given line, 
<a class="xref" href="#XDrawSegments"><code class="function">XDrawSegments</code></a>
does not draw a pixel more than once.  
If lines intersect, the intersecting pixels are drawn multiple times.  
</p><p>

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
<a class="xref" href="#XDrawLines"><code class="function">XDrawLines</code></a>
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.
</p><p>

<a class="xref" href="#XDrawLine"><code class="function">XDrawLine</code></a>,
<a class="xref" href="#XDrawLines"><code class="function">XDrawLines</code></a>,
and
<a class="xref" href="#XDrawSegments"><code class="function">XDrawSegments</code></a>
can generate
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadMatch</span>
errors.
<a class="xref" href="#XDrawLines"><code class="function">XDrawLines</code></a>
also can generate
<span class="errorname">BadValue</span>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Drawing_Single_and_Multiple_Rectangles"></a>Drawing Single and Multiple Rectangles</h3></div></div></div><p>

<a id="idp47728972" class="indexterm"></a>
<a id="idp47729476" class="indexterm"></a>
<a id="idp47729980" class="indexterm"></a>
<a id="idp47730356" class="indexterm"></a>
</p><p>

To draw the outline of a single rectangle in a given drawable, use
<a class="xref" href="#XDrawRectangle"><code class="function">XDrawRectangle</code></a>.
</p><a id="idp47731564" class="indexterm"></a><div class="funcsynopsis"><a id="XDrawRectangle"></a><p><code class="funcdef"><strong class="fsfunc">XDrawRectangle</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, intx,<var class="pdparam"> y</var>, unsignedintwidth,<var class="pdparam"> height</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, which specify the upper-left corner of the
rectangle.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height, which specify the dimensions of the
rectangle.
    </p></td></tr></tbody></table></div><p>



To draw the outline of multiple rectangles
in a given drawable, use
<a class="xref" href="#XDrawRectangles"><code class="function">XDrawRectangles</code></a>.
</p><a id="idp47744852" class="indexterm"></a><div class="funcsynopsis"><a id="XDrawRectangles"></a><p><code class="funcdef"><strong class="fsfunc">XDrawRectangles</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, XRectangle<var class="pdparam"> rectangles[]</var>, int<var class="pdparam"> nrectangles</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>rectangles</em></span>
    </span></p></td><td><p>
Specifies an array of rectangles.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nrectangles</em></span>
    </span></p></td><td><p>
Specifies the number of rectangles in the array.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDrawRectangle"><code class="function">XDrawRectangle</code></a>
and
<a class="xref" href="#XDrawRectangles"><code class="function">XDrawRectangles</code></a>
functions draw the outlines of the specified rectangle or rectangles as
if a five-point 
<code class="systemitem">PolyLine</code>
protocol request were specified for each rectangle:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
[x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y]
    </p></li></ul></div><p>

For the specified rectangle or rectangles, 
these functions do not draw a pixel more than once.
<a class="xref" href="#XDrawRectangles"><code class="function">XDrawRectangles</code></a>
draws the rectangles in the order listed in the array.
If rectangles intersect,
the intersecting pixels are drawn multiple times.
</p><p>

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.
</p><p>

<a class="xref" href="#XDrawRectangle"><code class="function">XDrawRectangle</code></a>
and
<a class="xref" href="#XDrawRectangles"><code class="function">XDrawRectangles</code></a>
can generate
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadMatch</span>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Drawing_Single_and_Multiple_Arcs"></a>Drawing Single and Multiple Arcs</h3></div></div></div><p>

<a id="idp47761220" class="indexterm"></a>
<a id="idp47761724" class="indexterm"></a>
<a id="idp47762100" class="indexterm"></a>
<a id="idp47762604" class="indexterm"></a>
</p><p>


To draw a single arc in a given drawable, use
<a class="xref" href="#XDrawArc"><code class="function">XDrawArc</code></a>.
</p><a id="idp47763916" class="indexterm"></a><div class="funcsynopsis"><a id="XDrawArc"></a><p><code class="funcdef"><strong class="fsfunc">XDrawArc</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, intx,<var class="pdparam"> y</var>, unsignedintwidth,<var class="pdparam"> height</var>, intangle1,<var class="pdparam"> angle2</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height, which are the major and minor axes of the
arc.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>angle1</em></span>
    </span></p></td><td><p>
Specifies the start of the arc relative to the three-o'clock position
from the center, in units of degrees * 64.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>angle2</em></span>
    </span></p></td><td><p>
Specifies the path and extent of the arc relative to the start of the
arc, in units of degrees * 64.
    </p></td></tr></tbody></table></div><p>



To draw multiple arcs in a given drawable, use
<a class="xref" href="#XDrawArcs"><code class="function">XDrawArcs</code></a>.
</p><a id="idp47780084" class="indexterm"></a><div class="funcsynopsis"><a id="XDrawArcs"></a><p><code class="funcdef"><strong class="fsfunc">XDrawArcs</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, XArc<var class="pdparam"> *arcs</var>, int<var class="pdparam"> narcs</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>arcs</em></span>
    </span></p></td><td><p>
Specifies an array of arcs.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>narcs</em></span>
    </span></p></td><td><p>
Specifies the number of arcs in the array.
    </p></td></tr></tbody></table></div><p>



delim %%

<a class="xref" href="#XDrawArc"><code class="function">XDrawArc</code></a>
draws a single circular or elliptical arc, and 
<a class="xref" href="#XDrawArcs"><code class="function">XDrawArcs</code></a>
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, 
<a class="xref" href="#XDrawArc"><code class="function">XDrawArc</code></a>
or 
<a class="xref" href="#XDrawArcs"><code class="function">XDrawArcs</code></a>
truncates it to 360 degrees.
</p><p>

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

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

</p><pre class="literallayout">
% roman "skewed-angle" ~ = ~ atan left ( tan ( roman "normal-angle" )
 * width over height right ) +^ adjust%
</pre><p>
</p><p>

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

</p><pre class="literallayout">


%0%     for normal-angle in the range % [ 0 , ~pi over 2  ]%
%pi%     for normal-angle in the range % [ pi over 2 , ~{3 pi} over 2  ]%
%2 pi%     for normal-angle in the range % [ {3 pi} over 2 , ~2 pi  ]%
</pre><p>
</p><p>

For any given arc, 
<a class="xref" href="#XDrawArc"><code class="function">XDrawArc</code></a>
and
<a class="xref" href="#XDrawArcs"><code class="function">XDrawArcs</code></a>
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, 
<a class="xref" href="#XDrawArc"><code class="function">XDrawArc</code></a>
and
<a class="xref" href="#XDrawArcs"><code class="function">XDrawArcs</code></a>
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.
</p><p>

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.
</p><p>

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.
</p><p>

<a class="xref" href="#XDrawArc"><code class="function">XDrawArc</code></a>
and
<a class="xref" href="#XDrawArcs"><code class="function">XDrawArcs</code></a>
can generate
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadMatch</span>
errors.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Filling_Areas"></a>Filling Areas</h2></div></div></div><p>

Xlib provides functions that you can use to fill:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
A single rectangle or multiple rectangles
    </p></li><li class="listitem"><p>
A single polygon
    </p></li><li class="listitem"><p>
A single arc or multiple arcs
    </p></li></ul></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Filling_Single_and_Multiple_Rectangles"></a>Filling Single and Multiple Rectangles</h3></div></div></div><p>

<a id="idp47806308" class="indexterm"></a>
<a id="idp47806812" class="indexterm"></a>
<a id="idp47807188" class="indexterm"></a>
<a id="idp47807692" class="indexterm"></a>
</p><p>


To fill a single rectangular area in a given drawable, use
<a class="xref" href="#XFillRectangle"><code class="function">XFillRectangle</code></a>.
</p><a id="idp47809020" class="indexterm"></a><div class="funcsynopsis"><a id="XFillRectangle"></a><p><code class="funcdef"><strong class="fsfunc">XFillRectangle</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, intx,<var class="pdparam"> y</var>, unsignedintwidth,<var class="pdparam"> height</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, which are relative to the origin of the
drawable and specify the upper-left corner of the rectangle.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height, which are the dimensions of the rectangle to
be filled.
    </p></td></tr></tbody></table></div><p>



To fill multiple rectangular areas in a given drawable, use
<a class="xref" href="#XFillRectangles"><code class="function">XFillRectangles</code></a>.
</p><a id="idp47822356" class="indexterm"></a><div class="funcsynopsis"><a id="XFillRectangles"></a><p><code class="funcdef"><strong class="fsfunc">XFillRectangles</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, XRectangle<var class="pdparam"> *rectangles</var>, int<var class="pdparam"> nrectangles</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>rectangles</em></span>
    </span></p></td><td><p>
Specifies an array of rectangles.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nrectangles</em></span>
    </span></p></td><td><p>
Specifies the number of rectangles in the array.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFillRectangle"><code class="function">XFillRectangle</code></a>
and
<a class="xref" href="#XFillRectangles"><code class="function">XFillRectangles</code></a>
functions fill the specified rectangle or rectangles
as if a four-point 
<code class="systemitem">FillPolygon</code>
protocol request were specified for each rectangle:
</p><p>

</p><pre class="literallayout">
[x,y] [x+width,y] [x+width,y+height] [x,y+height]
</pre><p>
</p><p>

Each function uses the x and y coordinates,
width and height dimensions, and GC you specify.
</p><p>

<a class="xref" href="#XFillRectangles"><code class="function">XFillRectangles</code></a>
fills the rectangles in the order listed in the array.  
For any given rectangle,
<a class="xref" href="#XFillRectangle"><code class="function">XFillRectangle</code></a>
and
<a class="xref" href="#XFillRectangles"><code class="function">XFillRectangles</code></a>
do not draw a pixel more than once.  
If rectangles intersect, the intersecting pixels are
drawn multiple times.
</p><p>

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.
</p><p>

<a class="xref" href="#XFillRectangle"><code class="function">XFillRectangle</code></a>
and
<a class="xref" href="#XFillRectangles"><code class="function">XFillRectangles</code></a>
can generate
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadMatch</span>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Filling_a_Single_Polygon"></a>Filling a Single Polygon</h3></div></div></div><p>


To fill a polygon area in a given drawable, use
<a class="xref" href="#XFillPolygon"><code class="function">XFillPolygon</code></a>.
<a id="idp47840348" class="indexterm"></a>
<a id="idp47840852" class="indexterm"></a>
</p><a id="idp47841420" class="indexterm"></a><div class="funcsynopsis"><a id="XFillPolygon"></a><p><code class="funcdef"><strong class="fsfunc">XFillPolygon</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, XPoint<var class="pdparam"> *points</var>, int<var class="pdparam"> npoints</var>, int<var class="pdparam"> shape</var>, int<var class="pdparam"> mode</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>points</em></span>
    </span></p></td><td><p>
Specifies an array of points.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>npoints</em></span>
    </span></p></td><td><p>
Specifies the number of points in the array.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>shape</em></span>
    </span></p></td><td><p>
Specifies a shape that helps the server to improve performance.
You can pass 
<span class="symbol">Complex</span>,
<span class="symbol">Convex</span>,
or 
<span class="symbol">Nonconvex</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>mode</em></span>
    </span></p></td><td><p>
Specifies the coordinate mode. 
You can pass
<span class="symbol">CoordModeOrigin</span>
or
<span class="symbol">CoordModePrevious</span>.
    </p></td></tr></tbody></table></div><p>


<a class="xref" href="#XFillPolygon"><code class="function">XFillPolygon</code></a>
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.
<a class="xref" href="#XFillPolygon"><code class="function">XFillPolygon</code></a>
does not draw a pixel of the region more than once.
<span class="symbol">CoordModeOrigin</span>
treats all coordinates as relative to the origin,
and
<span class="symbol">CoordModePrevious</span>
treats all coordinates after the first as relative to the previous point.
</p><p>

Depending on the specified shape, the following occurs: 
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If shape is
<span class="symbol">Complex</span>,
the path may self-intersect. 
Note that contiguous coincident points in the path are not treated 
as self-intersection.
    </p></li><li class="listitem"><p>
If shape is
<span class="symbol">Convex</span>,
for every pair of points inside the polygon,
the line segment connecting them does not intersect the path.
If known by the client,
specifying 
<span class="symbol">Convex</span>
can improve performance.  
If you specify
<span class="symbol">Convex</span>
for a path that is not convex, 
the graphics results are undefined.
    </p></li><li class="listitem"><p>
If shape is
<span class="symbol">Nonconvex</span>,
the path does not self-intersect, but the shape is not
wholly convex. 
If known by the client, 
specifying 
<span class="symbol">Nonconvex</span>
instead of
<span class="symbol">Complex</span>
may improve performance.  
If you specify
<span class="symbol">Nonconvex</span>
for a self-intersecting path, the graphics results are undefined.
    </p></li></ul></div><p>

The fill-rule of the GC controls the filling behavior of 
self-intersecting polygons.
</p><p>

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.
</p><p>

<a class="xref" href="#XFillPolygon"><code class="function">XFillPolygon</code></a>
can generate
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadGC</span>,
<span class="errorname">BadMatch</span>,
and
<span class="errorname">BadValue</span>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Filling_Single_and_Multiple_Arcs"></a>Filling Single and Multiple Arcs</h3></div></div></div><p>

<a id="idp47864740" class="indexterm"></a>
<a id="idp47865116" class="indexterm"></a>
<a id="idp47865620" class="indexterm"></a>
To fill a single arc in a given drawable, use
<a class="xref" href="#XFillArc"><code class="function">XFillArc</code></a>.
</p><a id="idp47866612" class="indexterm"></a><div class="funcsynopsis"><a id="XFillArc"></a><p><code class="funcdef"><strong class="fsfunc">XFillArc</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, intx,<var class="pdparam"> y</var>, unsignedintwidth,<var class="pdparam"> height</var>, intangle1,<var class="pdparam"> angle2</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height, which are the major and minor axes of the
arc.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>angle1</em></span>
    </span></p></td><td><p>
Specifies the start of the arc relative to the three-o'clock position
from the center, in units of degrees * 64.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>angle2</em></span>
    </span></p></td><td><p>
Specifies the path and extent of the arc relative to the start of the
arc, in units of degrees * 64.
    </p></td></tr></tbody></table></div><p>



To fill multiple arcs in a given drawable, use
<a class="xref" href="#XFillArcs"><code class="function">XFillArcs</code></a>.
</p><a id="idp47882780" class="indexterm"></a><div class="funcsynopsis"><a id="XFillArcs"></a><p><code class="funcdef"><strong class="fsfunc">XFillArcs</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, XArc<var class="pdparam"> *arcs</var>, int<var class="pdparam"> narcs</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>arcs</em></span>
    </span></p></td><td><p>
Specifies an array of arcs.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>narcs</em></span>
    </span></p></td><td><p>
Specifies the number of arcs in the array.
    </p></td></tr></tbody></table></div><p>


For each arc, 
<a class="xref" href="#XFillArc"><code class="function">XFillArc</code></a>
or
<a class="xref" href="#XFillArcs"><code class="function">XFillArcs</code></a>
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 
<span class="symbol">ArcChord</span>,
the single line segment joining the endpoints of the arc is used.  
For 
<span class="symbol">ArcPieSlice</span>,
the two line segments joining the endpoints of the arc with the center
point are used.  
<a class="xref" href="#XFillArcs"><code class="function">XFillArcs</code></a>
fills the arcs in the order listed in the array.  
For any given arc,  
<a class="xref" href="#XFillArc"><code class="function">XFillArc</code></a>
and
<a class="xref" href="#XFillArcs"><code class="function">XFillArcs</code></a>
do not draw a pixel more than once.  
If regions intersect, 
the intersecting pixels are drawn multiple times.
</p><p>

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.
</p><p>

<a class="xref" href="#XFillArc"><code class="function">XFillArc</code></a>
and
<a class="xref" href="#XFillArcs"><code class="function">XFillArcs</code></a>
can generate
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadMatch</span>
errors.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Font_Metrics"></a>Font Metrics</h2></div></div></div><p>

<a id="idp47898956" class="indexterm"></a>
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.
</p><p>

This section discusses how to:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Load and free fonts
    </p></li><li class="listitem"><p>
Obtain and free font names
    </p></li><li class="listitem"><p>
Compute character string sizes
    </p></li><li class="listitem"><p>
Compute logical extents
    </p></li><li class="listitem"><p>
Query character string sizes
    </p></li></ul></div><p>

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 
<a class="xref" href="#XLoadQueryFont"><code class="function">XLoadQueryFont</code></a>
to load a font and query the font metrics.
</p><p>

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).
</p><p>


The
<span class="structname">XFontStruct</span>
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
<span class="structname">XCharStruct</span>
structures for the
characters contained in the font.
The
<span class="structname">XFontStruct</span>,
<span class="structname">XFontProp</span>,
and
<span class="structname">XCharStruct</span>
structures contain:
</p><p>

<a id="idp47905684" class="indexterm"></a>
</p><pre class="literallayout">


typedef struct {
     short lbearing;               /* origin to left edge of raster */
     short rbearing;               /* origin to right edge of raster */
     short width;                  /* advance to next char's origin */
     short ascent;                 /* baseline to top edge of raster */
     short descent;                /* baseline to bottom edge of raster */
     unsigned short attributes;    /* per char flags (not predefined) */
} XCharStruct;
</pre><p>
</p><p>

<a id="idp47907540" class="indexterm"></a>
</p><pre class="literallayout">


typedef struct {
     Atom     name;
     unsigned long card32;
} XFontProp;
</pre><p>
</p><p>

<a id="idp47909012" class="indexterm"></a>
</p><pre class="literallayout">


typedef struct {     /* normal 16 bit characters are two bytes */
    unsigned char byte1;
    unsigned char byte2;
} XChar2b;
</pre><p>
</p><p>

<a id="idp47910532" class="indexterm"></a>
</p><pre class="literallayout">


typedef struct {
     XExtData *ext_data;               /* hook for extension to hang data */
     Font fid;                         /* Font id for this font */
     unsigned direction;               /* hint about the direction font is painted */
     unsigned min_char_or_byte2;       /* first character */
     unsigned max_char_or_byte2;       /* last character */
     unsigned min_byte1;               /* first row that exists */
     unsigned max_byte1;               /* last row that exists */
     Bool all_chars_exist;             /* flag if all characters have nonzero size */
     unsigned default_char;            /* char to print for undefined character */
     int n_properties;                 /* how many properties there are */
     XFontProp *properties;            /* pointer to array of additional properties */
     XCharStruct min_bounds;           /* minimum bounds over all existing char */
     XCharStruct max_bounds;           /* maximum bounds over all existing char */
     XCharStruct *per_char;            /* first_char to last_char information */
     int ascent;                       /* logical extent above baseline for spacing */
     int descent;                      /* logical descent below baseline for spacing */
} XFontStruct;
</pre><p>
</p><p>


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.
</p><p>

The bounding box of a character is defined by the 
<span class="structname">XCharStruct</span>
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
<span class="structname">XFontStruct</span>
min and max bounds are used.
</p><p>

The members of the 
<span class="structname">XFontStruct</span>
have the following semantics:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The direction member can be either 
<span class="symbol">FontLeftToRight</span>
or 
<span class="symbol">FontRightToLeft</span>.
It is just a hint as to whether most 
<span class="structname">XCharStruct</span>
elements 
have a positive 
(<span class="symbol">FontLeftToRight</span>)
or a negative 
(<span class="symbol">FontRightToLeft</span>)
character width 
metric.
The core protocol defines no support for vertical text.
    </p></li><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
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:
    </p></li><li class="listitem"><p>

     byte1 = N/D + min_byte1

     byte2 = N\\D + min_char_or_byte2
    </p></li><li class="listitem"><p>

where:
    </p></li><li class="listitem"><p>

        D = max_char_or_byte2 - min_char_or_byte2 + 1
        / = integer division
        \\ = integer modulus

    </p></li><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
If all_chars_exist is 
<span class="symbol">True</span>,
all characters in the per_char array have nonzero bounding boxes.
    </p></li><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
The min_bounds and max_bounds members contain the most extreme values of
each individual 
<span class="structname">XCharStruct</span>
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:
</p><pre class="literallayout">
     [x + min_bounds.lbearing, y - max_bounds.ascent]
</pre><p>
    </p></li><li class="listitem"><p>
Its width is:
</p><pre class="literallayout">
     max_bounds.rbearing - min_bounds.lbearing
</pre><p>
    </p></li><li class="listitem"><p>
Its height is:
</p><pre class="literallayout">
     max_bounds.ascent + max_bounds.descent
</pre><p>
    </p></li><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
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.
    </p></li></ul></div><p>

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 
<span class="structname">XCharStruct</span>
components is a rectangle with its upper-left corner at:
</p><p>

</p><pre class="literallayout">
[x + lbearing, y - ascent]
</pre><p>
</p><p>

Its width is:
</p><p>

</p><pre class="literallayout">
rbearing - lbearing
</pre><p>
</p><p>

Its height is:
</p><p>

</p><pre class="literallayout">
ascent + descent
</pre><p>
</p><p>

The origin for the next character is defined to be:
</p><p>

</p><pre class="literallayout">
[x + width, y]
</pre><p>
</p><p>

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.
</p><p>

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
<span class="structname">XCharStruct</span>
metric members could be negative.
If the width is negative,
the next character will be placed to the left of the current origin.
</p><p>

The X protocol does not define the interpretation of the attributes member 
in the
<span class="structname">XCharStruct</span>
structure.
A nonexistent character is represented with all members of its
<span class="structname">XCharStruct</span>
set to zero.
</p><p>

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 <span class="emphasis"><em>a priori</em></span> knowledge of the property. 
A basic set of font properties is specified in the X Consortium standard
<span class="olink"><em class="citetitle">X Logical Font Description Conventions</em></span>.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Loading_and_Freeing_Fonts"></a>Loading and Freeing Fonts</h3></div></div></div><p>

Xlib provides functions that you can use to load fonts, get font information,
unload fonts, and free font information.
<a id="idp47937796" class="indexterm"></a>
<a id="idp47938300" class="indexterm"></a>
<a id="idp47938804" class="indexterm"></a>
A few font functions use a 
<span class="type">GContext</span>
resource ID or a font ID interchangeably.
</p><p>


To load a given font, use
<a class="xref" href="#XLoadFont"><code class="function">XLoadFont</code></a>.
</p><a id="idp47940468" class="indexterm"></a><div class="funcsynopsis"><a id="XLoadFont"></a><p><code class="funcdef">Font <strong class="fsfunc">XLoadFont</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> *name</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>name</em></span>
    </span></p></td><td><p>
Specifies the name of the font,
which is a null-terminated string.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XLoadFont"><code class="function">XLoadFont</code></a>
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 
<span class="olink"><em class="citetitle">X Logical Font Description Conventions</em></span>.
If 
<a class="xref" href="#XLoadFont"><code class="function">XLoadFont</code></a>
was unsuccessful at loading the specified font, 
a 
<span class="errorname">BadName</span>
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 
<a class="xref" href="#XUnloadFont"><code class="function">XUnloadFont</code></a>.
</p><p>

<a class="xref" href="#XLoadFont"><code class="function">XLoadFont</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadName</span>
errors.
</p><p>


To return information about an available font, use
<a class="xref" href="#XQueryFont"><code class="function">XQueryFont</code></a>.
</p><a id="idp47950436" class="indexterm"></a><div class="funcsynopsis"><a id="XQueryFont"></a><p><code class="funcdef">XFontStruct *<strong class="fsfunc">XQueryFont</strong>(</code>Display<var class="pdparam"> *display</var>, XID<var class="pdparam"> font_ID</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>font_ID</em></span>
    </span></p></td><td><p>
Specifies the font ID or the 
<span class="type">GContext</span>
ID.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XQueryFont"><code class="function">XQueryFont</code></a>
function returns a pointer to the
<span class="structname">XFontStruct</span>
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 
<span class="structname">XFontStruct</span>
structure will be the 
<span class="type">GContext</span>
ID, and you need to be careful when using this ID in other functions
(see
<a class="xref" href="#XGContextFromGC"><code class="function">XGContextFromGC</code></a>).
If the font does not exist,
<a class="xref" href="#XQueryFont"><code class="function">XQueryFont</code></a>
returns NULL.
To free this data, use
<a class="xref" href="#XFreeFontInfo"><code class="function">XFreeFontInfo</code></a>.
</p><p>


To perform a
<a class="xref" href="#XLoadFont"><code class="function">XLoadFont</code></a>
and
<a class="xref" href="#XQueryFont"><code class="function">XQueryFont</code></a>
in a single operation, use
<a class="xref" href="#XLoadQueryFont"><code class="function">XLoadQueryFont</code></a>.
</p><a id="idp47959980" class="indexterm"></a><div class="funcsynopsis"><a id="XLoadQueryFont"></a><p><code class="funcdef">XFontStruct *<strong class="fsfunc">XLoadQueryFont</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> *name</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>name</em></span>
    </span></p></td><td><p>
Specifies the name of the font,
which is a null-terminated string.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XLoadQueryFont"><code class="function">XLoadQueryFont</code></a>
function provides the most common way for accessing a font.
<a class="xref" href="#XLoadQueryFont"><code class="function">XLoadQueryFont</code></a>
both opens (loads) the specified font and returns a pointer to the
appropriate
<span class="structname">XFontStruct</span>
structure.
If the font name is not in the Host Portable Character Encoding,
the result is implementation-dependent.
If the font does not exist,
<a class="xref" href="#XLoadQueryFont"><code class="function">XLoadQueryFont</code></a>
returns NULL.
</p><p>

<a class="xref" href="#XLoadQueryFont"><code class="function">XLoadQueryFont</code></a>
can generate a
<span class="errorname">BadAlloc</span>
error.
</p><p>


To unload the font and free the storage used by the font structure
that was allocated by
<a class="xref" href="#XQueryFont"><code class="function">XQueryFont</code></a>
or
<a class="xref" href="#XLoadQueryFont"><code class="function">XLoadQueryFont</code></a>,
use
<a class="xref" href="#XFreeFont"><code class="function">XFreeFont</code></a>.
</p><a id="idp47969508" class="indexterm"></a><div class="funcsynopsis"><a id="XFreeFont"></a><p><code class="funcdef"><strong class="fsfunc">XFreeFont</strong>(</code>Display<var class="pdparam"> *display</var>, XFontStruct<var class="pdparam"> *font_struct</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>font_struct</em></span>
    </span></p></td><td><p>
Specifies the storage associated with the font.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFreeFont"><code class="function">XFreeFont</code></a>
function deletes the association between the font resource ID and the specified 
font and frees the
<span class="structname">XFontStruct</span>
structure.
The font itself will be freed when no other resource references it.
The data and the font should not be referenced again.
</p><p>

<a class="xref" href="#XFreeFont"><code class="function">XFreeFont</code></a>
can generate a
<span class="errorname">BadFont</span>
error.
</p><p>


To return a given font property, use
<a class="xref" href="#XGetFontProperty"><code class="function">XGetFontProperty</code></a>.
</p><a id="idp47977380" class="indexterm"></a><div class="funcsynopsis"><a id="XGetFontProperty"></a><p><code class="funcdef">Bool <strong class="fsfunc">XGetFontProperty</strong>(</code>XFontStruct<var class="pdparam"> *font_struct</var>, Atom<var class="pdparam"> atom</var>, unsignedlong<var class="pdparam"> *value_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>font_struct</em></span>
    </span></p></td><td><p>
Specifies the storage associated with the font.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>atom</em></span>
    </span></p></td><td><p>
Specifies the atom for the property name you want returned.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>value_return</em></span>
    </span></p></td><td><p>
Returns the value of the font property.
    </p></td></tr></tbody></table></div><p>


Given the atom for that property,
the
<a class="xref" href="#XGetFontProperty"><code class="function">XGetFontProperty</code></a>
function returns the value of the specified font property. 
<a class="xref" href="#XGetFontProperty"><code class="function">XGetFontProperty</code></a>
also returns 
<span class="symbol">False</span>
if the property was not defined or 
<span class="symbol">True</span>
if it was defined.
A set of predefined atoms exists for font properties,
which can be found in
<code class="filename">&lt;X11/Xatom.h&gt;</code>.
<a id="idp47986108" class="indexterm"></a>
<a id="idp47986908" class="indexterm"></a>
<a id="idp47987716" class="indexterm"></a>
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.
</p><p>


To unload a font that was loaded by
<a class="xref" href="#XLoadFont"><code class="function">XLoadFont</code></a>,
use
<a class="xref" href="#XUnloadFont"><code class="function">XUnloadFont</code></a>.
</p><a id="idp47989996" class="indexterm"></a><div class="funcsynopsis"><a id="XUnloadFont"></a><p><code class="funcdef"><strong class="fsfunc">XUnloadFont</strong>(</code>Display<var class="pdparam"> *display</var>, Font<var class="pdparam"> font</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>font</em></span>
    </span></p></td><td><p>
Specifies the font.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XUnloadFont"><code class="function">XUnloadFont</code></a>
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.
</p><p>

<a class="xref" href="#XUnloadFont"><code class="function">XUnloadFont</code></a>
can generate a
<span class="errorname">BadFont</span>
error.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Obtaining_and_Freeing_Font_Names_and_Information"></a>Obtaining and Freeing Font Names and Information</h3></div></div></div><p>

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.
</p><p>


To return a list of the available font names, use
<a class="xref" href="#XListFonts"><code class="function">XListFonts</code></a>.
</p><a id="idp47999164" class="indexterm"></a><div class="funcsynopsis"><a id="XListFonts"></a><p><code class="funcdef">char **<strong class="fsfunc">XListFonts</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> *pattern</var>, int<var class="pdparam"> maxnames</var>, int<var class="pdparam"> *actual_count_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>pattern</em></span>
    </span></p></td><td><p>
Specifies the null-terminated pattern string that can contain wildcard 
characters.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>maxnames</em></span>
    </span></p></td><td><p>
Specifies the maximum number of names to be returned.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>actual_count_return</em></span>
    </span></p></td><td><p>
Returns the actual number of font names.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XListFonts"><code class="function">XListFonts</code></a>
function returns an array of available font names 
(as controlled by the font search path; see
<a class="xref" href="#XSetFontPath"><code class="function">XSetFontPath</code></a>)
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,
<a class="xref" href="#XListFonts"><code class="function">XListFonts</code></a>
returns NULL.
The client should call
<a class="xref" href="#XFreeFontNames"><code class="function">XFreeFontNames</code></a>
when finished with the result to free the memory.
</p><p>


To free a font name array, use
<a class="xref" href="#XFreeFontNames"><code class="function">XFreeFontNames</code></a>.
</p><a id="idp48010956" class="indexterm"></a><div class="funcsynopsis"><a id="XFreeFontNames"></a><p><code class="funcdef"><strong class="fsfunc">XFreeFontNames</strong>(</code>char<var class="pdparam"> *list[]</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>list</em></span>
    </span></p></td><td><p>
Specifies the array of strings you want to free.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFreeFontNames"><code class="function">XFreeFontNames</code></a>
function frees the array and strings returned by
<a class="xref" href="#XListFonts"><code class="function">XListFonts</code></a>
or
<a class="xref" href="#XListFontsWithInfo"><code class="function">XListFontsWithInfo</code></a>.
</p><p>


To obtain the names and information about available fonts, use
<a class="xref" href="#XListFontsWithInfo"><code class="function">XListFontsWithInfo</code></a>.
</p><a id="idp48016740" class="indexterm"></a><div class="funcsynopsis"><a id="XListFontsWithInfo"></a><p><code class="funcdef">char **<strong class="fsfunc">XListFontsWithInfo</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> *pattern</var>, int<var class="pdparam"> maxnames</var>, int<var class="pdparam"> *count_return</var>, XFontStruct<var class="pdparam"> **info_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>pattern</em></span>
    </span></p></td><td><p>
Specifies the null-terminated pattern string that can contain wildcard 
characters.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>maxnames</em></span>
    </span></p></td><td><p>
Specifies the maximum number of names to be returned.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count_return</em></span>
    </span></p></td><td><p>
Returns the actual number of matched font names.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>info_return</em></span>
    </span></p></td><td><p>
Returns the font information.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XListFontsWithInfo"><code class="function">XListFontsWithInfo</code></a>
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
<a class="xref" href="#XLoadQueryFont"><code class="function">XLoadQueryFont</code></a>
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,
<a class="xref" href="#XListFontsWithInfo"><code class="function">XListFontsWithInfo</code></a>
returns NULL.
</p><p>

To free only the allocated name array,
the client should call
<a class="xref" href="#XFreeFontNames"><code class="function">XFreeFontNames</code></a>.
To free both the name array and the font information array
or to free just the font information array,
the client should call
<a class="xref" href="#XFreeFontInfo"><code class="function">XFreeFontInfo</code></a>.
</p><p>


To free font structures and font names, use
<a class="xref" href="#XFreeFontInfo"><code class="function">XFreeFontInfo</code></a>.
</p><a id="idp48031060" class="indexterm"></a><div class="funcsynopsis"><a id="XFreeFontInfo"></a><p><code class="funcdef"><strong class="fsfunc">XFreeFontInfo</strong>(</code>char<var class="pdparam"> **names</var>, XFontStruct<var class="pdparam"> *free_info</var>, int<var class="pdparam"> actual_count</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>names</em></span>
    </span></p></td><td><p>
Specifies the list of font names.

      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>free_info</em></span>
    </span></p></td><td><p>
Specifies the font information.

      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>actual_count</em></span>
    </span></p></td><td><p>
Specifies the actual number of font names.

    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFreeFontInfo"><code class="function">XFreeFontInfo</code></a>
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
<a class="xref" href="#XLoadQueryFont"><code class="function">XLoadQueryFont</code></a>)
is passed, the structure is freed,
but the font is not closed; use
<a class="xref" href="#XUnloadFont"><code class="function">XUnloadFont</code></a>
to close the font.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Computing_Character_String_Sizes"></a>Computing Character String Sizes</h3></div></div></div><p>

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.
<a id="idp48040796" class="indexterm"></a>
<a id="idp48041172" class="indexterm"></a>
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.
</p><p>


To determine the width of an 8-bit character string, use
<a class="xref" href="#XTextWidth"><code class="function">XTextWidth</code></a>.
</p><a id="idp48042700" class="indexterm"></a><div class="funcsynopsis"><a id="XTextWidth"></a><p><code class="funcdef">int <strong class="fsfunc">XTextWidth</strong>(</code>XFontStruct<var class="pdparam"> *font_struct</var>, char<var class="pdparam"> *string</var>, int<var class="pdparam"> count</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>font_struct</em></span>
    </span></p></td><td><p>
Specifies the font used for the width computation.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the character string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count</em></span>
    </span></p></td><td><p>
Specifies the character count in the specified string.
    </p></td></tr></tbody></table></div><p>



To determine the width of a 2-byte character string, use
<a class="xref" href="#XTextWidth16"><code class="function">XTextWidth16</code></a>.
</p><a id="idp48050220" class="indexterm"></a><div class="funcsynopsis"><a id="XTextWidth16"></a><p><code class="funcdef">int <strong class="fsfunc">XTextWidth16</strong>(</code>XFontStruct<var class="pdparam"> *font_struct</var>, XChar2b<var class="pdparam"> *string</var>, int<var class="pdparam"> count</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>font_struct</em></span>
    </span></p></td><td><p>
Specifies the font used for the width computation.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the character string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count</em></span>
    </span></p></td><td><p>
Specifies the character count in the specified string.
    </p></td></tr></tbody></table></div><p>


</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Computing_Logical_Extents"></a>Computing Logical Extents</h3></div></div></div><p>

To compute the bounding box of an 8-bit character string in a given font, use
<a class="xref" href="#XTextExtents"><code class="function">XTextExtents</code></a>.
</p><a id="idp48058884" class="indexterm"></a><div class="funcsynopsis"><a id="XTextExtents"></a><p><code class="funcdef"><strong class="fsfunc">XTextExtents</strong>(</code>XFontStruct<var class="pdparam"> *font_struct</var>, char<var class="pdparam"> *string</var>, int<var class="pdparam"> nchars</var>, int<var class="pdparam"> *direction_return</var>, int*font_ascent_return,<var class="pdparam"> *font_descent_return</var>, XCharStruct<var class="pdparam"> *overall_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>font_struct</em></span>
    </span></p></td><td><p>
Specifies the 
<span class="structname">XFontStruct</span>
structure.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the character string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nchars</em></span>
    </span></p></td><td><p>
Specifies the number of characters in the character string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>direction_return</em></span>
    </span></p></td><td><p>
Returns the value of the direction hint
(<span class="symbol">FontLeftToRight</span>
or
<span class="symbol">FontRightToLeft</span>).
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>font_ascent_return</em></span>
    </span></p></td><td><p>
Returns the font ascent.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>font_descent_return</em></span>
    </span></p></td><td><p>
Returns the font descent.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>overall_return</em></span>
    </span></p></td><td><p>
Returns the overall size in the specified
<span class="structname">XCharStruct</span>
structure.
    </p></td></tr></tbody></table></div><p>



To compute the bounding box of a 2-byte character string in a given font, use
<a class="xref" href="#XTextExtents16"><code class="function">XTextExtents16</code></a>.
</p><a id="idp48072884" class="indexterm"></a><div class="funcsynopsis"><a id="XTextExtents16"></a><p><code class="funcdef"><strong class="fsfunc">XTextExtents16</strong>(</code>XFontStruct<var class="pdparam"> *font_struct</var>, XChar2b<var class="pdparam"> *string</var>, int<var class="pdparam"> nchars</var>, int<var class="pdparam"> *direction_return</var>, int*font_ascent_return,<var class="pdparam"> *font_descent_return</var>, XCharStruct<var class="pdparam"> *overall_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>font_struct</em></span>
    </span></p></td><td><p>
Specifies the 
<span class="structname">XFontStruct</span>
structure.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the character string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nchars</em></span>
    </span></p></td><td><p>
Specifies the number of characters in the character string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>direction_return</em></span>
    </span></p></td><td><p>
Returns the value of the direction hint
(<span class="symbol">FontLeftToRight</span>
or
<span class="symbol">FontRightToLeft</span>).
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>font_ascent_return</em></span>
    </span></p></td><td><p>
Returns the font ascent.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>font_descent_return</em></span>
    </span></p></td><td><p>
Returns the font descent.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>overall_return</em></span>
    </span></p></td><td><p>
Returns the overall size in the specified
<span class="structname">XCharStruct</span>
structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XTextExtents"><code class="function">XTextExtents</code></a>
and
<a class="xref" href="#XTextExtents16"><code class="function">XTextExtents16</code></a>
functions 
perform the size computation locally and, thereby,
avoid the round-trip overhead of
<a class="xref" href="#XQueryTextExtents"><code class="function">XQueryTextExtents</code></a>
and
<a class="xref" href="#XQueryTextExtents16"><code class="function">XQueryTextExtents16</code></a>.
Both functions return an
<span class="structname">XCharStruct</span>
structure, whose members are set to the values as follows.
</p><p>

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.
</p><p>

For fonts defined with linear indexing rather than 2-byte matrix indexing,
each 
<span class="structname">XChar2b</span>
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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Querying_Character_String_Sizes"></a>Querying Character String Sizes</h3></div></div></div><p>

To query the server for the bounding box of an 8-bit character string in a 
given font, use 
<a class="xref" href="#XQueryTextExtents"><code class="function">XQueryTextExtents</code></a>.
</p><a id="idp48091772" class="indexterm"></a><div class="funcsynopsis"><a id="XQueryTextExtents"></a><p><code class="funcdef"><strong class="fsfunc">XQueryTextExtents</strong>(</code>Display<var class="pdparam"> *display</var>, XID<var class="pdparam"> font_ID</var>, char<var class="pdparam"> *string</var>, int<var class="pdparam"> nchars</var>, int<var class="pdparam"> *direction_return</var>, int*font_ascent_return,<var class="pdparam"> *font_descent_return</var>, XCharStruct<var class="pdparam"> *overall_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>font_ID</em></span>
    </span></p></td><td><p>
Specifies either the font ID or the 
<span class="type">GContext</span>
ID that contains the font.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the character string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nchars</em></span>
    </span></p></td><td><p>
Specifies the number of characters in the character string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>direction_return</em></span>
    </span></p></td><td><p>
Returns the value of the direction hint
(<span class="symbol">FontLeftToRight</span>
or
<span class="symbol">FontRightToLeft</span>).
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>font_ascent_return</em></span>
    </span></p></td><td><p>
Returns the font ascent.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>font_descent_return</em></span>
    </span></p></td><td><p>
Returns the font descent.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>overall_return</em></span>
    </span></p></td><td><p>
Returns the overall size in the specified
<span class="structname">XCharStruct</span>
structure.
    </p></td></tr></tbody></table></div><p>



To query the server for the bounding box of a 2-byte character string
in a given font, use
<a class="xref" href="#XQueryTextExtents16"><code class="function">XQueryTextExtents16</code></a>.
</p><a id="idp48107452" class="indexterm"></a><div class="funcsynopsis"><a id="XQueryTextExtents16"></a><p><code class="funcdef"><strong class="fsfunc">XQueryTextExtents16</strong>(</code>Display<var class="pdparam"> *display</var>, XID<var class="pdparam"> font_ID</var>, XChar2b<var class="pdparam"> *string</var>, int<var class="pdparam"> nchars</var>, int<var class="pdparam"> *direction_return</var>, int*font_ascent_return,<var class="pdparam"> *font_descent_return</var>, XCharStruct<var class="pdparam"> *overall_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>font_ID</em></span>
    </span></p></td><td><p>
Specifies either the font ID or the 
<span class="type">GContext</span>
ID that contains the font.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the character string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nchars</em></span>
    </span></p></td><td><p>
Specifies the number of characters in the character string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>direction_return</em></span>
    </span></p></td><td><p>
Returns the value of the direction hint
(<span class="symbol">FontLeftToRight</span>
or
<span class="symbol">FontRightToLeft</span>).
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>font_ascent_return</em></span>
    </span></p></td><td><p>
Returns the font ascent.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>font_descent_return</em></span>
    </span></p></td><td><p>
Returns the font descent.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>overall_return</em></span>
    </span></p></td><td><p>
Returns the overall size in the specified
<span class="structname">XCharStruct</span>
structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XQueryTextExtents"><code class="function">XQueryTextExtents</code></a>
and
<a class="xref" href="#XQueryTextExtents16"><code class="function">XQueryTextExtents16</code></a>
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
<a class="xref" href="#XTextExtents"><code class="function">XTextExtents</code></a>
and 
<a class="xref" href="#XTextExtents16"><code class="function">XTextExtents16</code></a>.
Both functions return a
<span class="structname">XCharStruct</span>
structure, whose members are set to the values as follows.
</p><p>

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.
</p><p>

For fonts defined with linear indexing rather than 2-byte matrix indexing,
each 
<span class="structname">XChar2b</span>
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.
</p><p>

Characters with all zero metrics are ignored.
If the font has no defined default_char,
the undefined characters in the string are also ignored.
</p><p>

<a class="xref" href="#XQueryTextExtents"><code class="function">XQueryTextExtents</code></a>
and
<a class="xref" href="#XQueryTextExtents16"><code class="function">XQueryTextExtents16</code></a>
can generate
<span class="errorname">BadFont</span>
and
<span class="errorname">BadGC</span>
errors.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Drawing_Text"></a>Drawing Text</h2></div></div></div><p>

This section discusses how to draw:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Complex text 
    </p></li><li class="listitem"><p>
Text characters
    </p></li><li class="listitem"><p>
Image text characters
    </p></li></ul></div><p>

The fundamental text functions
<a class="xref" href="#XDrawText"><code class="function">XDrawText</code></a>
and
<a class="xref" href="#XDrawText16"><code class="function">XDrawText16</code></a>
use the following structures:
</p><p>

<a id="idp48132284" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     char *chars;     /* pointer to string */
     int nchars;      /* number of characters */
     int delta;       /* delta between strings */
     Font font;       /* Font to print it in, None don't change */
} XTextItem;
</pre><p>
</p><p>

<a id="idp48134044" class="indexterm"></a>
</p><pre class="literallayout">


typedef struct {
     XChar2b *chars;     /* pointer to two-byte characters */
     int nchars;         /* number of characters */
     int delta;         /* delta between strings */
     Font font;         /* font to print it in, None don't change */
} XTextItem16;
</pre><p>
</p><p>


If the font member is not
<span class="symbol">None</span>,
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.
</p><p>

For example, consider the background rectangle drawn by
<a class="xref" href="#XDrawImageString"><code class="function">XDrawImageString</code></a>.
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
<span class="structname">XFontStruct</span>
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
<span class="structname">XFontStruct</span>
structure.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Drawing_Complex_Text"></a>Drawing Complex Text</h3></div></div></div><p>

<a id="idp48139076" class="indexterm"></a>
<a id="idp48139580" class="indexterm"></a>
</p><p>

To draw 8-bit characters in a given drawable, use
<a class="xref" href="#XDrawText"><code class="function">XDrawText</code></a>.
</p><a id="idp48140892" class="indexterm"></a><div class="funcsynopsis"><a id="XDrawText"></a><p><code class="funcdef"><strong class="fsfunc">XDrawText</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, intx,<var class="pdparam"> y</var>, XTextItem<var class="pdparam"> *items</var>, int<var class="pdparam"> nitems</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, which are relative to the origin of the
specified drawable and define the origin of the first character.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>items</em></span>
    </span></p></td><td><p>
Specifies an array of text items.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nitems</em></span>
    </span></p></td><td><p>
Specifies the number of text items in the array.
    </p></td></tr></tbody></table></div><p>



To draw 2-byte characters in a given drawable, use
<a class="xref" href="#XDrawText16"><code class="function">XDrawText16</code></a>.
</p><a id="idp48154420" class="indexterm"></a><div class="funcsynopsis"><a id="XDrawText16"></a><p><code class="funcdef"><strong class="fsfunc">XDrawText16</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, intx,<var class="pdparam"> y</var>, XTextItem16<var class="pdparam"> *items</var>, int<var class="pdparam"> nitems</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, which are relative to the origin of the
specified drawable and define the origin of the first character.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>items</em></span>
    </span></p></td><td><p>
Specifies an array of text items.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nitems</em></span>
    </span></p></td><td><p>
Specifies the number of text items in the array.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDrawText16"><code class="function">XDrawText16</code></a>
function is similar to
<a class="xref" href="#XDrawText"><code class="function">XDrawText</code></a>
except that it uses 2-byte or 16-bit characters.
Both functions allow complex spacing and font shifts between counted strings.
</p><p>

Each text item is processed in turn.
A font member other than 
<span class="symbol">None</span>
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
<span class="errorname">BadFont</span>
error, the previous text items may have been drawn.
</p><p>

For fonts defined with linear indexing rather than 2-byte matrix indexing,
each 
<span class="structname">XChar2b</span>
structure is interpreted as a 16-bit number with byte1 as the 
most significant byte.
</p><p>

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.
</p><p>

<a class="xref" href="#XDrawText"><code class="function">XDrawText</code></a>
and
<a class="xref" href="#XDrawText16"><code class="function">XDrawText16</code></a>
can generate
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadFont</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadMatch</span>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Drawing_Text_Characters"></a>Drawing Text Characters</h3></div></div></div><p>

<a id="idp48173964" class="indexterm"></a>
<a id="idp48174468" class="indexterm"></a>
To draw 8-bit characters in a given drawable, use
<a class="xref" href="#XDrawString"><code class="function">XDrawString</code></a>.
</p><a id="idp48175460" class="indexterm"></a><div class="funcsynopsis"><a id="XDrawString"></a><p><code class="funcdef"><strong class="fsfunc">XDrawString</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, int<var class="pdparam"> x</var>, int<var class="pdparam"> y</var>, char<var class="pdparam"> *string</var>, int<var class="pdparam"> length</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, which are relative to the origin of the
specified drawable and define the origin of the first character.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the character string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>length</em></span>
    </span></p></td><td><p>
Specifies the number of characters in the string argument.
    </p></td></tr></tbody></table></div><p>



To draw 2-byte characters in a given drawable, use
<a class="xref" href="#XDrawString16"><code class="function">XDrawString16</code></a>.
</p><a id="idp48189436" class="indexterm"></a><div class="funcsynopsis"><a id="XDrawString16"></a><p><code class="funcdef"><strong class="fsfunc">XDrawString16</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, intx,<var class="pdparam"> y</var>, XChar2b<var class="pdparam"> *string</var>, int<var class="pdparam"> length</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, which are relative to the origin of the
specified drawable and define the origin of the first character.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the character string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>length</em></span>
    </span></p></td><td><p>
Specifies the number of characters in the string argument.
    </p></td></tr></tbody></table></div><p>


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
<a class="xref" href="#XDrawString16"><code class="function">XDrawString16</code></a>,
each byte is used as a byte2 with a byte1 of zero.
</p><p>

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.
</p><p>

<a class="xref" href="#XDrawString"><code class="function">XDrawString</code></a>
and
<a class="xref" href="#XDrawString16"><code class="function">XDrawString16</code></a>
can generate
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadMatch</span>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Drawing_Image_Text_Characters"></a>Drawing Image Text Characters</h3></div></div></div><p>

<a id="idp48209220" class="indexterm"></a>
<a id="idp48209788" class="indexterm"></a>
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.
<a id="idp48210556" class="indexterm"></a>
<a id="idp48210988" class="indexterm"></a>
</p><p>


To draw 8-bit image text characters in a given drawable, use
<a class="xref" href="#XDrawImageString"><code class="function">XDrawImageString</code></a>.
</p><a id="idp48212532" class="indexterm"></a><div class="funcsynopsis"><a id="XDrawImageString"></a><p><code class="funcdef"><strong class="fsfunc">XDrawImageString</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, intx,<var class="pdparam"> y</var>, char<var class="pdparam"> *string</var>, int<var class="pdparam"> length</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, which are relative to the origin of the
specified drawable and define the origin of the first character.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the character string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>length</em></span>
    </span></p></td><td><p>
Specifies the number of characters in the string argument.
    </p></td></tr></tbody></table></div><p>



To draw 2-byte image text characters in a given drawable, use
<a class="xref" href="#XDrawImageString16"><code class="function">XDrawImageString16</code></a>.
</p><a id="idp48228252" class="indexterm"></a><div class="funcsynopsis"><a id="XDrawImageString16"></a><p><code class="funcdef"><strong class="fsfunc">XDrawImageString16</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, intx,<var class="pdparam"> y</var>, XChar2b<var class="pdparam"> *string</var>, int<var class="pdparam"> length</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, which are relative to the origin of the
specified drawable and define the origin of the first character.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the character string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>length</em></span>
    </span></p></td><td><p>
Specifies the number of characters in the string argument.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDrawImageString16"><code class="function">XDrawImageString16</code></a>
function is similar to
<a class="xref" href="#XDrawImageString"><code class="function">XDrawImageString</code></a>
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.
</p><p>

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:
</p><p>

</p><pre class="literallayout">
[x, y - font-ascent]
</pre><p>
</p><p>

The width is:
</p><p>

</p><pre class="literallayout">
overall-width
</pre><p>
</p><p>

The height is:
</p><p>

</p><pre class="literallayout">
font-ascent + font-descent
</pre><p>
</p><p>

The overall-width, font-ascent, and font-descent
are as would be returned by 
<a class="xref" href="#XQueryTextExtents"><code class="function">XQueryTextExtents</code></a>
using gc and string.
The function and fill-style defined in the GC are ignored for these functions. 
The effective function is 
<span class="symbol">GXcopy</span>,
and the effective fill-style is
<span class="symbol">FillSolid</span>.
</p><p>

For fonts defined with 2-byte matrix indexing
and used with
<a class="xref" href="#XDrawImageString"><code class="function">XDrawImageString</code></a>,
each byte is used as a byte2 with a byte1 of zero.
</p><p>

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

<a class="xref" href="#XDrawImageString"><code class="function">XDrawImageString</code></a>
and
<a class="xref" href="#XDrawImageString16"><code class="function">XDrawImageString16</code></a>
can generate
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadMatch</span>
errors.
</p><p>

</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Transferring_Images_between_Client_and_Server"></a>Transferring Images between Client and Server</h2></div></div></div><p>

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 <a class="link" href="#Manipulating_Images" title="Manipulating Images">section 16.8</a>).
</p><p>

All the image manipulation functions discussed in this section make use of 
the 
<span class="structname">XImage</span>
structure,
which describes an image as it exists in the client's memory.
</p><p>

<a id="idp48257492" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct _XImage {
     int width, height;         /* size of image */
     int xoffset;               /* number of pixels offset in X direction */
     int format;                /* XYBitmap, XYPixmap, ZPixmap */
     char *data;                /* pointer to image data */
     int byte_order;            /* data byte order, LSBFirst, MSBFirst */
     int bitmap_unit;           /* quant. of scanline 8, 16, 32 */
     int bitmap_bit_order;      /* LSBFirst, MSBFirst */
     int bitmap_pad;            /* 8, 16, 32 either XY or ZPixmap */
     int depth;                 /* depth of image */
     int bytes_per_line;        /* accelerator to next scanline */
     int bits_per_pixel;        /* bits per pixel (ZPixmap) */
     unsigned long red_mask;    /* bits in z arrangement */
     unsigned long green_mask;
     unsigned long blue_mask;
     XPointer obdata;           /* hook for the object routines to hang on */
     struct funcs {             /* image manipulation routines */
          struct _XImage *(*create_image)();
          int             (*destroy_image)();
          unsigned long   (*get_pixel)();
          int             (*put_pixel)();
          struct _XImage  *(*sub_image)();
          int            (*add_pixel)();
     } f;
} XImage;
</pre><p>
</p><p>



To initialize the image manipulation routines of an image structure, use
<a class="xref" href="#XInitImage"><code class="function">XInitImage</code></a>.
</p><a id="idp48261452" class="indexterm"></a><div class="funcsynopsis"><a id="XInitImage"></a><p><code class="funcdef">Status <strong class="fsfunc">XInitImage</strong>(</code>XImage<var class="pdparam"> *image</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ximage</em></span>
    </span></p></td><td><p>
Specifies the image.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XInitImage"><code class="function">XInitImage</code></a>
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,
<a class="xref" href="#XInitImage"><code class="function">XInitImage</code></a>
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.
</p><p>

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.
</p><p>

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.
</p><p>


To combine an image with a rectangle of a drawable on the display,
use
<a class="xref" href="#XPutImage"><code class="function">XPutImage</code></a>.
</p><a id="idp48269572" class="indexterm"></a><div class="funcsynopsis"><a id="XPutImage"></a><p><code class="funcdef"><strong class="fsfunc">XPutImage</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, XImage<var class="pdparam"> *image</var>, intsrc_x,<var class="pdparam"> src_y</var>, intdest_x,<var class="pdparam"> dest_y</var>, unsignedintwidth,<var class="pdparam"> height</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>image</em></span>
    </span></p></td><td><p>
Specifies the image you want combined with the rectangle. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>src_x</em></span>
    </span></p></td><td><p>
Specifies the offset in X from the left edge of the image defined
by the 
<span class="structname">XImage</span>
structure.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>src_y</em></span>
    </span></p></td><td><p>
Specifies the offset in Y from the top edge of the image defined
by the 
<span class="structname">XImage</span>
structure.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dest_x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dest_y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, which are relative to the origin of the
drawable and are the coordinates of the subimage.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height of the subimage, which define the dimensions
of the rectangle.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XPutImage"><code class="function">XPutImage</code></a>
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 
<span class="symbol">XYBitmap</span>
format is used, the depth of the image must be one,
or a
<span class="errorname">BadMatch</span>
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 
<span class="symbol">XYPixmap</span>
and 
<span class="symbol">ZPixmap</span>,
the depth of the image must match the depth of the drawable,
or a
<span class="errorname">BadMatch</span>
error results.
</p><p>

If the characteristics of the image (for example, byte_order and bitmap_unit)
differ from what the server requires,
<a class="xref" href="#XPutImage"><code class="function">XPutImage</code></a>
automatically makes the appropriate
conversions.
</p><p>

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.
</p><p>

<a class="xref" href="#XPutImage"><code class="function">XPutImage</code></a>
can generate
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadGC</span>,
<span class="errorname">BadMatch</span>,
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To return the contents of a rectangle in a given drawable on the display,
use
<a class="xref" href="#XGetImage"><code class="function">XGetImage</code></a>.
This function specifically supports rudimentary screen dumps.
</p><a id="idp48296212" class="indexterm"></a><div class="funcsynopsis"><a id="XGetImage"></a><p><code class="funcdef">XImage *<strong class="fsfunc">XGetImage</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, intx,<var class="pdparam"> y</var>, unsignedintwidth,<var class="pdparam"> height</var>, unsignedlong<var class="pdparam"> plane_mask</var>, int<var class="pdparam"> format</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, which are relative to the origin of the
drawable and define the upper-left corner of the rectangle.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height of the subimage, which define the dimensions
of the rectangle.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>plane_mask</em></span>
    </span></p></td><td><p>
Specifies the plane mask.

      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>format</em></span>
    </span></p></td><td><p>
Specifies the format for the image.
You can pass
<span class="symbol">XYPixmap</span>
or 
<span class="symbol">ZPixmap</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetImage"><code class="function">XGetImage</code></a>
function returns a pointer to an
<span class="structname">XImage</span>
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 
<span class="symbol">XYPixmap</span>,
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 
<span class="symbol">ZPixmap</span>,
<a class="xref" href="#XGetImage"><code class="function">XGetImage</code></a>
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.
</p><p>

<a class="xref" href="#XGetImage"><code class="function">XGetImage</code></a>
returns the depth of the image to the depth member of the
<span class="structname">XImage</span>
structure.
The depth of the image is as specified when the drawable was created,
except when getting a subset of the planes in 
<span class="symbol">XYPixmap</span>
format, when the depth is given by the number of bits set to 1 in plane_mask.
</p><p>

If the drawable is a pixmap, 
the given rectangle must be wholly contained within the pixmap, 
or a
<span class="errorname">BadMatch</span>
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
<span class="errorname">BadMatch</span>
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,
<a class="xref" href="#XGetImage"><code class="function">XGetImage</code></a>
returns NULL.
</p><p>

<a class="xref" href="#XGetImage"><code class="function">XGetImage</code></a>
can generate
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadMatch</span>,
and
<span class="errorname">BadValue</span>
errors.

</p><p>

To copy the contents of a rectangle on the display
to a location within a preexisting image structure, use
<a class="xref" href="#XGetSubImage"><code class="function">XGetSubImage</code></a>.
</p><a id="idp48321980" class="indexterm"></a><div class="funcsynopsis"><a id="XGetSubImage"></a><p><code class="funcdef">XImage *<strong class="fsfunc">XGetSubImage</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, intx,<var class="pdparam"> y</var>, unsignedintwidth,<var class="pdparam"> height</var>, unsignedlong<var class="pdparam"> plane_mask</var>, int<var class="pdparam"> format</var>, XImage<var class="pdparam"> *dest_image</var>, intdest_x,<var class="pdparam"> dest_y</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, which are relative to the origin of the
drawable and define the upper-left corner of the rectangle.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height of the subimage, which define the dimensions
of the rectangle.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>plane_mask</em></span>
    </span></p></td><td><p>
Specifies the plane mask.

      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>format</em></span>
    </span></p></td><td><p>
Specifies the format for the image.
You can pass
<span class="symbol">XYPixmap</span>
or 
<span class="symbol">ZPixmap</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dest_image</em></span>
    </span></p></td><td><p>
Specifies the destination image.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dest_x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dest_y</em></span>
    </span></p></td><td><p>
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.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XGetSubImage"><code class="function">XGetSubImage</code></a>
function updates dest_image with the specified subimage in the same manner as 
<a class="xref" href="#XGetImage"><code class="function">XGetImage</code></a>.
If the format argument is 
<span class="symbol">XYPixmap</span>,
the image contains only the bit planes you passed to the plane_mask argument.
If the format argument is 
<span class="symbol">ZPixmap</span>,
<a class="xref" href="#XGetSubImage"><code class="function">XGetSubImage</code></a>
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,
<a class="xref" href="#XGetSubImage"><code class="function">XGetSubImage</code></a>
returns a pointer to the same
<span class="structname">XImage</span>
structure specified by dest_image.
</p><p>

The depth of the destination
<span class="structname">XImage</span>
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
<span class="errorname">BadMatch</span>
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
<span class="errorname">BadMatch</span>
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,
<a class="xref" href="#XGetSubImage"><code class="function">XGetSubImage</code></a>
returns NULL.
</p><p>

<a class="xref" href="#XGetSubImage"><code class="function">XGetSubImage</code></a>
can generate
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadGC</span>,
<span class="errorname">BadMatch</span>,
and
<span class="errorname">BadValue</span>
errors.



</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Window_and_Session_Manager_Functions"></a>Chapter 9. Window and Session Manager Functions</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Changing_the_Parent_of_a_Window">Changing the Parent of a Window</a></span></dt><dt><span class="sect1"><a href="#Controlling_the_Lifetime_of_a_Window">Controlling the Lifetime of a Window</a></span></dt><dt><span class="sect1"><a href="#Managing_Installed_Colormaps">Managing Installed Colormaps</a></span></dt><dt><span class="sect1"><a href="#Setting_and_Retrieving_the_Font_Search_Path">Setting and Retrieving the Font Search Path</a></span></dt><dt><span class="sect1"><a href="#Grabbing_the_Server">Grabbing the Server</a></span></dt><dt><span class="sect1"><a href="#Killing_Clients">Killing Clients</a></span></dt><dt><span class="sect1"><a href="#Controlling_the_Screen_Saver">Controlling the Screen Saver</a></span></dt><dt><span class="sect1"><a href="#Controlling_Host_Access">Controlling Host Access</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Adding_Getting_or_Removing_Hosts">Adding, Getting, or Removing Hosts</a></span></dt><dt><span class="sect2"><a href="#Changing_Enabling_or_Disabling_Access_Control">Changing, Enabling, or Disabling Access Control</a></span></dt></dl></dd></dl></div><p>
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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Change the parent of a window</p></li><li class="listitem"><p>Control the lifetime of a window</p></li><li class="listitem"><p>Manage installed colormaps</p></li><li class="listitem"><p>Set and retrieve the font search path</p></li><li class="listitem"><p>Grab the server</p></li><li class="listitem"><p>Kill a client</p></li><li class="listitem"><p>Control the screen saver</p></li><li class="listitem"><p>Control host access</p></li></ul></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Changing_the_Parent_of_a_Window"></a>Changing the Parent of a Window</h2></div></div></div><p>

To change a window's parent to another window on the same screen, use
<a class="xref" href="#XReparentWindow"><code class="function">XReparentWindow</code></a>.
There is no way to move a window between screens.
</p><a id="idp40980852" class="indexterm"></a><div class="funcsynopsis"><a id="XReparentWindow"></a><p><code class="funcdef"><strong class="fsfunc">XReparentWindow</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, Window<var class="pdparam"> parent</var>, intx,<var class="pdparam"> y</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>parent</em></span>
    </span></p></td><td><p>
Specifies the parent window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates of the position in the new parent window.
    </p></td></tr></tbody></table></div><p>


If the specified window is mapped,
<a class="xref" href="#XReparentWindow"><code class="function">XReparentWindow</code></a>
automatically performs an
<code class="systemitem">UnmapWindow</code>
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.
</p><p>

After reparenting the specified window,
<a class="xref" href="#XReparentWindow"><code class="function">XReparentWindow</code></a>
causes the X server to generate a
<span class="symbol">ReparentNotify</span>
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
<span class="symbol">True</span>.
Finally, if the specified window was originally mapped,
the X server automatically performs a
<code class="systemitem">MapWindow</code>
request on it.
</p><p>

The X server performs normal exposure processing on formerly obscured
windows.
The X server might not generate 
<span class="symbol">Expose</span>
events for regions from the initial
<code class="systemitem">UnmapWindow</code>
request that are immediately obscured by the final
<code class="systemitem">MapWindow</code>
request.
A
<span class="errorname">BadMatch</span>
error results if:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The new parent window is not on the same screen as
the old parent window.
    </p></li><li class="listitem"><p>
The new parent window is the specified window or an inferior of the
specified window.
    </p></li><li class="listitem"><p>
The new parent is
<span class="symbol">InputOnly</span>,
and the window is not.
    </p></li><li class="listitem"><p>
The specified window has a
<span class="symbol">ParentRelative</span>
background, and the new parent window is not the same depth as the
specified window.
    </p></li></ul></div><p>

<a class="xref" href="#XReparentWindow"><code class="function">XReparentWindow</code></a>
can generate
<span class="errorname">BadMatch</span>
and
<span class="errorname">BadWindow</span>
errors.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Controlling_the_Lifetime_of_a_Window"></a>Controlling the Lifetime of a Window</h2></div></div></div><p>

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 <a class="link" href="#Using_X_Server_Connection_Close_Operations" title="Using X Server Connection Close Operations">section 2.6</a>.
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.
</p><p>

The X server automatically removes windows from the save-set
when they are destroyed.
</p><p>


To add or remove a window from the client's save-set, use
<a class="xref" href="#XChangeSaveSet"><code class="function">XChangeSaveSet</code></a>.
</p><a id="idp45753604" class="indexterm"></a><div class="funcsynopsis"><a id="XChangeSaveSet"></a><p><code class="funcdef"><strong class="fsfunc">XChangeSaveSet</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, int<var class="pdparam"> change_mode</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window that you want to add to or delete from the client's
save-set.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>change_mode</em></span>
    </span></p></td><td><p>
Specifies the mode.
You can pass
<span class="symbol">SetModeInsert</span>
or
<span class="symbol">SetModeDelete</span>.
    </p></td></tr></tbody></table></div><p>


Depending on the specified mode,
<a class="xref" href="#XChangeSaveSet"><code class="function">XChangeSaveSet</code></a>
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
<span class="errorname">BadMatch</span>
error results.
</p><p>

<a class="xref" href="#XChangeSaveSet"><code class="function">XChangeSaveSet</code></a>
can generate
<span class="errorname">BadMatch</span>,
<span class="errorname">BadValue</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To add a window to the client's save-set, use
<a class="xref" href="#XAddToSaveSet"><code class="function">XAddToSaveSet</code></a>.
</p><a id="idp43484604" class="indexterm"></a><div class="funcsynopsis"><a id="XAddToSaveSet"></a><p><code class="funcdef"><strong class="fsfunc">XAddToSaveSet</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window that you want to add to the client's save-set.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XAddToSaveSet"><code class="function">XAddToSaveSet</code></a>
function adds the specified window to the client's save-set.
The specified window must have been created by some other client,
or a
<span class="errorname">BadMatch</span>
error results.
</p><p>

<a class="xref" href="#XAddToSaveSet"><code class="function">XAddToSaveSet</code></a>
can generate
<span class="errorname">BadMatch</span>
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To remove a window from the client's save-set, use
<a class="xref" href="#XRemoveFromSaveSet"><code class="function">XRemoveFromSaveSet</code></a>.
</p><a id="idp43493884" class="indexterm"></a><div class="funcsynopsis"><a id="XRemoveFromSaveSet"></a><p><code class="funcdef"><strong class="fsfunc">XRemoveFromSaveSet</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window that you want to delete from the client's save-set.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XRemoveFromSaveSet"><code class="function">XRemoveFromSaveSet</code></a>
function removes the specified window from the client's save-set.
The specified window must have been created by some other client,
or a
<span class="errorname">BadMatch</span>
error results.
</p><p>

<a class="xref" href="#XRemoveFromSaveSet"><code class="function">XRemoveFromSaveSet</code></a>
can generate
<span class="errorname">BadMatch</span>
and
<span class="errorname">BadWindow</span>
errors.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Managing_Installed_Colormaps"></a>Managing Installed Colormaps</h2></div></div></div><p>

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.
</p><p>

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
<a class="xref" href="#XInstallColormap"><code class="function">XInstallColormap</code></a>,
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
<a class="xref" href="#XUninstallColormap"><code class="function">XUninstallColormap</code></a>
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.
</p><p>


To install a colormap, use
<a class="xref" href="#XInstallColormap"><code class="function">XInstallColormap</code></a>.
</p><a id="idp44286804" class="indexterm"></a><div class="funcsynopsis"><a id="XInstallColormap"></a><p><code class="funcdef"><strong class="fsfunc">XInstallColormap</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XInstallColormap"><code class="function">XInstallColormap</code></a>
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
<a class="xref" href="#XCreateWindow"><code class="function">XCreateWindow</code></a>,
<a class="xref" href="#XCreateSimpleWindow"><code class="function">XCreateSimpleWindow</code></a>,
<a class="xref" href="#XChangeWindowAttributes"><code class="function">XChangeWindowAttributes</code></a>,
or
<a class="xref" href="#XSetWindowColormap"><code class="function">XSetWindowColormap</code></a>.
</p><p>

If the specified colormap is not already an installed colormap, 
the X server generates a
<span class="symbol">ColormapNotify</span>
event on each window that has that colormap.
In addition, for every other colormap that is installed as 
a result of a call to
<a class="xref" href="#XInstallColormap"><code class="function">XInstallColormap</code></a>,
the X server generates a
<span class="symbol">ColormapNotify</span>
event on each window that has that colormap.
</p><p>

<a class="xref" href="#XInstallColormap"><code class="function">XInstallColormap</code></a>
can generate a
<span class="errorname">BadColor</span>
error.
</p><p>


To uninstall a colormap, use
<a class="xref" href="#XUninstallColormap"><code class="function">XUninstallColormap</code></a>.
</p><a id="idp44090900" class="indexterm"></a><div class="funcsynopsis"><a id="XUninstallColormap"></a><p><code class="funcdef"><strong class="fsfunc">XUninstallColormap</strong>(</code>Display<var class="pdparam"> *display</var>, Colormap<var class="pdparam"> colormap</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XUninstallColormap"><code class="function">XUninstallColormap</code></a>
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.
</p><p>

If the specified colormap becomes uninstalled, 
the X server generates a
<span class="symbol">ColormapNotify</span>
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 
<a class="xref" href="#XUninstallColormap"><code class="function">XUninstallColormap</code></a>,
the X server generates a
<span class="symbol">ColormapNotify</span>
event on each window that has that colormap.
</p><p>

<a class="xref" href="#XUninstallColormap"><code class="function">XUninstallColormap</code></a>
can generate a
<span class="errorname">BadColor</span>
error.
</p><p>


To obtain a list of the currently installed colormaps for a given screen, use
<a class="xref" href="#XListInstalledColormaps"><code class="function">XListInstalledColormaps</code></a>.
</p><a id="idp44101348" class="indexterm"></a><div class="funcsynopsis"><a id="XListInstalledColormaps"></a><p><code class="funcdef">Colormap *<strong class="fsfunc">XListInstalledColormaps</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, int<var class="pdparam"> *num_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window that determines the screen.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>num_return</em></span>
    </span></p></td><td><p>
Returns the number of currently installed colormaps.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XListInstalledColormaps"><code class="function">XListInstalledColormaps</code></a>
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
<a class="xref" href="#XFree"></a>.
</p><p>

<a class="xref" href="#XListInstalledColormaps"><code class="function">XListInstalledColormaps</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Setting_and_Retrieving_the_Font_Search_Path"></a>Setting and Retrieving the Font Search Path</h2></div></div></div><p>

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.
</p><p>


To set the font search path, use
<a class="xref" href="#XSetFontPath"><code class="function">XSetFontPath</code></a>.
</p><a id="idp44245996" class="indexterm"></a><div class="funcsynopsis"><a id="XSetFontPath"></a><p><code class="funcdef"><strong class="fsfunc">XSetFontPath</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> **directories</var>, int<var class="pdparam"> ndirs</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>directories</em></span>
    </span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>ndirs</em></span>
    </span></p></td><td><p>
Specifies the number of directories in the path.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetFontPath"><code class="function">XSetFontPath</code></a>
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.
</p><p>

<a class="xref" href="#XSetFontPath"><code class="function">XSetFontPath</code></a>
can generate a
<span class="errorname">BadValue</span>
error.
</p><p>


To get the current font search path, use
<a class="xref" href="#XGetFontPath"><code class="function">XGetFontPath</code></a>.
</p><a id="idp44257324" class="indexterm"></a><div class="funcsynopsis"><a id="XGetFontPath"></a><p><code class="funcdef">char **<strong class="fsfunc">XGetFontPath</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> *npaths_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>npaths_return</em></span>
    </span></p></td><td><p>
Returns the number of strings in the font path array.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetFontPath"><code class="function">XGetFontPath</code></a>
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
<a class="xref" href="#XFreeFontPath"><code class="function">XFreeFontPath</code></a>.
</p><p>


To free data returned by
<a class="xref" href="#XGetFontPath"><code class="function">XGetFontPath</code></a>,
use
<a class="xref" href="#XFreeFontPath"><code class="function">XFreeFontPath</code></a>.
</p><a id="idp44266124" class="indexterm"></a><div class="funcsynopsis"><a id="XFreeFontPath"></a><p><code class="funcdef"><strong class="fsfunc">XFreeFontPath</strong>(</code>char<var class="pdparam"> **list</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>list</em></span>
    </span></p></td><td><p>
Specifies the array of strings you want to free.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFreeFontPath"><code class="function">XFreeFontPath</code></a>
function
frees the data allocated by
<a class="xref" href="#XGetFontPath"><code class="function">XGetFontPath</code></a>.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Grabbing_the_Server"></a>Grabbing the Server</h2></div></div></div><p>

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.
<a id="idp45720164" class="indexterm"></a>
<a id="idp45720588" class="indexterm"></a>
Although grabbing the server is highly discouraged, it is sometimes necessary.
</p><p>


To grab the server, use
<a class="xref" href="#XGrabServer"><code class="function">XGrabServer</code></a>.
</p><a id="idp45722260" class="indexterm"></a><a id="idp45722828" class="indexterm"></a><a id="idp45723396" class="indexterm"></a><div class="funcsynopsis"><a id="XGrabServer"></a><p><code class="funcdef"><strong class="fsfunc">XGrabServer</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGrabServer"><code class="function">XGrabServer</code></a>
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.
</p><p>


To ungrab the server, use
<a class="xref" href="#XUngrabServer"><code class="function">XUngrabServer</code></a>.
</p><a id="idp45729300" class="indexterm"></a><div class="funcsynopsis"><a id="XUngrabServer"></a><p><code class="funcdef"><strong class="fsfunc">XUngrabServer</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XUngrabServer"><code class="function">XUngrabServer</code></a>
function restarts processing of requests and close downs on other connections.
You should avoid grabbing the X server as much as possible.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Killing_Clients"></a>Killing Clients</h2></div></div></div><p>

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
<a class="xref" href="#XKillClient"><code class="function">XKillClient</code></a>.
</p><a id="idp45736260" class="indexterm"></a><div class="funcsynopsis"><a id="XKillClient"></a><p><code class="funcdef"><strong class="fsfunc">XKillClient</strong>(</code>Display<var class="pdparam"> *display</var>, XID<var class="pdparam"> resource</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>resource</em></span>
    </span></p></td><td><p>
Specifies any resource associated with the client that you want to destroy or
<span class="symbol">AllTemporary</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XKillClient"><code class="function">XKillClient</code></a>
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 
<span class="symbol">RetainPermanent</span>
or 
<span class="symbol">RetainTemporary</span>
mode, all of the client's
resources are destroyed.
If 
<span class="symbol">AllTemporary</span>
is specified, the resources of all clients that have terminated in
<span class="symbol">RetainTemporary</span>
are destroyed (see <a class="link" href="#Closing_the_Display" title="Closing the Display">section 2.5</a>).
This permits implementation of window manager facilities that aid debugging.
A client can set its close-down mode to
<span class="symbol">RetainTemporary</span>.
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.
</p><p>

<a class="xref" href="#XKillClient"><code class="function">XKillClient</code></a>
can generate a
<span class="errorname">BadValue</span>
error.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Controlling_the_Screen_Saver"></a>Controlling the Screen Saver</h2></div></div></div><p>

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.
</p><p>


To set the screen saver mode, use
<a class="xref" href="#XSetScreenSaver"><code class="function">XSetScreenSaver</code></a>.
</p><a id="idp45511884" class="indexterm"></a><div class="funcsynopsis"><a id="XSetScreenSaver"></a><p><code class="funcdef"><strong class="fsfunc">XSetScreenSaver</strong>(</code>Display<var class="pdparam"> *display</var>, inttimeout,<var class="pdparam"> interval</var>, int<var class="pdparam"> prefer_blanking</var>, int<var class="pdparam"> allow_exposures</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>timeout</em></span>
    </span></p></td><td><p>
Specifies the timeout, in seconds, until the screen saver turns on.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>interval</em></span>
    </span></p></td><td><p>
Specifies the interval, in seconds, between screen saver alterations.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>prefer_blanking</em></span>
    </span></p></td><td><p>
Specifies how to enable screen blanking.
You can pass
<span class="symbol">DontPreferBlanking</span>,
<span class="symbol">PreferBlanking</span>,
or
<span class="symbol">DefaultBlanking</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>allow_exposures</em></span>
    </span></p></td><td><p>
Specifies the screen save control values.
You can pass
<span class="symbol">DontAllowExposures</span>,
<span class="symbol">AllowExposures</span>,
or
<span class="symbol">DefaultExposures</span>.
    </p></td></tr></tbody></table></div><p>


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
<span class="errorname">BadValue</span>
error.
If the timeout value is nonzero, 
<a class="xref" href="#XSetScreenSaver"><code class="function">XSetScreenSaver</code></a>
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.
</p><p>

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 
<span class="symbol">Expose</span>
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
<a class="xref" href="#XForceScreenSaver"><code class="function">XForceScreenSaver</code></a>
with mode
<span class="symbol">ScreenSaverReset</span>.
</p><p>

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.
</p><p>

<a class="xref" href="#XSetScreenSaver"><code class="function">XSetScreenSaver</code></a>
can generate a
<span class="errorname">BadValue</span>
error.
</p><p>


To force the screen saver on or off, use
<a class="xref" href="#XForceScreenSaver"><code class="function">XForceScreenSaver</code></a>.
</p><a id="idp45530276" class="indexterm"></a><div class="funcsynopsis"><a id="XForceScreenSaver"></a><p><code class="funcdef"><strong class="fsfunc">XForceScreenSaver</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> mode</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>mode</em></span>
    </span></p></td><td><p>
Specifies the mode that is to be applied.
You can pass
<span class="symbol">ScreenSaverActive</span>
or
<span class="symbol">ScreenSaverReset</span>.
    </p></td></tr></tbody></table></div><p>


If the specified mode is 
<span class="symbol">ScreenSaverActive</span>
and the screen saver currently is deactivated,
<a class="xref" href="#XForceScreenSaver"><code class="function">XForceScreenSaver</code></a>
activates the screen saver even if the screen saver had been disabled
with a timeout of zero.
If the specified mode is 
<span class="symbol">ScreenSaverReset</span>
and the screen saver currently is enabled,
<a class="xref" href="#XForceScreenSaver"><code class="function">XForceScreenSaver</code></a>
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).
</p><p>

<a class="xref" href="#XForceScreenSaver"><code class="function">XForceScreenSaver</code></a>
can generate a
<span class="errorname">BadValue</span>
error.
</p><p>


To activate the screen saver, use
<a class="xref" href="#XActivateScreenSaver"><code class="function">XActivateScreenSaver</code></a>.
</p><a id="idp45779492" class="indexterm"></a><div class="funcsynopsis"><a id="XActivateScreenSaver"></a><p><code class="funcdef"><strong class="fsfunc">XActivateScreenSaver</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>



To reset the screen saver, use
<a class="xref" href="#XResetScreenSaver"><code class="function">XResetScreenSaver</code></a>.
</p><a id="idp45784340" class="indexterm"></a><div class="funcsynopsis"><a id="XResetScreenSaver"></a><p><code class="funcdef"><strong class="fsfunc">XResetScreenSaver</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>



To get the current screen saver values, use
<a class="xref" href="#XGetScreenSaver"><code class="function">XGetScreenSaver</code></a>.
</p><a id="idp45789340" class="indexterm"></a><div class="funcsynopsis"><a id="XGetScreenSaver"></a><p><code class="funcdef"><strong class="fsfunc">XGetScreenSaver</strong>(</code>Display<var class="pdparam"> *display</var>, int*timeout_return,<var class="pdparam"> *interval_return</var>, int<var class="pdparam"> *prefer_blanking_return</var>, int<var class="pdparam"> *allow_exposures_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>timeout_return</em></span>
    </span></p></td><td><p>
Returns the timeout, in seconds, until the screen saver turns on.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>interval_return</em></span>
    </span></p></td><td><p>
Returns the interval between screen saver invocations.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>prefer_blanking_return</em></span>
    </span></p></td><td><p>
Returns the current screen blanking preference
(<span class="symbol">DontPreferBlanking</span>,
<span class="symbol">PreferBlanking</span>,
or
<span class="symbol">DefaultBlanking</span>).
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>allow_exposures_return</em></span>
    </span></p></td><td><p>
Returns the current screen save control value
(<span class="symbol">DontAllowExposures</span>,
<span class="symbol">AllowExposures</span>,
or
<span class="symbol">DefaultExposures</span>).
    </p></td></tr></tbody></table></div><p>


</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Controlling_Host_Access"></a>Controlling Host Access</h2></div></div></div><p>

This section discusses how to:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Add, get, or remove hosts from the access control list
    </p></li><li class="listitem"><p>
Change, enable, or disable access
    </p></li></ul></div><p>

<a id="idp45682524" class="indexterm"></a>
<a id="idp45682956" class="indexterm"></a>
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.
</p><p>

<a id="idp45684292" class="indexterm"></a>
The initial set of hosts allowed to open connections typically consists of:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The host the window system is running on.
    </p></li><li class="listitem"><p>
On <acronym class="acronym">POSIX</acronym>-conformant systems, each host listed in the
<code class="filename">/etc/X<em class="replaceable"><code>?</code></em>.hosts</code>
file.
The ? indicates the number of the
display.
<a id="idp45686684" class="indexterm"></a>
This file should consist of host names separated by newlines.
DECnet nodes must terminate in :: to distinguish them from Internet hosts.
    </p></li></ul></div><p>

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.
</p><p>

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 <span class="olink"><em class="citetitle">X Window System Protocol</em></span>.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Adding_Getting_or_Removing_Hosts"></a>Adding, Getting, or Removing Hosts</h3></div></div></div><p>

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 
<span class="structname">XHostAddress</span>
structure, which contains:
</p><p>

<a id="idp45691924" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int family;        /* for example FamilyInternet */
     int length;        /* length of address, in bytes */
     char *address;     /* pointer to where to find the address */
} XHostAddress;
</pre><p>
</p><p>


The family member specifies which protocol address family to use 
(for example, <acronym class="acronym">TCP</acronym>/<acronym class="acronym">IP</acronym> or DECnet) and can be
<span class="symbol">FamilyInternet</span>,
<span class="symbol">FamilyInternet6</span>,
<span class="symbol">FamilyServerInterpreted</span>,
<span class="symbol">FamilyDECnet</span>,
or
<span class="symbol">FamilyChaos</span>.
The length member specifies the length of the address in bytes.
The address member specifies a pointer to the address.
</p><p>

For <acronym class="acronym">TCP</acronym>/<acronym class="acronym">IP</acronym>, the address should be in network byte order.
For <acronym class="acronym">IP</acronym> version 4 addresses, the family should be FamilyInternet
and the length should be 4 bytes.  For <acronym class="acronym">IP</acronym> version 6 addresses, the
family should be FamilyInternet6 and the length should be 16 bytes.
</p><p>

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.
</p><p>

For the ServerInterpreted family, the length is ignored and the address 
member is a pointer to a 
<span class="structname">XServerInterpretedAddress</span>
structure, which contains:
</p><p>

<a id="idp45699148" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int typelength;     /* length of type string, in bytes */
     int valuelength;    /* length of value string, in bytes */
     char *type;         /* pointer to where to find the type string */
     char *value;        /* pointer to where to find the address */
} XServerInterpretedAddress;
</pre><p>
</p><p>


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.
</p><p>


To add a single host, use
<a class="xref" href="#XAddHost"><code class="function">XAddHost</code></a>.
</p><a id="idp45702724" class="indexterm"></a><div class="funcsynopsis"><a id="XAddHost"></a><p><code class="funcdef"><strong class="fsfunc">XAddHost</strong>(</code>Display<var class="pdparam"> *display</var>, XHostAddress<var class="pdparam"> *host</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>host</em></span>
    </span></p></td><td><p>
Specifies the host that is to be added.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XAddHost"><code class="function">XAddHost</code></a>
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
<span class="errorname">BadAccess</span>
error results.
</p><p>

<a class="xref" href="#XAddHost"><code class="function">XAddHost</code></a>
can generate
<span class="errorname">BadAccess</span>
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To add multiple hosts at one time, use
<a class="xref" href="#XAddHosts"><code class="function">XAddHosts</code></a>.
</p><a id="idp45711932" class="indexterm"></a><div class="funcsynopsis"><a id="XAddHosts"></a><p><code class="funcdef"><strong class="fsfunc">XAddHosts</strong>(</code>Display<var class="pdparam"> *display</var>, XHostAddress<var class="pdparam"> *hosts</var>, int<var class="pdparam"> num_hosts</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hosts</em></span>
    </span></p></td><td><p>
Specifies each host that is to be added.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>num_hosts</em></span>
    </span></p></td><td><p>
Specifies the number of hosts.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XAddHosts"><code class="function">XAddHosts</code></a>
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
<span class="errorname">BadAccess</span>
error results.
</p><p>

<a class="xref" href="#XAddHosts"><code class="function">XAddHosts</code></a>
can generate
<span class="errorname">BadAccess</span>
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To obtain a host list, use
<a class="xref" href="#XListHosts"><code class="function">XListHosts</code></a>.
</p><a id="idp45644380" class="indexterm"></a><div class="funcsynopsis"><a id="XListHosts"></a><p><code class="funcdef">XHostAddress *<strong class="fsfunc">XListHosts</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> *nhosts_return</var>, Bool<var class="pdparam"> *state_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nhosts_return</em></span>
    </span></p></td><td><p>
Returns the number of hosts currently in the access control list.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>state_return</em></span>
    </span></p></td><td><p>
Returns the state of the access control.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XListHosts"><code class="function">XListHosts</code></a>
function returns the current access control list as well as whether the use 
of the list at connection setup was enabled or disabled.
<a class="xref" href="#XListHosts"><code class="function">XListHosts</code></a>
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
<a class="xref" href="#XFree"></a>.
</p><p>


To remove a single host, use
<a class="xref" href="#XRemoveHost"><code class="function">XRemoveHost</code></a>.
</p><a id="idp45655028" class="indexterm"></a><div class="funcsynopsis"><a id="XRemoveHost"></a><p><code class="funcdef"><strong class="fsfunc">XRemoveHost</strong>(</code>Display<var class="pdparam"> *display</var>, XHostAddress<var class="pdparam"> *host</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>host</em></span>
    </span></p></td><td><p>
Specifies the host that is to be removed.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XRemoveHost"><code class="function">XRemoveHost</code></a>
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
<span class="errorname">BadAccess</span>
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.
</p><p>

<a class="xref" href="#XRemoveHost"><code class="function">XRemoveHost</code></a>
can generate
<span class="errorname">BadAccess</span>
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To remove multiple hosts at one time, use
<a class="xref" href="#XRemoveHosts"><code class="function">XRemoveHosts</code></a>.
</p><a id="idp45664404" class="indexterm"></a><div class="funcsynopsis"><a id="XRemoveHosts"></a><p><code class="funcdef"><strong class="fsfunc">XRemoveHosts</strong>(</code>Display<var class="pdparam"> *display</var>, XHostAddress<var class="pdparam"> *hosts</var>, int<var class="pdparam"> num_hosts</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hosts</em></span>
    </span></p></td><td><p>
Specifies each host that is to be removed.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>num_hosts</em></span>
    </span></p></td><td><p>
Specifies the number of hosts.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XRemoveHosts"><code class="function">XRemoveHosts</code></a>
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
<span class="errorname">BadAccess</span>
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.
</p><p>

<a class="xref" href="#XRemoveHosts"><code class="function">XRemoveHosts</code></a>
can generate
<span class="errorname">BadAccess</span>
and
<span class="errorname">BadValue</span>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Changing_Enabling_or_Disabling_Access_Control"></a>Changing, Enabling, or Disabling Access Control</h3></div></div></div><p>

Xlib provides functions that you can use to enable, disable, 
or change access control.
</p><p>

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.
</p><p>


To change access control, use
<a class="xref" href="#XSetAccessControl"><code class="function">XSetAccessControl</code></a>.
</p><a id="idp45586108" class="indexterm"></a><div class="funcsynopsis"><a id="XSetAccessControl"></a><p><code class="funcdef"><strong class="fsfunc">XSetAccessControl</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> mode</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>mode</em></span>
    </span></p></td><td><p>
Specifies the mode.
You can pass
<span class="symbol">EnableAccess</span>
or
<span class="symbol">DisableAccess</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetAccessControl"><code class="function">XSetAccessControl</code></a>
function either enables or disables the use of the access control list 
at each connection setup.
</p><p>

<a class="xref" href="#XSetAccessControl"><code class="function">XSetAccessControl</code></a>
can generate
<span class="errorname">BadAccess</span>
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To enable access control, use
<a class="xref" href="#XEnableAccessControl"><code class="function">XEnableAccessControl</code></a>.
</p><a id="idp45595356" class="indexterm"></a><div class="funcsynopsis"><a id="XEnableAccessControl"></a><p><code class="funcdef"><strong class="fsfunc">XEnableAccessControl</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XEnableAccessControl"><code class="function">XEnableAccessControl</code></a>
function enables the use of the access control list at each connection setup.
</p><p>

<a class="xref" href="#XEnableAccessControl"><code class="function">XEnableAccessControl</code></a>
can generate a
<span class="errorname">BadAccess</span>
error.
</p><p>


To disable access control, use
<a class="xref" href="#XDisableAccessControl"><code class="function">XDisableAccessControl</code></a>.
</p><a id="idp45602068" class="indexterm"></a><div class="funcsynopsis"><a id="XDisableAccessControl"></a><p><code class="funcdef"><strong class="fsfunc">XDisableAccessControl</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDisableAccessControl"><code class="function">XDisableAccessControl</code></a>
function disables the use of the access control list at each connection setup.
</p><p>

<a class="xref" href="#XDisableAccessControl"><code class="function">XDisableAccessControl</code></a>
can generate a
<span class="errorname">BadAccess</span>
error.


</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Events"></a>Chapter 10. Events</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Event_Types">Event Types</a></span></dt><dt><span class="sect1"><a href="#Event_Structures">Event Structures</a></span></dt><dt><span class="sect1"><a href="#Event_Masks">Event Masks</a></span></dt><dt><span class="sect1"><a href="#Event_Processing_Overview">Event Processing Overview</a></span></dt><dt><span class="sect1"><a href="#Keyboard_and_Pointer_Events">Keyboard and Pointer Events</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Pointer_Button_Events">Pointer Button Events</a></span></dt><dt><span class="sect2"><a href="#Keyboard_and_Pointer_Events_b">Keyboard and Pointer Events</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Window_EntryExit_Events">Window Entry/Exit Events</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Normal_EntryExit_Events">Normal Entry/Exit Events</a></span></dt><dt><span class="sect2"><a href="#Grab_and_Ungrab_EntryExit_Events">Grab and Ungrab Entry/Exit Events</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Input_Focus_Events">Input Focus Events</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Normal_Focus_Events_and_Focus_Events_While_Grabbed">Normal Focus Events and Focus Events While Grabbed</a></span></dt><dt><span class="sect2"><a href="#Focus_Events_Generated_by_Grabs">Focus Events Generated by Grabs</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Key_Map_State_Notification_Events">Key Map State Notification Events</a></span></dt><dt><span class="sect1"><a href="#Exposure_Events">Exposure Events</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Expose_Events">Expose Events</a></span></dt><dt><span class="sect2"><a href="#GraphicsExpose_and_NoExpose_Events">GraphicsExpose and NoExpose Events</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Window_State_Change_Events">Window State Change Events</a></span></dt><dd><dl><dt><span class="sect2"><a href="#CirculateNotify_Events">CirculateNotify Events</a></span></dt><dt><span class="sect2"><a href="#ConfigureNotify_Events">ConfigureNotify Events</a></span></dt><dt><span class="sect2"><a href="#CreateNotify_Events">CreateNotify Events</a></span></dt><dt><span class="sect2"><a href="#DestroyNotify_Events">DestroyNotify Events</a></span></dt><dt><span class="sect2"><a href="#GravityNotify_Events">GravityNotify Events</a></span></dt><dt><span class="sect2"><a href="#MapNotify_Events">MapNotify Events</a></span></dt><dt><span class="sect2"><a href="#MappingNotify_Events">MappingNotify Events</a></span></dt><dt><span class="sect2"><a href="#ReparentNotify_Events">ReparentNotify Events</a></span></dt><dt><span class="sect2"><a href="#UnmapNotify_Events">UnmapNotify Events</a></span></dt><dt><span class="sect2"><a href="#VisibilityNotify_Events">VisibilityNotify Events</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Structure_Control_Events">Structure Control Events</a></span></dt><dd><dl><dt><span class="sect2"><a href="#CirculateRequest_Events">CirculateRequest Events</a></span></dt><dt><span class="sect2"><a href="#ConfigureRequest_Events">ConfigureRequest Events</a></span></dt><dt><span class="sect2"><a href="#MapRequest_Events">MapRequest Events</a></span></dt><dt><span class="sect2"><a href="#ResizeRequest_Events">ResizeRequest Events</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Colormap_State_Change_Events">Colormap State Change Events</a></span></dt><dt><span class="sect1"><a href="#Client_Communication_Events">Client Communication Events</a></span></dt><dd><dl><dt><span class="sect2"><a href="#ClientMessage_Events">ClientMessage Events</a></span></dt><dt><span class="sect2"><a href="#PropertyNotify_Events">PropertyNotify Events</a></span></dt><dt><span class="sect2"><a href="#SelectionClear_Events">SelectionClear Events</a></span></dt><dt><span class="sect2"><a href="#SelectionRequest_Events">SelectionRequest Events</a></span></dt><dt><span class="sect2"><a href="#SelectionNotify_Events">SelectionNotify Events</a></span></dt></dl></dd></dl></div><p>
A client application communicates with the X server through the connection you establish with
the XOpenDisplay 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.
</p><p>
This chapter discusses the following topics associated with events:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Event types</p></li><li class="listitem"><p>Event structures</p></li><li class="listitem"><p>Event masks</p></li><li class="listitem"><p>Event processing</p></li></ul></div><p>
Functions for handling events are dealt with in
<a class="link" href="#Event_Handling_Functions" title="Chapter 11. Event Handling Functions">the next chapter</a>.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Event_Types"></a>Event Types</h2></div></div></div><p>

<a id="idp44383964" class="indexterm"></a>
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.
<a id="idp44384676" class="indexterm"></a>
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,
<span class="symbol">MappingNotify</span>
events are always sent to all clients.
<a id="idp43051284" class="indexterm"></a>
<a id="idp41292388" class="indexterm"></a>
</p><p>

An event type describes a specific event generated by the X server.
For each event type, 
a corresponding constant name is defined in
<code class="filename">&lt;X11/X.h&gt;</code>,
<a id="idp40394044" class="indexterm"></a>
<a id="idp41428348" class="indexterm"></a>
<a id="idp41279884" class="indexterm"></a>
which is used when referring to an event type.
<a id="idp40881636" class="indexterm"></a>
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.
</p><p>



</p><p>

</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Event Category</th><th align="left">Event Type</th></tr></thead><tbody><tr><td align="left">Keyboard events</td><td align="left"><span class="symbol">KeyPress</span>,
      <span class="symbol">KeyRelease</span></td></tr><tr><td align="left">Pointer events</td><td align="left"><span class="symbol">ButtonPress</span>,
      <span class="symbol">ButtonRelease</span>,
      <span class="symbol">MotionNotify</span></td></tr><tr><td align="left">Window crossing events</td><td align="left"><span class="symbol">EnterNotify</span>,
      <span class="symbol">LeaveNotify</span></td></tr><tr><td align="left">Input focus events</td><td align="left"><span class="symbol">FocusIn</span>,
      <span class="symbol">FocusOut</span></td></tr><tr><td align="left">Keymap state notification event</td><td align="left"><span class="symbol">KeymapNotify</span></td></tr><tr><td align="left">Exposure events</td><td align="left"><span class="symbol">Expose</span>,
      <span class="symbol">GraphicsExpose</span>,
      <span class="symbol">NoExpose</span></td></tr><tr><td align="left">Structure control events</td><td align="left"><span class="symbol">CirculateRequest</span>,
      <span class="symbol">ConfigureRequest</span>,
      <span class="symbol">MapRequest</span>,
      <span class="symbol">ResizeRequest</span></td></tr><tr><td align="left">Window state notification events</td><td align="left">
      <span class="symbol">CirculateNotify</span>,
      <span class="symbol">ConfigureNotify</span>,
      <span class="symbol">CreateNotify</span>,
      <span class="symbol">DestroyNotify</span>,
      <span class="symbol">GravityNotify</span>,
      <span class="symbol">MapNotify</span>,
      <span class="symbol">MappingNotify</span>,
      <span class="symbol">ReparentNotify</span>,
      <span class="symbol">UnmapNotify</span>,
      <span class="symbol">VisibilityNotify</span></td></tr><tr><td align="left">Colormap state notification event</td><td align="left"><span class="symbol">ColormapNotify</span></td></tr><tr><td align="left">Client communication events</td><td align="left"><span class="symbol">ClientMessage</span>,
      <span class="symbol">PropertyNotify</span>,
      <span class="symbol">SelectionClear</span>,
      <span class="symbol">SelectionNotify</span>,
      <span class="symbol">SelectionRequest</span></td></tr></tbody></table></div><p>










</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Event_Structures"></a>Event Structures</h2></div></div></div><p>

For each event type,
a corresponding structure is declared in
<code class="filename">&lt;X11/Xlib.h&gt;</code>.
<a id="idp45416356" class="indexterm"></a>
<a id="idp45417252" class="indexterm"></a>
<a id="idp45418164" class="indexterm"></a>
All the event structures have the following common members:
</p><p>

<a id="idp45419516" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;
     unsigned long serial;     /* # of last request processed by server */
     Bool          send_event; /* true if this came from a SendEvent request */
     Display       *display;   /* Display the event was read from */
     Window        window;
} XAnyEvent;
</pre><p>
</p><p>


The type member is set to the event type constant name that uniquely identifies
it.
For example, when the X server reports a
<span class="symbol">GraphicsExpose</span>
event to a client application, it sends an
<span class="structname">XGraphicsExposeEvent</span>
structure with the type member set to
<span class="symbol">GraphicsExpose</span>.
The display member is set to a pointer to the display the event was read on.
The send_event member is set to
<span class="symbol">True</span>
if the event came from a
<code class="systemitem">SendEvent</code>
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.
</p><p>

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 <a class="link" href="#Event_Queue_Management" title="Event Queue Management">section 11.3</a>).
</p><p>

In addition to the individual structures declared for each event type, the
<span class="structname">XEvent</span>
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 
<span class="structname">XEvent</span>
union.
</p><p>

<a id="idp45609652" class="indexterm"></a>

</p><pre class="literallayout">


typedef union _XEvent {
     int                            type;          /* must not be changed */
     XAnyEvent                      xany;
     XKeyEvent                      xkey;
     XButtonEvent                   xbutton;
     XMotionEvent                   xmotion;
     XCrossingEvent                 xcrossing;
     XFocusChangeEvent              xfocus;
     XExposeEvent                   xexpose;
     XGraphicsExposeEvent           xgraphicsexpose;
     XNoExposeEvent                 xnoexpose;
     XVisibilityEvent               xvisibility;
     XCreateWindowEvent             xcreatewindow;
     XDestroyWindowEvent            xdestroywindow;
     XUnmapEvent                    xunmap;
     XMapEvent                      xmap;
     XMapRequestEvent               xmaprequest;
     XReparentEvent                 xreparent;
     XConfigureEvent                xconfigure;
     XGravityEvent                  xgravity;
     XResizeRequestEvent            xresizerequest;
     XConfigureRequestEvent         xconfigurerequest;
     XCirculateEvent                xcirculate;
     XCirculateRequestEvent         xcirculaterequest;
     XPropertyEvent                 xproperty;
     XSelectionClearEvent           xselectionclear;
     XSelectionRequestEvent         xselectionrequest;
     XSelectionEvent                xselection;
     XColormapEvent                 xcolormap;
     XClientMessageEvent            xclient;
     XMappingEvent                  xmapping;
     XErrorEvent                    xerror;
     XKeymapEvent                   xkeymap;
     long                           pad[24];
} XEvent;
</pre><p>


An
<span class="structname">XEvent</span>
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
<span class="type">Bool</span>
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.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Event_Masks"></a>Event Masks</h2></div></div></div><p>

<a id="idp45615940" class="indexterm"></a>
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
<code class="filename">&lt;X11/X.h&gt;</code>.
<a id="idp45617068" class="indexterm"></a>
<a id="idp45617964" class="indexterm"></a>
<a id="idp45618868" class="indexterm"></a>
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.
</p><p>

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
<span class="symbol">False</span>,
<span class="symbol">GraphicsExpose</span>
and 
<span class="symbol">NoExpose</span>
are reported by default as a result of
<a class="xref" href="#XCopyPlane"><code class="function">XCopyPlane</code></a>
and
<a class="xref" href="#XCopyArea"><code class="function">XCopyArea</code></a>.
<span class="symbol">SelectionClear</span>,
<span class="symbol">SelectionRequest</span>,
<span class="symbol">SelectionNotify</span>,
or
<span class="symbol">ClientMessage</span>
cannot be masked.
Selection-related events are only sent to clients cooperating
with selections
(see <a class="link" href="#Obtaining_and_Changing_Window_Properties" title="Obtaining and Changing Window Properties">section 4.5</a>).
When the keyboard or pointer mapping is changed,
<span class="symbol">MappingNotify</span>
is always sent to clients.
</p><p>


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:
</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Event Mask</th><th align="left">Circumstances</th></tr></thead><tbody><tr><td align="left"><span class="symbol">NoEventMask</span></td><td align="left">No events wanted</td></tr><tr><td align="left"><span class="symbol">KeyPressMask</span></td><td align="left">Keyboard down events wanted</td></tr><tr><td align="left"><span class="symbol">KeyReleaseMask</span></td><td align="left">Keyboard up events wanted</td></tr><tr><td align="left"><span class="symbol">ButtonPressMask</span></td><td align="left">Pointer button down events wanted</td></tr><tr><td align="left"><span class="symbol">ButtonReleaseMask</span></td><td align="left">Pointer button up events wanted</td></tr><tr><td align="left"><span class="symbol">EnterWindowMask</span></td><td align="left">Pointer window entry events wanted</td></tr><tr><td align="left"><span class="symbol">LeaveWindowMask</span></td><td align="left">Pointer window leave events wanted</td></tr><tr><td align="left"><span class="symbol">PointerMotionMask</span></td><td align="left">Pointer motion events wanted</td></tr><tr><td align="left"><span class="symbol">PointerMotionHintMask</span></td><td align="left">Pointer motion hints wanted</td></tr><tr><td align="left"><span class="symbol">Button1MotionMask</span></td><td align="left">Pointer motion while button 1 down</td></tr><tr><td align="left"><span class="symbol">Button2MotionMask</span></td><td align="left">Pointer motion while button 2 down</td></tr><tr><td align="left"><span class="symbol">Button3MotionMask</span></td><td align="left">Pointer motion while button 3 down</td></tr><tr><td align="left"><span class="symbol">Button4MotionMask</span></td><td align="left">Pointer motion while button 4 down</td></tr><tr><td align="left"><span class="symbol">Button5MotionMask</span></td><td align="left">Pointer motion while button 5 down</td></tr><tr><td align="left"><span class="symbol">ButtonMotionMask</span></td><td align="left">Pointer motion while any button down</td></tr><tr><td align="left"><span class="symbol">KeymapStateMask</span></td><td align="left">Keyboard state wanted at window entry and focus in</td></tr><tr><td align="left"><span class="symbol">ExposureMask</span></td><td align="left">Any exposure wanted</td></tr><tr><td align="left"><span class="symbol">VisibilityChangeMask</span></td><td align="left">Any change in visibility wanted</td></tr><tr><td align="left"><span class="symbol">StructureNotifyMask</span></td><td align="left">Any change in window structure wanted</td></tr><tr><td align="left"><span class="symbol">ResizeRedirectMask</span></td><td align="left">Redirect resize of this window</td></tr><tr><td align="left"><span class="symbol">SubstructureNotifyMask</span></td><td align="left">Substructure notification wanted</td></tr><tr><td align="left"><span class="symbol">SubstructureRedirectMask</span></td><td align="left">Redirect structure requests on children</td></tr><tr><td align="left"><span class="symbol">FocusChangeMask</span></td><td align="left">Any change in input focus wanted</td></tr><tr><td align="left"><span class="symbol">PropertyChangeMask</span></td><td align="left">Any change in property wanted</td></tr><tr><td align="left"><span class="symbol">ColormapChangeMask</span></td><td align="left">Any change in colormap wanted</td></tr><tr><td align="left"><span class="symbol">OwnerGrabButtonMask</span></td><td align="left">Automatic grabs should activate with owner_events set to True</td></tr></tbody></table></div><p>

</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Event_Processing_Overview"></a>Event Processing Overview</h2></div></div></div><p>

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
<span class="symbol">ButtonPressMask</span>,
the X server sends back only
<span class="symbol">ButtonPress</span>
events.
<a id="idp47704476" class="indexterm"></a>
Most events contain a time member,
which is the time at which an event occurred.
</p><p>

In other cases, one event mask constant can map to several event type constants.
For example, if you pass the event mask
<span class="symbol">SubstructureNotifyMask</span>,
the X server can send back
<span class="symbol">CirculateNotify</span>,
<span class="symbol">ConfigureNotify</span>,
<span class="symbol">CreateNotify</span>,
<span class="symbol">DestroyNotify</span>,
<span class="symbol">GravityNotify</span>,
<span class="symbol">MapNotify</span>,
<span class="symbol">ReparentNotify</span>,
or
<span class="symbol">UnmapNotify</span>
events.
</p><p>

In another case, 
two event masks can map to one event type.
For example, 
if you pass either
<span class="symbol">PointerMotionMask</span>
or
<span class="symbol">ButtonMotionMask</span>,
the X server sends back
a
<span class="symbol">MotionNotify</span>
event.
</p><p>

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.
</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">Event Mask</th><th align="left">Event Type</th><th align="left">Structure</th><th align="left">Generic Structure</th></tr></thead><tbody><tr><td align="left">
      <p>ButtonMotionMask</p>
      <p>Button1MotionMask</p>
      <p>Button2MotionMask</p>
      <p>Button3MotionMask</p>
      <p>Button4MotionMask</p>
      <p>Button5MotionMask</p>
      </td><td align="left">MotionNotify</td><td align="left">XPointerMovedEvent</td><td align="left">XMotionEvent</td></tr><tr><td align="left">ButtonPressMask</td><td align="left">ButtonPress</td><td align="left">XButtonPressedEvent</td><td align="left">XButtonEvent</td></tr><tr><td align="left">ButtonReleaseMask</td><td align="left">ButtonRelease</td><td align="left">XButtonReleasedEvent</td><td align="left">XButtonEvent</td></tr><tr><td align="left">ColormapChangeMask</td><td align="left">ColormapNotify</td><td align="left">XColormapEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">EnterWindowMask</td><td align="left">EnterNotify</td><td align="left">XEnterWindowEvent</td><td align="left">XCrossingEvent</td></tr><tr><td align="left">LeaveWindowMask</td><td align="left">LeaveNotify</td><td align="left">XLeaveWindowEvent</td><td align="left">XCrossingEvent</td></tr><tr><td align="left">ExposureMask</td><td align="left">Expose</td><td align="left">XExposeEvent </td><td class="auto-generated"> </td></tr><tr><td rowspan="2" align="left">GCGraphicsExposures in GC</td><td align="left">GraphicsExpose</td><td align="left">XGraphicsExposeEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">NoExpose</td><td align="left">XNoExposeEvent</td><td class="auto-generated"> </td></tr><tr><td rowspan="2" align="left">FocusChangeMask</td><td align="left">FocusIn</td><td align="left">XFocusInEvent</td><td align="left">XFocusChangeEvent</td></tr><tr><td align="left">FocusOut</td><td align="left">XFocusOutEvent</td><td align="left">XFocusChangeEvent</td></tr><tr><td align="left">KeymapStateMask</td><td align="left">KeymapNotify</td><td align="left">XKeymapEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">KeyPressMask</td><td align="left">KeyPress</td><td align="left">XKeyPressedEvent</td><td align="left">XKeyEvent</td></tr><tr><td align="left">KeyReleaseMask</td><td align="left">KeyRelease</td><td align="left">XKeyReleasedEvent</td><td align="left">XKeyEvent</td></tr><tr><td align="left">OwnerGrabButtonMask</td><td align="left">N.A.</td><td align="left">N.A.</td><td class="auto-generated"> </td></tr><tr><td align="left">PointerMotionMask</td><td align="left">MotionNotify</td><td align="left">XPointerMovedEvent</td><td align="left">XMotionEvent</td></tr><tr><td align="left">PointerMotionHintMask</td><td align="left">N.A.</td><td align="left">N.A.</td><td class="auto-generated"> </td></tr><tr><td align="left">PropertyChangeMask</td><td align="left">PropertyNotify</td><td align="left">XPropertyEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">ResizeRedirectMask</td><td align="left">ResizeRequest</td><td align="left">XResizeRequestEvent</td><td class="auto-generated"> </td></tr><tr><td rowspan="7" align="left">StructureNotifyMask</td><td align="left">CirculateNotify</td><td align="left">XCirculateEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">ConfigureNotify</td><td align="left">XConfigureEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">DestroyNotify</td><td align="left">XDestroyWindowEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">GravityNotify</td><td align="left">XGravityEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">MapNotify</td><td align="left">XMapEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">ReparentNotify</td><td align="left">XReparentEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">UnmapNotify</td><td align="left">XUnmapEvent</td><td class="auto-generated"> </td></tr><tr><td rowspan="8" align="left">SubstructureNotifyMask</td><td align="left">CirculateNotify</td><td align="left">XCirculateEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">ConfigureNotify</td><td align="left">XConfigureEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">CreateNotify</td><td align="left">XCreateWindowEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">DestroyNotify</td><td align="left">XDestroyWindowEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">GravityNotify</td><td align="left">XGravityEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">MapNotify</td><td align="left">XMapEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">ReparentNotify</td><td align="left">XReparentEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">UnmapNotify</td><td align="left">XUnmapEvent</td><td class="auto-generated"> </td></tr><tr><td rowspan="3" align="left">SubstructureRedirectMask</td><td align="left">CirculateRequest</td><td align="left">XCirculateRequestEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">ConfigureRequest</td><td align="left">XConfigureRequestEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">MapRequest</td><td align="left">XMapRequestEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">N.A.</td><td align="left">ClientMessage</td><td align="left">XClientMessageEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">N.A.</td><td align="left">MappingNotify</td><td align="left">XMappingEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">N.A.</td><td align="left">SelectionClear</td><td align="left">XSelectionClearEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">N.A.</td><td align="left">SelectionNotify</td><td align="left">XSelectionEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">N.A.</td><td align="left">SelectionRequest</td><td align="left">XSelectionRequestEvent</td><td class="auto-generated"> </td></tr><tr><td align="left">VisibilityChangeMask</td><td align="left">VisibilityNotify</td><td align="left">XVisibilityEvent</td><td class="auto-generated"> </td></tr></tbody></table></div><p>

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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Keyboard and pointer events
    </p></li><li class="listitem"><p>
Window crossing events
    </p></li><li class="listitem"><p>
Input focus events
    </p></li><li class="listitem"><p>
Keymap state notification events
    </p></li><li class="listitem"><p>
Exposure events
    </p></li><li class="listitem"><p>
Window state notification events
    </p></li><li class="listitem"><p>
Structure control events
    </p></li><li class="listitem"><p>
Colormap state notification events
    </p></li><li class="listitem"><p>
Client communication events
    </p></li></ul></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Keyboard_and_Pointer_Events"></a>Keyboard and Pointer Events</h2></div></div></div><p>

This section discusses:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Pointer button events
    </p></li><li class="listitem"><p>
Keyboard and pointer events
    </p></li></ul></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Pointer_Button_Events"></a>Pointer Button Events</h3></div></div></div><p>

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.
</p><p>

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
<a class="xref" href="#XGrabButton"><code class="function">XGrabButton</code></a>
with these client passed arguments:
</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Argument</th><th align="left">Value</th></tr></thead><tbody><tr><td align="left"><span class="emphasis"><em>w</em></span></td><td align="left">The event window </td></tr><tr><td align="left"><span class="emphasis"><em>event_mask</em></span></td><td align="left">The client's selected pointer events on the event window</td></tr><tr><td align="left"><span class="emphasis"><em>pointer_mode</em></span></td><td align="left"><span class="symbol">GrabModeAsync</span></td></tr><tr><td align="left"><span class="emphasis"><em>keyboard_mode</em></span></td><td align="left"><span class="symbol">GrabModeAsync</span></td></tr><tr><td align="left"><span class="emphasis"><em>owner_events</em></span></td><td align="left"><span class="symbol">True</span>,
      if the client has selected
      <span class="symbol">OwnerGrabButtonMask</span>
      on the event window,
      otherwise
      <span class="symbol">False</span></td></tr><tr><td align="left"><span class="emphasis"><em>confine_to</em></span></td><td align="left"><span class="symbol">None</span></td></tr><tr><td align="left"><span class="emphasis"><em>cursor</em></span></td><td align="left"><span class="symbol">None</span></td></tr></tbody></table></div><p>

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
<a class="xref" href="#XUngrabPointer"><code class="function">XUngrabPointer</code></a>
and
<a class="xref" href="#XChangeActivePointerGrab"><code class="function">XChangeActivePointerGrab</code></a>.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Keyboard_and_Pointer_Events_b"></a>Keyboard and Pointer Events</h3></div></div></div><p>

<a id="idp47328308" class="indexterm"></a>
<a id="idp47328876" class="indexterm"></a>
<a id="idp47329452" class="indexterm"></a>
<a id="idp47330020" class="indexterm"></a>
<a id="idp47330588" class="indexterm"></a>
This section discusses the processing that occurs for the
keyboard events
<span class="symbol">KeyPress</span>
and 
<span class="symbol">KeyRelease</span>
and the pointer events
<span class="symbol">ButtonPress</span>,
<span class="symbol">ButtonRelease</span>,
and
<span class="symbol">MotionNotify</span>.
For information about the keyboard event-handling utilities,
see <a class="link" href="#Event_Handling_Functions" title="Chapter 11. Event Handling Functions">chapter 11</a>.
</p><p>

<a id="idp47333132" class="indexterm"></a>
<a id="idp47333556" class="indexterm"></a>
The X server reports
<span class="symbol">KeyPress</span>
or
<span class="symbol">KeyRelease</span>
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.
<a id="idp47334572" class="indexterm"></a>
<a id="idp47334996" class="indexterm"></a>
The X server reports
<span class="symbol">ButtonPress</span>
or
<span class="symbol">ButtonRelease</span>
events to clients wanting information about buttons that logically change state.
</p><p>

<a id="idp47336324" class="indexterm"></a>
The X server reports
<span class="symbol">MotionNotify</span>
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
<span class="symbol">MotionNotify</span>
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.
</p><p>

The generation of the logical changes lags the physical changes 
if device event processing is frozen.
</p><p>

To receive
<span class="symbol">KeyPress</span>,
<span class="symbol">KeyRelease</span>,
<span class="symbol">ButtonPress</span>,
and
<span class="symbol">ButtonRelease</span>
events, set 
<span class="symbol">KeyPressMask</span>,
<span class="symbol">KeyReleaseMask</span>,
<span class="symbol">ButtonPressMask</span>,
and
<span class="symbol">ButtonReleaseMask</span>
bits in the event-mask attribute of the window.
</p><p>

To receive 
<span class="symbol">MotionNotify</span>
events, set one or more of the following event 
masks bits in the event-mask attribute of the window.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<span class="symbol">Button1MotionMask</span> - <span class="symbol">Button5MotionMask</span>
    </p></li><li class="listitem"><p>
The client application receives
<span class="symbol">MotionNotify</span>
events only when one or more of the specified buttons is pressed.
    </p></li><li class="listitem"><p>
<span class="symbol">ButtonMotionMask</span>
    </p></li><li class="listitem"><p>
The client application receives
<span class="symbol">MotionNotify</span>
events only when at least one button is pressed.
    </p></li><li class="listitem"><p>
<span class="symbol">PointerMotionMask</span>
    </p></li><li class="listitem"><p>
The client application receives 
<span class="symbol">MotionNotify</span>
events independent of the state of
the pointer buttons.
    </p></li><li class="listitem"><p>
<span class="symbol">PointerMotionHintMask</span>
    </p></li><li class="listitem"><p>
If
<span class="symbol">PointerMotionHintMask</span>
is selected in combination with one or more of the above masks, 
the X server is free to send only one
<span class="symbol">MotionNotify</span>
event (with the is_hint member  of the
<span class="type">XPointerMovedEvent</span>
structure set to
<span class="symbol">NotifyHint</span>)
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
<a class="xref" href="#XQueryPointer"><code class="function">XQueryPointer</code></a>
or
<a class="xref" href="#XGetMotionEvents"></a>.
The server still may send
<span class="symbol">MotionNotify</span>
events without is_hint set to
<span class="symbol">NotifyHint</span>.
    </p></li></ul></div><p>

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.
</p><p>

The structures for these event types contain:
</p><pre class="literallayout">
typedef struct {
     int            type;            /* ButtonPress or ButtonRelease */
     unsigned long  serial;          /* # of last request processed by server */
     Bool           send_event;      /* true if this came from a SendEvent request */
     Display        *display;        /* Display the event was read from */
     Window         window;          /* ``event'' window it is reported relative to */
     Window         root;            /* root window that the event occurred on */
     Window         subwindow;       /* child window */
     Time           time;            /* milliseconds */
     int            x, y;            /* pointer x, y coordinates in event window */
     int            x_root, y_root;  /* coordinates relative to root */
     unsigned int   state;           /* key or button mask */
     unsigned int   button;          /* detail */
     Bool           same_screen;     /* same screen flag */
} XButtonEvent;
typedef XButtonEvent XButtonPressedEvent;
typedef XButtonEvent XButtonReleasedEvent;
</pre><pre class="literallayout">
typedef struct {
     int            type;            /* KeyPress or KeyRelease */
     unsigned long  serial;          /* # of last request processed by server */
     Bool           send_event;      /* true if this came from a SendEvent request */
     Display        *display;        /* Display the event was read from */
     Window         window;          /* ``event'' window it is reported relative to */
     Window         root;            /* root window that the event occurred on */
     Window         subwindow;       /* child window */
     Time           time;            /* milliseconds */
     int            x, y;            /* pointer x, y coordinates in event window */
     int            x_root, y_root;  /* coordinates relative to root */
     unsigned int   state;           /* key or button mask */
     unsigned int   keycode;         /* detail */
     Bool           same_screen;     /* same screen flag */
} XKeyEvent;
typedef XKeyEvent XKeyPressedEvent;
typedef XKeyEvent XKeyReleasedEvent;
</pre><pre class="literallayout">
typedef struct {
     int            type;              /* MotionNotify */
     unsigned long  serial;            /* # of last request processed by server */
     Bool           send_event;        /* true if this came from a SendEvent request */
     Display        *display;          /* Display the event was read from */
     Window         window;            /* ``event'' window reported relative to */
     Window         root;              /* root window that the event occurred on */
     Window         subwindow;         /* child window */
     Time           time;              /* milliseconds */
     int            x, y;              /* pointer x, y coordinates in event window */
     int            x_root, y_root;    /* coordinates relative to root */
     unsigned int   state;             /* key or button mask */
     char           is_hint;           /* detail */
     Bool           same_screen;       /* same screen flag */
} XMotionEvent;
typedef XMotionEvent XPointerMovedEvent;
</pre><p>
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.
</p><p>

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
<span class="symbol">True</span>
or
<span class="symbol">False</span>.
If
<span class="symbol">True</span>,
the event and root windows are on the same screen.
If
<span class="symbol">False</span>,
the event and root windows are not on the same screen.
</p><p>

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
<span class="symbol">None</span>.
The time member is set to the time when the event was generated 
and is expressed in milliseconds.
</p><p>

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.
</p><p>

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:
<span class="symbol">Button1Mask</span>,
<span class="symbol">Button2Mask</span>,
<span class="symbol">Button3Mask</span>,
<span class="symbol">Button4Mask</span>,
<span class="symbol">Button5Mask</span>,
<span class="symbol">ShiftMask</span>,
<span class="symbol">LockMask</span>,
<span class="symbol">ControlMask</span>,
<span class="symbol">Mod1Mask</span>,
<span class="symbol">Mod2Mask</span>,
<span class="symbol">Mod3Mask</span>,
<span class="symbol">Mod4Mask</span>,
and
<span class="symbol">Mod5Mask</span>.
</p><p>

Each of these structures also has a member that indicates the detail.
For the
<span class="type">XKeyPressedEvent</span>
and
<span class="type">XKeyReleasedEvent</span>
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 <a class="link" href="#Manipulating_the_Keyboard_Encoding" title="Manipulating the Keyboard Encoding">12.7</a>
 and <a class="link" href="#Using_Keyboard_Utility_Functions" title="Using Keyboard Utility Functions">16.1</a>).
</p><p>

For the
<span class="type">XButtonPressedEvent</span>
and
<span class="type">XButtonReleasedEvent</span>
structures, this member is called button.
It represents the pointer button that changed state and can be the
<span class="symbol">Button1</span>,
<span class="symbol">Button2</span>,
<span class="symbol">Button3</span>,
<span class="symbol">Button4</span>,
or
<span class="symbol">Button5</span>
value.
For the
<span class="type">XPointerMovedEvent</span>
structure, this member is called is_hint.
It can be set to 
<span class="symbol">NotifyNormal</span>
or
<span class="symbol">NotifyHint</span>.
</p><p>

Some of the symbols mentioned in this section have fixed values, as
follows:
</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Symbol</th><th align="left">Value</th></tr></thead><tbody><tr><td align="left"><span class="symbol">Button1MotionMask</span></td><td align="left">(1L&lt;&lt;8)</td></tr><tr><td align="left"><span class="symbol">Button2MotionMask</span></td><td align="left">(1L&lt;&lt;9)</td></tr><tr><td align="left"><span class="symbol">Button3MotionMask</span></td><td align="left">(1L&lt;&lt;10)</td></tr><tr><td align="left"><span class="symbol">Button4MotionMask</span></td><td align="left">(1L&lt;&lt;11)</td></tr><tr><td align="left"><span class="symbol">Button5MotionMask</span></td><td align="left">(1L&lt;&lt;12)</td></tr><tr><td align="left"><span class="symbol">Button1Mask</span></td><td align="left">(1&lt;&lt;8)</td></tr><tr><td align="left"><span class="symbol">Button2Mask</span></td><td align="left">(1&lt;&lt;9)</td></tr><tr><td align="left"><span class="symbol">Button3Mask</span></td><td align="left">(1&lt;&lt;10)</td></tr><tr><td align="left"><span class="symbol">Button4Mask</span></td><td align="left">(1&lt;&lt;11)</td></tr><tr><td align="left"><span class="symbol">Button5Mask</span></td><td align="left">(1&lt;&lt;12)</td></tr><tr><td align="left"><span class="symbol">ShiftMask</span></td><td align="left">(1&lt;&lt;0)</td></tr><tr><td align="left"><span class="symbol">LockMask</span></td><td align="left">(1&lt;&lt;1)</td></tr><tr><td align="left"><span class="symbol">ControlMask</span></td><td align="left">(1&lt;&lt;2)</td></tr><tr><td align="left"><span class="symbol">Mod1Mask</span></td><td align="left">(1&lt;&lt;3)</td></tr><tr><td align="left"><span class="symbol">Mod2Mask</span></td><td align="left">(1&lt;&lt;4)</td></tr><tr><td align="left"><span class="symbol">Mod3Mask</span></td><td align="left">(1&lt;&lt;5)</td></tr><tr><td align="left"><span class="symbol">Mod4Mask</span></td><td align="left">(1&lt;&lt;6)</td></tr><tr><td align="left"><span class="symbol">Mod5Mask</span></td><td align="left">(1&lt;&lt;7)</td></tr><tr><td align="left"><span class="symbol">Button1</span></td><td align="left">1</td></tr><tr><td align="left"><span class="symbol">Button2</span></td><td align="left">2</td></tr><tr><td align="left"><span class="symbol">Button3</span></td><td align="left">3</td></tr><tr><td align="left"><span class="symbol">Button4</span></td><td align="left">4</td></tr><tr><td align="left"><span class="symbol">Button5</span></td><td align="left">5</td></tr></tbody></table></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Window_EntryExit_Events"></a>Window Entry/Exit Events</h2></div></div></div><p>

<a id="idp48750892" class="indexterm"></a>
<a id="idp48751396" class="indexterm"></a>
This section describes the processing that 
occurs for the window crossing events
<span class="symbol">EnterNotify</span>
and
<span class="symbol">LeaveNotify</span>.
<a id="idp48752372" class="indexterm"></a>
<a id="idp48752748" class="indexterm"></a>
If a pointer motion or a window hierarchy change causes the
pointer to be in a different window than before, the X server reports
<span class="symbol">EnterNotify</span>
or
<span class="symbol">LeaveNotify</span>
events to clients who have selected for these events.
All 
<span class="symbol">EnterNotify</span>
and 
<span class="symbol">LeaveNotify</span>
events caused by a hierarchy change are
generated after any hierarchy event
(<span class="symbol">UnmapNotify</span>,
<span class="symbol">MapNotify</span>,
<span class="symbol">ConfigureNotify</span>,
<span class="symbol">GravityNotify</span>,
<span class="symbol">CirculateNotify</span>)
caused by that change;
however, the X protocol does not constrain the ordering of 
<span class="symbol">EnterNotify</span>
and 
<span class="symbol">LeaveNotify</span>
events with respect to
<span class="symbol">FocusOut</span>,
<span class="symbol">VisibilityNotify</span>,
and 
<span class="symbol">Expose</span>
events.
</p><p>

This contrasts with
<span class="symbol">MotionNotify</span>
events, which are also generated when the pointer moves
but only when the pointer motion begins and ends in a single window.
An
<span class="symbol">EnterNotify</span>
or
<span class="symbol">LeaveNotify</span>
event also can be generated when some client application calls
<a class="xref" href="#XGrabPointer"><code class="function">XGrabPointer</code></a>
and
<a class="xref" href="#XUngrabPointer"><code class="function">XUngrabPointer</code></a>.
</p><p>

To receive
<span class="symbol">EnterNotify</span>
or
<span class="symbol">LeaveNotify</span>
events, set the
<span class="symbol">EnterWindowMask</span>
or
<span class="symbol">LeaveWindowMask</span>
bits of the event-mask attribute of the window.
</p><p>

The structure for these event types contains:
</p><a id="idp48759756" class="indexterm"></a><a id="idp48760132" class="indexterm"></a><a id="idp48760508" class="indexterm"></a><pre class="literallayout">


typedef struct {
     int           type;           /* EnterNotify or LeaveNotify */
     unsigned long serial;         /* # of last request processed by server */
     Bool          send_event;     /* true if this came from a SendEvent request */
     Display       *display;       /* Display the event was read from */
     Window        window;         /* ``event'' window reported relative to */
     Window        root;           /* root window that the event occurred on */
     Window        subwindow;      /* child window */
     Time          time;           /* milliseconds */
     int           x, y;           /* pointer x, y coordinates in event window */
     int           x_root, y_root; /* coordinates relative to root */
     int           mode;           /* NotifyNormal, NotifyGrab, NotifyUngrab */
     int           detail;
                   /*
                    * NotifyAncestor, NotifyVirtual, NotifyInferior, 
                    * NotifyNonlinear,NotifyNonlinearVirtual
                    */
     Bool          same_screen;    /* same screen flag */
     Bool          focus;          /* boolean focus */
     unsigned int  state;          /* key or button mask */
} XCrossingEvent;
typedef XCrossingEvent XEnterWindowEvent;
typedef XCrossingEvent XLeaveWindowEvent;
</pre><p>


The window member is set to the window on which the
<span class="symbol">EnterNotify</span>
or
<span class="symbol">LeaveNotify</span>
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.
</p><p>

For a
<span class="symbol">LeaveNotify</span>
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
<span class="symbol">None</span>.
For an
<span class="symbol">EnterNotify</span>
event, if a child of the event window contains the final pointer position, 
the subwindow component is set to that child or
<span class="symbol">None</span>.
</p><p>

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.
</p><p>

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
<span class="symbol">True</span>
or
<span class="symbol">False</span>.
If
<span class="symbol">True</span>,
the event and root windows are on the same screen.
If
<span class="symbol">False</span>,
the event and root windows are not on the same screen.
</p><p>

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
<span class="symbol">True</span>
or
<span class="symbol">False</span>.
If
<span class="symbol">True</span>,
the event window is the focus window or an inferior of the focus window.
If
<span class="symbol">False</span>,
the event window is not the focus window or an inferior of the focus window.
</p><p>

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:
<span class="symbol">Button1Mask</span>,
<span class="symbol">Button2Mask</span>,
<span class="symbol">Button3Mask</span>,
<span class="symbol">Button4Mask</span>,
<span class="symbol">Button5Mask</span>,
<span class="symbol">ShiftMask</span>,
<span class="symbol">LockMask</span>,
<span class="symbol">ControlMask</span>,
<span class="symbol">Mod1Mask</span>,
<span class="symbol">Mod2Mask</span>,
<span class="symbol">Mod3Mask</span>,
<span class="symbol">Mod4Mask</span>,
<span class="symbol">Mod5Mask</span>.
</p><p>

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 
<span class="symbol">NotifyNormal</span>,
<span class="symbol">NotifyGrab</span>,
or
<span class="symbol">NotifyUngrab</span>.
</p><p>

The detail member is set to indicate the notify detail and can be
<span class="symbol">NotifyAncestor</span>,
<span class="symbol">NotifyVirtual</span>,
<span class="symbol">NotifyInferior</span>,
<span class="symbol">NotifyNonlinear</span>,
or
<span class="symbol">NotifyNonlinearVirtual</span>.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Normal_EntryExit_Events"></a>Normal Entry/Exit Events</h3></div></div></div><p>

<span class="symbol">EnterNotify</span>
and
<span class="symbol">LeaveNotify</span>
events are generated when the pointer moves from
one window to another window.
Normal events are identified by
<span class="type">XEnterWindowEvent</span>
or
<span class="type">XLeaveWindowEvent</span>
structures whose mode member is set to
<span class="symbol">NotifyNormal</span>.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
When the pointer moves from window A to window B and A is an inferior of B, 
the X server does the following:

    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">LeaveNotify</span>
event on window A, with the detail member of the
<span class="type">XLeaveWindowEvent</span>
structure set to
<span class="symbol">NotifyAncestor</span>.
    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">LeaveNotify</span>
event on each window between window A and window B, exclusive,
with the detail member of each
<span class="type">XLeaveWindowEvent</span>
structure set to
<span class="symbol">NotifyVirtual</span>.
    </p></li><li class="listitem"><p>
It generates an
<span class="symbol">EnterNotify</span>
event on window B, with the detail member of the 
<span class="type">XEnterWindowEvent</span>
structure set to
<span class="symbol">NotifyInferior</span>.

    </p></li><li class="listitem"><p>
When the pointer moves from window A to window B and B is an inferior of A,
the X server does the following:

    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">LeaveNotify</span>
event on window A,
with the detail member of the
<span class="type">XLeaveWindowEvent</span>
structure set to
<span class="symbol">NotifyInferior</span>.
    </p></li><li class="listitem"><p>
It generates an
<span class="symbol">EnterNotify</span>
event on each window between window A and window B, exclusive, with the 
detail member of each 
<span class="type">XEnterWindowEvent</span>
structure set to
<span class="symbol">NotifyVirtual</span>.
    </p></li><li class="listitem"><p>
It generates an
<span class="symbol">EnterNotify</span>
event on window B, with the detail member of the 
<span class="type">XEnterWindowEvent</span>
structure set to
<span class="symbol">NotifyAncestor</span>.

    </p></li><li class="listitem"><p>
When the pointer moves from window A to window B 
and window C is their least common ancestor, 
the X server does the following:

    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">LeaveNotify</span>
event on window A,
with the detail member of the
<span class="type">XLeaveWindowEvent</span>
structure set to 
<span class="symbol">NotifyNonlinear</span>.
    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">LeaveNotify</span>
event on each window between window A and window C, exclusive,
with the detail member of each
<span class="type">XLeaveWindowEvent</span>
structure set to
<span class="symbol">NotifyNonlinearVirtual</span>.
    </p></li><li class="listitem"><p>
It generates an
<span class="symbol">EnterNotify</span>
event on each window between window C and window B, exclusive, 
with the detail member of each
<span class="type">XEnterWindowEvent</span>
structure set to
<span class="symbol">NotifyNonlinearVirtual</span>.
    </p></li><li class="listitem"><p>
It generates an
<span class="symbol">EnterNotify</span>
event on window B, with the detail member of the 
<span class="type">XEnterWindowEvent</span>
structure set to 
<span class="symbol">NotifyNonlinear</span>.

    </p></li><li class="listitem"><p>
When the pointer moves from window A to window B on different screens, 
the X server does the following:

    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">LeaveNotify</span>
event on window A,
with the detail member of the
<span class="type">XLeaveWindowEvent</span>
structure set to 
<span class="symbol">NotifyNonlinear</span>.
    </p></li><li class="listitem"><p>
If window A is not a root window,
it generates a
<span class="symbol">LeaveNotify</span>
event on each window above window A up to and including its root,
with the detail member of each
<span class="type">XLeaveWindowEvent</span>
structure set to 
<span class="symbol">NotifyNonlinearVirtual</span>.
    </p></li><li class="listitem"><p>
If window B is not a root window,
it generates an
<span class="symbol">EnterNotify</span>
event on each window from window B's root down to but not including
window B, with the detail member of each
<span class="type">XEnterWindowEvent</span>
structure set to 
<span class="symbol">NotifyNonlinearVirtual</span>.
    </p></li><li class="listitem"><p>
It generates an
<span class="symbol">EnterNotify</span>
event on window B, with the detail member of the
<span class="type">XEnterWindowEvent</span>
structure set to 
<span class="symbol">NotifyNonlinear</span>.


    </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Grab_and_Ungrab_EntryExit_Events"></a>Grab and Ungrab Entry/Exit Events</h3></div></div></div><p>

Pseudo-motion mode
<span class="symbol">EnterNotify</span>
and
<span class="symbol">LeaveNotify</span>
events are generated when a pointer grab activates or deactivates.
Events in which the pointer grab activates
are identified by
<span class="type">XEnterWindowEvent</span>
or
<span class="type">XLeaveWindowEvent</span>
structures whose mode member is set to 
<span class="symbol">NotifyGrab</span>.
Events in which the pointer grab deactivates
are identified by
<span class="type">XEnterWindowEvent</span>
or
<span class="type">XLeaveWindowEvent</span>
structures whose mode member is set to 
<span class="symbol">NotifyUngrab</span>
(see
<a class="xref" href="#XGrabPointer"><code class="function">XGrabPointer</code></a>).
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
When a pointer grab activates after any initial warp into a confine_to
window and before generating any actual
<span class="symbol">ButtonPress</span>
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:

    </p></li><li class="listitem"><p>
It generates
<span class="symbol">EnterNotify</span>
and
<span class="symbol">LeaveNotify</span>
events (see <a class="link" href="#Normal_EntryExit_Events" title="Normal Entry/Exit Events">section 10.6.1</a>)
with the mode members of the 
<span class="type">XEnterWindowEvent</span>
and
<span class="type">XLeaveWindowEvent</span>
structures set to 
<span class="symbol">NotifyGrab</span>.
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.

    </p></li><li class="listitem"><p>
When a pointer grab deactivates after generating any actual
<span class="symbol">ButtonRelease</span>
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:

    </p></li><li class="listitem"><p>
It generates
<span class="symbol">EnterNotify</span>
and
<span class="symbol">LeaveNotify</span>
events (see <a class="link" href="#Normal_EntryExit_Events" title="Normal Entry/Exit Events">section 10.6.1</a>)
with the mode members of the
<span class="type">XEnterWindowEvent</span>
and
<span class="type">XLeaveWindowEvent</span>
structures set to 
<span class="symbol">NotifyUngrab</span>.
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.

    </p></li></ul></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Input_Focus_Events"></a>Input Focus Events</h2></div></div></div><p>

<a id="idp48805900" class="indexterm"></a>
<a id="idp48806404" class="indexterm"></a>
This section describes the processing that occurs for the input focus events
<span class="symbol">FocusIn</span>
and
<span class="symbol">FocusOut</span>.
<a id="idp48807380" class="indexterm"></a>
<a id="idp48807756" class="indexterm"></a>
The X server can report
<span class="symbol">FocusIn</span>
or
<span class="symbol">FocusOut</span>
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.
</p><p>

To receive
<span class="symbol">FocusIn</span>
or
<span class="symbol">FocusOut</span>
events, set the
<span class="symbol">FocusChangeMask</span>
bit in the event-mask attribute of the window. 
</p><p>

The structure for these event types contains:
</p><a id="idp48810460" class="indexterm"></a><a id="idp48810836" class="indexterm"></a><a id="idp48811212" class="indexterm"></a><pre class="literallayout">


typedef struct {
     int           type;       /* FocusIn or FocusOut */
     unsigned long serial;     /* # of last request processed by server */
     Bool          send_event; /* true if this came from a SendEvent request */
     Display       *display;   /* Display the event was read from */
     Window        window;     /* window of event */
     int           mode;       /* NotifyNormal, NotifyGrab, NotifyUngrab */
     int           detail;
                   /*
                    * NotifyAncestor, NotifyVirtual, NotifyInferior, 
                    * NotifyNonlinear,NotifyNonlinearVirtual, NotifyPointer,
                    * NotifyPointerRoot, NotifyDetailNone 
                    */
} XFocusChangeEvent;
typedef XFocusChangeEvent XFocusInEvent;
typedef XFocusChangeEvent XFocusOutEvent;
</pre><p>


The window member is set to the window on which the
<span class="symbol">FocusIn</span>
or
<span class="symbol">FocusOut</span>
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 
<span class="symbol">NotifyNormal</span>,
<span class="symbol">NotifyWhileGrabbed</span>,
<span class="symbol">NotifyGrab</span>,
or
<span class="symbol">NotifyUngrab</span>.
</p><p>

All 
<span class="symbol">FocusOut</span>
events caused by a window unmap are generated after any
<span class="symbol">UnmapNotify</span>
event; however, the X protocol does not constrain the ordering of 
<span class="symbol">FocusOut</span>
events with respect to
generated 
<span class="symbol">EnterNotify</span>,
<span class="symbol">LeaveNotify</span>,
<span class="symbol">VisibilityNotify</span>,
and
<span class="symbol">Expose</span>
events.
</p><p>

Depending on the event mode,
the detail member is set to indicate the notify detail and can be
<span class="symbol">NotifyAncestor</span>,
<span class="symbol">NotifyVirtual</span>,
<span class="symbol">NotifyInferior</span>,
<span class="symbol">NotifyNonlinear</span>,
<span class="symbol">NotifyNonlinearVirtual</span>,
<span class="symbol">NotifyPointer</span>,
<span class="symbol">NotifyPointerRoot</span>,
or
<span class="symbol">NotifyDetailNone</span>.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Normal_Focus_Events_and_Focus_Events_While_Grabbed"></a>Normal Focus Events and Focus Events While Grabbed</h3></div></div></div><p>

Normal focus events are identified by
<span class="type">XFocusInEvent</span>
or
<span class="type">XFocusOutEvent</span>
structures whose mode member is set to 
<span class="symbol">NotifyNormal</span>.
Focus events while grabbed are identified by
<span class="type">XFocusInEvent</span>
or
<span class="type">XFocusOutEvent</span>
structures whose mode member is set to 
<span class="symbol">NotifyWhileGrabbed</span>.
The X server processes normal focus and focus events while grabbed according to 
the following:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
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:

    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">FocusOut</span>
event on window A, with the detail member of the
<span class="type">XFocusOutEvent</span>
structure set to 
<span class="symbol">NotifyAncestor</span>.
    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">FocusOut</span>
event on each window between window A and window B, exclusive,
with the detail member of each
<span class="type">XFocusOutEvent</span>
structure set to 
<span class="symbol">NotifyVirtual</span>.
    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">FocusIn</span>
event on window B, with the detail member of the 
<span class="type">XFocusOutEvent</span>
structure set to 
<span class="symbol">NotifyInferior</span>.
    </p></li><li class="listitem"><p>
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
<span class="symbol">FocusIn</span>
event on each window below window B, down to and including window P, 
with the detail member of each 
<span class="type">XFocusInEvent</span>
structure set to 
<span class="symbol">NotifyPointer</span>.

    </p></li><li class="listitem"><p>
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:

    </p></li><li class="listitem"><p>
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
<span class="symbol">FocusOut</span>
event on each window from window P up to but not including window A,
with the detail member of each 
<span class="type">XFocusOutEvent</span>
structure set to  
<span class="symbol">NotifyPointer</span>.
    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">FocusOut</span>
event on window A,
with the detail member of the
<span class="type">XFocusOutEvent</span>
structure set to  
<span class="symbol">NotifyInferior</span>.
    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">FocusIn</span>
event on each window between window A and window B, exclusive, with the 
detail member of each 
<span class="type">XFocusInEvent</span>
structure set to  
<span class="symbol">NotifyVirtual</span>.
    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">FocusIn</span>
event on window B, with the detail member of the 
<span class="type">XFocusInEvent</span>
structure set to  
<span class="symbol">NotifyAncestor</span>.

    </p></li><li class="listitem"><p>
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:

    </p></li><li class="listitem"><p>
If window P is an inferior of window A,
it generates a
<span class="symbol">FocusOut</span>
event on each window from window P up to but not including window A, 
with the detail member of the 
<span class="type">XFocusOutEvent</span>
structure set to  
<span class="symbol">NotifyPointer</span>.
    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">FocusOut</span>
event on window A,
with the detail member of the
<span class="type">XFocusOutEvent</span>
structure set to  
<span class="symbol">NotifyNonlinear</span>.
    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">FocusOut</span>
event on each window between window A and window C, exclusive,
with the detail member of each
<span class="type">XFocusOutEvent</span>
structure set to  
<span class="symbol">NotifyNonlinearVirtual</span>.
    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">FocusIn</span>
event on each window between C and B, exclusive,
with the detail member of each
<span class="type">XFocusInEvent</span>
structure set to  
<span class="symbol">NotifyNonlinearVirtual</span>.
    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">FocusIn</span>
event on window B, with the detail member of the 
<span class="type">XFocusInEvent</span>
structure set to  
<span class="symbol">NotifyNonlinear</span>.
    </p></li><li class="listitem"><p>
If window P is an inferior of window B, it generates a
<span class="symbol">FocusIn</span>
event on each window below window B down to and including window P, 
with the detail member of the 
<span class="type">XFocusInEvent</span>
structure set to  
<span class="symbol">NotifyPointer</span>.

    </p></li><li class="listitem"><p>
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:

    </p></li><li class="listitem"><p>
If window P is an inferior of window A, it generates a
<span class="symbol">FocusOut</span>
event on each window from window P up to but not including window A, 
with the detail member of each 
<span class="type">XFocusOutEvent</span>
structure set to  
<span class="symbol">NotifyPointer</span>.
    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">FocusOut</span>
event on window A,
with the detail member of the
<span class="type">XFocusOutEvent</span>
structure set to  
<span class="symbol">NotifyNonlinear</span>.
    </p></li><li class="listitem"><p>
If window A is not a root window,
it generates a
<span class="symbol">FocusOut</span>
event on each window above window A up to and including its root, 
with the detail member of each
<span class="type">XFocusOutEvent</span>
structure set to  
<span class="symbol">NotifyNonlinearVirtual</span>.
    </p></li><li class="listitem"><p>
If window B is not a root window,
it generates a
<span class="symbol">FocusIn</span>
event on each window from window B's root down to but not including
window B, with the detail member of each
<span class="type">XFocusInEvent</span>
structure set to  
<span class="symbol">NotifyNonlinearVirtual</span>.
    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">FocusIn</span>
event on window B, with the detail member of each 
<span class="type">XFocusInEvent</span>
structure set to  
<span class="symbol">NotifyNonlinear</span>.
    </p></li><li class="listitem"><p>
If window P is an inferior of window B, it generates a
<span class="symbol">FocusIn</span>
event on each window below window B down to and including window P, 
with the detail member of each 
<span class="type">XFocusInEvent</span>
structure set to  
<span class="symbol">NotifyPointer</span>.

    </p></li><li class="listitem"><p>
When the focus moves from window A to 
<span class="symbol">PointerRoot</span>
(events sent to the window under the pointer)
or
<span class="symbol">None</span>
(discard), and the pointer is in window P,
the X server does the following:

    </p></li><li class="listitem"><p>
If window P is an inferior of window A, it generates a
<span class="symbol">FocusOut</span>
event on each window from window P up to but not including window A, 
with the detail member of each 
<span class="type">XFocusOutEvent</span>
structure set to  
<span class="symbol">NotifyPointer</span>.
    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">FocusOut</span>
event on window A, with the detail member of the
<span class="type">XFocusOutEvent</span>
structure set to
<span class="symbol">NotifyNonlinear</span>.
    </p></li><li class="listitem"><p>
If window A is not a root window,
it generates a
<span class="symbol">FocusOut</span>
event on each window above window A up to and including its root, 
with the detail member of each
<span class="type">XFocusOutEvent</span>
structure set to
<span class="symbol">NotifyNonlinearVirtual</span>.
    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">FocusIn</span>
event on the root window of all screens, with the detail member of each
<span class="type">XFocusInEvent</span>
structure set to
<span class="symbol">NotifyPointerRoot</span>
(or
<span class="symbol">NotifyDetailNone</span>).
    </p></li><li class="listitem"><p>
If the new focus is
<span class="symbol">PointerRoot</span>,
it generates a
<span class="symbol">FocusIn</span>
event on each window from window P's root down to and including window P, 
with the detail member of each
<span class="type">XFocusInEvent</span>
structure set to
<span class="symbol">NotifyPointer</span>.

    </p></li><li class="listitem"><p>
When the focus moves from 
<span class="symbol">PointerRoot</span>
(events sent to the window under the pointer)
or
<span class="symbol">None</span>
to window A, and the pointer is in window P, 
the X server does the following: 

    </p></li><li class="listitem"><p>
If the old focus is
<span class="symbol">PointerRoot</span>,
it generates a
<span class="symbol">FocusOut</span>
event on each window from window P up to and including window P's root, 
with the detail member of each
<span class="type">XFocusOutEvent</span>
structure set to
<span class="symbol">NotifyPointer</span>.
    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">FocusOut</span>
event on all root windows,
with the detail member of each
<span class="type">XFocusOutEvent</span>
structure set to
<span class="symbol">NotifyPointerRoot</span>
(or
<span class="symbol">NotifyDetailNone</span>).
    </p></li><li class="listitem"><p>
If window A is not a root window,
it generates a
<span class="symbol">FocusIn</span>
event on each window from window A's root down to but not including window A,
with the detail member of each
<span class="type">XFocusInEvent</span>
structure set to
<span class="symbol">NotifyNonlinearVirtual</span>.
    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">FocusIn</span>
event on window A,
with the detail member of the 
<span class="type">XFocusInEvent</span>
structure set to  
<span class="symbol">NotifyNonlinear</span>.
    </p></li><li class="listitem"><p>
If window P is an inferior of window A, it generates a
<span class="symbol">FocusIn</span>
event on each window below window A down to and including window P, 
with the detail member of each 
<span class="type">XFocusInEvent</span>
structure set to  
<span class="symbol">NotifyPointer</span>.

    </p></li><li class="listitem"><p>
When the focus moves from 
<span class="symbol">PointerRoot</span>
(events sent to the window under the pointer)
to
<span class="symbol">None</span>
(or vice versa), and the pointer is in window P, 
the X server does the following:

    </p></li><li class="listitem"><p>
If the old focus is
<span class="symbol">PointerRoot</span>,
it generates a
<span class="symbol">FocusOut</span>
event on each window from window P up to and including window P's root, 
with the detail member of each
<span class="type">XFocusOutEvent</span>
structure set to
<span class="symbol">NotifyPointer</span>.
    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">FocusOut</span>
event on all root windows,
with the detail member of each 
<span class="type">XFocusOutEvent</span>
structure set to either
<span class="symbol">NotifyPointerRoot</span>
or
<span class="symbol">NotifyDetailNone</span>.
    </p></li><li class="listitem"><p>
It generates a
<span class="symbol">FocusIn</span>
event on all root windows,
with the detail member of each
<span class="type">XFocusInEvent</span>
structure set to
<span class="symbol">NotifyDetailNone</span>
or
<span class="symbol">NotifyPointerRoot</span>.
    </p></li><li class="listitem"><p>
If the new focus is
<span class="symbol">PointerRoot</span>,
it generates a
<span class="symbol">FocusIn</span>
event on each window from window P's root down to and including window P, 
with the detail member of each
<span class="type">XFocusInEvent</span>
structure set to
<span class="symbol">NotifyPointer</span>.


    </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Focus_Events_Generated_by_Grabs"></a>Focus Events Generated by Grabs</h3></div></div></div><p>

Focus events in which the keyboard grab activates
are identified by
<span class="type">XFocusInEvent</span>
or
<span class="type">XFocusOutEvent</span>
structures whose mode member is set to 
<span class="symbol">NotifyGrab</span>.
Focus events in which the keyboard grab deactivates
are identified by
<span class="type">XFocusInEvent</span>
or
<span class="type">XFocusOutEvent</span>
structures whose mode member is set to 
<span class="symbol">NotifyUngrab</span>
(see 
<a class="xref" href="#XGrabKeyboard"><code class="function">XGrabKeyboard</code></a>).
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
When a keyboard grab activates before generating any actual 
<span class="symbol">KeyPress</span>
event that activates the grab,
G is the grab_window, and F is the current focus, 
the X server does the following:

    </p></li><li class="listitem"><p>
It generates 
<span class="symbol">FocusIn</span>
and
<span class="symbol">FocusOut</span>
events, with the mode members of the 
<span class="type">XFocusInEvent</span>
and
<span class="type">XFocusOutEvent</span>
structures set to 
<span class="symbol">NotifyGrab</span>.
These events are generated
as if the focus were to change from
F to G.

    </p></li><li class="listitem"><p>
When a keyboard grab deactivates after generating any actual
<span class="symbol">KeyRelease</span>
event that deactivates the grab,
G is the grab_window, and F is the current focus,
the X server does the following:

    </p></li><li class="listitem"><p>
It generates 
<span class="symbol">FocusIn</span>
and
<span class="symbol">FocusOut</span>
events, with the mode members of the 
<span class="type">XFocusInEvent</span>
and
<span class="type">XFocusOutEvent</span>
structures set to
<span class="symbol">NotifyUngrab</span>.
These events are generated
as if the focus were to change from
G to F.

    </p></li></ul></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Key_Map_State_Notification_Events"></a>Key Map State Notification Events</h2></div></div></div><p>

<a id="idp48876700" class="indexterm"></a>
<a id="idp48877204" class="indexterm"></a>
The X server can report
<span class="symbol">KeymapNotify</span>
events to clients that want information about changes in their keyboard state.
</p><p>

To receive
<span class="symbol">KeymapNotify</span>
events, set the
<span class="symbol">KeymapStateMask</span>
bit in the event-mask attribute of the window. 
The X server generates this event immediately after every
<span class="symbol">EnterNotify</span>
and
<span class="symbol">FocusIn</span>
event.
</p><p>

The structure for this event type contains:
</p><p>

<a id="idp48879756" class="indexterm"></a>

</p><pre class="literallayout">


/* generated on EnterWindow and FocusIn when KeymapState selected */
typedef struct {
     int            type;           /* KeymapNotify */
     unsigned long  serial;         /* # of last request processed by server */
     Bool           send_event;     /* true if this came from a SendEvent request */
     Display        *display;       /* Display the event was read from */
     Window         window;
     char           key_vector[32];
} XKeymapEvent;     
</pre><p>
</p><p>


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.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Exposure_Events"></a>Exposure Events</h2></div></div></div><p>

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 
<span class="symbol">Expose</span>
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.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Expose_Events"></a>Expose Events</h3></div></div></div><p>

<a id="idp48885532" class="indexterm"></a>
<a id="idp48886036" class="indexterm"></a>
The X server can report
<span class="symbol">Expose</span>
events to clients wanting information about when the contents of window regions
have been lost.
The circumstances in which the X server generates
<span class="symbol">Expose</span>
events are not as definite as those for other events.
However, the X server never generates
<span class="symbol">Expose</span>
events on windows whose class you specified as
<span class="symbol">InputOnly</span>.
The X server can generate
<span class="symbol">Expose</span>
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
<span class="symbol">Always</span>
or
<span class="symbol">WhenMapped</span>.
The regions decompose into an (arbitrary) set of rectangles,
and an
<span class="symbol">Expose</span>
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 
<span class="symbol">Expose</span>
events, such as raising a window.
</p><p>

To receive
<span class="symbol">Expose</span>
events, set the
<span class="symbol">ExposureMask</span>
bit in the event-mask attribute of the window. 
</p><p>

The structure for this event type contains:
</p><p>

<a id="idp48890572" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;           /* Expose */
     unsigned long serial;         /* # of last request processed by server */
     Bool          send_event;     /* true if this came from a SendEvent request */
     Display       *display;       /* Display the event was read from */
     Window        window;
     int           x, y;
     int           width, height;
     int           count;          /* if nonzero, at least this many more */
} XExposeEvent;
</pre><p>
</p><p>


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
<span class="symbol">Expose</span>
events that are to follow.
If count is zero, no more
<span class="symbol">Expose</span>
events follow for this window.
However, if count is nonzero, at least that number of 
<span class="symbol">Expose</span>
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
<span class="symbol">Expose</span>
events with nonzero counts and perform full redisplays
on events with zero counts.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="GraphicsExpose_and_NoExpose_Events"></a>GraphicsExpose and NoExpose Events</h3></div></div></div><p>

<a id="idp48895612" class="indexterm"></a>
<a id="idp48896116" class="indexterm"></a>
<a id="idp48896620" class="indexterm"></a>
The X server can report
<span class="symbol">GraphicsExpose</span>
events to clients wanting information about when a destination region could not
be computed during certain graphics requests:
<a class="xref" href="#XCopyArea"><code class="function">XCopyArea</code></a>
or
<a class="xref" href="#XCopyPlane"><code class="function">XCopyPlane</code></a>.
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).
</p><p>

<a id="idp48898716" class="indexterm"></a>
The X server generates a
<span class="symbol">NoExpose</span>
event whenever a graphics request that might
produce a
<span class="symbol">GraphicsExpose</span>
event does not produce any.
In other words, the client is really asking for a
<span class="symbol">GraphicsExpose</span>
event but instead receives a
<span class="symbol">NoExpose</span>
event.
</p><p>

To receive
<span class="symbol">GraphicsExpose</span>
or
<span class="symbol">NoExpose</span>
events, you must first set the graphics-exposure 
attribute of the graphics context to
<span class="symbol">True</span>.
You also can set the graphics-expose attribute when creating a graphics
context using
<a class="xref" href="#XCreateGC"><code class="function">XCreateGC</code></a>
or by calling
<a class="xref" href="#XSetGraphicsExposures"><code class="function">XSetGraphicsExposures</code></a>.
</p><p>

The structures for these event types contain:
</p><p>

<a id="idp48902572" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int            type;           /* GraphicsExpose */
     unsigned long  serial;         /* # of last request processed by server */
     Bool           send_event;     /* true if this came from a SendEvent request */
     Display        *display;       /* Display the event was read from */
     Drawable       drawable;
     int            x, y;
     int            width, height;
     int            count;          /* if nonzero, at least this many more */
     int            major_code;     /* core is CopyArea or CopyPlane */
     int            minor_code;     /* not defined in the core */
} XGraphicsExposeEvent;
</pre><p>
</p><p>

<a id="idp48904740" class="indexterm"></a>
</p><pre class="literallayout">


typedef struct {
     int           type;         /* NoExpose */
     unsigned long serial;       /* # of last request processed by server */
     Bool          send_event;   /* true if this came from a SendEvent request */
     Display       *display;     /* Display the event was read from */
     Drawable      drawable;
     int           major_code;   /* core is CopyArea or CopyPlane */
     int           minor_code;   /* not defined in the core */
} XNoExposeEvent;
</pre><p>
</p><p>


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
<span class="symbol">X_CopyArea</span>
or
<span class="symbol">X_CopyPlane</span>.
If it is
<span class="symbol">X_CopyArea</span>,
a call to
<a class="xref" href="#XCopyArea"><code class="function">XCopyArea</code></a>
initiated the request.
If it is
<span class="symbol">X_CopyPlane</span>,
a call to
<a class="xref" href="#XCopyPlane"><code class="function">XCopyPlane</code></a>
initiated the request.
These constants are defined in 
<code class="filename">&lt;X11/Xproto.h&gt;</code>.
<a id="idp48909076" class="indexterm"></a>
<a id="idp48909876" class="indexterm"></a>
<a id="idp48910684" class="indexterm"></a>
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.
</p><p>

The 
<span class="structname">XGraphicsExposeEvent</span>
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
<span class="symbol">GraphicsExpose</span>
events to follow.
If count is zero, no more
<span class="symbol">GraphicsExpose</span>
events follow for this window.
However, if count is nonzero, at least that number of
<span class="symbol">GraphicsExpose</span>
events (and possibly more) are to follow for this window.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Window_State_Change_Events"></a>Window State Change Events</h2></div></div></div><p>

The following sections discuss:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<span class="symbol">CirculateNotify</span>
events
    </p></li><li class="listitem"><p>
<span class="symbol">ConfigureNotify</span>
events
    </p></li><li class="listitem"><p>
<span class="symbol">CreateNotify</span>
events
    </p></li><li class="listitem"><p>
<span class="symbol">DestroyNotify</span>
events
    </p></li><li class="listitem"><p>
<span class="symbol">GravityNotify</span>
events
    </p></li><li class="listitem"><p>
<span class="symbol">MapNotify</span>
events
    </p></li><li class="listitem"><p>
<span class="symbol">MappingNotify</span>
events
    </p></li><li class="listitem"><p>
<span class="symbol">ReparentNotify</span>
events
    </p></li><li class="listitem"><p>
<span class="symbol">UnmapNotify</span>
events
    </p></li><li class="listitem"><p>
<span class="symbol">VisibilityNotify</span>
events

    </p></li></ul></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="CirculateNotify_Events"></a>CirculateNotify Events</h3></div></div></div><p>

<a id="idp48922020" class="indexterm"></a>
<a id="idp48922524" class="indexterm"></a>
The X server can report
<span class="symbol">CirculateNotify</span>
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
<a class="xref" href="#XCirculateSubwindows"><code class="function">XCirculateSubwindows</code></a>,
<a class="xref" href="#XCirculateSubwindowsUp"><code class="function">XCirculateSubwindowsUp</code></a>,
or
<a class="xref" href="#XCirculateSubwindowsDown"><code class="function">XCirculateSubwindowsDown</code></a>.
</p><p>

To receive 
<span class="symbol">CirculateNotify</span>
events, set the
<span class="symbol">StructureNotifyMask</span>
bit in the event-mask attribute of the window
or the
<span class="symbol">SubstructureNotifyMask</span>
bit in the event-mask attribute of the parent window
(in which case, circulating any child generates an event).
</p><p>

The structure for this event type contains:
</p><p>

<a id="idp48926196" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int type;     /* CirculateNotify */
     unsigned long serial;     /* # of last request processed by server */
     Bool send_event;     /* true if this came from a SendEvent request */
     Display *display;     /* Display the event was read from */
     Window event;
     Window window;
     int place;     /* PlaceOnTop, PlaceOnBottom */
} XCirculateEvent;
</pre><p>
</p><p>


The event member is set either to the restacked window or to its parent,
depending on whether
<code class="systemitem">StructureNotify</code>
or
<code class="systemitem">SubstructureNotify</code>
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
<span class="symbol">PlaceOnTop</span>
or
<span class="symbol">PlaceOnBottom</span>.
If it is
<span class="symbol">PlaceOnTop</span>,
the window is now on top of all siblings.
If it is
<span class="symbol">PlaceOnBottom</span>,
the window is now below all siblings.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="ConfigureNotify_Events"></a>ConfigureNotify Events</h3></div></div></div><p>

<a id="idp48931492" class="indexterm"></a>
<a id="idp48931996" class="indexterm"></a>
The X server can report
<span class="symbol">ConfigureNotify</span>
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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
A window's size, position, border, and/or stacking order is reconfigured 
by calling
<a class="xref" href="#XConfigureWindow"><code class="function">XConfigureWindow</code></a>.
    </p></li><li class="listitem"><p>
The window's position in the stacking order is changed by calling
<a class="xref" href="#XLowerWindow"><code class="function">XLowerWindow</code></a>,
<a class="xref" href="#XRaiseWindow"><code class="function">XRaiseWindow</code></a>,
or
<a class="xref" href="#XRestackWindows"><code class="function">XRestackWindows</code></a>.
    </p></li><li class="listitem"><p>
A window is moved by calling
<a class="xref" href="#XMoveWindow"><code class="function">XMoveWindow</code></a>.
    </p></li><li class="listitem"><p>
A window's size is changed by calling
<a class="xref" href="#XResizeWindow"><code class="function">XResizeWindow</code></a>.
    </p></li><li class="listitem"><p>
A window's size and location is changed by calling
<a class="xref" href="#XMoveResizeWindow"><code class="function">XMoveResizeWindow</code></a>.
    </p></li><li class="listitem"><p>
A window is mapped and its position in the stacking order is changed
by calling
<a class="xref" href="#XMapRaised"><code class="function">XMapRaised</code></a>.
    </p></li><li class="listitem"><p>
A window's border width is changed by calling
<a class="xref" href="#XSetWindowBorderWidth"><code class="function">XSetWindowBorderWidth</code></a>.
    </p></li></ul></div><p>

To receive 
<span class="symbol">ConfigureNotify</span>
events, set the
<span class="symbol">StructureNotifyMask</span>
bit in the event-mask attribute of the window or the
<span class="symbol">SubstructureNotifyMask</span>
bit in the event-mask attribute of the parent window
(in which case, configuring any child generates an event).
</p><p>

The structure for this event type contains:
</p><a id="idp48941156" class="indexterm"></a><pre class="literallayout">


typedef struct {
     int           type;       /* ConfigureNotify */
     unsigned long serial;     /* # of last request processed by server */
     Bool          send_event; /* true if this came from a SendEvent request */
     Display       *display;   /* Display the event was read from */
     Window        event;
     Window        window;
     int           x, y;
     int           width, height;
     int           border_width;
     Window        above;
     Bool          override_redirect;
} XConfigureEvent;
</pre><p>


The event member is set either to the reconfigured window or to its parent,
depending on whether
<code class="systemitem">StructureNotify</code>
or
<code class="systemitem">SubstructureNotify</code>
was selected.
The window member is set to the window whose size, position, 
border, and/or stacking
order was changed.
</p><p>

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.
</p><p>

The above member is set to the sibling window and is used 
for stacking operations.
If the X server sets this member to
<span class="symbol">None</span>,
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.
</p><p>

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
<span class="symbol">True</span>.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="CreateNotify_Events"></a>CreateNotify Events</h3></div></div></div><p>

<a id="idp48947812" class="indexterm"></a>
<a id="idp48948316" class="indexterm"></a>
The X server can report
<span class="symbol">CreateNotify</span>
events to clients wanting information about creation of windows.
The X server generates this event whenever a client
application creates a window by calling
<a class="xref" href="#XCreateWindow"><code class="function">XCreateWindow</code></a>
or
<a class="xref" href="#XCreateSimpleWindow"><code class="function">XCreateSimpleWindow</code></a>.
</p><p>

To receive 
<span class="symbol">CreateNotify</span>
events, set the
<span class="symbol">SubstructureNotifyMask</span>
bit in the event-mask attribute of the window.
Creating any children then generates an event.
</p><p>

The structure for the event type contains:
</p><p>

<a id="idp48951292" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;               /* CreateNotify */
     unsigned long serial;             /* # of last request processed by server */
     Bool          send_event;         /* true if this came from a SendEvent request */
     Display       *display;           /* Display the event was read from */
     Window        parent;             /* parent of the window */
     Window        window;             /* window id of window created */
     int           x, y;               /* window location */
     int           width, height;      /* size of window */
     int           border_width;       /* border width */
     Bool          override_redirect;  /* creation should be overridden */
} XCreateWindowEvent;
</pre><p>
</p><p>


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
<span class="symbol">True</span>.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="DestroyNotify_Events"></a>DestroyNotify Events</h3></div></div></div><p>

<a id="idp48955772" class="indexterm"></a>
<a id="idp48956276" class="indexterm"></a>
The X server can report
<span class="symbol">DestroyNotify</span>
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
<a class="xref" href="#XDestroyWindow"><code class="function">XDestroyWindow</code></a>
or
<a class="xref" href="#XDestroySubwindows"><code class="function">XDestroySubwindows</code></a>.
</p><p>

The ordering of the 
<span class="symbol">DestroyNotify</span>
events is such that for any given window, 
<span class="symbol">DestroyNotify</span>
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.
</p><p>

To receive 
<span class="symbol">DestroyNotify</span>
events, set the
<span class="symbol">StructureNotifyMask</span>
bit in the event-mask attribute of the window or the
<span class="symbol">SubstructureNotifyMask</span>
bit in the event-mask attribute of the parent window
(in which case, destroying any child generates an event).
</p><p>

The structure for this event type contains:
</p><p>

<a id="idp48960484" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;       /* DestroyNotify */
     unsigned long serial;     /* # of last request processed by server */
     Bool          send_event; /* true if this came from a SendEvent request */
     Display       *display;   /* Display the event was read from */
     Window        event;
     Window        window;
} XDestroyWindowEvent;
</pre><p>
</p><p>


The event member is set either to the destroyed window or to its parent,
depending on whether
<code class="systemitem">StructureNotify</code>
or 
<code class="systemitem">SubstructureNotify</code>
was selected.
The window member is set to the window that is destroyed.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="GravityNotify_Events"></a>GravityNotify Events</h3></div></div></div><p>

<a id="idp48964756" class="indexterm"></a>
<a id="idp48965260" class="indexterm"></a>
The X server can report
<span class="symbol">GravityNotify</span>
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
<a class="xref" href="#XConfigureWindow"><code class="function">XConfigureWindow</code></a>,
<a class="xref" href="#XMoveResizeWindow"><code class="function">XMoveResizeWindow</code></a>,
or
<a class="xref" href="#XResizeWindow"><code class="function">XResizeWindow</code></a>.
</p><p>

To receive 
<span class="symbol">GravityNotify</span>
events, set the
<span class="symbol">StructureNotifyMask</span>
bit in the event-mask attribute of the window or the
<span class="symbol">SubstructureNotifyMask</span>
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).
</p><p>

The structure for this event type contains:
</p><p>

<a id="idp48969012" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;       /* GravityNotify */
     unsigned long serial;     /* # of last request processed by server */
     Bool          send_event; /* true if this came from a SendEvent request */
     Display       *display;   /* Display the event was read from */
     Window        event;
     Window        window;
     int           x, y;
} XGravityEvent;
</pre><p>
</p><p>


The event member is set either to the window that was moved or to its parent,
depending on whether
<code class="systemitem">StructureNotify</code>
or
<code class="systemitem">SubstructureNotify</code>
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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="MapNotify_Events"></a>MapNotify Events</h3></div></div></div><p>

<a id="idp48973484" class="indexterm"></a>
<a id="idp48973988" class="indexterm"></a>
The X server can report
<span class="symbol">MapNotify</span>
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
<a class="xref" href="#XMapWindow"><code class="function">XMapWindow</code></a>,
<a class="xref" href="#XMapRaised"><code class="function">XMapRaised</code></a>,
<a class="xref" href="#XMapSubwindows"><code class="function">XMapSubwindows</code></a>,
<a class="xref" href="#XReparentWindow"><code class="function">XReparentWindow</code></a>,
or as a result of save-set processing.
</p><p>

To receive 
<span class="symbol">MapNotify</span>
events, set the
<span class="symbol">StructureNotifyMask</span>
bit in the event-mask attribute of the window or the
<span class="symbol">SubstructureNotifyMask</span>
bit in the event-mask attribute of the parent window
(in which case, mapping any child generates an event).
</p><p>

The structure for this event type contains:
</p><p>

<a id="idp48978060" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;                  /* MapNotify */
     unsigned long serial;                /* # of last request processed by server */
     Bool          send_event;            /* true if this came from a SendEvent request */
     Display       *display;              /* Display the event was read from */
     Window        event;
     Window        window;
     Bool          override_redirect;     /* boolean, is override set... */
} XMapEvent;
</pre><p>
</p><p>


The event member is set either to the window that was mapped or to its parent,
depending on whether
<code class="systemitem">StructureNotify</code>
or
<code class="systemitem">SubstructureNotify</code>
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
<span class="symbol">True</span>,
because these events usually are generated from pop-ups,
which override structure control.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="MappingNotify_Events"></a>MappingNotify Events</h3></div></div></div><p>

<a id="idp48982924" class="indexterm"></a>
<a id="idp48983428" class="indexterm"></a>
The X server reports
<span class="symbol">MappingNotify</span>
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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<a class="xref" href="#XSetModifierMapping"><code class="function">XSetModifierMapping</code></a>
to indicate which KeyCodes are to be used as modifiers
    </p></li><li class="listitem"><p>
<a class="xref" href="#XChangeKeyboardMapping"><code class="function">XChangeKeyboardMapping</code></a>
to change the keyboard mapping
    </p></li><li class="listitem"><p>
<a class="xref" href="#XSetPointerMapping"><code class="function">XSetPointerMapping</code></a>
to set the pointer mapping
    </p></li></ul></div><p>

The structure for this event type contains:
</p><p>

<a id="idp48987484" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;           /* MappingNotify */
     unsigned long serial;         /* # of last request processed by server */
     Bool          send_event;     /* true if this came from a SendEvent request */
     Display       *display;       /* Display the event was read from */
     Window        window;         /* unused */
     int           request;        /* one of MappingModifier, MappingKeyboard,
                   MappingPointer  */
     int           first_keycode;  /* first keycode */
     int           count;          /* defines range of change w. first_keycode*/
} XMappingEvent;
</pre><p>
</p><p>


The request member is set to indicate the kind of mapping change that occurred
and can be
<span class="symbol">MappingModifier</span>,
<span class="symbol">MappingKeyboard</span>,
or
<span class="symbol">MappingPointer</span>.
If it is
<span class="symbol">MappingModifier</span>,
the modifier mapping was changed.
If it is
<span class="symbol">MappingKeyboard</span>,
the keyboard mapping was changed.
If it is
<span class="symbol">MappingPointer</span>,
the pointer button mapping was changed. 
The first_keycode and count members are set only 
if the request member was set to
<span class="symbol">MappingKeyboard</span>.
The number in first_keycode represents the first number in the range 
of the altered mapping, 
and count represents the number of keycodes altered.
</p><p>

To update the client application's knowledge of the keyboard,
you should call
<a class="xref" href="#XRefreshKeyboardMapping"><code class="function">XRefreshKeyboardMapping</code></a>.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="ReparentNotify_Events"></a>ReparentNotify Events</h3></div></div></div><p>

<a id="idp48993588" class="indexterm"></a>
<a id="idp48994092" class="indexterm"></a>
The X server can report
<span class="symbol">ReparentNotify</span>
events to clients wanting information about changing a window's parent.
The X server generates this event whenever a client
application calls
<a class="xref" href="#XReparentWindow"><code class="function">XReparentWindow</code></a>
and the window is actually reparented.
</p><p>

To receive 
<span class="symbol">ReparentNotify</span>
events, set the
<span class="symbol">StructureNotifyMask</span>
bit in the event-mask attribute of the window or the
<span class="symbol">SubstructureNotifyMask</span>
bit in the event-mask attribute of either the old or the new parent window
(in which case, reparenting any child generates an event).
</p><p>

The structure for this event type contains:
</p><p>

<a id="idp48997028" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;       /* ReparentNotify */
     unsigned long serial;     /* # of last request processed by server */
     Bool          send_event; /* true if this came from a SendEvent request */
     Display       *display;   /* Display the event was read from */
     Window        event;
     Window        window;
     Window        parent;
     int           x, y;
     Bool          override_redirect;
} XReparentEvent;
</pre><p>
</p><p>


The event member is set either to the reparented window
or to the old or the new parent, depending on whether
<code class="systemitem">StructureNotify</code>
or
<code class="systemitem">SubstructureNotify</code>
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
<span class="symbol">True</span>.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="UnmapNotify_Events"></a>UnmapNotify Events</h3></div></div></div><p>

<a id="idp49002036" class="indexterm"></a>
<a id="idp49002540" class="indexterm"></a>
The X server can report
<span class="symbol">UnmapNotify</span>
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.
</p><p>

To receive 
<span class="symbol">UnmapNotify</span>
events, set the
<span class="symbol">StructureNotifyMask</span>
bit in the event-mask attribute of the window or the
<span class="symbol">SubstructureNotifyMask</span>
bit in the event-mask attribute of the parent window
(in which case, unmapping any child window generates an event).
</p><p>

The structure for this event type contains:
</p><p>

<a id="idp49005092" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;       /* UnmapNotify */
     unsigned long serial;     /* # of last request processed by server */
     Bool          send_event; /* true if this came from a SendEvent request */
     Display       *display;   /* Display the event was read from */
     Window        event;
     Window        window;
     Bool          from_configure;
} XUnmapEvent;
</pre><p>
</p><p>


The event member is set either to the unmapped window or to its parent,
depending on whether
<code class="systemitem">StructureNotify</code>
or
<code class="systemitem">SubstructureNotify</code>
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
<span class="symbol">True</span>
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
<span class="symbol">UnmapGravity</span>.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="VisibilityNotify_Events"></a>VisibilityNotify Events</h3></div></div></div><p>

<a id="idp49010036" class="indexterm"></a>
<a id="idp49010540" class="indexterm"></a>
The X server can report
<span class="symbol">VisibilityNotify</span>
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
<span class="symbol">InputOnly</span>.
</p><p>

All 
<span class="symbol">VisibilityNotify</span>
events caused by a hierarchy change are generated
after any hierarchy event
(<span class="symbol">UnmapNotify</span>,
<span class="symbol">MapNotify</span>,
<span class="symbol">ConfigureNotify</span>,
<span class="symbol">GravityNotify</span>,
<span class="symbol">CirculateNotify</span>)
caused by that change.  Any
<span class="symbol">VisibilityNotify</span>
event on a given window is generated before any
<span class="symbol">Expose</span>
events on that window, but it is not required that all
<span class="symbol">VisibilityNotify</span>
events on all windows be generated before all 
<span class="symbol">Expose</span>
events on all windows.  
The X protocol does not constrain the ordering of 
<span class="symbol">VisibilityNotify</span>
events with
respect to 
<span class="symbol">FocusOut</span>,
<span class="symbol">EnterNotify</span>,
and 
<span class="symbol">LeaveNotify</span>
events.
</p><p>

To receive 
<span class="symbol">VisibilityNotify</span>
events, set the
<span class="symbol">VisibilityChangeMask</span>
bit in the event-mask attribute of the window. 
</p><p>

The structure for this event type contains:
</p><p>

<a id="idp49016468" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;       /* VisibilityNotify */
     unsigned long serial;     /* # of last request processed by server */
     Bool          send_event; /* true if this came from a SendEvent request */
     Display       *display;   /* Display the event was read from */
     Window        window;
     int           state;
} XVisibilityEvent;
</pre><p>
</p><p>


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
<span class="symbol">VisibilityUnobscured</span>,
<span class="symbol">VisibilityPartiallyObscured</span>,
or
<span class="symbol">VisibilityFullyObscured</span>.
The X server ignores all of a window's subwindows
when determining the visibility state of the window and processes 
<span class="symbol">VisibilityNotify</span>
events according to the following:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
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
<span class="structname">XVisibilityEvent</span>
structure set to
<span class="symbol">VisibilityUnobscured</span>.
    </p></li><li class="listitem"><p>
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
<span class="structname">XVisibilityEvent</span>
structure set to
<span class="symbol">VisibilityPartiallyObscured</span>.
    </p></li><li class="listitem"><p>
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
<span class="structname">XVisibilityEvent</span>
structure set to
<span class="symbol">VisibilityFullyObscured</span>.
    </p></li></ul></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Structure_Control_Events"></a>Structure Control Events</h2></div></div></div><p>

This section discusses:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<span class="symbol">CirculateRequest</span>
events
    </p></li><li class="listitem"><p>
<span class="symbol">ConfigureRequest</span>
events
    </p></li><li class="listitem"><p>
<span class="symbol">MapRequest</span>
events
    </p></li><li class="listitem"><p>
<span class="symbol">ResizeRequest</span>
events
    </p></li></ul></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="CirculateRequest_Events"></a>CirculateRequest Events</h3></div></div></div><p>

<a id="idp49027684" class="indexterm"></a>
<a id="idp49028188" class="indexterm"></a>
The X server can report
<span class="symbol">CirculateRequest</span>
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
<a class="xref" href="#XCirculateSubwindows"><code class="function">XCirculateSubwindows</code></a>,
<a class="xref" href="#XCirculateSubwindowsUp"><code class="function">XCirculateSubwindowsUp</code></a>,
or
<a class="xref" href="#XCirculateSubwindowsDown"><code class="function">XCirculateSubwindowsDown</code></a>.
</p><p>

To receive
<span class="symbol">CirculateRequest</span>
events, set the
<span class="symbol">SubstructureRedirectMask</span>
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
<a class="xref" href="#XCirculateSubwindowsUp"><code class="function">XCirculateSubwindowsUp</code></a>
to raise a subwindow to the top of the stack.
If you had selected
<span class="symbol">SubstructureRedirectMask</span>
on the window, the X server reports to you a
<span class="symbol">CirculateRequest</span>
event and does not raise the subwindow to the top of the stack.
</p><p>

The structure for this event type contains:
</p><p>

<a id="idp49032828" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;       /* CirculateRequest */
     unsigned long serial;     /* # of last request processed by server */
     Bool          send_event; /* true if this came from a SendEvent request */
     Display       *display;   /* Display the event was read from */
     Window        parent;
     Window        window;
     int place;                /* PlaceOnTop, PlaceOnBottom */
} XCirculateRequestEvent;
</pre><p>
</p><p>


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
<span class="symbol">PlaceOnTop</span>
or
<span class="symbol">PlaceOnBottom</span>.
If it is
<span class="symbol">PlaceOnTop</span>,
the subwindow should be on top of all siblings.
If it is
<span class="symbol">PlaceOnBottom</span>,
the subwindow should be below all siblings.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="ConfigureRequest_Events"></a>ConfigureRequest Events</h3></div></div></div><p>

<a id="idp49037260" class="indexterm"></a>
<a id="idp49037764" class="indexterm"></a>
The X server can report
<span class="symbol">ConfigureRequest</span>
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
<a class="xref" href="#XConfigureWindow"><code class="function">XConfigureWindow</code></a>,
<a class="xref" href="#XLowerWindow"><code class="function">XLowerWindow</code></a>,
<a class="xref" href="#XRaiseWindow"><code class="function">XRaiseWindow</code></a>,
<a class="xref" href="#XMapRaised"><code class="function">XMapRaised</code></a>,
<a class="xref" href="#XMoveResizeWindow"><code class="function">XMoveResizeWindow</code></a>,
<a class="xref" href="#XMoveWindow"><code class="function">XMoveWindow</code></a>,
<a class="xref" href="#XResizeWindow"><code class="function">XResizeWindow</code></a>,
<a class="xref" href="#XRestackWindows"><code class="function">XRestackWindows</code></a>,
or
<a class="xref" href="#XSetWindowBorderWidth"><code class="function">XSetWindowBorderWidth</code></a>.
</p><p>

To receive
<span class="symbol">ConfigureRequest</span>
events, set the
<span class="symbol">SubstructureRedirectMask</span>
bit in the event-mask attribute of the window. 
<span class="symbol">ConfigureRequest</span>
events are generated when a
<code class="systemitem">ConfigureWindow</code>
protocol request is issued on a child window by another client.
For example, suppose a client application calls
<a class="xref" href="#XLowerWindow"><code class="function">XLowerWindow</code></a>
to lower a window.
If you had selected
<span class="symbol">SubstructureRedirectMask</span>
on the parent window and if the override-redirect attribute 
of the window is set to
<span class="symbol">False</span>,
the X server reports a
<span class="symbol">ConfigureRequest</span>
event to you and does not lower the specified window.
</p><p>

The structure for this event type contains:
</p><p>

<a id="idp49045300" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;         /* ConfigureRequest */
     unsigned long serial;       /* # of last request processed by server */
     Bool          send_event;   /* true if this came from a SendEvent request */
     Display       *display;     /* Display the event was read from */
     Window        parent;
     Window        window;
     int           x, y;
     int           width, height;
     int           border_width;
     Window        above;
     int           detail;       /* Above, Below, TopIf, BottomIf, Opposite */
     unsigned long value_mask;
} XConfigureRequestEvent;
</pre><p>
</p><p>


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
<code class="systemitem">ConfigureWindow</code>
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
<span class="symbol">None</span>
and
<span class="symbol">Above</span>,
respectively, if they are not given in the request.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="MapRequest_Events"></a>MapRequest Events</h3></div></div></div><p>

<a id="idp49050028" class="indexterm"></a>
<a id="idp49050532" class="indexterm"></a>
The X server can report
<span class="symbol">MapRequest</span>
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
<span class="symbol">False</span>.
Clients initiate map window requests by calling
<a class="xref" href="#XMapWindow"><code class="function">XMapWindow</code></a>,
<a class="xref" href="#XMapRaised"><code class="function">XMapRaised</code></a>,
or
<a class="xref" href="#XMapSubwindows"><code class="function">XMapSubwindows</code></a>.
</p><p>

To receive
<span class="symbol">MapRequest</span>
events, set the
<span class="symbol">SubstructureRedirectMask</span>
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 
<span class="symbol">MapRequest</span>
instead.
For example, suppose a client application calls
<a class="xref" href="#XMapWindow"><code class="function">XMapWindow</code></a>
to map a window.
If you (usually a window manager) had selected
<span class="symbol">SubstructureRedirectMask</span>
on the parent window and if the override-redirect attribute 
of the window is set to
<span class="symbol">False</span>,
the X server reports a
<span class="symbol">MapRequest</span>
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.
</p><p>

The structure for this event type contains:
</p><p>

<a id="idp49055908" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;       /* MapRequest */
     unsigned long serial;     /* # of last request processed by server */
     Bool          send_event; /* true if this came from a SendEvent request */
     Display       *display;   /* Display the event was read from */
     Window        parent;
     Window        window;
} XMapRequestEvent;
</pre><p>
</p><p>


The parent member is set to the parent window.
The window member is set to the window to be mapped.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="ResizeRequest_Events"></a>ResizeRequest Events</h3></div></div></div><p>

<a id="idp49059244" class="indexterm"></a>
<a id="idp49059748" class="indexterm"></a>
The X server can report
<span class="symbol">ResizeRequest</span>
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
<a class="xref" href="#XConfigureWindow"><code class="function">XConfigureWindow</code></a>,
<a class="xref" href="#XResizeWindow"><code class="function">XResizeWindow</code></a>,
or
<a class="xref" href="#XMoveResizeWindow"><code class="function">XMoveResizeWindow</code></a>.
</p><p>

To receive
<span class="symbol">ResizeRequest</span>
events, set the
<span class="symbol">ResizeRedirect</span>
bit in the event-mask attribute of the window. 
Any attempts to change the size by other clients are then redirected.
</p><p>

The structure for this event type contains:
</p><p>

<a id="idp49063180" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;        /* ResizeRequest */
     unsigned long serial;      /* # of last request processed by server */
     Bool          send_event;  /* true if this came from a SendEvent request */
     Display       *display;    /* Display the event was read from */
     Window        window;
     int           width, height;
} XResizeRequestEvent;
</pre><p>
</p><p>


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.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Colormap_State_Change_Events"></a>Colormap State Change Events</h2></div></div></div><p>

<a id="idp49066836" class="indexterm"></a>
<a id="idp49067340" class="indexterm"></a>
The X server can report
<span class="symbol">ColormapNotify</span>
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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Changes the colormap member of the
<span class="structname">XSetWindowAttributes</span>
structure by 
calling
<a class="xref" href="#XChangeWindowAttributes"><code class="function">XChangeWindowAttributes</code></a>,
<a class="xref" href="#XFreeColormap"><code class="function">XFreeColormap</code></a>,
or
<a class="xref" href="#XSetWindowColormap"><code class="function">XSetWindowColormap</code></a>
    </p></li><li class="listitem"><p>
Installs or uninstalls the colormap by calling
<a class="xref" href="#XInstallColormap"><code class="function">XInstallColormap</code></a>
or
<a class="xref" href="#XUninstallColormap"><code class="function">XUninstallColormap</code></a>
    </p></li></ul></div><p>

To receive 
<span class="symbol">ColormapNotify</span>
events, set the
<span class="symbol">ColormapChangeMask</span>
bit in the event-mask attribute of the window. 
</p><p>

The structure for this event type contains:
</p><p>

<a id="idp49072660" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;       /* ColormapNotify */
     unsigned long serial;     /* # of last request processed by server */
     Bool          send_event; /* true if this came from a SendEvent request */
     Display       *display;   /* Display the event was read from */
     Window        window;
     Colormap      colormap;   /* colormap or None */
     Bool          new;
     int           state;      /* ColormapInstalled, ColormapUninstalled */
} XColormapEvent;
</pre><p>
</p><p>


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
<a class="xref" href="#XFreeColormap"><code class="function">XFreeColormap</code></a>,
the colormap member is set to
<span class="symbol">None</span>.
The new member is set to indicate whether the colormap 
for the specified window was changed or installed or uninstalled
and can be 
<span class="symbol">True</span>
or
<span class="symbol">False</span>.
If it is
<span class="symbol">True</span>,
the colormap was changed.
If it is
<span class="symbol">False</span>,
the colormap was installed or uninstalled.
The state member is always set to indicate whether the colormap is installed or
uninstalled and can be 
<span class="symbol">ColormapInstalled</span>
or
<span class="symbol">ColormapUninstalled</span>.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Client_Communication_Events"></a>Client Communication Events</h2></div></div></div><p>

This section discusses:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<span class="symbol">ClientMessage</span>
events
    </p></li><li class="listitem"><p>
<span class="symbol">PropertyNotify</span>
events
    </p></li><li class="listitem"><p>
<span class="symbol">SelectionClear</span>
events
    </p></li><li class="listitem"><p>
<span class="symbol">SelectionNotify</span>
events
    </p></li><li class="listitem"><p>
<span class="symbol">SelectionRequest</span>
events
    </p></li></ul></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="ClientMessage_Events"></a>ClientMessage Events</h3></div></div></div><p>

<a id="idp49082660" class="indexterm"></a>
<a id="idp49083164" class="indexterm"></a>
The X server generates
<span class="symbol">ClientMessage</span>
events only when a client calls the function
<a class="xref" href="#XSendEvent"><code class="function">XSendEvent</code></a>.
</p><p>

The structure for this event type contains:
</p><p>

<a id="idp49084852" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;           /* ClientMessage */
     unsigned long serial;         /* # of last request processed by server */
     Bool          send_event;     /* true if this came from a SendEvent request */
     Display       *display;       /* Display the event was read from */
     Window        window;
     Atom          message_type;
     int           format;
     union         {
                     char  b[20];
                     short s[10];
                     long  l[5];
                   } data;
} XClientMessageEvent;
</pre><p>
</p><p>


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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="PropertyNotify_Events"></a>PropertyNotify Events</h3></div></div></div><p>

<a id="idp49088868" class="indexterm"></a>
<a id="idp49089372" class="indexterm"></a>
The X server can report
<span class="symbol">PropertyNotify</span>
events to clients wanting information about property changes 
for a specified window.
</p><p>

To receive
<span class="symbol">PropertyNotify</span>
events, set the
<span class="symbol">PropertyChangeMask</span>
bit in the event-mask attribute of the window. 
</p><p>

The structure for this event type contains:
</p><p>

<a id="idp49091492" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;       /* PropertyNotify */
     unsigned long serial;     /* # of last request processed by server */
     Bool          send_event; /* true if this came from a SendEvent request */
     Display       *display;   /* Display the event was read from */
     Window        window;
     Atom atom;
     Time time;
     int state;                /* PropertyNewValue or PropertyDelete */
} XPropertyEvent;
</pre><p>
</p><p>


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
<span class="symbol">PropertyNewValue</span>
or
<span class="symbol">PropertyDelete</span>.
The state member is set to
<span class="symbol">PropertyNewValue</span>
when a property of the window is changed using
<a class="xref" href="#XChangeProperty"><code class="function">XChangeProperty</code></a>
or
<a class="xref" href="#XRotateWindowProperties"><code class="function">XRotateWindowProperties</code></a>
(even when adding zero-length data using
<a class="xref" href="#XChangeProperty"><code class="function">XChangeProperty</code></a>)
and when replacing all or part of a property with identical data using
<a class="xref" href="#XChangeProperty"><code class="function">XChangeProperty</code></a>
or 
<a class="xref" href="#XRotateWindowProperties"><code class="function">XRotateWindowProperties</code></a>.
The state member is set to
<span class="symbol">PropertyDelete</span>
when a property of the window is deleted using
<a class="xref" href="#XDeleteProperty"><code class="function">XDeleteProperty</code></a>
or, if the delete argument is 
<span class="symbol">True</span>,
<a class="xref" href="#XGetWindowProperty"><code class="function">XGetWindowProperty</code></a>.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="SelectionClear_Events"></a>SelectionClear Events</h3></div></div></div><p>

<a id="idp49099052" class="indexterm"></a>
<a id="idp49099556" class="indexterm"></a>
The X server reports
<span class="symbol">SelectionClear</span>
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
<a class="xref" href="#XSetSelectionOwner"><code class="function">XSetSelectionOwner</code></a>.
</p><p>

The structure for this event type contains:
</p><p>

<a id="idp49101356" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;       /* SelectionClear */
     unsigned long serial;     /* # of last request processed by server */
     Bool          send_event; /* true if this came from a SendEvent request */
     Display       *display;   /* Display the event was read from */
     Window        window;
     Atom          selection;
     Time          time;
} XSelectionClearEvent;
</pre><p>
</p><p>


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
<a class="xref" href="#XSetSelectionOwner"><code class="function">XSetSelectionOwner</code></a>
call.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="SelectionRequest_Events"></a>SelectionRequest Events</h3></div></div></div><p>

<a id="idp49105268" class="indexterm"></a>
<a id="idp49105772" class="indexterm"></a>
The X server reports
<span class="symbol">SelectionRequest</span>
events to the owner of a selection.
The X server generates this event whenever a client 
requests a selection conversion by calling 
<a class="xref" href="#XConvertSelection"><code class="function">XConvertSelection</code></a>
for the owned selection.
</p><p>

The structure for this event type contains:
</p><p>

<a id="idp49107548" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;       /* SelectionRequest */
     unsigned long serial;     /* # of last request processed by server */
     Bool          send_event; /* true if this came from a SendEvent request */
     Display       *display;   /* Display the event was read from */
     Window        owner;
     Window        requestor;
     Atom          selection;
     Atom          target;
     Atom          property;
     Time          time;
} XSelectionRequestEvent;
</pre><p>
</p><p>


The owner member is set to the window
that was specified by the current owner in its
<a class="xref" href="#XSetSelectionOwner"><code class="function">XSetSelectionOwner</code></a>
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 
<span class="symbol">None</span>.
The time member is set to the timestamp or 
<span class="symbol">CurrentTime</span>
value from the
<code class="systemitem">ConvertSelection</code>
request.
</p><p>

The owner should convert the selection based on the specified target type
and send a
<span class="symbol">SelectionNotify</span>
event back to the requestor.
A <span class="olink">complete
specification for using selections</span> is given in the X Consortium
standard <em class="citetitle">Inter-Client Communication Conventions Manual</em>.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="SelectionNotify_Events"></a>SelectionNotify Events</h3></div></div></div><p>

<a id="idp49113980" class="indexterm"></a>
<a id="idp49114484" class="indexterm"></a>
This event is generated by the X server in response to a
<code class="systemitem">ConvertSelection</code>
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
<a class="xref" href="#XSendEvent"><code class="function">XSendEvent</code></a>.
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
<span class="symbol">None</span>).
</p><p>

If
<span class="symbol">None</span>
is specified as the property in the 
<code class="systemitem">ConvertSelection</code>
protocol request, the owner should choose a property name,
store the result as that property on the requestor window,
and then send a 
<span class="symbol">SelectionNotify</span>
giving that actual property name.
</p><p>

The structure for this event type contains:
</p><p>

<a id="idp49118132" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int           type;       /* SelectionNotify */
     unsigned long serial;     /* # of last request processed by server */
     Bool          send_event; /* true if this came from a SendEvent request */
     Display       *display;   /* Display the event was read from */
     Window        requestor;
     Atom          selection;
     Atom          target;
     Atom          property;   /* atom or None */
     Time          time;
} XSelectionEvent;
</pre><p>
</p><p>


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
<span class="symbol">None</span>.
The time member is set to the time the conversion took place and
can be a timestamp or
<span class="symbol">CurrentTime</span>.



</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Event_Handling_Functions"></a>Chapter 11. Event Handling Functions</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Selecting_Events">Selecting Events</a></span></dt><dt><span class="sect1"><a href="#Handling_the_Output_Buffer">Handling the Output Buffer</a></span></dt><dt><span class="sect1"><a href="#Event_Queue_Management">Event Queue Management</a></span></dt><dt><span class="sect1"><a href="#Manipulating_the_Event_Queue">Manipulating the Event Queue</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Returning_the_Next_Event">Returning the Next Event</a></span></dt><dt><span class="sect2"><a href="#Selecting_Events_Using_a_Predicate_Procedure">Selecting Events Using a Predicate Procedure</a></span></dt><dt><span class="sect2"><a href="#Selecting_Events_Using_a_Window_or_Event_Mask">Selecting Events Using a Window or Event Mask</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Putting_an_Event_Back_into_the_Queue">Putting an Event Back into the Queue</a></span></dt><dt><span class="sect1"><a href="#Sending_Events_to_Other_Applications">Sending Events to Other Applications</a></span></dt><dt><span class="sect1"><a href="#Getting_Pointer_Motion_History">Getting Pointer Motion History</a></span></dt><dt><span class="sect1"><a href="#Handling_Protocol_Errors">Handling Protocol Errors</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Enabling_or_Disabling_Synchronization">Enabling or Disabling Synchronization</a></span></dt><dt><span class="sect2"><a href="#Using_the_Default_Error_Handlers">Using the Default Error Handlers</a></span></dt></dl></dd></dl></div><p>
This chapter discusses the Xlib functions you can use to:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Select events</p></li><li class="listitem"><p>Handle the output buffer and the event queue</p></li><li class="listitem"><p>Select events from the event queue</p></li><li class="listitem"><p>Send and get events</p></li><li class="listitem"><p>Handle protocol errors</p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
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.
</p></div><p>
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.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Selecting_Events"></a>Selecting Events</h2></div></div></div><p>

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
<span class="structname">XSetWindowAttributes</span>
structure when you call
<a class="xref" href="#XCreateWindow"><code class="function">XCreateWindow</code></a>
and
<a class="xref" href="#XChangeWindowAttributes"><code class="function">XChangeWindowAttributes</code></a>.
Another way is to use
<a class="xref" href="#XSelectInput"><code class="function">XSelectInput</code></a>.
</p><a id="idp43016108" class="indexterm"></a><div class="funcsynopsis"><a id="XSelectInput"></a><p><code class="funcdef"><strong class="fsfunc">XSelectInput</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, long<var class="pdparam"> event_mask</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window whose events you are interested in.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_mask</em></span>
    </span></p></td><td><p>
Specifies the event mask.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSelectInput"><code class="function">XSelectInput</code></a>
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.
<a id="idp47246004" class="indexterm"></a>
</p><p>

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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
Only one client at a time can select
<span class="symbol">CirculateRequest</span>,
<span class="symbol">ConfigureRequest</span>,
or
<span class="symbol">MapRequest</span>
events, which are associated with
the event mask
<span class="symbol">SubstructureRedirectMask</span>.
    </p></li><li class="listitem"><p>
Only one client at a time can select
a
<span class="symbol">ResizeRequest</span>
event, which is associated with
the event mask
<span class="symbol">ResizeRedirectMask</span>.
    </p></li><li class="listitem"><p>
Only one client at a time can select a 
<span class="symbol">ButtonPress</span>
event, which is associated with
the event mask
<span class="symbol">ButtonPressMask</span>.
    </p></li></ul></div><p>

The server reports the event to all interested clients.
</p><p>

<a class="xref" href="#XSelectInput"><code class="function">XSelectInput</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Handling_the_Output_Buffer"></a>Handling the Output Buffer</h2></div></div></div><p>

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.
</p><p>


To flush the output buffer, use 
<a class="xref" href="#XFlush"><code class="function">XFlush</code></a>.
</p><a id="idp47613420" class="indexterm"></a><div class="funcsynopsis"><a id="XFlush"></a><p><code class="funcdef"><strong class="fsfunc">XFlush</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFlush"><code class="function">XFlush</code></a>
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
<a class="xref" href="#XPending"><code class="function">XPending</code></a>,
<a class="xref" href="#XNextEvent"><code class="function">XNextEvent</code></a>,
and
<a class="xref" href="#XWindowEvent"><code class="function">XWindowEvent</code></a>.
<a id="idp47549516" class="indexterm"></a>
<a id="idp47549940" class="indexterm"></a>
<a id="idp47550364" class="indexterm"></a>
Events generated by the server may be enqueued into the library's event queue.
</p><p>


To flush the output buffer and then wait until all requests have been processed,
use 
<a class="xref" href="#XSync"><code class="function">XSync</code></a>.
</p><a id="idp47551996" class="indexterm"></a><div class="funcsynopsis"><a id="XSync"></a><p><code class="funcdef"><strong class="fsfunc">XSync</strong>(</code>Display<var class="pdparam"> *display</var>, Bool<var class="pdparam"> discard</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>discard</em></span>
    </span></p></td><td><p>
Specifies a Boolean value that indicates whether 
<a class="xref" href="#XSync"><code class="function">XSync</code></a>
discards all events on the event queue.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSync"><code class="function">XSync</code></a>
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,
<a class="xref" href="#XSync"><code class="function">XSync</code></a>
calls the client application's error handling routine
(see <a class="link" href="#Using_the_Default_Error_Handlers" title="Using the Default Error Handlers">section 11.8.2</a>).
Any events generated by the server are enqueued into the library's 
event queue.
</p><p>

Finally, if you passed 
<span class="symbol">False</span>,
<a class="xref" href="#XSync"><code class="function">XSync</code></a>
does not discard the events in the queue.
If you passed 
<span class="symbol">True</span>,
<a class="xref" href="#XSync"><code class="function">XSync</code></a>
discards all events in the queue,
including those events that were on the queue before
<a class="xref" href="#XSync"><code class="function">XSync</code></a>
was called.
Client applications seldom need to call
<a class="xref" href="#XSync"><code class="function">XSync</code></a>.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Event_Queue_Management"></a>Event Queue Management</h2></div></div></div><p>

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.
</p><p>


To check the number of events in the event queue, use
<a class="xref" href="#XEventsQueued"><code class="function">XEventsQueued</code></a>.
</p><a id="idp47527700" class="indexterm"></a><div class="funcsynopsis"><a id="XEventsQueued"></a><p><code class="funcdef">int <strong class="fsfunc">XEventsQueued</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> mode</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>mode</em></span>
    </span></p></td><td><p>
Specifies the mode.
You can pass
<span class="symbol">QueuedAlready</span>,
<span class="symbol">QueuedAfterFlush</span>,
or
<span class="symbol">QueuedAfterReading</span>.
    </p></td></tr></tbody></table></div><p>


If mode is 
<span class="symbol">QueuedAlready</span>,
<a class="xref" href="#XEventsQueued"><code class="function">XEventsQueued</code></a>
returns the number of events
already in the event queue (and never performs a system call).
If mode is 
<span class="symbol">QueuedAfterFlush</span>,
<a class="xref" href="#XEventsQueued"><code class="function">XEventsQueued</code></a>
returns the number of events already in the queue if the number is nonzero.
If there are no events in the queue, 
<a class="xref" href="#XEventsQueued"><code class="function">XEventsQueued</code></a>
flushes the output buffer, 
attempts to read more events out of the application's connection,
and returns the number read.
If mode is 
<span class="symbol">QueuedAfterReading</span>,
<a class="xref" href="#XEventsQueued"><code class="function">XEventsQueued</code></a>
returns the number of events already in the queue if the number is nonzero. 
If there are no events in the queue, 
<a class="xref" href="#XEventsQueued"><code class="function">XEventsQueued</code></a>
attempts to read more events out of the application's connection 
without flushing the output buffer and returns the number read.
</p><p>

<a class="xref" href="#XEventsQueued"><code class="function">XEventsQueued</code></a>
always returns immediately without I/O if there are events already in the
queue.
<a class="xref" href="#XEventsQueued"><code class="function">XEventsQueued</code></a>
with mode 
<span class="symbol">QueuedAfterFlush</span>
is identical in behavior to
<a class="xref" href="#XPending"><code class="function">XPending</code></a>.
<a class="xref" href="#XEventsQueued"><code class="function">XEventsQueued</code></a>
with mode
<span class="symbol">QueuedAlready</span>
is identical to the
<a class="xref" href="#XQLength"><code class="function">XQLength</code></a>
function.
</p><p>


To return the number of events that are pending, use 
<a class="xref" href="#XPending"><code class="function">XPending</code></a>.
</p><a id="idp45441508" class="indexterm"></a><div class="funcsynopsis"><a id="XPending"></a><p><code class="funcdef">int <strong class="fsfunc">XPending</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XPending"><code class="function">XPending</code></a>
function returns the number of events that have been received from the
X server but have not been removed from the event queue.
<a class="xref" href="#XPending"><code class="function">XPending</code></a>
is identical to
<a class="xref" href="#XEventsQueued"><code class="function">XEventsQueued</code></a>
with the mode
<span class="symbol">QueuedAfterFlush</span>
specified.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Manipulating_the_Event_Queue"></a>Manipulating the Event Queue</h2></div></div></div><p>

Xlib provides functions that let you manipulate the event queue.
This section discusses how to:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Obtain events, in order, and remove them from the queue
    </p></li><li class="listitem"><p>
Peek at events in the queue without removing them
    </p></li><li class="listitem"><p>
Obtain events that match the event mask or the arbitrary
predicate procedures that you provide
    </p></li></ul></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Returning_the_Next_Event"></a>Returning the Next Event</h3></div></div></div><p>

To get the next event and remove it from the queue, use
<a class="xref" href="#XNextEvent"><code class="function">XNextEvent</code></a>.
</p><a id="idp45452628" class="indexterm"></a><div class="funcsynopsis"><a id="XNextEvent"></a><p><code class="funcdef"><strong class="fsfunc">XNextEvent</strong>(</code>Display<var class="pdparam"> *display</var>, XEvent<var class="pdparam"> *event_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_return</em></span>
    </span></p></td><td><p>
Returns the next event in the queue.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XNextEvent"><code class="function">XNextEvent</code></a>
function copies the first event from the event queue into the specified
<span class="structname">XEvent</span>
structure and then removes it from the queue.
If the event queue is empty,
<a class="xref" href="#XNextEvent"><code class="function">XNextEvent</code></a>
flushes the output buffer and blocks until an event is received.
</p><p>


To peek at the event queue, use
<a class="xref" href="#XPeekEvent"><code class="function">XPeekEvent</code></a>.
</p><a id="idp45460940" class="indexterm"></a><div class="funcsynopsis"><a id="XPeekEvent"></a><p><code class="funcdef"><strong class="fsfunc">XPeekEvent</strong>(</code>Display<var class="pdparam"> *display</var>, XEvent<var class="pdparam"> *event_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_return</em></span>
    </span></p></td><td><p>
Returns a copy of the matched event's associated structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XPeekEvent"><code class="function">XPeekEvent</code></a>
function returns the first event from the event queue,
but it does not remove the event from the queue.
If the queue is empty,
<a class="xref" href="#XPeekEvent"><code class="function">XPeekEvent</code></a>
flushes the output buffer and blocks until an event is received.
It then copies the event into the client-supplied
<span class="structname">XEvent</span>
structure without removing it from the event queue.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Selecting_Events_Using_a_Predicate_Procedure"></a>Selecting Events Using a Predicate Procedure</h3></div></div></div><p>

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
<code class="function">XLockDisplay</code>.
</p><p>

The predicate procedure and its associated arguments are:
</p><div class="funcsynopsis"><p><code class="funcdef">Bool(</code>Display<var class="pdparam"> *display</var>, XEvent<var class="pdparam"> *event</var>, XPointer<var class="pdparam"> arg</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event</em></span>
    </span></p></td><td><p>
Specifies the
<span class="structname">XEvent</span>
structure.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>arg</em></span>
    </span></p></td><td><p>
Specifies the argument passed in from the 
<a class="xref" href="#XIfEvent"><code class="function">XIfEvent</code></a>,
<a class="xref" href="#XCheckIfEvent"><code class="function">XCheckIfEvent</code></a>,
or
<a class="xref" href="#XPeekIfEvent"><code class="function">XPeekIfEvent</code></a>
function.
    </p></td></tr></tbody></table></div><p>


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 
<span class="symbol">True</span>.
If it did not find a match, it must return
<span class="symbol">False</span>.
</p><p>


To check the event queue for a matching event
and, if found, remove the event from the queue, use
<a class="xref" href="#XIfEvent"><code class="function">XIfEvent</code></a>.
</p><a id="idp47215316" class="indexterm"></a><div class="funcsynopsis"><a id="XIfEvent"></a><p><code class="funcdef"><strong class="fsfunc">XIfEvent</strong>(</code>Display<var class="pdparam"> *display</var>, XEvent<var class="pdparam"> *event_return</var>, Bool<var class="pdparam"> (*predicate)()</var>, XPointer<var class="pdparam"> arg</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_return</em></span>
    </span></p></td><td><p>
Returns the matched event's associated structure.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>predicate</em></span>
    </span></p></td><td><p>
Specifies the procedure that is to be called to determine
if the next event in the queue matches what you want.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>arg</em></span>
    </span></p></td><td><p>
Specifies the user-supplied argument that will be passed to the predicate procedure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XIfEvent"><code class="function">XIfEvent</code></a>
function completes only when the specified predicate
procedure returns 
<span class="symbol">True</span>
for an event, 
which indicates an event in the queue matches.
<a class="xref" href="#XIfEvent"><code class="function">XIfEvent</code></a>
flushes the output buffer if it blocks waiting for additional events.
<a class="xref" href="#XIfEvent"><code class="function">XIfEvent</code></a>
removes the matching event from the queue 
and copies the structure into the client-supplied
<span class="structname">XEvent</span>
structure.
</p><p>


To check the event queue for a matching event without blocking, use
<a class="xref" href="#XCheckIfEvent"><code class="function">XCheckIfEvent</code></a>.
</p><a id="idp47459756" class="indexterm"></a><div class="funcsynopsis"><a id="XCheckIfEvent"></a><p><code class="funcdef">Bool <strong class="fsfunc">XCheckIfEvent</strong>(</code>Display<var class="pdparam"> *display</var>, XEvent<var class="pdparam"> *event_return</var>, Bool<var class="pdparam"> (*predicate)()</var>, XPointer<var class="pdparam"> arg</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_return</em></span>
    </span></p></td><td><p>
Returns a copy of the matched event's associated structure.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>predicate</em></span>
    </span></p></td><td><p>
Specifies the procedure that is to be called to determine
if the next event in the queue matches what you want.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>arg</em></span>
    </span></p></td><td><p>
Specifies the user-supplied argument that will be passed to the predicate procedure.
    </p></td></tr></tbody></table></div><p>


When the predicate procedure finds a match,
<a class="xref" href="#XCheckIfEvent"><code class="function">XCheckIfEvent</code></a>
copies the matched event into the client-supplied
<span class="structname">XEvent</span>
structure and returns 
<span class="symbol">True</span>.
(This event is removed from the queue.)
If the predicate procedure finds no match,
<a class="xref" href="#XCheckIfEvent"><code class="function">XCheckIfEvent</code></a>
returns
<span class="symbol">False</span>,
and the output buffer will have been flushed.
All earlier events stored in the queue are not discarded.
</p><p>


To check the event queue for a matching event
without removing the event from the queue, use
<a class="xref" href="#XPeekIfEvent"><code class="function">XPeekIfEvent</code></a>.
</p><a id="idp47472596" class="indexterm"></a><div class="funcsynopsis"><a id="XPeekIfEvent"></a><p><code class="funcdef"><strong class="fsfunc">XPeekIfEvent</strong>(</code>Display<var class="pdparam"> *display</var>, XEvent<var class="pdparam"> *event_return</var>, Bool<var class="pdparam"> (*predicate)()</var>, XPointer<var class="pdparam"> arg</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_return</em></span>
    </span></p></td><td><p>
Returns a copy of the matched event's associated structure.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>predicate</em></span>
    </span></p></td><td><p>
Specifies the procedure that is to be called to determine
if the next event in the queue matches what you want.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>arg</em></span>
    </span></p></td><td><p>
Specifies the user-supplied argument that will be passed to the predicate procedure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XPeekIfEvent"><code class="function">XPeekIfEvent</code></a>
function returns only when the specified predicate
procedure returns 
<span class="symbol">True</span>
for an event.
After the predicate procedure finds a match,
<a class="xref" href="#XPeekIfEvent"><code class="function">XPeekIfEvent</code></a>
copies the matched event into the client-supplied
<span class="structname">XEvent</span>
structure without removing the event from the queue.
<a class="xref" href="#XPeekIfEvent"><code class="function">XPeekIfEvent</code></a>
flushes the output buffer if it blocks waiting for additional events.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Selecting_Events_Using_a_Window_or_Event_Mask"></a>Selecting Events Using a Window or Event Mask</h3></div></div></div><p>

The functions discussed in this section let you select events by window 
or event types, allowing you to process events out of order.
</p><p>


To remove the next event that matches both a window and an event mask, use
<a class="xref" href="#XWindowEvent"><code class="function">XWindowEvent</code></a>.
</p><a id="idp47386556" class="indexterm"></a><div class="funcsynopsis"><a id="XWindowEvent"></a><p><code class="funcdef"><strong class="fsfunc">XWindowEvent</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, long<var class="pdparam"> event_mask</var>, XEvent<var class="pdparam"> *event_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window whose events you are interested in.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_mask</em></span>
    </span></p></td><td><p>
Specifies the event mask.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_return</em></span>
    </span></p></td><td><p>
Returns the matched event's associated structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XWindowEvent"><code class="function">XWindowEvent</code></a>
function searches the event queue for an event that matches both the specified
window and event mask.
When it finds a match,
<a class="xref" href="#XWindowEvent"><code class="function">XWindowEvent</code></a>
removes that event from the queue and copies it into the specified
<span class="structname">XEvent</span>
structure.
The other events stored in the queue are not discarded.
If a matching event is not in the queue,
<a class="xref" href="#XWindowEvent"><code class="function">XWindowEvent</code></a>
flushes the output buffer and blocks until one is received.
</p><p>


To remove the next event that matches both a window and an event mask (if any),
use
<a class="xref" href="#XCheckWindowEvent"><code class="function">XCheckWindowEvent</code></a>.
<a id="idp47399148" class="indexterm"></a>
This function is similar to
<a class="xref" href="#XWindowEvent"><code class="function">XWindowEvent</code></a>
except that it never blocks and it returns a 
<span class="type">Bool</span>
indicating if the event was returned.
</p><a id="idp47400324" class="indexterm"></a><div class="funcsynopsis"><a id="XCheckWindowEvent"></a><p><code class="funcdef">Bool <strong class="fsfunc">XCheckWindowEvent</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, long<var class="pdparam"> event_mask</var>, XEvent<var class="pdparam"> *event_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window whose events you are interested in.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_mask</em></span>
    </span></p></td><td><p>
Specifies the event mask.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_return</em></span>
    </span></p></td><td><p>
Returns the matched event's associated structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCheckWindowEvent"><code class="function">XCheckWindowEvent</code></a>
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,
<a class="xref" href="#XCheckWindowEvent"><code class="function">XCheckWindowEvent</code></a>
removes that event, copies it into the specified
<span class="structname">XEvent</span>
structure, and returns
<span class="symbol">True</span>.
The other events stored in the queue are not discarded.
If the event you requested is not available,
<a class="xref" href="#XCheckWindowEvent"><code class="function">XCheckWindowEvent</code></a>
returns
<span class="symbol">False</span>,
and the output buffer will have been flushed.
</p><p>


To remove the next event that matches an event mask, use
<a class="xref" href="#XMaskEvent"><code class="function">XMaskEvent</code></a>.
</p><a id="idp47413476" class="indexterm"></a><div class="funcsynopsis"><a id="XMaskEvent"></a><p><code class="funcdef"><strong class="fsfunc">XMaskEvent</strong>(</code>Display<var class="pdparam"> *display</var>, long<var class="pdparam"> event_mask</var>, XEvent<var class="pdparam"> *event_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_mask</em></span>
    </span></p></td><td><p>
Specifies the event mask.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_return</em></span>
    </span></p></td><td><p>
Returns the matched event's associated structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XMaskEvent"><code class="function">XMaskEvent</code></a>
function searches the event queue for the events associated with the 
specified mask.
When it finds a match,
<a class="xref" href="#XMaskEvent"><code class="function">XMaskEvent</code></a>
removes that event and copies it into the specified
<span class="structname">XEvent</span>
structure.
The other events stored in the queue are not discarded.
If the event you requested is not in the queue,
<a class="xref" href="#XMaskEvent"><code class="function">XMaskEvent</code></a>
flushes the output buffer and blocks until one is received.
</p><p>


To return and remove the next event that matches an event mask (if any), use
<a class="xref" href="#XCheckMaskEvent"><code class="function">XCheckMaskEvent</code></a>.
This function is similar to 
<a class="xref" href="#XMaskEvent"><code class="function">XMaskEvent</code></a>
except that it never blocks and it returns a 
<span class="type">Bool</span>
indicating if the event was returned.
</p><a id="idp47424900" class="indexterm"></a><div class="funcsynopsis"><a id="XCheckMaskEvent"></a><p><code class="funcdef">Bool <strong class="fsfunc">XCheckMaskEvent</strong>(</code>Display<var class="pdparam"> *display</var>, long<var class="pdparam"> event_mask</var>, XEvent<var class="pdparam"> *event_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_mask</em></span>
    </span></p></td><td><p>
Specifies the event mask.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_return</em></span>
    </span></p></td><td><p>
Returns the matched event's associated structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCheckMaskEvent"><code class="function">XCheckMaskEvent</code></a>
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,
<a class="xref" href="#XCheckMaskEvent"><code class="function">XCheckMaskEvent</code></a>
removes that event, copies it into the specified
<span class="structname">XEvent</span>
structure, and returns
<span class="symbol">True</span>.
The other events stored in the queue are not discarded.
If the event you requested is not available,
<a class="xref" href="#XCheckMaskEvent"><code class="function">XCheckMaskEvent</code></a>
returns
<span class="symbol">False</span>,
and the output buffer will have been flushed.
</p><p>


To return and remove the next event in the queue that matches an event type, use
<a class="xref" href="#XCheckTypedEvent"><code class="function">XCheckTypedEvent</code></a>.
</p><a id="idp47436252" class="indexterm"></a><div class="funcsynopsis"><a id="XCheckTypedEvent"></a><p><code class="funcdef">Bool <strong class="fsfunc">XCheckTypedEvent</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> event_type</var>, XEvent<var class="pdparam"> *event_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_type</em></span>
    </span></p></td><td><p>
Specifies the event type to be compared.

      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_return</em></span>
    </span></p></td><td><p>
Returns the matched event's associated structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCheckTypedEvent"><code class="function">XCheckTypedEvent</code></a>
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,
<a class="xref" href="#XCheckTypedEvent"><code class="function">XCheckTypedEvent</code></a>
removes that event, copies it into the specified
<span class="structname">XEvent</span>
structure, and returns
<span class="symbol">True</span>.
The other events in the queue are not discarded.
If the event is not available,
<a class="xref" href="#XCheckTypedEvent"><code class="function">XCheckTypedEvent</code></a>
returns
<span class="symbol">False</span>,
and the output buffer will have been flushed.
</p><p>


To return and remove the next event in the queue that matches an event type 
and a window, use
<a class="xref" href="#XCheckTypedWindowEvent"><code class="function">XCheckTypedWindowEvent</code></a>.
</p><a id="idp47447628" class="indexterm"></a><div class="funcsynopsis"><a id="XCheckTypedWindowEvent"></a><p><code class="funcdef">Bool <strong class="fsfunc">XCheckTypedWindowEvent</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, int<var class="pdparam"> event_type</var>, XEvent<var class="pdparam"> *event_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_type</em></span>
    </span></p></td><td><p>
Specifies the event type to be compared.

      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_return</em></span>
    </span></p></td><td><p>
Returns the matched event's associated structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCheckTypedWindowEvent"><code class="function">XCheckTypedWindowEvent</code></a>
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,
<a class="xref" href="#XCheckTypedWindowEvent"><code class="function">XCheckTypedWindowEvent</code></a>
removes the event from the queue, copies it into the specified
<span class="structname">XEvent</span>
structure, and returns
<span class="symbol">True</span>.
The other events in the queue are not discarded.
If the event is not available,
<a class="xref" href="#XCheckTypedWindowEvent"><code class="function">XCheckTypedWindowEvent</code></a>
returns
<span class="symbol">False</span>,
and the output buffer will have been flushed.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Putting_an_Event_Back_into_the_Queue"></a>Putting an Event Back into the Queue</h2></div></div></div><p>

To push an event back into the event queue, use
<a class="xref" href="#XPutBackEvent"><code class="function">XPutBackEvent</code></a>.
</p><a id="idp48359516" class="indexterm"></a><div class="funcsynopsis"><a id="XPutBackEvent"></a><p><code class="funcdef"><strong class="fsfunc">XPutBackEvent</strong>(</code>Display<var class="pdparam"> *display</var>, XEvent<var class="pdparam"> *event</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event</em></span>
    </span></p></td><td><p>
Specifies the event.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XPutBackEvent"><code class="function">XPutBackEvent</code></a>
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
<a class="xref" href="#XPutBackEvent"><code class="function">XPutBackEvent</code></a>.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Sending_Events_to_Other_Applications"></a>Sending Events to Other Applications</h2></div></div></div><p>

To send an event to a specified window, use
<a class="xref" href="#XSendEvent"><code class="function">XSendEvent</code></a>.
<a id="idp48368548" class="indexterm"></a>
This function is often used in selection processing.
For example, the owner of a selection should use
<a class="xref" href="#XSendEvent"><code class="function">XSendEvent</code></a>
to send a
<span class="symbol">SelectionNotify</span>
event to a requestor when a selection has been converted 
and stored as a property.
</p><a id="idp48369884" class="indexterm"></a><div class="funcsynopsis"><a id="XSendEvent"></a><p><code class="funcdef">Status <strong class="fsfunc">XSendEvent</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, Bool<var class="pdparam"> propagate</var>, long<var class="pdparam"> event_mask</var>, XEvent<var class="pdparam"> *event_send</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window the event is to be sent to, or
<span class="symbol">PointerWindow</span>,
or
<span class="symbol">InputFocus</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>propagate</em></span>
    </span></p></td><td><p>
Specifies a Boolean value.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_mask</em></span>
    </span></p></td><td><p>
Specifies the event mask.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_send</em></span>
    </span></p></td><td><p>
Specifies the event that is to be sent.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSendEvent"><code class="function">XSendEvent</code></a>
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 <a class="link" href="#Event_Masks" title="Event Masks">section 10.3</a>.
This function uses the w argument to identify the destination window as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If w is
<span class="symbol">PointerWindow</span>,
the destination window is the window that contains the pointer.
    </p></li><li class="listitem"><p>
If w is
<span class="symbol">InputFocus</span>
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.
    </p></li></ul></div><p>

To determine which clients should receive the specified events,
<a class="xref" href="#XSendEvent"><code class="function">XSendEvent</code></a>
uses the propagate argument as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
If propagate is 
<span class="symbol">False</span>,
the event is sent to every client selecting on destination any of the event
types in the event_mask argument.
    </p></li><li class="listitem"><p>
If propagate is 
<span class="symbol">True</span>
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 
<span class="symbol">InputFocus</span>
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.
    </p></li></ul></div><p>

The event in the
<span class="structname">XEvent</span>
structure must be one of the core events or one of the events
defined by an extension (or a 
<span class="errorname">BadValue</span>
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
<span class="symbol">True</span>
in the forwarded event and to set the serial number in the event correctly;
therefore these fields
and the display field are ignored by
<a class="xref" href="#XSendEvent"><code class="function">XSendEvent</code></a>.
</p><p>

<a class="xref" href="#XSendEvent"><code class="function">XSendEvent</code></a>
returns zero if the conversion to wire protocol format failed
and returns nonzero otherwise.
</p><p>

<a class="xref" href="#XSendEvent"><code class="function">XSendEvent</code></a>
can generate
<span class="errorname">BadValue</span>
and 
<span class="errorname">BadWindow</span>
errors.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Getting_Pointer_Motion_History"></a>Getting Pointer Motion History</h2></div></div></div><p>

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.
</p><p>


To determine the approximate maximum number of elements in the motion buffer, 
use
<code class="function">XDisplayMotionBufferSize</code>.
</p><a id="idp48395692" class="indexterm"></a><div class="funcsynopsis"><a id="XGetMotionEvents"></a><p><code class="funcdef">unsigned long(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


The server may retain the recent history of the pointer motion
and do so to a finer granularity than is reported by
<span class="symbol">MotionNotify</span>
events.
The
<a class="xref" href="#XGetMotionEvents"></a>
function makes this history available.
</p><p>


To get the motion history for a specified window and time, use
<a class="xref" href="#XGetMotionEvents"></a>.
</p><a id="idp48401820" class="indexterm"></a><div class="funcsynopsis"><a id="xgetmotionevents"></a><p><code class="funcdef">XTimeCoord *<strong class="fsfunc">XGetMotionEvents</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, Timestart,<var class="pdparam"> stop</var>, int<var class="pdparam"> *nevents_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>start</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>stop</em></span>
    </span></p></td><td><p>
Specify the time interval in which the events are returned from the motion
history buffer.
You can pass a timestamp or
<span class="symbol">CurrentTime</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nevents_return</em></span>
    </span></p></td><td><p>
Returns the number of events from the motion history buffer.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetMotionEvents"></a>
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;
<a class="xref" href="#XGetMotionEvents"></a>
returns NULL.
If the stop time is in the future, it is equivalent to specifying
<span class="symbol">CurrentTime</span>.
The return type for this function is a structure defined as follows:
</p><p>

<a id="idp48415436" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
	Time time;
	short x, y;
} XTimeCoord;
</pre><p>
</p><p>


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
<a class="xref" href="#XFree"></a>.
</p><p>

<a class="xref" href="#XGetMotionEvents"></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Handling_Protocol_Errors"></a>Handling Protocol Errors</h2></div></div></div><p>

Xlib provides functions that you can use to enable or disable synchronization
and to use the default error handlers.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Enabling_or_Disabling_Synchronization"></a>Enabling or Disabling Synchronization</h3></div></div></div><p>

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.
<a id="idp48422468" class="indexterm"></a>
On <acronym class="acronym">POSIX</acronym>-conformant systems,
there is also a global variable 
<code class="varname">_Xdebug</code>
that, if set to nonzero before starting a program under a debugger, will force
synchronous library behavior.
</p><p>

After completing their work,
all Xlib functions that generate protocol requests call what is known as
an after function.
<a class="xref" href="#XSetAfterFunction"></a>
sets which function is to be called.
</p><a id="idp48424532" class="indexterm"></a><div class="funcsynopsis"><a id="XSetAfterFunction"></a><p><code class="funcdef">int(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> (*procedure)()</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>procedure</em></span>
    </span></p></td><td><p>
Specifies the procedure to be called.
    </p></td></tr></tbody></table></div><p>


The specified procedure is called with only a display pointer.
<a class="xref" href="#XSetAfterFunction"></a>
returns the previous after function.
</p><p>

To enable or disable synchronization, use 
<code class="function">XSynchronize</code>.
</p><a id="idp48431868" class="indexterm"></a><a id="idp48432444" class="indexterm"></a><div class="funcsynopsis"><a id="xsynchronize"></a><p><code class="funcdef">int(</code>Display<var class="pdparam"> *display</var>, Bool<var class="pdparam"> onoff</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>onoff</em></span>
    </span></p></td><td><p>
Specifies a Boolean value that indicates whether to enable 
or disable synchronization.
    </p></td></tr></tbody></table></div><p>


The
<code class="function">XSynchronize</code>
function returns 
the previous after function.
If onoff is 
<span class="symbol">True</span>,
<code class="function">XSynchronize</code>
turns on synchronous behavior.
If onoff is
<span class="symbol">False</span>,
<code class="function">XSynchronize</code>
turns off synchronous behavior.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Using_the_Default_Error_Handlers"></a>Using the Default Error Handlers</h3></div></div></div><p>

<a id="idp48441516" class="indexterm"></a>
<a id="idp48442092" class="indexterm"></a>
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.
</p><p>


To set the error handler, use
<a class="xref" href="#XSetErrorHandler"><code class="function">XSetErrorHandler</code></a>.
</p><a id="idp48444220" class="indexterm"></a><div class="funcsynopsis"><a id="XSetErrorHandler"></a><p><code class="funcdef">int *<strong class="fsfunc">XSetErrorHandler</strong>(</code>int <var class="pdparam"> *handler</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>handler</em></span>
    </span></p></td><td><p>
Specifies the program's supplied error handler.
    </p></td></tr></tbody></table></div><p>


Xlib generally calls the program's
supplied error handler whenever an error is received.
It is not called on
<span class="errorname">BadName</span>
errors from
<code class="systemitem">OpenFont</code>,
<code class="systemitem">LookupColor</code>,
or
<code class="systemitem">AllocNamedColor</code>
protocol requests or on
<span class="errorname">BadFont</span>
errors from a
<code class="systemitem">QueryFont</code>
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.
</p><p>

The 
<span class="structname">XErrorEvent</span>
structure contains:
<a id="idp48451636" class="indexterm"></a>
</p><p>

<a id="idp48452588" class="indexterm"></a>
</p><pre class="literallayout">


typedef struct {
	int type;
	Display *display;	/* Display the event was read from */
	unsigned long serial;		/* serial number of failed request */
	unsigned char error_code;	/* error code of failed request */
	unsigned char request_code;	/* Major op-code of failed request */
	unsigned char minor_code;	/* Minor op-code of failed request */
	XID resourceid;		/* resource id */
} XErrorEvent;
</pre><p>
</p><p>

<a id="idp48454620" class="indexterm"></a>
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 
<code class="function">NextRequest</code>
immediately before the failing call was made.  
The request_code member is a protocol request
of the procedure that failed, as defined in 
<code class="filename">&lt;X11/Xproto.h&gt;</code>.
The following error codes can be returned by the functions described in this
chapter:
</p><a id="idp48456684" class="indexterm"></a><a id="idp48457260" class="indexterm"></a><a id="idp48458164" class="indexterm"></a><a id="idp48458588" class="indexterm"></a><a id="idp48459012" class="indexterm"></a><a id="idp48459436" class="indexterm"></a><a id="idp48459860" class="indexterm"></a><a id="idp48460284" class="indexterm"></a><a id="idp48460708" class="indexterm"></a><a id="idp48461132" class="indexterm"></a><a id="idp48461556" class="indexterm"></a><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Error Code</th><th align="left">Description</th></tr></thead><tbody><tr><td align="left"><span class="errorname"><a id="BadAccess"></a>BadAccess</span></td><td align="left">
      <p>A client attempts to grab a key/button combination already grabbed
      by another client.</p>
      <p>A client attempts to free a colormap entry that it had not already allocated
      or to free an entry in a colormap that was created with all entries writable.</p>
      <p>A client attempts to store into a read-only or unallocated colormap entry.</p>
      <p>A client attempts to modify the access control list from other than the local
      (or otherwise authorized) host.</p>
      <p>A client attempts to select an event type that another client
      has already selected.</p>
      </td></tr><tr><td align="left"><span class="errorname"><a id="BadAlloc"></a>BadAlloc</span></td><td align="left">The server fails to allocate the requested resource.
      Note that the explicit listing of
      <span class="errorname">BadAlloc</span>
      errors in requests only covers allocation errors at a very coarse level
      and is not intended to (nor can it in practice hope to) cover all cases of
      a server running out of allocation space in the middle of service.
      The semantics when a server runs out of allocation space are left unspecified,
      but a server may generate a
      <span class="errorname">BadAlloc</span>
      error on any request for this reason,
      and clients should be prepared to receive such errors and handle or discard
      them.</td></tr><tr><td align="left"><span class="errorname"><a id="BadAtom"></a>BadAtom</span></td><td align="left">A value for an atom argument does not name a defined atom.</td></tr><tr><td align="left"><span class="errorname"><a id="BadColor"></a>BadColor</span></td><td align="left">A value for a colormap argument does not name a defined colormap.</td></tr><tr><td align="left"><span class="errorname"><a id="BadCursor"></a>BadCursor</span></td><td align="left">A value for a cursor argument does not name a defined cursor.</td></tr><tr><td align="left"><span class="errorname"><a id="BadDrawable"></a>BadDrawable</span></td><td align="left">A value for a drawable argument does not name a defined window or pixmap.</td></tr><tr><td align="left"><span class="errorname"><a id="BadFont"></a>BadFont</span></td><td align="left">A value for a font argument does not name a defined font (or, in some cases,
      <span class="type">GContext</span>).</td></tr><tr><td align="left"><span class="errorname"><a id="BadGC"></a>BadGC</span></td><td align="left">A value for a
      <span class="type">GContext</span>
      argument does not name a defined 
      <span class="type">GContext</span>.</td></tr><tr><td align="left"><span class="errorname"><a id="BadIDChoice"></a>BadIDChoice</span></td><td align="left">The value chosen for a resource identifier either is not included in the
      range assigned to the client or is already in use.
      Under normal circumstances,
      this cannot occur and should be considered a server or Xlib error.</td></tr><tr><td align="left"><span class="errorname"><a id="BadImplementation"></a>BadImplementation</span></td><td align="left">The server does not implement some aspect of the request.
      A server that generates this error for a core request is deficient.
      As such, this error is not listed for any of the requests,
      but clients should be prepared to receive such errors
      and handle or discard them.</td></tr><tr><td align="left"><span class="errorname"><a id="BadLength"></a>BadLength</span></td><td align="left"><p>The length of a request is shorter or longer than that required to
      contain the arguments.
      This is an internal Xlib or server error.</p>
      <p>The length of a request exceeds the maximum length accepted by the server.</p>
      </td></tr><tr><td align="left"><span class="errorname"><a id="BadMatch"></a>BadMatch</span></td><td align="left"><p>In a graphics request,
      the root and depth of the graphics context do not match those of the drawable.</p>
      <p>An <span class="symbol">InputOnly</span> window is used as a drawable.</p>
      <p>Some argument or pair of arguments has the correct type and range,
      but it fails to match in some other way required by the request.</p>
      <p>An <span class="symbol">InputOnly</span>
      window lacks this attribute.</p>
      </td></tr><tr><td align="left"><span class="errorname"><a id="BadName"></a>BadName</span></td><td align="left">A font or color of the specified name does not exist.</td></tr><tr><td align="left"><span class="errorname"><a id="BadPixmap"></a>BadPixmap</span></td><td align="left">A value for a pixmap argument does not name a defined pixmap.</td></tr><tr><td align="left"><span class="errorname"><a id="BadRequest"></a>BadRequest</span></td><td align="left">The major or minor opcode does not specify a valid request.
      This usually is an Xlib or server error.</td></tr><tr><td align="left"><span class="errorname"><a id="BadValue"></a>BadValue</span></td><td align="left">Some numeric value falls outside of the range of values accepted
      by the request.
      Unless a specific range is specified for an argument,
      the full range defined by the argument's type is accepted.
      Any argument defined as a set of alternatives typically can generate
      this error (due to the encoding).</td></tr><tr><td align="left"><span class="errorname"><a id="BadWindow"></a>BadWindow</span></td><td align="left">A value for a window argument does not name a defined window.</td></tr></tbody></table></div><a id="idp48536348" class="indexterm"></a><a id="idp48536780" class="indexterm"></a><a id="idp48537204" class="indexterm"></a><a id="idp48537628" class="indexterm"></a><a id="idp48538052" class="indexterm"></a><a id="idp48538476" class="indexterm"></a><a id="idp48538900" class="indexterm"></a><a id="idp48539324" class="indexterm"></a><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
The 
<span class="errorname">BadAtom</span>,
<span class="errorname">BadColor</span>,
<span class="errorname">BadCursor</span>,
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadFont</span>,
<span class="errorname">BadGC</span>,
<span class="errorname">BadPixmap</span>,
and 
<span class="errorname">BadWindow</span>
errors are also used when the argument type is extended by a set of
fixed alternatives.
</p></div><p>

To obtain textual descriptions of the specified error code, use 
<a class="xref" href="#XGetErrorText"><code class="function">XGetErrorText</code></a>.
</p><a id="idp48543420" class="indexterm"></a><a id="idp48543852" class="indexterm"></a><div class="funcsynopsis"><a id="XGetErrorText"></a><p><code class="funcdef"><strong class="fsfunc">XGetErrorText</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> code</var>, char<var class="pdparam"> *buffer_return</var>, int<var class="pdparam"> length</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>code</em></span>
    </span></p></td><td><p>
Specifies the error code for which you want to obtain a description.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>buffer_return</em></span>
    </span></p></td><td><p>
Returns the error description.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>length</em></span>
    </span></p></td><td><p>
Specifies the size of the buffer.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetErrorText"><code class="function">XGetErrorText</code></a>
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.
</p><p>


To obtain error messages from the error database, use
<a class="xref" href="#XGetErrorDatabaseText"><code class="function">XGetErrorDatabaseText</code></a>.
</p><a id="idp48555516" class="indexterm"></a><div class="funcsynopsis"><a id="XGetErrorDatabaseText"></a><p><code class="funcdef"><strong class="fsfunc">XGetErrorDatabaseText</strong>(</code>Display<var class="pdparam"> *display</var>, char*name,<var class="pdparam"> *message</var>, char<var class="pdparam"> *default_string</var>, char<var class="pdparam"> *buffer_return</var>, int<var class="pdparam"> length</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>name</em></span>
    </span></p></td><td><p>
Specifies the name of the application.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>message</em></span>
    </span></p></td><td><p>
Specifies the type of the error message.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>default_string</em></span>
    </span></p></td><td><p>
Specifies the default error message if none is found in the database.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>buffer_return</em></span>
    </span></p></td><td><p>
Returns the error description.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>length</em></span>
    </span></p></td><td><p>
Specifies the size of the buffer.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetErrorDatabaseText"><code class="function">XGetErrorDatabaseText</code></a>
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.
</p><p>

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.
</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      XProtoError
    </span></p></td><td><p>
The protocol error number is used as a string for the message argument.
      </p></td></tr><tr><td><p><span class="term">
      XlibMessage
    </span></p></td><td><p>
These are the message strings that are used internally by the library.
      </p></td></tr><tr><td><p><span class="term">
      XRequest
    </span></p></td><td><p>
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
<code class="function">InitExtension</code>)
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.
    </p></td></tr></tbody></table></div><p>
</p><p>


To report an error to the user when the requested display does not exist, use
<a class="xref" href="#XDisplayName"><code class="function">XDisplayName</code></a>.
</p><a id="idp48574620" class="indexterm"></a><div class="funcsynopsis"><a id="XDisplayName"></a><p><code class="funcdef">char *<strong class="fsfunc">XDisplayName</strong>(</code>char<var class="pdparam"> *string</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the character string.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDisplayName"><code class="function">XDisplayName</code></a>
function returns the name of the display that 
<a class="xref" href="#XOpenDisplay"><code class="function">XOpenDisplay</code></a>
would attempt to use.
If a NULL string is specified,
<a class="xref" href="#XDisplayName"><code class="function">XDisplayName</code></a>
looks in the environment for the display and returns the display name that
<a class="xref" href="#XOpenDisplay"><code class="function">XOpenDisplay</code></a>
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.
</p><p>


To handle fatal I/O errors, use
<code class="function">XSetIOErrorHandler</code>.
</p><a id="idp48582004" class="indexterm"></a><div class="funcsynopsis"><a id="xsetioerrorhandler"></a><p><code class="funcdef">int(</code>int(*handler)(Display<var class="pdparam"> *)</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>handler</em></span>
    </span></p></td><td><p>
Specifies the program's supplied error handler.
    </p></td></tr></tbody></table></div><p>


The
<code class="function">XSetIOErrorHandler</code>
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.
</p><p>

Note that the previous error handler is returned.


</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Input_Device_Functions"></a>Chapter 12. Input Device Functions</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Pointer_Grabbing">Pointer Grabbing</a></span></dt><dt><span class="sect1"><a href="#Keyboard_Grabbing">Keyboard Grabbing</a></span></dt><dt><span class="sect1"><a href="#Resuming_Event_Processing">Resuming Event Processing</a></span></dt><dt><span class="sect1"><a href="#Moving_the_Pointer">Moving the Pointer</a></span></dt><dt><span class="sect1"><a href="#Controlling_Input_Focus">Controlling Input Focus</a></span></dt><dt><span class="sect1"><a href="#Manipulating_the_Keyboard_and_Pointer_Settings">Manipulating the Keyboard and Pointer Settings</a></span></dt><dt><span class="sect1"><a href="#Manipulating_the_Keyboard_Encoding">Manipulating the Keyboard Encoding</a></span></dt></dl></div><p>
You can use the Xlib input device functions to:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Grab the pointer and individual buttons on the pointer</p></li><li class="listitem"><p>Grab the keyboard and individual keys on the keyboard</p></li><li class="listitem"><p>Resume event processing</p></li><li class="listitem"><p>Move the pointer</p></li><li class="listitem"><p>Set the input focus</p></li><li class="listitem"><p>Manipulate the keyboard and pointer settings</p></li><li class="listitem"><p>Manipulate the keyboard encoding</p></li></ul></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Pointer_Grabbing"></a>Pointer Grabbing</h2></div></div></div><p>

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.
</p><p>

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
<a class="xref" href="#XAllowEvents"><code class="function">XAllowEvents</code></a>).
The keyboard or pointer is considered frozen during this
interval.
The event that triggered the grab can also be replayed.
</p><p>

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

<a id="idp40286180" class="indexterm"></a>
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
<a class="xref" href="#XGrabPointer"><code class="function">XGrabPointer</code></a>
and
<a class="xref" href="#XGrabKeyboard"><code class="function">XGrabKeyboard</code></a>).
<a id="idp40767036" class="indexterm"></a>
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.
</p><p>

For many operations,
there are functions that take a time argument.
The X server includes a timestamp in various events.
One special time, called
<a id="idp40421172" class="indexterm"></a>
<a id="idp43365292" class="indexterm"></a>
<span class="symbol">CurrentTime</span>,
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.
</p><p>

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
<span class="symbol">CurrentTime</span>,
is never generated by the server.
This value is reserved for use in requests to represent the current server time.
</p><p>

For many functions in this section,
you pass pointer event mask bits.
The valid pointer event mask bits are:
<span class="symbol">ButtonPressMask</span>,
<span class="symbol">ButtonReleaseMask</span>,
<span class="symbol">EnterWindowMask</span>,
<span class="symbol">LeaveWindowMask</span>,
<span class="symbol">PointerMotionMask</span>,
<span class="symbol">PointerMotionHintMask</span>,
<span class="symbol">Button1MotionMask</span>,
<span class="symbol">Button2MotionMask</span>,
<span class="symbol">Button3MotionMask</span>,
<span class="symbol">Button4MotionMask</span>,
<span class="symbol">Button5MotionMask</span>,
<span class="symbol">ButtonMotionMask</span>,
and
<span class="symbol">KeymapStateMask</span>.
For other functions in this section,
you pass keymask bits.
The valid keymask bits are:
<span class="symbol">ShiftMask</span>,
<span class="symbol">LockMask</span>,
<span class="symbol">ControlMask</span>,
<span class="symbol">Mod1Mask</span>,
<span class="symbol">Mod2Mask</span>,
<span class="symbol">Mod3Mask</span>,
<span class="symbol">Mod4Mask</span>,
and
<span class="symbol">Mod5Mask</span>.
</p><p>


To grab the pointer, use
<a class="xref" href="#XGrabPointer"><code class="function">XGrabPointer</code></a>.
</p><a id="idp43502308" class="indexterm"></a><a id="idp43502876" class="indexterm"></a><a id="idp43503444" class="indexterm"></a><div class="funcsynopsis"><a id="XGrabPointer"></a><p><code class="funcdef">int <strong class="fsfunc">XGrabPointer</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> grab_window</var>, Bool<var class="pdparam"> owner_events</var>, unsignedint<var class="pdparam"> event_mask</var>, intpointer_mode,<var class="pdparam"> keyboard_mode</var>, Window<var class="pdparam"> confine_to</var>, Cursor<var class="pdparam"> cursor</var>, Time<var class="pdparam"> time</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>grab_window</em></span>
    </span></p></td><td><p>
Specifies the grab window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>owner_events</em></span>
    </span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_mask</em></span>
    </span></p></td><td><p>
Specifies which pointer events are reported to the client.
The mask is the bitwise inclusive OR of the valid pointer event mask bits.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>pointer_mode</em></span>
    </span></p></td><td><p>
Specifies further processing of pointer events.
You can pass 
<span class="symbol">GrabModeSync</span>
or
<span class="symbol">GrabModeAsync</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>keyboard_mode</em></span>
    </span></p></td><td><p>
Specifies further processing of keyboard events.
You can pass 
<span class="symbol">GrabModeSync</span>
or
<span class="symbol">GrabModeAsync</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>confine_to</em></span>
    </span></p></td><td><p>
Specifies the window to confine the pointer in or
<span class="symbol">None</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>cursor</em></span>
    </span></p></td><td><p>
Specifies the cursor that is to be displayed during the grab or
<span class="symbol">None</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>time</em></span>
    </span></p></td><td><p>
Specifies the time.
You can pass either a timestamp or
<span class="symbol">CurrentTime</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGrabPointer"><code class="function">XGrabPointer</code></a>
function actively grabs control of the pointer and returns
<span class="symbol">GrabSuccess</span>
if the grab was successful.
Further pointer events are reported only to the grabbing client.
<a class="xref" href="#XGrabPointer"><code class="function">XGrabPointer</code></a>
overrides any active pointer grab by this client.
If owner_events is 
<span class="symbol">False</span>,
all generated pointer events
are reported with respect to grab_window and are reported only if
selected by event_mask.
If owner_events is 
<span class="symbol">True</span>
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.
</p><p>

If the pointer_mode is 
<span class="symbol">GrabModeAsync</span>,
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 
<span class="symbol">GrabModeSync</span>,
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 
<a class="xref" href="#XAllowEvents"><code class="function">XAllowEvents</code></a>
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.
</p><p>

If the keyboard_mode is 
<span class="symbol">GrabModeAsync</span>,
keyboard event processing is unaffected by activation of the grab.
If the keyboard_mode is 
<span class="symbol">GrabModeSync</span>,
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 
<a class="xref" href="#XAllowEvents"><code class="function">XAllowEvents</code></a>
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.
</p><p>

If a cursor is specified, it is displayed regardless of what
window the pointer is in.  
If 
<span class="symbol">None</span>
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.
</p><p>

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.
</p><p>

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.
</p><p>

<a class="xref" href="#XGrabPointer"><code class="function">XGrabPointer</code></a>
generates
<span class="symbol">EnterNotify</span>
and
<span class="symbol">LeaveNotify</span>
events.
</p><p>

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,
<a class="xref" href="#XGrabPointer"><code class="function">XGrabPointer</code></a>
fails and returns
<span class="symbol">GrabNotViewable</span>.
If the pointer is actively grabbed by some other client,
it fails and returns
<span class="symbol">AlreadyGrabbed</span>.
If the pointer is frozen by an active grab of another client,
it fails and returns
<span class="symbol">GrabFrozen</span>.
If the specified time is earlier than the last-pointer-grab time or later 
than the current X server time, it fails and returns
<span class="symbol">GrabInvalidTime</span>.
Otherwise, the last-pointer-grab time is set to the specified time
(<span class="symbol">CurrentTime</span>
is replaced by the current X server time).
</p><p>

<a class="xref" href="#XGrabPointer"><code class="function">XGrabPointer</code></a>
can generate
<span class="errorname">BadCursor</span>,
<span class="errorname">BadValue</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To ungrab the pointer, use
<a class="xref" href="#XUngrabPointer"><code class="function">XUngrabPointer</code></a>.
</p><a id="idp49127724" class="indexterm"></a><a id="idp49128292" class="indexterm"></a><a id="idp49128860" class="indexterm"></a><div class="funcsynopsis"><a id="XUngrabPointer"></a><p><code class="funcdef"><strong class="fsfunc">XUngrabPointer</strong>(</code>Display<var class="pdparam"> *display</var>, Time<var class="pdparam"> time</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>time</em></span>
    </span></p></td><td><p>
Specifies the time.
You can pass either a timestamp or
<span class="symbol">CurrentTime</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XUngrabPointer"><code class="function">XUngrabPointer</code></a>
function releases the pointer and any queued events
if this client has actively grabbed the pointer from
<a class="xref" href="#XGrabPointer"><code class="function">XGrabPointer</code></a>,
<a class="xref" href="#XGrabButton"><code class="function">XGrabButton</code></a>,
or from a normal button press.
<a class="xref" href="#XUngrabPointer"><code class="function">XUngrabPointer</code></a>
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 
<span class="symbol">EnterNotify</span>
and 
<span class="symbol">LeaveNotify</span>
events.
The X server performs an 
<code class="systemitem">UngrabPointer</code>
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.
</p><p>


To change an active pointer grab, use
<a class="xref" href="#XChangeActivePointerGrab"><code class="function">XChangeActivePointerGrab</code></a>.
</p><a id="idp49139172" class="indexterm"></a><a id="idp49139740" class="indexterm"></a><a id="idp49140316" class="indexterm"></a><div class="funcsynopsis"><a id="XChangeActivePointerGrab"></a><p><code class="funcdef"><strong class="fsfunc">XChangeActivePointerGrab</strong>(</code>Display<var class="pdparam"> *display</var>, unsignedint<var class="pdparam"> event_mask</var>, Cursor<var class="pdparam"> cursor</var>, Time<var class="pdparam"> time</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_mask</em></span>
    </span></p></td><td><p>
Specifies which pointer events are reported to the client.
The mask is the bitwise inclusive OR of the valid pointer event mask bits.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>cursor</em></span>
    </span></p></td><td><p>
Specifies the cursor that is to be displayed or
<span class="symbol">None</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>time</em></span>
    </span></p></td><td><p>
Specifies the time.
You can pass either a timestamp or
<span class="symbol">CurrentTime</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XChangeActivePointerGrab"><code class="function">XChangeActivePointerGrab</code></a>
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
<a class="xref" href="#XGrabButton"><code class="function">XGrabButton</code></a>.
The interpretation of event_mask and cursor is the same as described in
<a class="xref" href="#XGrabPointer"><code class="function">XGrabPointer</code></a>.
</p><p>

<a class="xref" href="#XChangeActivePointerGrab"><code class="function">XChangeActivePointerGrab</code></a>
can generate
<span class="errorname">BadCursor</span>
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To grab a pointer button, use
<a class="xref" href="#XGrabButton"><code class="function">XGrabButton</code></a>.
</p><a id="idp49154340" class="indexterm"></a><a id="idp49154908" class="indexterm"></a><a id="idp49155476" class="indexterm"></a><div class="funcsynopsis"><a id="XGrabButton"></a><p><code class="funcdef"><strong class="fsfunc">XGrabButton</strong>(</code>Display<var class="pdparam"> *display</var>, unsignedint<var class="pdparam"> button</var>, unsignedint<var class="pdparam"> modifiers</var>, Window<var class="pdparam"> grab_window</var>, Bool<var class="pdparam"> owner_events</var>, unsignedint<var class="pdparam"> event_mask</var>, intpointer_mode,<var class="pdparam"> keyboard_mode</var>, Window<var class="pdparam"> confine_to</var>, Cursor<var class="pdparam"> cursor</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>button</em></span>
    </span></p></td><td><p>
Specifies the pointer button that is to be grabbed or
<span class="symbol">AnyButton</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>modifiers</em></span>
    </span></p></td><td><p>
Specifies the set of keymasks or
<span class="symbol">AnyModifier</span>.
The mask is the bitwise inclusive OR of the valid keymask bits.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>grab_window</em></span>
    </span></p></td><td><p>
Specifies the grab window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>owner_events</em></span>
    </span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_mask</em></span>
    </span></p></td><td><p>
Specifies which pointer events are reported to the client.
The mask is the bitwise inclusive OR of the valid pointer event mask bits.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>pointer_mode</em></span>
    </span></p></td><td><p>
Specifies further processing of pointer events.
You can pass 
<span class="symbol">GrabModeSync</span>
or
<span class="symbol">GrabModeAsync</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>keyboard_mode</em></span>
    </span></p></td><td><p>
Specifies further processing of keyboard events.
You can pass 
<span class="symbol">GrabModeSync</span>
or
<span class="symbol">GrabModeAsync</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>confine_to</em></span>
    </span></p></td><td><p>
Specifies the window to confine the pointer in or
<span class="symbol">None</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>cursor</em></span>
    </span></p></td><td><p>
Specifies the cursor that is to be displayed or
<span class="symbol">None</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGrabButton"><code class="function">XGrabButton</code></a>
function establishes a passive grab.
In the future,
the pointer is actively grabbed (as for
<a class="xref" href="#XGrabPointer"><code class="function">XGrabPointer</code></a>),
the last-pointer-grab time is set to the time at which the button was pressed
(as transmitted in the
<span class="symbol">ButtonPress</span>
event), and the
<span class="symbol">ButtonPress</span>
event is reported if all of the following conditions are true:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
The grab_window contains the pointer.
    </p></li><li class="listitem"><p>
The confine_to window (if any) is viewable.
    </p></li><li class="listitem"><p>
A passive grab on the same button/key combination does not exist
on any ancestor of grab_window.
    </p></li></ul></div><p>

The interpretation of the remaining arguments is as for
<a class="xref" href="#XGrabPointer"><code class="function">XGrabPointer</code></a>.
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).
</p><p>

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

This request overrides all previous grabs by the same client on the same
button/key combinations on the same window.
A modifiers of 
<span class="symbol">AnyModifier</span>
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 
<span class="symbol">AnyButton</span>
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.
</p><p>

If some other client has already issued an
<a class="xref" href="#XGrabButton"><code class="function">XGrabButton</code></a>
with the same button/key combination on the same window, a
<span class="errorname">BadAccess</span>
error results.
When using 
<span class="symbol">AnyModifier</span>
or 
<span class="symbol">AnyButton</span>,
the request fails completely,
and a
<span class="errorname">BadAccess</span>
error results (no grabs are
established) if there is a conflicting grab for any combination.
<a class="xref" href="#XGrabButton"><code class="function">XGrabButton</code></a>
has no effect on an active grab.
</p><p>

<a class="xref" href="#XGrabButton"><code class="function">XGrabButton</code></a>
can generate
<span class="errorname">BadCursor</span>,
<span class="errorname">BadValue</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To ungrab a pointer button, use
<a class="xref" href="#XUngrabButton"><code class="function">XUngrabButton</code></a>.
</p><a id="idp49189068" class="indexterm"></a><a id="idp49189636" class="indexterm"></a><a id="idp49190204" class="indexterm"></a><div class="funcsynopsis"><a id="XUngrabButton"></a><p><code class="funcdef"><strong class="fsfunc">XUngrabButton</strong>(</code>Display<var class="pdparam"> *display</var>, unsignedint<var class="pdparam"> button</var>, unsignedint<var class="pdparam"> modifiers</var>, Window<var class="pdparam"> grab_window</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>button</em></span>
    </span></p></td><td><p>
Specifies the pointer button that is to be released or
<span class="symbol">AnyButton</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>modifiers</em></span>
    </span></p></td><td><p>
Specifies the set of keymasks or
<span class="symbol">AnyModifier</span>.
The mask is the bitwise inclusive OR of the valid keymask bits.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>grab_window</em></span>
    </span></p></td><td><p>
Specifies the grab window.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XUngrabButton"><code class="function">XUngrabButton</code></a>
function releases the passive button/key combination on the specified window if
it was grabbed by this client.
A modifiers of 
<span class="symbol">AnyModifier</span>
is
equivalent to issuing 
the ungrab request for all possible modifier combinations, including 
the combination of no modifiers.
A button of 
<span class="symbol">AnyButton</span>
is equivalent to issuing the
request for all possible buttons.
<a class="xref" href="#XUngrabButton"><code class="function">XUngrabButton</code></a>
has no effect on an active grab.
</p><p>

<a class="xref" href="#XUngrabButton"><code class="function">XUngrabButton</code></a>
can generate
<span class="errorname">BadValue</span>
and
<span class="errorname">BadWindow</span>
errors.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Keyboard_Grabbing"></a>Keyboard Grabbing</h2></div></div></div><p>

Xlib provides functions that you can use to grab or ungrab the keyboard
as well as allow events.
</p><p>

For many functions in this section,
you pass keymask bits.
The valid keymask bits are:
<span class="symbol">ShiftMask</span>,
<span class="symbol">LockMask</span>,
<span class="symbol">ControlMask</span>,
<span class="symbol">Mod1Mask</span>,
<span class="symbol">Mod2Mask</span>,
<span class="symbol">Mod3Mask</span>,
<span class="symbol">Mod4Mask</span>,
and
<span class="symbol">Mod5Mask</span>.
</p><p>


To grab the keyboard, use
<a class="xref" href="#XGrabKeyboard"><code class="function">XGrabKeyboard</code></a>.
</p><a id="idp49208044" class="indexterm"></a><a id="idp49208612" class="indexterm"></a><a id="idp49209180" class="indexterm"></a><div class="funcsynopsis"><a id="XGrabKeyboard"></a><p><code class="funcdef">int <strong class="fsfunc">XGrabKeyboard</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> grab_window</var>, Bool<var class="pdparam"> owner_events</var>, intpointer_mode,<var class="pdparam"> keyboard_mode</var>, Time<var class="pdparam"> time</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>grab_window</em></span>
    </span></p></td><td><p>
Specifies the grab window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>owner_events</em></span>
    </span></p></td><td><p>
Specifies a Boolean value that indicates whether the keyboard events 
are to be reported as usual.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>pointer_mode</em></span>
    </span></p></td><td><p>
Specifies further processing of pointer events.
You can pass 
<span class="symbol">GrabModeSync</span>
or
<span class="symbol">GrabModeAsync</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>keyboard_mode</em></span>
    </span></p></td><td><p>
Specifies further processing of keyboard events.
You can pass 
<span class="symbol">GrabModeSync</span>
or
<span class="symbol">GrabModeAsync</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>time</em></span>
    </span></p></td><td><p>
Specifies the time.
You can pass either a timestamp or
<span class="symbol">CurrentTime</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGrabKeyboard"><code class="function">XGrabKeyboard</code></a>
function actively grabs control of the keyboard and generates
<span class="symbol">FocusIn</span>
and
<span class="symbol">FocusOut</span>
events.
Further key events are reported only to the
grabbing client.
<a class="xref" href="#XGrabKeyboard"><code class="function">XGrabKeyboard</code></a>
overrides any active keyboard grab by this client.
If owner_events is 
<span class="symbol">False</span>,
all generated key events are reported with
respect to grab_window.  
If owner_events is 
<span class="symbol">True</span>
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 
<span class="symbol">KeyPress</span>
and 
<span class="symbol">KeyRelease</span>
events are always reported,
independent of any event selection made by the client.
</p><p>

If the keyboard_mode argument is 
<span class="symbol">GrabModeAsync</span>,
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
<span class="symbol">GrabModeSync</span>,
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 
<a class="xref" href="#XAllowEvents"><code class="function">XAllowEvents</code></a>
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.
</p><p>

If pointer_mode is 
<span class="symbol">GrabModeAsync</span>,
pointer event processing is unaffected
by activation of the grab.  
If pointer_mode is 
<span class="symbol">GrabModeSync</span>,
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 
<a class="xref" href="#XAllowEvents"><code class="function">XAllowEvents</code></a>
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.
</p><p>

If the keyboard is actively grabbed by some other client,
<a class="xref" href="#XGrabKeyboard"><code class="function">XGrabKeyboard</code></a>
fails and returns
<span class="symbol">AlreadyGrabbed</span>.
If grab_window is not viewable,
it fails and returns
<span class="symbol">GrabNotViewable</span>.
If the keyboard is frozen by an active grab of another client,
it fails and returns
<span class="symbol">GrabFrozen</span>.
If the specified time is earlier than the last-keyboard-grab time 
or later than the current X server time,
it fails and returns
<span class="symbol">GrabInvalidTime</span>.
Otherwise, the last-keyboard-grab time is set to the specified time
(<span class="symbol">CurrentTime</span>
is replaced by the current X server time).
</p><p>

<a class="xref" href="#XGrabKeyboard"><code class="function">XGrabKeyboard</code></a>
can generate
<span class="errorname">BadValue</span>
and 
<span class="errorname">BadWindow</span>
errors.
</p><p>


To ungrab the keyboard, use
<a class="xref" href="#XUngrabKeyboard"><code class="function">XUngrabKeyboard</code></a>.
</p><a id="idp49234156" class="indexterm"></a><a id="idp49234724" class="indexterm"></a><a id="idp49235292" class="indexterm"></a><div class="funcsynopsis"><a id="XUngrabKeyboard"></a><p><code class="funcdef"><strong class="fsfunc">XUngrabKeyboard</strong>(</code>Display<var class="pdparam"> *display</var>, Time<var class="pdparam"> time</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>time</em></span>
    </span></p></td><td><p>
Specifies the time.
You can pass either a timestamp or
<span class="symbol">CurrentTime</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XUngrabKeyboard"><code class="function">XUngrabKeyboard</code></a>
function
releases the keyboard and any queued events if this client has it actively grabbed from
either
<a class="xref" href="#XGrabKeyboard"><code class="function">XGrabKeyboard</code></a>
or
<a class="xref" href="#XGrabKey"><code class="function">XGrabKey</code></a>.
<a class="xref" href="#XUngrabKeyboard"><code class="function">XUngrabKeyboard</code></a>
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
<span class="symbol">FocusIn</span>
and 
<span class="symbol">FocusOut</span>
events.
The X server automatically performs an 
<code class="systemitem">UngrabKeyboard</code>
request if the event window for an
active keyboard grab becomes not viewable.
</p><p>


To passively grab a single key of the keyboard, use
<a class="xref" href="#XGrabKey"><code class="function">XGrabKey</code></a>.
</p><a id="idp49695452" class="indexterm"></a><a id="idp49695956" class="indexterm"></a><a id="idp49696460" class="indexterm"></a><div class="funcsynopsis"><a id="XGrabKey"></a><p><code class="funcdef"><strong class="fsfunc">XGrabKey</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> keycode</var>, unsignedint<var class="pdparam"> modifiers</var>, Window<var class="pdparam"> grab_window</var>, Bool<var class="pdparam"> owner_events</var>, intpointer_mode,<var class="pdparam"> keyboard_mode</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>keycode</em></span>
    </span></p></td><td><p>
Specifies the KeyCode or
<span class="symbol">AnyKey</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>modifiers</em></span>
    </span></p></td><td><p>
Specifies the set of keymasks or
<span class="symbol">AnyModifier</span>.
The mask is the bitwise inclusive OR of the valid keymask bits.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>grab_window</em></span>
    </span></p></td><td><p>
Specifies the grab window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>owner_events</em></span>
    </span></p></td><td><p>
Specifies a Boolean value that indicates whether the keyboard events 
are to be reported as usual.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>pointer_mode</em></span>
    </span></p></td><td><p>
Specifies further processing of pointer events.
You can pass 
<span class="symbol">GrabModeSync</span>
or
<span class="symbol">GrabModeAsync</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>keyboard_mode</em></span>
    </span></p></td><td><p>
Specifies further processing of keyboard events.
You can pass 
<span class="symbol">GrabModeSync</span>
or
<span class="symbol">GrabModeAsync</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGrabKey"><code class="function">XGrabKey</code></a>
function establishes a passive grab on the keyboard.
In the future,
the keyboard is actively grabbed (as for
<a class="xref" href="#XGrabKeyboard"><code class="function">XGrabKeyboard</code></a>),
the last-keyboard-grab time is set to the time at which the key was pressed
(as transmitted in the
<span class="symbol">KeyPress</span>
event), and the
<span class="symbol">KeyPress</span>
event is reported if all of the following conditions are true:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
A passive grab on the same key combination does not exist
on any ancestor of grab_window.
    </p></li></ul></div><p>

The interpretation of the remaining arguments is as for 
<a class="xref" href="#XGrabKeyboard"><code class="function">XGrabKeyboard</code></a>.
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).
</p><p>

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

A modifiers argument of 
<span class="symbol">AnyModifier</span>
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 
<span class="symbol">AnyKey</span>
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
<span class="errorname">BadValue</span>
error results.
</p><p>

If some other client has issued a 
<a class="xref" href="#XGrabKey"><code class="function">XGrabKey</code></a>
with the same key combination on the same window, a 
<span class="errorname">BadAccess</span>
error results.
When using
<span class="symbol">AnyModifier</span>
or 
<span class="symbol">AnyKey</span>,
the request fails completely,
and a
<span class="errorname">BadAccess</span>
error results (no grabs are established) 
if there is a conflicting grab for any combination.
</p><p>

<a class="xref" href="#XGrabKey"><code class="function">XGrabKey</code></a>
can generate
<span class="errorname">BadAccess</span>,
<span class="errorname">BadValue</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To ungrab a key, use
<a class="xref" href="#XUngrabKey"><code class="function">XUngrabKey</code></a>.
</p><a id="idp49720052" class="indexterm"></a><a id="idp49720556" class="indexterm"></a><a id="idp49721060" class="indexterm"></a><div class="funcsynopsis"><a id="XUngrabKey"></a><p><code class="funcdef"><strong class="fsfunc">XUngrabKey</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> keycode</var>, unsignedint<var class="pdparam"> modifiers</var>, Window<var class="pdparam"> grab_window</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>keycode</em></span>
    </span></p></td><td><p>
Specifies the KeyCode or
<span class="symbol">AnyKey</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>modifiers</em></span>
    </span></p></td><td><p>
Specifies the set of keymasks or
<span class="symbol">AnyModifier</span>.
The mask is the bitwise inclusive OR of the valid keymask bits.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>grab_window</em></span>
    </span></p></td><td><p>
Specifies the grab window.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XUngrabKey"><code class="function">XUngrabKey</code></a>
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
<span class="symbol">AnyModifier</span>
is equivalent to issuing
the request for all possible modifier combinations
(including the combination of no modifiers).
A keycode argument of
<span class="symbol">AnyKey</span>
is equivalent to issuing the request for all possible key codes.
</p><p>

<a class="xref" href="#XUngrabKey"><code class="function">XUngrabKey</code></a>
can generate
<span class="errorname">BadValue</span>
and
<span class="errorname">BadWindow</span>
errors.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Resuming_Event_Processing"></a>Resuming Event Processing</h2></div></div></div><p>

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.
</p><p>


To allow further events to be processed when the device has been frozen, use
<a class="xref" href="#XAllowEvents"><code class="function">XAllowEvents</code></a>.
</p><a id="idp49734332" class="indexterm"></a><div class="funcsynopsis"><a id="XAllowEvents"></a><p><code class="funcdef"><strong class="fsfunc">XAllowEvents</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> event_mode</var>, Time<var class="pdparam"> time</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_mode</em></span>
    </span></p></td><td><p>
Specifies the event mode.
You can pass 
<span class="symbol">AsyncPointer</span>,
<span class="symbol">SyncPointer</span>,
<span class="symbol">AsyncKeyboard</span>,
<span class="symbol">SyncKeyboard</span>,
<span class="symbol">ReplayPointer</span>,
<span class="symbol">ReplayKeyboard</span>,
<span class="symbol">AsyncBoth</span>,
or
<span class="symbol">SyncBoth</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>time</em></span>
    </span></p></td><td><p>
Specifies the time.
You can pass either a timestamp or
<span class="symbol">CurrentTime</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XAllowEvents"><code class="function">XAllowEvents</code></a>
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:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left"><span class="symbol">AsyncPointer</span></td><td align="left">If the pointer is frozen by the client,
      pointer event processing continues as usual.
      If the pointer is frozen twice by the client on behalf of two separate grabs,
      <span class="symbol">AsyncPointer</span>
      thaws for both.
      <span class="symbol">AsyncPointer</span>
      has no effect if the pointer is not frozen by the client,
      but the pointer need not be grabbed by the client.</td></tr><tr><td align="left"><span class="symbol">SyncPointer</span></td><td align="left">If the pointer is frozen and actively grabbed by the client,
      pointer event processing continues as usual until the next
      <span class="symbol">ButtonPress</span>
      or
      <span class="symbol">ButtonRelease</span>
      event is reported to the client.
      At this time,
      the pointer again appears to freeze.
      However, if the reported event causes the pointer grab to be released,
      the pointer does not freeze.
      <span class="symbol">SyncPointer</span>
      has no effect if the pointer is not frozen by the client
      or if the pointer is not grabbed by the client.</td></tr><tr><td align="left"><span class="symbol">ReplayPointer</span></td><td align="left">If the pointer is actively grabbed by the client and is frozen as the result of
      an event having been sent to the client (either from the activation of an
      <a class="xref" href="#XGrabButton"><code class="function">XGrabButton</code></a>
      or from a previous
      <a class="xref" href="#XAllowEvents"><code class="function">XAllowEvents</code></a>
      with mode
      <span class="symbol">SyncPointer</span>
      but not from an 
      <a class="xref" href="#XGrabPointer"><code class="function">XGrabPointer</code></a>),
      the pointer grab is released and that event is completely reprocessed.
      This time, however, the function ignores any passive grabs at or above 
      (toward the root of) the grab_window of the grab just released.
      The request has no effect if the pointer is not grabbed by the client
      or if the pointer is not frozen as the result of an event.</td></tr><tr><td align="left"><span class="symbol">AsyncKeyboard</span></td><td align="left">If the keyboard is frozen by the client,
      keyboard event processing continues as usual.
      If the keyboard is frozen twice by the client on behalf of two separate grabs,
      <span class="symbol">AsyncKeyboard</span>
      thaws for both.
      <span class="symbol">AsyncKeyboard</span>
      has no effect if the keyboard is not frozen by the client,
      but the keyboard need not be grabbed by the client.</td></tr><tr><td align="left"><span class="symbol">SyncKeyboard</span></td><td align="left">If the keyboard is frozen and actively grabbed by the client,
      keyboard event processing continues as usual until the next
      <span class="symbol">KeyPress</span>
      or
      <span class="symbol">KeyRelease</span>
      event is reported to the client.
      At this time,
      the keyboard again appears to freeze.
      However, if the reported event causes the keyboard grab to be released,
      the keyboard does not freeze.
      <span class="symbol">SyncKeyboard</span>
      has no effect if the keyboard is not frozen by the client
      or if the keyboard is not grabbed by the client.</td></tr><tr><td align="left"><span class="symbol">ReplayKeyboard</span></td><td align="left">If the keyboard is actively grabbed by the client and is frozen
      as the result of an event having been sent to the client (either from the
      activation of an
      <a class="xref" href="#XGrabKey"><code class="function">XGrabKey</code></a>
      or from a previous
      <a class="xref" href="#XAllowEvents"><code class="function">XAllowEvents</code></a>
      with mode
      <span class="symbol">SyncKeyboard</span>
      but not from an 
      <a class="xref" href="#XGrabKeyboard"><code class="function">XGrabKeyboard</code></a>),
      the keyboard grab is released and that event is completely reprocessed.
      This time, however, the function ignores any passive grabs at or above
      (toward the root of)
      the grab_window of the grab just released.
      The request has no effect if the keyboard is not grabbed by the client
      or if the keyboard is not frozen as the result of an event.</td></tr><tr><td align="left"><span class="symbol">SyncBoth</span></td><td align="left">If both pointer and keyboard are frozen by the client,
      event processing for both devices continues as usual until the next
      <span class="symbol">ButtonPress</span>,
      <span class="symbol">ButtonRelease</span>,
      <span class="symbol">KeyPress</span>,
      or 
      <span class="symbol">KeyRelease</span>
      event is reported to the client for a grabbed device 
      (button event for the pointer, key event for the keyboard), 
      at which time the devices again appear to freeze.  
      However, if the reported event causes the grab to be released,
      then the devices do not freeze (but if the other device is still
      grabbed, then a subsequent event for it will still cause both devices
      to freeze).  
      <span class="symbol">SyncBoth</span>
      has no effect unless both pointer and keyboard
      are frozen by the client.
      If the pointer or keyboard is frozen twice
      by the client on behalf of two separate grabs, 
      <span class="symbol">SyncBoth</span>
      thaws for both (but a subsequent freeze for 
      <span class="symbol">SyncBoth</span>
      will only freeze each device once).</td></tr><tr><td align="left"><span class="symbol">AsyncBoth</span></td><td align="left">If the pointer and the keyboard are frozen by the
      client, event processing for both devices continues as usual.
      If a device is frozen twice by the client on behalf of two separate grabs,
      <span class="symbol">AsyncBoth</span>
      thaws for both.
      <span class="symbol">AsyncBoth</span>
      has no effect unless both
      pointer and keyboard are frozen by the client.</td></tr></tbody></table></div><p>

<span class="symbol">AsyncPointer</span>,
<span class="symbol">SyncPointer</span>,
and 
<span class="symbol">ReplayPointer</span>
have no effect on the
processing of keyboard events.
<span class="symbol">AsyncKeyboard</span>,
<span class="symbol">SyncKeyboard</span>,
and 
<span class="symbol">ReplayKeyboard</span>
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
<a class="xref" href="#XAllowEvents"><code class="function">XAllowEvents</code></a>
releases both.
</p><p>

<a class="xref" href="#XAllowEvents"><code class="function">XAllowEvents</code></a>
can generate a
<span class="errorname">BadValue</span>
error.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Moving_the_Pointer"></a>Moving the Pointer</h2></div></div></div><p>

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.
</p><p>


To move the pointer to an arbitrary point in a window, use
<a class="xref" href="#XWarpPointer"><code class="function">XWarpPointer</code></a>.
</p><a id="idp49766508" class="indexterm"></a><div class="funcsynopsis"><a id="XWarpPointer"></a><p><code class="funcdef"><strong class="fsfunc">XWarpPointer</strong>(</code>Display<var class="pdparam"> *display</var>, Windowsrc_w,<var class="pdparam"> dest_w</var>, intsrc_x,<var class="pdparam"> src_y</var>, unsignedintsrc_width,<var class="pdparam"> src_height</var>, intdest_x,<var class="pdparam"> dest_y</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>src_w</em></span>
    </span></p></td><td><p>
Specifies the source window or
<span class="symbol">None</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dest_w</em></span>
    </span></p></td><td><p>
Specifies the destination window or
<span class="symbol">None</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>src_x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>src_y</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>src_width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>src_height</em></span>
    </span></p></td><td><p>
Specify a rectangle in the source window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dest_x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dest_y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates within the destination window.
    </p></td></tr></tbody></table></div><p>


If dest_w is
<span class="symbol">None</span>,
<a class="xref" href="#XWarpPointer"><code class="function">XWarpPointer</code></a>
moves the pointer by the offsets (dest_x, dest_y) relative to the current
position of the pointer.
If dest_w is a window,
<a class="xref" href="#XWarpPointer"><code class="function">XWarpPointer</code></a>
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.
</p><p>

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.
</p><p>

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
<a class="xref" href="#XWarpPointer"><code class="function">XWarpPointer</code></a>
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. 
</p><p>

<a class="xref" href="#XWarpPointer"><code class="function">XWarpPointer</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Controlling_Input_Focus"></a>Controlling Input Focus</h2></div></div></div><p>

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
<span class="olink"><em class="citetitle">Inter-Client Communication Conventions Manual</em></span>
for input focus policy.
</p><p>


To set the input focus, use
<a class="xref" href="#XSetInputFocus"><code class="function">XSetInputFocus</code></a>.
</p><a id="idp49788876" class="indexterm"></a><div class="funcsynopsis"><a id="XSetInputFocus"></a><p><code class="funcdef"><strong class="fsfunc">XSetInputFocus</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> focus</var>, int<var class="pdparam"> revert_to</var>, Time<var class="pdparam"> time</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>focus</em></span>
    </span></p></td><td><p>
Specifies the window,
<span class="symbol">PointerRoot</span>,
or
<span class="symbol">None</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>revert_to</em></span>
    </span></p></td><td><p>
Specifies where the input focus reverts to if the window becomes not
viewable.
You can pass 
<span class="symbol">RevertToParent</span>,
<span class="symbol">RevertToPointerRoot</span>,
or 
<span class="symbol">RevertToNone</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>time</em></span>
    </span></p></td><td><p>
Specifies the time.
You can pass either a timestamp or
<span class="symbol">CurrentTime</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetInputFocus"><code class="function">XSetInputFocus</code></a>
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
(<span class="symbol">CurrentTime</span>
is replaced by the current X server time).
<a class="xref" href="#XSetInputFocus"><code class="function">XSetInputFocus</code></a>
causes the X server to generate
<span class="symbol">FocusIn</span>
and 
<span class="symbol">FocusOut</span>
events.
</p><p>

Depending on the focus argument,
the following occurs: 
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If focus is
<span class="symbol">None</span>,
all keyboard events are discarded until a new focus window is set,
and the revert_to argument is ignored.
    </p></li><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
If focus is
<span class="symbol">PointerRoot</span>,
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.
    </p></li></ul></div><p>

The specified focus window must be viewable at the time 
<a class="xref" href="#XSetInputFocus"><code class="function">XSetInputFocus</code></a>
is called,
or a
<span class="errorname">BadMatch</span>
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: 
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If revert_to is
<span class="symbol">RevertToParent</span>,
the focus reverts to the parent (or the closest viewable ancestor), 
and the new revert_to value is taken to be
<span class="symbol">RevertToNone</span>.
    </p></li><li class="listitem"><p>
If revert_to is
<span class="symbol">RevertToPointerRoot</span>
or 
<span class="symbol">RevertToNone</span>,
the focus reverts to
<span class="symbol">PointerRoot</span>
or
<span class="symbol">None</span>,
respectively.
When the focus reverts,
the X server generates
<span class="symbol">FocusIn</span>
and
<span class="symbol">FocusOut</span>
events, but the last-focus-change time is not affected.
    </p></li></ul></div><p>

<a class="xref" href="#XSetInputFocus"><code class="function">XSetInputFocus</code></a>
can generate
<span class="errorname">BadMatch</span>,
<span class="errorname">BadValue</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To obtain the current input focus, use
<a class="xref" href="#XGetInputFocus"><code class="function">XGetInputFocus</code></a>.
</p><a id="idp49808772" class="indexterm"></a><div class="funcsynopsis"><a id="XGetInputFocus"></a><p><code class="funcdef"><strong class="fsfunc">XGetInputFocus</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> *focus_return</var>, int<var class="pdparam"> *revert_to_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>focus_return</em></span>
    </span></p></td><td><p>
Returns the focus window,
<span class="symbol">PointerRoot</span>,
or 
<span class="symbol">None</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>revert_to_return</em></span>
    </span></p></td><td><p>
Returns the current focus state
(<span class="symbol">RevertToParent</span>,
<span class="symbol">RevertToPointerRoot</span>,
or 
<span class="symbol">RevertToNone</span>).
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetInputFocus"><code class="function">XGetInputFocus</code></a>
function returns the focus window and the current focus state.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Manipulating_the_Keyboard_and_Pointer_Settings"></a>Manipulating the Keyboard and Pointer Settings</h2></div></div></div><p>

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.
</p><p>

<a id="idp49818908" class="indexterm"></a>
<a id="idp49819412" class="indexterm"></a>
<a id="idp49819916" class="indexterm"></a>
<a id="idp49820420" class="indexterm"></a>
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.
</p><p>

The
<a class="xref" href="#XChangeKeyboardControl"><code class="function">XChangeKeyboardControl</code></a>
function changes control of a keyboard and operates on a
<span class="structname">XKeyboardControl</span>
structure:

</p><pre class="literallayout">
/* Mask bits for ChangeKeyboardControl */


#define     KBBellPercent           (1L&lt;&lt;0)
#define     KBBellPitch             (1L&lt;&lt;1)
#define     KBBellDuration          (1L&lt;&lt;2)
#define     KBLed                   (1L&lt;&lt;3)
#define     KBLedMode               (1L&lt;&lt;4)
#define     KBKey                   (1L&lt;&lt;5)
#define     KBAutoRepeatMode        (1L&lt;&lt;6)


/* Values */

typedef struct {
int key_click_percent;
int bell_percent;
int bell_pitch;
int bell_duration;
int led;
int led_mode;                /* LedModeOn, LedModeOff */
int key;
int auto_repeat_mode;        /* AutoRepeatModeOff, AutoRepeatModeOn,
                                AutoRepeatModeDefault */
} XKeyboardControl;

</pre><p>


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
<span class="errorname">BadValue</span>
error.
</p><p>

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
<span class="errorname">BadValue</span>
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
<span class="errorname">BadValue</span>
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
<span class="errorname">BadValue</span>
error.
</p><p>

If both the led_mode and led members are specified,
the state of that <acronym class="acronym">LED</acronym> is changed, if possible.  
The led_mode member can be set to
<span class="symbol">LedModeOn</span>
or
<span class="symbol">LedModeOff</span>.
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
<span class="errorname">BadMatch</span>
error results. 
</p><p>

If both the auto_repeat_mode and key members are specified, 
the auto_repeat_mode of that key is changed (according to
<span class="symbol">AutoRepeatModeOn</span>,
<span class="symbol">AutoRepeatModeOff</span>,
or
<span class="symbol">AutoRepeatModeDefault</span>),
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
<span class="errorname">BadMatch</span>
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
<span class="symbol">AutoRepeatModeOn</span>,
keys should obey their individual auto-repeat modes.
When global mode is
<span class="symbol">AutoRepeatModeOff</span>,
no keys should auto-repeat.
An auto-repeating key generates alternating
<span class="symbol">KeyPress</span>
and
<span class="symbol">KeyRelease</span>
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.
</p><p>

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.
</p><p>


</p><a id="idp49831028" class="indexterm"></a><div class="funcsynopsis"><a id="XChangeKeyboardControl"></a><p><code class="funcdef"><strong class="fsfunc">XChangeKeyboardControl</strong>(</code>Display<var class="pdparam"> *display</var>, unsignedlong<var class="pdparam"> value_mask</var>, XKeyboardControl<var class="pdparam"> *values</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>value_mask</em></span>
    </span></p></td><td><p>
Specifies which controls to change.
This mask is the bitwise inclusive OR of the valid control mask bits.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>values</em></span>
    </span></p></td><td><p>
Specifies one value for each bit set to 1 in the mask.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XChangeKeyboardControl"><code class="function">XChangeKeyboardControl</code></a>
function controls the keyboard characteristics defined by the
<span class="structname">XKeyboardControl</span>
structure.
The value_mask argument specifies which values are to be changed.
</p><p>

<a class="xref" href="#XChangeKeyboardControl"><code class="function">XChangeKeyboardControl</code></a>
can generate
<span class="errorname">BadMatch</span>
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To obtain the current control values for the keyboard, use
<a class="xref" href="#XGetKeyboardControl"><code class="function">XGetKeyboardControl</code></a>.
</p><a id="idp49840668" class="indexterm"></a><div class="funcsynopsis"><a id="XGetKeyboardControl"></a><p><code class="funcdef"><strong class="fsfunc">XGetKeyboardControl</strong>(</code>Display<var class="pdparam"> *display</var>, XKeyboardState<var class="pdparam"> *values_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>values_return</em></span>
    </span></p></td><td><p>
Returns the current keyboard controls in the specified
<span class="structname">XKeyboardState</span>
structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetKeyboardControl"><code class="function">XGetKeyboardControl</code></a>
function returns the current control values for the keyboard to the
<span class="structname">XKeyboardState</span>
structure.
</p><p>

<a id="idp49847068" class="indexterm"></a>
<a id="idp49847444" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
	int key_click_percent;
	int bell_percent;
	unsigned int bell_pitch, bell_duration;
	unsigned long led_mask;
	int global_auto_repeat;
	char auto_repeats[32];
} XKeyboardState;
</pre><p>
</p><p>


For the LEDs, 
the least significant bit of led_mask corresponds to <acronym class="acronym">LED</acronym> one,
and each bit set to 1 in led_mask indicates an <acronym class="acronym">LED</acronym> that is lit.
The global_auto_repeat member can be set to
<span class="symbol">AutoRepeatModeOn</span>
or
<span class="symbol">AutoRepeatModeOff</span>.
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.
</p><p>


To turn on keyboard auto-repeat, use
<a class="xref" href="#XAutoRepeatOn"><code class="function">XAutoRepeatOn</code></a>.
</p><a id="idp49851436" class="indexterm"></a><div class="funcsynopsis"><a id="XAutoRepeatOn"></a><p><code class="funcdef"><strong class="fsfunc">XAutoRepeatOn</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XAutoRepeatOn"><code class="function">XAutoRepeatOn</code></a>
function turns on auto-repeat for the keyboard on the specified display.
</p><p>


To turn off keyboard auto-repeat, use
<a class="xref" href="#XAutoRepeatOff"><code class="function">XAutoRepeatOff</code></a>.
</p><a id="idp49856428" class="indexterm"></a><div class="funcsynopsis"><a id="XAutoRepeatOff"></a><p><code class="funcdef"><strong class="fsfunc">XAutoRepeatOff</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XAutoRepeatOff"><code class="function">XAutoRepeatOff</code></a>
function turns off auto-repeat for the keyboard on the specified display.
</p><p>


To ring the bell, use
<a class="xref" href="#XBell"><code class="function">XBell</code></a>.
</p><a id="idp49861420" class="indexterm"></a><div class="funcsynopsis"><a id="XBell"></a><p><code class="funcdef"><strong class="fsfunc">XBell</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> percent</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>percent</em></span>
    </span></p></td><td><p>
Specifies the volume for the bell,
which can range from -100 to 100 inclusive. 
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XBell"><code class="function">XBell</code></a>
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
<span class="errorname">BadValue</span>
error results.
The volume at which the bell rings
when the percent argument is nonnegative is:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
base - [(base * percent) / 100] + percent
    </p></li></ul></div><p>

The volume at which the bell rings
when the percent argument is negative is:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
base + [(base * percent) / 100]
    </p></li></ul></div><p>

To change the base volume of the bell, use
<a class="xref" href="#XChangeKeyboardControl"><code class="function">XChangeKeyboardControl</code></a>.
</p><p>

<a class="xref" href="#XBell"><code class="function">XBell</code></a>
can generate a
<span class="errorname">BadValue</span>
error.
</p><p>


To obtain a bit vector that describes the state of the keyboard, use
<a class="xref" href="#XQueryKeymap"><code class="function">XQueryKeymap</code></a>.
</p><a id="idp49871804" class="indexterm"></a><div class="funcsynopsis"><a id="XQueryKeymap"></a><p><code class="funcdef"><strong class="fsfunc">XQueryKeymap</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> keys_return[32]</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>keys_return</em></span>
    </span></p></td><td><p>
Returns an array of bytes that identifies which keys are pressed down.
Each bit represents one key of the keyboard.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XQueryKeymap"><code class="function">XQueryKeymap</code></a>
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.
</p><p>

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


To set the mapping of the pointer buttons, use
<a class="xref" href="#XSetPointerMapping"><code class="function">XSetPointerMapping</code></a>.
</p><a id="idp49879212" class="indexterm"></a><div class="funcsynopsis"><a id="XSetPointerMapping"></a><p><code class="funcdef">int <strong class="fsfunc">XSetPointerMapping</strong>(</code>Display<var class="pdparam"> *display</var>, unsignedchar<var class="pdparam"> map[]</var>, int<var class="pdparam"> nmap</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>map</em></span>
    </span></p></td><td><p>
Specifies the mapping list.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nmap</em></span>
    </span></p></td><td><p>
Specifies the number of items in the mapping list.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetPointerMapping"><code class="function">XSetPointerMapping</code></a>
function sets the mapping of the pointer.
If it succeeds, the X server generates a
<span class="symbol">MappingNotify</span>
event, and
<a class="xref" href="#XSetPointerMapping"><code class="function">XSetPointerMapping</code></a>
returns
<span class="symbol">MappingSuccess</span>.
Element map[i] defines the logical button number for the physical button
i+1.
The length of the list must be the same as
<a class="xref" href="#XGetPointerMapping"><code class="function">XGetPointerMapping</code></a>
would return,
or a
<span class="errorname">BadValue</span>
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
<span class="errorname">BadValue</span>
error results.
If any of the buttons to be altered are logically in the down state,
<a class="xref" href="#XSetPointerMapping"><code class="function">XSetPointerMapping</code></a>
returns
<span class="symbol">MappingBusy</span>,
and the mapping is not changed.
</p><p>

<a class="xref" href="#XSetPointerMapping"><code class="function">XSetPointerMapping</code></a>
can generate a
<span class="errorname">BadValue</span>
error.
</p><p>


To get the pointer mapping, use
<a class="xref" href="#XGetPointerMapping"><code class="function">XGetPointerMapping</code></a>.
</p><a id="idp49890756" class="indexterm"></a><div class="funcsynopsis"><a id="XGetPointerMapping"></a><p><code class="funcdef">int <strong class="fsfunc">XGetPointerMapping</strong>(</code>Display<var class="pdparam"> *display</var>, unsignedchar<var class="pdparam"> map_return[]</var>, int<var class="pdparam"> nmap</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>map_return</em></span>
    </span></p></td><td><p>
Returns the mapping list.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nmap</em></span>
    </span></p></td><td><p>
Specifies the number of items in the mapping list.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetPointerMapping"><code class="function">XGetPointerMapping</code></a>
function returns the current mapping of the pointer.
Pointer buttons are numbered starting from one.
<a class="xref" href="#XGetPointerMapping"><code class="function">XGetPointerMapping</code></a>
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.
</p><p>


To control the pointer's interactive feel, use
<a class="xref" href="#XChangePointerControl"><code class="function">XChangePointerControl</code></a>.
</p><a id="idp49899684" class="indexterm"></a><div class="funcsynopsis"><a id="XChangePointerControl"></a><p><code class="funcdef"><strong class="fsfunc">XChangePointerControl</strong>(</code>Display<var class="pdparam"> *display</var>, Booldo_accel,<var class="pdparam"> do_threshold</var>, intaccel_numerator,<var class="pdparam"> accel_denominator</var>, int<var class="pdparam"> threshold</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>do_accel</em></span>
    </span></p></td><td><p>
Specifies a Boolean value that controls whether the values for 
the accel_numerator or accel_denominator are used.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>do_threshold</em></span>
    </span></p></td><td><p>
Specifies a Boolean value that controls whether the value for the 
threshold is used.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>accel_numerator</em></span>
    </span></p></td><td><p>
Specifies the numerator for the acceleration multiplier.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>accel_denominator</em></span>
    </span></p></td><td><p>
Specifies the denominator for the acceleration multiplier.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>threshold</em></span>
    </span></p></td><td><p>
Specifies the acceleration threshold.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XChangePointerControl"><code class="function">XChangePointerControl</code></a>
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 
<span class="symbol">True</span>
for the pointer values to be set,
or the parameters are unchanged.
Negative values (other than -1) generate a
<span class="errorname">BadValue</span>
error, as does a zero value
for the accel_denominator argument.
</p><p>

<a class="xref" href="#XChangePointerControl"><code class="function">XChangePointerControl</code></a>
can generate a
<span class="errorname">BadValue</span>
error.
</p><p>


To get the current pointer parameters, use
<a class="xref" href="#XGetPointerControl"><code class="function">XGetPointerControl</code></a>.
</p><a id="idp49913796" class="indexterm"></a><div class="funcsynopsis"><a id="XGetPointerControl"></a><p><code class="funcdef"><strong class="fsfunc">XGetPointerControl</strong>(</code>Display<var class="pdparam"> *display</var>, int*accel_numerator_return,<var class="pdparam"> *accel_denominator_return</var>, int<var class="pdparam"> *threshold_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>accel_numerator_return</em></span>
    </span></p></td><td><p>
Returns the numerator for the acceleration multiplier.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>accel_denominator_return</em></span>
    </span></p></td><td><p>
Returns the denominator for the acceleration multiplier.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>threshold_return</em></span>
    </span></p></td><td><p>
Returns the acceleration threshold.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetPointerControl"><code class="function">XGetPointerControl</code></a>
function returns the pointer's current acceleration multiplier
and acceleration threshold.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Manipulating_the_Keyboard_Encoding"></a>Manipulating the Keyboard Encoding</h2></div></div></div><p>

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.
</p><p>

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
<code class="filename">&lt;X11/keysymdef.h&gt;</code>.
<a id="idp49925300" class="indexterm"></a>
<a id="idp49926100" class="indexterm"></a>
<a id="idp49926908" class="indexterm"></a>
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 
<code class="filename">&lt;X11/keysym.h&gt;</code>,
<a id="idp49928404" class="indexterm"></a>
<a id="idp49929204" class="indexterm"></a>
<a id="idp49930012" class="indexterm"></a>
which defines symbols for ISO Latin 1-4, Greek, and miscellaneous.
</p><p>

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
<span class="symbol">NoSymbol</span>
entries) is 
a single KeySym ``<span class="emphasis"><em>K</em></span>'',
then the list is treated as if it were the list 
``<span class="emphasis"><em>K</em></span> NoSymbol <span class="emphasis"><em>K</em></span> NoSymbol''.
If the list (ignoring trailing
<span class="symbol">NoSymbol</span>
entries) is a pair of KeySyms ``<span class="emphasis"><em>K1 K2</em></span>'',
then the list is treated as if it were the list ``<span class="emphasis"><em>K1 K2 K1 K2</em></span>''.
If the list (ignoring trailing
<span class="symbol">NoSymbol</span>
entries) is a triple of KeySyms ``<span class="emphasis"><em>K1 K2 K3</em></span>'',
then the list is treated as if it were the list ``<span class="emphasis"><em>K1 K2 K3</em></span> NoSymbol''.
When an explicit ``void'' element is desired in the list,
the value
<span class="symbol">VoidSymbol</span>
can be used.
</p><p>

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
<span class="symbol">NoSymbol</span>,
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 ``<span class="emphasis"><em>K</em></span>'' 
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 ``<span class="emphasis"><em>K</em></span>'' and the second element were 
the uppercase form of ``<span class="emphasis"><em>K</em></span>''.
</p><p>

The standard rules for obtaining a KeySym from a
<span class="symbol">KeyPress</span>
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
<span class="symbol">Mod1</span>
through
<span class="symbol">Mod5</span>.
This modifier is called the <span class="emphasis"><em>group modifier</em></span>.
For any KeyCode,
Group 1 is used when the group modifier is off,
and Group 2 is used when the group modifier is on.
</p><p>

The
<span class="symbol">Lock</span>
modifier is interpreted as CapsLock when the KeySym named XK_Caps_Lock
is attached to some KeyCode and that KeyCode is attached to the
<span class="symbol">Lock</span>
modifier.  The
<span class="symbol">Lock</span>
modifier is interpreted as ShiftLock when the KeySym named XK_Shift_Lock
is attached to some KeyCode and that KeyCode is attached to the
<span class="symbol">Lock</span>
modifier.  If the
<span class="symbol">Lock</span>
modifier could be interpreted as both
CapsLock and ShiftLock, the CapsLock interpretation is used.
</p><p>

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
<span class="symbol">Mod1</span>
through
<span class="symbol">Mod5</span>.
This modifier is called the
<span class="emphasis"><em>numlock modifier</em></span>.  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.
</p><p>

Within a group, the choice of KeySym is determined by applying the first
rule that is satisfied from the following list:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The numlock modifier is on and the second KeySym is a keypad KeySym.  In
this case, if the
<span class="symbol">Shift</span>
modifier is on, or if the
<span class="symbol">Lock</span>
modifier is on and
is interpreted as ShiftLock, then the first KeySym is used, otherwise the
second KeySym is used.
    </p></li><li class="listitem"><p>
The
<span class="symbol">Shift</span>
and
<span class="symbol">Lock</span>
modifiers are both off.  In this case, the first
KeySym is used.
    </p></li><li class="listitem"><p>
The
<span class="symbol">Shift</span>
modifier is off, and the
<span class="symbol">Lock</span>
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.
    </p></li><li class="listitem"><p>
The
<span class="symbol">Shift</span>
modifier is on, and the
<span class="symbol">Lock</span>
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.
    </p></li><li class="listitem"><p>
The
<span class="symbol">Shift</span>
modifier is on, or the
<span class="symbol">Lock</span>
modifier is on and is interpreted
as ShiftLock, or both.  In this case, the second KeySym is used.
    </p></li></ul></div><p>

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.

</p><p>

To obtain the legal KeyCodes for a display, use
<a class="xref" href="#XDisplayKeycodes"><code class="function">XDisplayKeycodes</code></a>.
</p><a id="idp49948764" class="indexterm"></a><div class="funcsynopsis"><a id="XDisplayKeycodes"></a><p><code class="funcdef"><strong class="fsfunc">XDisplayKeycodes</strong>(</code>Display<var class="pdparam"> *display</var>, int*min_keycodes_return,<var class="pdparam"> *max_keycodes_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>min_keycodes_return</em></span>
    </span></p></td><td><p>
Returns the minimum number of KeyCodes.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>max_keycodes_return</em></span>
    </span></p></td><td><p>
Returns the maximum number of KeyCodes.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDisplayKeycodes"><code class="function">XDisplayKeycodes</code></a>
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.

</p><p>

To obtain the symbols for the specified KeyCodes, use
<a class="xref" href="#XGetKeyboardMapping"><code class="function">XGetKeyboardMapping</code></a>.
</p><a id="idp49956756" class="indexterm"></a><div class="funcsynopsis"><a id="XGetKeyboardMapping"></a><p><code class="funcdef">KeySym *<strong class="fsfunc">XGetKeyboardMapping</strong>(</code>Display<var class="pdparam"> *display</var>, KeyCode<var class="pdparam"> first_keycode</var>, int<var class="pdparam"> keycode_count</var>, int<var class="pdparam"> *keysyms_per_keycode_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>first_keycode</em></span>
    </span></p></td><td><p>
Specifies the first KeyCode that is to be returned.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>keycode_count</em></span>
    </span></p></td><td><p>
Specifies the number of KeyCodes that are to be returned.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>keysyms_per_keycode_return</em></span>
    </span></p></td><td><p>
Returns the number of KeySyms per KeyCode.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetKeyboardMapping"><code class="function">XGetKeyboardMapping</code></a>
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
<a class="xref" href="#XDisplayKeycodes"><code class="function">XDisplayKeycodes</code></a>,
or a
<span class="errorname">BadValue</span>
error results.
In addition, the following expression must be less than or equal 
to max_keycode as returned by
<a class="xref" href="#XDisplayKeycodes"><code class="function">XDisplayKeycodes</code></a>:
</p><p>

</p><pre class="literallayout">
first_keycode + keycode_count - 1
</pre><p>
</p><p>

If this is not the case, a 
<span class="errorname">BadValue</span>
error results. 
The number of elements in the KeySyms list is:
</p><p>

</p><pre class="literallayout">
keycode_count * keysyms_per_keycode_return
</pre><p>
</p><p>

KeySym number N, counting from zero, for KeyCode K has the following index
in the list, counting from zero: 
</p><pre class="literallayout">
(K - first_code) * keysyms_per_code_return + N
</pre><p>
</p><p>

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 
<span class="symbol">NoSymbol</span>
is used to fill in unused elements for
individual KeyCodes.
To free the storage returned by 
<a class="xref" href="#XGetKeyboardMapping"><code class="function">XGetKeyboardMapping</code></a>,
use
<a class="xref" href="#XFree"></a>.
</p><p>

<a class="xref" href="#XGetKeyboardMapping"><code class="function">XGetKeyboardMapping</code></a>
can generate a
<span class="errorname">BadValue</span>
error.
</p><p>


To change the keyboard mapping, use
<a class="xref" href="#XChangeKeyboardMapping"><code class="function">XChangeKeyboardMapping</code></a>.
</p><a id="idp49973364" class="indexterm"></a><div class="funcsynopsis"><a id="XChangeKeyboardMapping"></a><p><code class="funcdef"><strong class="fsfunc">XChangeKeyboardMapping</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> first_keycode</var>, int<var class="pdparam"> keysyms_per_keycode</var>, KeySym<var class="pdparam"> *keysyms</var>, int<var class="pdparam"> num_codes</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>first_keycode</em></span>
    </span></p></td><td><p>
Specifies the first KeyCode that is to be changed.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>keysyms_per_keycode</em></span>
    </span></p></td><td><p>
Specifies the number of KeySyms per KeyCode.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>keysyms</em></span>
    </span></p></td><td><p>
Specifies an array of KeySyms.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>num_codes</em></span>
    </span></p></td><td><p>
Specifies the number of KeyCodes that are to be changed.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XChangeKeyboardMapping"><code class="function">XChangeKeyboardMapping</code></a>
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:
</p><p>

</p><pre class="literallayout">
num_codes * keysyms_per_keycode
</pre><p>
</p><p>

The specified first_keycode must be greater than or equal to min_keycode 
returned by
<a class="xref" href="#XDisplayKeycodes"><code class="function">XDisplayKeycodes</code></a>,
or a 
<span class="errorname">BadValue</span>
error results.
In addition, the following expression must be less than or equal to 
max_keycode as returned by
<a class="xref" href="#XDisplayKeycodes"><code class="function">XDisplayKeycodes</code></a>,
or a
<span class="errorname">BadValue</span>
error results:
</p><p>

</p><pre class="literallayout">
first_keycode + num_codes - 1
</pre><p>
</p><p>

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

</p><pre class="literallayout">
(K - first_keycode) * keysyms_per_keycode + N
</pre><p>
</p><p>

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 
<span class="symbol">NoSymbol</span>
should be used to fill in unused elements 
for individual KeyCodes.  
It is legal for 
<span class="symbol">NoSymbol</span>
to appear in nontrailing positions
of the effective list for a KeyCode.
<a class="xref" href="#XChangeKeyboardMapping"><code class="function">XChangeKeyboardMapping</code></a>
generates a 
<span class="symbol">MappingNotify</span>
event.
</p><p>

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

<a class="xref" href="#XChangeKeyboardMapping"><code class="function">XChangeKeyboardMapping</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadValue</span>
errors.
</p><p>

The next six functions make use of the 
<span class="structname">XModifierKeymap</span>
data structure, which contains:
</p><p>

<a id="idp49992468" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
	int max_keypermod;	/* This server's max number of keys per modifier */
	KeyCode *modifiermap;	/* An 8 by max_keypermod array of the modifiers */
} XModifierKeymap;
</pre><p>
</p><p>


To create an
<span class="structname">XModifierKeymap</span>
structure, use
<a class="xref" href="#XNewModifiermap"><code class="function">XNewModifiermap</code></a>.
</p><a id="idp49994924" class="indexterm"></a><div class="funcsynopsis"><a id="XNewModifiermap"></a><p><code class="funcdef">XModifierKeymap *<strong class="fsfunc">XNewModifiermap</strong>(</code>int<var class="pdparam"> max_keys_per_mod</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>max_keys_per_mod</em></span>
    </span></p></td><td><p>
Specifies the number of KeyCode entries preallocated to the modifiers
in the map.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XNewModifiermap"><code class="function">XNewModifiermap</code></a>
function returns a pointer to
<span class="structname">XModifierKeymap</span>
structure for later use.
</p><p>


To add a new entry to an 
<span class="structname">XModifierKeymap</span>
structure, use
<a class="xref" href="#XInsertModifiermapEntry"><code class="function">XInsertModifiermapEntry</code></a>.
</p><a id="idp50000364" class="indexterm"></a><div class="funcsynopsis"><a id="XInsertModifiermapEntry"></a><p><code class="funcdef">XModifierKeymap *<strong class="fsfunc">XInsertModifiermapEntry</strong>(</code>XModifierKeymap<var class="pdparam"> *modmap</var>, KeyCode<var class="pdparam"> keycode_entry</var>, int<var class="pdparam"> modifier</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>modmap</em></span>
    </span></p></td><td><p>
Specifies the 
<span class="structname">XModifierKeymap</span>
structure.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>keycode_entry</em></span>
    </span></p></td><td><p>
Specifies the KeyCode. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>modifier</em></span>
    </span></p></td><td><p>
Specifies the modifier.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XInsertModifiermapEntry"><code class="function">XInsertModifiermapEntry</code></a>
function adds the specified KeyCode to the set that controls the specified
modifier and returns the resulting
<span class="structname">XModifierKeymap</span>
structure (expanded as needed).
</p><p>


To delete an entry from an 
<span class="structname">XModifierKeymap</span>
structure, use
<a class="xref" href="#XDeleteModifiermapEntry"><code class="function">XDeleteModifiermapEntry</code></a>.
</p><a id="idp50009180" class="indexterm"></a><div class="funcsynopsis"><a id="XDeleteModifiermapEntry"></a><p><code class="funcdef">XModifierKeymap *<strong class="fsfunc">XDeleteModifiermapEntry</strong>(</code>XModifierKeymap<var class="pdparam"> *modmap</var>, KeyCode<var class="pdparam"> keycode_entry</var>, int<var class="pdparam"> modifier</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>modmap</em></span>
    </span></p></td><td><p>
Specifies the 
<span class="structname">XModifierKeymap</span>
structure.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>keycode_entry</em></span>
    </span></p></td><td><p>
Specifies the KeyCode. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>modifier</em></span>
    </span></p></td><td><p>
Specifies the modifier.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDeleteModifiermapEntry"><code class="function">XDeleteModifiermapEntry</code></a>
function deletes the specified KeyCode from the set that controls the
specified modifier and returns a pointer to the resulting
<span class="structname">XModifierKeymap</span>
structure.
</p><p>


To destroy an
<span class="structname">XModifierKeymap</span>
structure, use
<a class="xref" href="#XFreeModifiermap"><code class="function">XFreeModifiermap</code></a>.
</p><a id="idp50017932" class="indexterm"></a><div class="funcsynopsis"><a id="XFreeModifiermap"></a><p><code class="funcdef"><strong class="fsfunc">XFreeModifiermap</strong>(</code>XModifierKeymap<var class="pdparam"> *modmap</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>modmap</em></span>
    </span></p></td><td><p>
Specifies the 
<span class="structname">XModifierKeymap</span>
structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFreeModifiermap"><code class="function">XFreeModifiermap</code></a>
function frees the specified
<span class="structname">XModifierKeymap</span>
structure.
</p><p>


To set the KeyCodes to be used as modifiers, use
<a class="xref" href="#XSetModifierMapping"><code class="function">XSetModifierMapping</code></a>.
</p><a id="idp50023268" class="indexterm"></a><div class="funcsynopsis"><a id="XSetModifierMapping"></a><p><code class="funcdef">int <strong class="fsfunc">XSetModifierMapping</strong>(</code>Display<var class="pdparam"> *display</var>, XModifierKeymap<var class="pdparam"> *modmap</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>modmap</em></span>
    </span></p></td><td><p>
Specifies the 
<span class="structname">XModifierKeymap</span>
structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetModifierMapping"><code class="function">XSetModifierMapping</code></a>
function specifies the KeyCodes of the keys (if any) that are to be used 
as modifiers.
If it succeeds,
the X server generates a
<span class="symbol">MappingNotify</span>
event, and
<a class="xref" href="#XSetModifierMapping"><code class="function">XSetModifierMapping</code></a>
returns
<span class="symbol">MappingSuccess</span>.
X permits at most 8 modifier keys.
If more than 8 are specified in the
<span class="structname">XModifierKeymap</span>
structure, a
<span class="errorname">BadLength</span>
error results.
</p><p>

The modifiermap member of the 
<span class="structname">XModifierKeymap</span>
structure contains 8 sets of max_keypermod KeyCodes, 
one for each modifier in the order 
<span class="symbol">Shift</span>,
<span class="symbol">Lock</span>,
<span class="symbol">Control</span>,
<span class="symbol">Mod1</span>,
<span class="symbol">Mod2</span>,
<span class="symbol">Mod3</span>,
<span class="symbol">Mod4</span>,
and 
<span class="symbol">Mod5</span>.
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 
<span class="type">Display</span>
structure,
or a 
<span class="errorname">BadValue</span>
error results.
</p><p>

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
<span class="symbol">MappingFailed</span>,
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, 
<a class="xref" href="#XSetModifierMapping"><code class="function">XSetModifierMapping</code></a>
returns
<span class="symbol">MappingBusy</span>,
and none of the modifiers is changed.
</p><p>

<a class="xref" href="#XSetModifierMapping"><code class="function">XSetModifierMapping</code></a>
can generate
<span class="errorname">BadAlloc</span>
and 
<span class="errorname">BadValue</span>
errors.
</p><p>


To obtain the KeyCodes used as modifiers, use
<a class="xref" href="#XGetModifierMapping"><code class="function">XGetModifierMapping</code></a>.
</p><a id="idp50036852" class="indexterm"></a><div class="funcsynopsis"><a id="XGetModifierMapping"></a><p><code class="funcdef">XModifierKeymap *<strong class="fsfunc">XGetModifierMapping</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetModifierMapping"><code class="function">XGetModifierMapping</code></a>
function returns a pointer to a newly created
<span class="structname">XModifierKeymap</span>
structure that contains the keys being used as modifiers.
The structure should be freed after use by calling
<a class="xref" href="#XFreeModifiermap"><code class="function">XFreeModifiermap</code></a>.
If only zero values appear in the set for any modifier, 
that modifier is disabled.



</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Locales_and_Internationalized_Text_Functions"></a>Chapter 13. Locales and Internationalized Text Functions</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#X_Locale_Management">X Locale Management</a></span></dt><dt><span class="sect1"><a href="#Locale_and_Modifier_Dependencies">Locale and Modifier Dependencies</a></span></dt><dt><span class="sect1"><a href="#Variable_Argument_Lists">Variable Argument Lists</a></span></dt><dt><span class="sect1"><a href="#Output_Methods">Output Methods</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Output_Method_Overview">Output Method Overview</a></span></dt><dt><span class="sect2"><a href="#Output_Method_Functions">Output Method Functions</a></span></dt><dt><span class="sect2"><a href="#X_Output_Method_Values">X Output Method Values</a></span></dt><dt><span class="sect2"><a href="#Output_Context_Functions">Output Context Functions</a></span></dt><dt><span class="sect2"><a href="#Output_Context_Values">Output Context Values</a></span></dt><dt><span class="sect2"><a href="#Creating_and_Freeing_a_Font_Set">Creating and Freeing a Font Set</a></span></dt><dt><span class="sect2"><a href="#Obtaining_Font_Set_Metrics">Obtaining Font Set Metrics</a></span></dt><dt><span class="sect2"><a href="#Drawing_Text_Using_Font_Sets">Drawing Text Using Font Sets</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Input_Methods">Input Methods</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Input_Method_Overview">Input Method Overview</a></span></dt><dt><span class="sect2"><a href="#Input_Method_Management">Input Method Management</a></span></dt><dt><span class="sect2"><a href="#Input_Method_Functions">Input Method Functions</a></span></dt><dt><span class="sect2"><a href="#Input_Method_Values">Input Method Values</a></span></dt><dt><span class="sect2"><a href="#Input_Context_Functions">Input Context Functions</a></span></dt><dt><span class="sect2"><a href="#Input_Context_Values">Input Context Values</a></span></dt><dt><span class="sect2"><a href="#Input_Method_Callback_Semantics">Input Method Callback Semantics</a></span></dt><dt><span class="sect2"><a href="#Event_Filtering_b">Event Filtering</a></span></dt><dt><span class="sect2"><a href="#Getting_Keyboard_Input_b">Getting Keyboard Input</a></span></dt><dt><span class="sect2"><a href="#Input_Method_Conventions">Input Method Conventions</a></span></dt></dl></dd><dt><span class="sect1"><a href="#String_Constants">String Constants</a></span></dt></dl></div><p>
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 localization. A goal of
internationalization is to permit localization without program source modifications or recompilation.
</p><p>
As one of the localization mechanisms, Xlib provides an X Input Method (<acronym class="acronym">XIM</acronym>)
functional interface for internationalized text input and an X Output Method
(<acronym class="acronym">XOM</acronym>) functional interface for internationalized text output.
</p><p>
Internationalization in X is based on the concept of a locale. A locale defines the localized
behavior of a program at run time. Locales affect Xlib in its:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Encoding and processing of input method text</p></li><li class="listitem"><p>Encoding of resource files and values</p></li><li class="listitem"><p>Encoding and imaging of text strings</p></li><li class="listitem"><p>Encoding and decoding for inter-client text communication</p></li></ul></div><p>
•
Encoding and decoding for inter-client text communication
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.
</p><p>
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.
</p><p>
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.
</p><p>
The remainder of this chapter discusses:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>X locale management</p></li><li class="listitem"><p>Locale and modifier dependencies</p></li><li class="listitem"><p>Variable argument lists</p></li><li class="listitem"><p>Output methods</p></li><li class="listitem"><p>Input methods</p></li><li class="listitem"><p>String constants</p></li></ul></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X_Locale_Management"></a>X Locale Management</h2></div></div></div><p>

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
<code class="function">setlocale</code>.
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 <span class="emphasis"><em>current locale</em></span>.
An implementation is permitted to provide implementation-dependent
mechanisms for announcing the locale in addition to
<code class="function">setlocale</code>.
</p><p>

On implementations that do not conform to the ANSI C library, 
the locale announcement method is Xlib implementation-dependent.
</p><p>

The mechanism by which the semantic operation of Xlib is defined
for a specific locale is implementation-dependent.
</p><p>


X is not required to support all the locales supported by the host.
To determine if the current locale is supported by X, use
<code class="function">XSupportsLocale</code>.
</p><p>Bool XSupportsLocale()</p><p>


The 
<code class="function">XSupportsLocale</code>
function returns 
<span class="symbol">True</span>
if Xlib functions are capable of operating under the current locale.
If it returns 
<span class="symbol">False</span>,
Xlib locale-dependent functions for which the 
<span class="symbol">XLocaleNotSupported</span>
return status is defined will return 
<span class="symbol">XLocaleNotSupported</span>.
Other Xlib locale-dependent routines will operate in the ``C'' locale.
</p><p>

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,
<code class="function">XSupportsLocale</code>,
and 
<a class="xref" href="#XSetLocaleModifiers"><code class="function">XSetLocaleModifiers</code></a>.
</p><p>

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.
</p><p>


To configure Xlib locale modifiers for the current locale, use
<a class="xref" href="#XSetLocaleModifiers"><code class="function">XSetLocaleModifiers</code></a>.
</p><a id="idp48617276" class="indexterm"></a><div class="funcsynopsis"><a id="XSetLocaleModifiers"></a><p><code class="funcdef">char *<strong class="fsfunc">XSetLocaleModifiers</strong>(</code>char<var class="pdparam"> *modifier_list</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>modifier_list</em></span>
    </span></p></td><td><p>
Specifies the modifiers.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetLocaleModifiers"><code class="function">XSetLocaleModifiers</code></a>
function sets the X modifiers for the current locale setting.
The modifier_list argument is a null-terminated string of the form
``{@<span class="emphasis"><em>category</em></span>=<span class="emphasis"><em>value</em></span>}'', that is,
having zero or more concatenated ``@<span class="emphasis"><em>category</em></span>=<span class="emphasis"><em>value</em></span>''
entries, where <span class="emphasis"><em>category</em></span> is a category name 
and <span class="emphasis"><em>value</em></span> is the (possibly empty) setting for that category.
The values are encoded in the current locale.
Category names are restricted to the <acronym class="acronym">POSIX</acronym> Portable Filename Character Set.
</p><p>

The local host X locale modifiers announcer (on <acronym class="acronym">POSIX</acronym>-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.
</p><p>

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,
<a class="xref" href="#XSetLocaleModifiers"><code class="function">XSetLocaleModifiers</code></a>
also returns a pointer to such a string,
and the current locale modifiers are not changed.
</p><p>

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.
</p><p>

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
<a class="xref" href="#XSetLocaleModifiers"><code class="function">XSetLocaleModifiers</code></a>
with a non-NULL modifier_list after setting the locale
before they call any locale-dependent Xlib routine.
</p><p>

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.
</p><p>

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.
</p><p>

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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
A command line option
    </p></li><li class="listitem"><p>
A resource
    </p></li><li class="listitem"><p>
The empty string ("")
    </p></li></ul></div><p>

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.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Locale_and_Modifier_Dependencies"></a>Locale and Modifier Dependencies</h2></div></div></div><p>

The internationalized Xlib functions operate in the current locale
configured by the host environment and X locale modifiers set by
<a class="xref" href="#XSetLocaleModifiers"><code class="function">XSetLocaleModifiers</code></a>
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:
</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">Locale from</th><th align="left">Affects the Function</th><th align="left">In</th></tr></thead><tbody><tr><td colspan="3" align="left">
      <span class="bold"><strong>Locale Query/Configuration:</strong></span></td></tr><tr><td rowspan="2" align="left"><code class="function">setlocale</code></td><td align="left"><code class="function">XSupportsLocale</code></td><td align="left">Locale queried</td></tr><tr><td align="left"><a class="xref" href="#XSetLocaleModifiers"><code class="function">XSetLocaleModifiers</code></a></td><td align="left">Locale modified</td></tr><tr><td colspan="3" align="left">
      <span class="bold"><strong>Resources:</strong></span></td></tr><tr><td align="left"><code class="function">setlocale</code></td><td align="left">
        <p><a class="xref" href="#XrmGetFileDatabase"><code class="function">XrmGetFileDatabase</code></a></p>
        <p><a class="xref" href="#XrmGetStringDatabase"><code class="function">XrmGetStringDatabase</code></a></p>
      </td><td align="left">Locale of <span class="type">XrmDatabase</span></td></tr><tr><td align="left"><span class="type">XrmDatabase</span></td><td align="left">
        <p><a class="xref" href="#XrmPutFileDatabase"><code class="function">XrmPutFileDatabase</code></a></p>
        <p><a class="xref" href="#XrmLocaleOfDatabase"><code class="function">XrmLocaleOfDatabase</code></a></p>
      </td><td align="left">Locale of <span class="type">XrmDatabase</span></td></tr><tr><td colspan="3" align="left">
      <span class="bold"><strong>Setting Standard Properties:</strong></span></td></tr><tr><td align="left"><code class="function">setlocale</code></td><td align="left"><a class="xref" href="#XmbSetWMProperties"><code class="function">XmbSetWMProperties</code></a></td><td align="left">Encoding of supplied/returned
      text (some WM_ property
      text in environment locale)</td></tr><tr><td align="left"><code class="function">setlocale</code></td><td align="left">
        <p><a class="xref" href="#XmbTextPropertyToTextList"><code class="function">XmbTextPropertyToTextList</code></a></p>
        <p><a class="xref" href="#XwcTextPropertyToTextList"><code class="function">XwcTextPropertyToTextList</code></a></p>
        <p><a class="xref" href="#XmbTextListToTextProperty"><code class="function">XmbTextListToTextProperty</code></a></p>
        <p><a class="xref" href="#XwcTextListToTextProperty"><code class="function">XwcTextListToTextProperty</code></a></p>
      </td><td align="left">Encoding of supplied/returned text</td></tr><tr><td colspan="3" align="left">
      <span class="bold"><strong>Text Input:</strong></span></td></tr><tr><td rowspan="3" align="left"><code class="function">setlocale</code></td><td align="left"><a class="xref" href="#XOpenIM"><code class="function">XOpenIM</code></a></td><td align="left"><acronym class="acronym">XIM</acronym> input method selection</td></tr><tr><td align="left"><a class="xref" href="#XRegisterIMInstantiateCallback"><code class="function">XRegisterIMInstantiateCallback</code></a></td><td align="left"><acronym class="acronym">XIM</acronym> selection</td></tr><tr><td align="left"><a class="xref" href="#XUnregisterIMInstantiateCallback"><code class="function">XUnregisterIMInstantiateCallback</code></a></td><td align="left"><acronym class="acronym">XIM</acronym> selection</td></tr><tr><td rowspan="2" align="left"><span class="type">XIM</span></td><td align="left"><a class="xref" href="#XCreateIC"><code class="function">XCreateIC</code></a></td><td align="left"><acronym class="acronym">XIC</acronym> input method configuration</td></tr><tr><td align="left"><a class="xref" href="#XLocaleOfIM"><code class="function">XLocaleOfIM</code></a>,  and so on</td><td align="left">Queried locale</td></tr><tr><td rowspan="2" align="left"><span class="type">XIC</span></td><td align="left"><a class="xref" href="#XmbLookupString"><code class="function">XmbLookupString</code></a></td><td align="left">Keyboard layout</td></tr><tr><td align="left"><a class="xref" href="#XwcLookupString"><code class="function">XwcLookupString</code></a></td><td align="left">Encoding of returned text</td></tr><tr><td colspan="3" align="left">
      <span class="bold"><strong>Text Drawing:</strong></span></td></tr><tr><td rowspan="2" align="left"><code class="function">setlocale</code></td><td align="left"><a class="xref" href="#XOpenOM"><code class="function">XOpenOM</code></a></td><td align="left"><acronym class="acronym">XOM</acronym> output method selection</td></tr><tr><td align="left"><a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a></td><td align="left">Charsets of fonts in XFontSet</td></tr><tr><td rowspan="2" align="left"><span class="type">XOM</span></td><td align="left"><a class="xref" href="#XCreateOC"><code class="function">XCreateOC</code></a></td><td align="left"><acronym class="acronym">XOC</acronym> output method configuration</td></tr><tr><td align="left"><a class="xref" href="#XLocaleOfOM"><code class="function">XLocaleOfOM</code></a>,  and so on</td><td align="left">Queried locale</td></tr><tr><td rowspan="3" align="left"><span class="type">XFontSet</span></td><td align="left"><a class="xref" href="#XmbDrawText"><code class="function">XmbDrawText</code></a>,</td><td align="left">Locale of supplied text</td></tr><tr><td align="left"><a class="xref" href="#XwcDrawText"><code class="function">XwcDrawText</code></a>, and so on</td><td align="left">Locale of supplied text</td></tr><tr><td align="left">
        <p><a class="xref" href="#XExtentsOfFontSet"><code class="function">XExtentsOfFontSet</code></a>,  and so on</p>
        <p><a class="xref" href="#XmbTextExtents"><code class="function">XmbTextExtents</code></a>,</p>
        <p><code class="function">XwcTextExtents</code>,  and so on</p>
      </td><td align="left">Locale-dependent metrics</td></tr><tr><td colspan="3" align="left">
      <span class="bold"><strong>Xlib Errors:</strong></span></td></tr><tr><td align="left"><code class="function">setlocale</code></td><td align="left">
        <p><a class="xref" href="#XGetErrorDatabaseText"><code class="function">XGetErrorDatabaseText</code></a>,</p>
        <p><a class="xref" href="#XGetErrorText"><code class="function">XGetErrorText</code></a>,  and so on</p>
      </td><td align="left">Locale of error message</td></tr></tbody></table></div><p>

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.
</p><p>

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.
</p><p>

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 
<a class="xref" href="#XSetLocaleModifiers"><code class="function">XSetLocaleModifiers</code></a>
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 
<code class="function">mblen</code>,
<code class="function">mbtowc</code>,
<code class="function">wctomb</code>,
and 
<code class="function">strtok</code>.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Variable_Argument_Lists"></a>Variable Argument Lists</h2></div></div></div><p>

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 
<span class="type">XPointer</span>.
A name argument that is NULL identifies the end of the list. 
</p><p>

A variable-length argument list may contain a nested list.
If the name 
<span class="symbol">XNVaNestedList</span>
is specified in place of an argument name,
then the following value is interpreted as an 
<span class="type">XVaNestedList</span>
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.
</p><p>


To allocate a nested variable argument list dynamically, use
<a class="xref" href="#XVaCreateNestedList"><code class="function">XVaCreateNestedList</code></a>.
</p><a id="idp49339844" class="indexterm"></a><div class="funcsynopsis"><a id="XVaCreateNestedList"></a><p><code class="funcdef">XVaNestedList <strong class="fsfunc">XVaCreateNestedList</strong>(</code>int<var class="pdparam"> dummy</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>dummy</em></span>
    </span></p></td><td><p>
Specifies an unused argument (required by ANSI C).

      </p></td></tr><tr><td><p><span class="term">
      ...
    </span></p></td><td><p>
Specifies the variable length argument list(Al.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XVaCreateNestedList"><code class="function">XVaCreateNestedList</code></a>
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
<a class="xref" href="#XFree"></a>
when it is no longer needed.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Output_Methods"></a>Output Methods</h2></div></div></div><p>

This section provides discussions of the following X Output Method
(<acronym class="acronym">XOM</acronym>) topics:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Output method overview
    </p></li><li class="listitem"><p>
Output method functions
    </p></li><li class="listitem"><p>
Output method values
    </p></li><li class="listitem"><p>
Output context functions
    </p></li><li class="listitem"><p>
Output context values
    </p></li><li class="listitem"><p>
Creating and freeing a font set
    </p></li><li class="listitem"><p>
Obtaining font set metrics
    </p></li><li class="listitem"><p>
Drawing text using font sets
    </p></li></ul></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Output_Method_Overview"></a>Output Method Overview</h3></div></div></div><p>

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.
</p><p>

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.
</p><p>

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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Creating a set of fonts required to draw locale-dependent text.
    </p></li><li class="listitem"><p>
Drawing locale-dependent text with a font set without the caller
needing to be aware of locale dependencies.
    </p></li><li class="listitem"><p>
Obtaining the escapement and extents in pixels of locale-dependent text.
    </p></li><li class="listitem"><p>
Determining if bidirectional or context-dependent drawing is required
in a specific locale with a specific font set.
    </p></li></ul></div><p>

Two different abstractions are used in the representation of
the output method for clients.
</p><p>

The abstraction used to communicate with an output method
is an opaque data structure represented by the 
<span class="type">XOM</span>
data type.
The abstraction for representing the state of a particular output thread
is called an <span class="emphasis"><em>output context</em></span>.
The Xlib representation of an output context is an 
<span class="type">XOC</span>,
which is compatible with 
<span class="type">XFontSet</span>
in terms of its functional interface, but is 
a broader, more generalized abstraction.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Output_Method_Functions"></a>Output Method Functions</h3></div></div></div><p>

To open an output method, use
<a class="xref" href="#XOpenOM"><code class="function">XOpenOM</code></a>.
</p><a id="idp49361788" class="indexterm"></a><div class="funcsynopsis"><a id="XOpenOM"></a><p><code class="funcdef">XOM <strong class="fsfunc">XOpenOM</strong>(</code>Display<var class="pdparam"> *display</var>, XrmDatabase<var class="pdparam"> db</var>, char<var class="pdparam"> *res_name</var>, char<var class="pdparam"> *res_class</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>db</em></span>
    </span></p></td><td><p>
Specifies a pointer to the resource database.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>res_name</em></span>
    </span></p></td><td><p>
Specifies the full resource name of the application.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>res_class</em></span>
    </span></p></td><td><p>
Specifies the full class name of the application.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XOpenOM"><code class="function">XOpenOM</code></a>
function opens an output method
matching the current locale and modifiers specification.
The current locale and modifiers are bound to the output method
when
<a class="xref" href="#XOpenOM"><code class="function">XOpenOM</code></a>
is called.
The locale associated with an output method cannot be changed.
</p><p>

The specific output method to which this call will be routed
is identified on the basis of the current locale and modifiers.
<a class="xref" href="#XOpenOM"><code class="function">XOpenOM</code></a>
will identify a default output method corresponding to the
current locale.
That default can be modified using 
<a class="xref" href="#XSetLocaleModifiers"><code class="function">XSetLocaleModifiers</code></a>
to set the output method modifier.
</p><p>

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.
</p><p>

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.
</p><p>

The res_name and res_class arguments are not assumed to exist beyond
the call to
<a class="xref" href="#XOpenOM"><code class="function">XOpenOM</code></a>.
The specified resource database is assumed to exist for the lifetime
of the output method.
</p><p>

<a class="xref" href="#XOpenOM"><code class="function">XOpenOM</code></a>
returns NULL if no output method could be opened.
</p><p>


To close an output method, use
<a class="xref" href="#XCloseOM"><code class="function">XCloseOM</code></a>.
</p><a id="idp49378460" class="indexterm"></a><div class="funcsynopsis"><a id="XCloseOM"></a><p><code class="funcdef">Status <strong class="fsfunc">XCloseOM</strong>(</code>XOM<var class="pdparam"> om</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>om</em></span>
    </span></p></td><td><p>
Specifies the output method.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCloseOM"><code class="function">XCloseOM</code></a>
function closes the specified output method.
</p><p>


To set output method attributes, use 
<a class="xref" href="#XSetOMValues"><code class="function">XSetOMValues</code></a>.
</p><a id="idp49384284" class="indexterm"></a><div class="funcsynopsis"><a id="XSetOMValues"></a><p><code class="funcdef">char *<strong class="fsfunc">XSetOMValues</strong>(</code>XOM<var class="pdparam"> om</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>om</em></span>
    </span></p></td><td><p>
Specifies the output method.
      </p></td></tr><tr><td><p><span class="term">
      ...
    </span></p></td><td><p>
Specifies the variable-length argument list to set <acronym class="acronym">XOM</acronym>
values.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetOMValues"><code class="function">XSetOMValues</code></a>
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.
</p><p>

No standard arguments are currently defined by Xlib.
</p><p>


To query an output method, use 
<a class="xref" href="#XGetOMValues"><code class="function">XGetOMValues</code></a>.
</p><a id="idp49391972" class="indexterm"></a><div class="funcsynopsis"><a id="XGetOMValues"></a><p><code class="funcdef">char *<strong class="fsfunc">XGetOMValues</strong>(</code>XOM<var class="pdparam"> om</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>om</em></span>
    </span></p></td><td><p>
Specifies the output method.
      </p></td></tr><tr><td><p><span class="term">
      ...
    </span></p></td><td><p>
Specifies the variable-length argument list to get XOM values.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetOMValues"><code class="function">XGetOMValues</code></a>
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.
</p><p>

To obtain the display associated with an output method, use
<a class="xref" href="#XDisplayOfOM"><code class="function">XDisplayOfOM</code></a>.
</p><a id="idp49398884" class="indexterm"></a><div class="funcsynopsis"><a id="XDisplayOfOM"></a><p><code class="funcdef">Display *<strong class="fsfunc">XDisplayOfOM</strong>(</code>XOM<var class="pdparam"> om</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>om</em></span>
    </span></p></td><td><p>
Specifies the output method.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDisplayOfOM"><code class="function">XDisplayOfOM</code></a>
function returns the display associated with the specified output method.
</p><p>


To get the locale associated with an output method, use
<a class="xref" href="#XLocaleOfOM"><code class="function">XLocaleOfOM</code></a>.
</p><a id="idp49404828" class="indexterm"></a><div class="funcsynopsis"><a id="XLocaleOfOM"></a><p><code class="funcdef">char *<strong class="fsfunc">XLocaleOfOM</strong>(</code>XOM<var class="pdparam"> om</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>om</em></span>
    </span></p></td><td><p>
Specifies the output method.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XLocaleOfOM"><code class="function">XLocaleOfOM</code></a>
returns the locale associated with the specified output method.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="X_Output_Method_Values"></a>X Output Method Values</h3></div></div></div><p>

The following table describes how <acronym class="acronym">XOM</acronym> values are interpreted by an
output method.
The first column lists the <acronym class="acronym">XOM</acronym> values.  The second column indicates
how each of the <acronym class="acronym">XOM</acronym> values are treated by a particular output style.
</p><p>

</p><p>

The following key applies to this table.
</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Key</th><th align="left">Explanation</th></tr></thead><tbody><tr><td align="left">G</td><td align="left">This value may be read using <a class="xref" href="#XGetOMValues"><code class="function">XGetOMValues</code></a>.</td></tr></tbody></table></div><p></p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left"><acronym class="acronym">XOM</acronym> Value</th><th align="left">Key</th></tr></thead><tbody><tr><td align="left"><span class="symbol">XNRequiredCharSet</span></td><td align="left">G</td></tr><tr><td align="left"><span class="symbol">XNQueryOrientation</span></td><td align="left">G</td></tr><tr><td align="left"><span class="symbol">XNDirectionalDependentDrawing</span></td><td align="left">G</td></tr><tr><td align="left"><span class="symbol">XNContextualDrawing</span></td><td align="left">G</td></tr></tbody></table></div><p>

</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Required_Char_Set"></a>Required Char Set</h4></div></div></div><p>

The
<span class="symbol">XNRequiredCharSet</span>
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
<span class="structname">XOMCharSetList</span>.
</p><p>

The
<span class="structname">XOMCharSetList</span>
structure is defined as follows:
<a id="idp49426836" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     int    charset_count;
     char   **charset_list;
} XOMCharSetList;
</pre><p>


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.
</p><p>

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 
<a class="xref" href="#XCloseOM"><code class="function">XCloseOM</code></a>
with the associated 
<span class="type">XOM</span>.
Until freed, its contents will not be modified by Xlib.
</p><p>

</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Query_Orientation"></a>Query Orientation</h4></div></div></div><p>

The
<span class="symbol">XNQueryOrientation</span>
argument returns the global orientation of text when drawn.
Other than
<code class="constant">XOMOrientation_LTR_TTB</code>,
the set of orientations supported is locale-dependent.
The value of the argument is a pointer to a structure of type
<span class="structname">XOMOrientation</span>.
Clients are responsible for freeing the
<span class="structname">XOMOrientation</span>
structure by using
<a class="xref" href="#XFree"></a>;
this also frees the contents of the structure.
</p><pre class="literallayout">


typedef struct {
     int          num_orientation;
     XOrientation *orientation;     /* Input Text description */
} XOMOrientation;

typedef enum {
     XOMOrientation_LTR_TTB,
     XOMOrientation_RTL_TTB,     
     XOMOrientation_TTB_LTR,
     XOMOrientation_TTB_RTL,
     XOMOrientation_Context
} XOrientation;
</pre><p>


The possible value for XOrientation may be:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="constant">XOMOrientation_LTR_TTB</code>
left-to-right, top-to-bottom global orientation
    </p></li><li class="listitem"><p>
<code class="constant">XOMOrientation_RTL_TTB</code>
right-to-left, top-to-bottom global orientation
    </p></li><li class="listitem"><p>
<code class="constant">XOMOrientation_TTB_LTR</code>
top-to-bottom, left-to-right global orientation
    </p></li><li class="listitem"><p>
<code class="constant">XOMOrientation_TTB_RTL</code>
top-to-bottom, right-to-left global orientation
    </p></li><li class="listitem"><p>
<code class="constant">XOMOrientation_Context</code>
contextual global orientation
    </p></li></ul></div><p>

</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Directional_Dependent_Drawing"></a>Directional Dependent Drawing</h4></div></div></div><p>

The
<span class="symbol">XNDirectionalDependentDrawing</span>
argument indicates whether the text rendering functions
implement implicit handling of directional text.  If this value
is
<span class="symbol">True</span>,
the output method has knowledge of directional
dependencies and reorders text as necessary when
rendering text.  If this value is
<span class="symbol">False</span>,
the output method does not implement any directional text
handling, and all character directions are assumed to be left-to-right.
</p><p>

Regardless of the rendering order of characters,
the origins of all characters are on the primary draw direction side
of the drawing origin.
</p><p>

This OM value presents functionality identical to the
<a class="xref" href="#XDirectionalDependentDrawing"><code class="function">XDirectionalDependentDrawing</code></a>
function.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Context_Dependent_Drawing"></a>Context Dependent Drawing</h4></div></div></div><p>

The
<span class="symbol">XNContextualDrawing</span>
argument indicates whether the text rendering functions
implement implicit context-dependent drawing.  If this value is
<span class="symbol">True</span>,
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.
</p><p>

This OM value presents functionality identical to the
<a class="xref" href="#XContextualDrawing"><code class="function">XContextualDrawing</code></a>
function.
</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Output_Context_Functions"></a>Output Context Functions</h3></div></div></div><p>

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 <acronym class="acronym">XOC</acronym> values.
It is intended that output methods be controlled by these <acronym class="acronym">XOC</acronym> values.
As new <acronym class="acronym">XOC</acronym> values are created,
they should be registered with the X Consortium.
An
<span class="type">XOC</span>
can be used anywhere an
<span class="type">XFontSet</span>
can be used, and vice versa;
<span class="type">XFontSet</span>
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,
<span class="type">XFontSet</span>
is widely used in several interfaces, so
<span class="type">XOC</span>
is defined as an upward compatible type of
<span class="type">XFontSet</span>.
</p><p>


To create an output context, use
<a class="xref" href="#XCreateOC"><code class="function">XCreateOC</code></a>.
</p><a id="idp51174172" class="indexterm"></a><div class="funcsynopsis"><a id="XCreateOC"></a><p><code class="funcdef">XOC <strong class="fsfunc">XCreateOC</strong>(</code>XOM<var class="pdparam"> om</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>om</em></span>
    </span></p></td><td><p>
Specifies the output method.
      </p></td></tr><tr><td><p><span class="term">
      ...
    </span></p></td><td><p>
Specifies the variable-length argument list to set <acronym class="acronym">XOC</acronym>
values.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCreateOC"><code class="function">XCreateOC</code></a>
function creates an output context within the specified output method.
</p><p>

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.
</p><p>

<a class="xref" href="#XCreateOC"><code class="function">XCreateOC</code></a>
returns NULL if no output context could be created.
NULL can be returned for any of the following reasons:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
A required argument was not set.
    </p></li><li class="listitem"><p>
A read-only argument was set.
    </p></li><li class="listitem"><p>
An argument name is not recognized.
    </p></li><li class="listitem"><p>
The output method encountered an output method implementation-dependent error.
    </p></li></ul></div><p>

<a class="xref" href="#XCreateOC"><code class="function">XCreateOC</code></a>
can generate a
<span class="errorname">BadAtom</span>
error.
</p><p>


To destroy an output context, use
<a class="xref" href="#XDestroyOC"><code class="function">XDestroyOC</code></a>.
</p><a id="idp51184436" class="indexterm"></a><div class="funcsynopsis"><a id="XDestroyOC"></a><p><code class="funcdef">void <strong class="fsfunc">XDestroyOC</strong>(</code>XOC<var class="pdparam"> oc</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>oc</em></span>
    </span></p></td><td><p>
Specifies the output context.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDestroyOC"><code class="function">XDestroyOC</code></a>
function destroys the specified output context.
</p><p>


To get the output method associated with an output context, use
<a class="xref" href="#XOMOfOC"><code class="function">XOMOfOC</code></a>.
</p><a id="idp51189524" class="indexterm"></a><div class="funcsynopsis"><a id="XOMOfOC"></a><p><code class="funcdef">XOM <strong class="fsfunc">XOMOfOC</strong>(</code>XOC<var class="pdparam"> oc</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>oc</em></span>
    </span></p></td><td><p>
Specifies the output context.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XOMOfOC"><code class="function">XOMOfOC</code></a>
function returns the output method associated with the
specified output context.
</p><p>


Xlib provides two functions for setting and reading output context values,
respectively,
<a class="xref" href="#XSetOCValues"><code class="function">XSetOCValues</code></a>
and
<a class="xref" href="#XGetOCValues"><code class="function">XGetOCValues</code></a>.
Both functions have a variable-length argument list.
In that argument list, any <acronym class="acronym">XOC</acronym> value's name must be denoted
with a character string using the X Portable Character Set.
</p><p>


To set <acronym class="acronym">XOC</acronym> values, use
<a class="xref" href="#XSetOCValues"><code class="function">XSetOCValues</code></a>.
</p><a id="idp51196420" class="indexterm"></a><div class="funcsynopsis"><a id="XSetOCValues"></a><p><code class="funcdef">char *<strong class="fsfunc">XSetOCValues</strong>(</code>XOC<var class="pdparam"> oc</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>oc</em></span>
    </span></p></td><td><p>
Specifies the output context.
      </p></td></tr><tr><td><p><span class="term">
      ...
    </span></p></td><td><p>
Specifies the variable-length argument list to set <acronym class="acronym">XOC</acronym>
values.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetOCValues"><code class="function">XSetOCValues</code></a>
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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The argument is read-only.
    </p></li><li class="listitem"><p>
The argument name is not recognized.
    </p></li><li class="listitem"><p>
An implementation-dependent error occurs.
    </p></li></ul></div><p>

Each value to be set must be an appropriate datum,
matching the data type imposed by the semantics of the argument.
</p><p>

<a class="xref" href="#XSetOCValues"><code class="function">XSetOCValues</code></a>
can generate a
<span class="errorname">BadAtom</span>
error.
</p><p>


To obtain <acronym class="acronym">XOC</acronym> values, use
<a class="xref" href="#XGetOCValues"><code class="function">XGetOCValues</code></a>.
</p><a id="idp51206412" class="indexterm"></a><div class="funcsynopsis"><a id="XGetOCValues"></a><p><code class="funcdef">char *<strong class="fsfunc">XGetOCValues</strong>(</code>XOC<var class="pdparam"> oc</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>oc</em></span>
    </span></p></td><td><p>
Specifies the output context.
      </p></td></tr><tr><td><p><span class="term">
      ...
    </span></p></td><td><p>
Specifies the variable-length argument list to get XOC values.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetOCValues"><code class="function">XGetOCValues</code></a>
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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The argument name is not recognized.
    </p></li><li class="listitem"><p>
An implementation-dependent error occurs.
    </p></li></ul></div><p>

Each argument value
following a name must point to a location where the value is to be stored.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Output_Context_Values"></a>Output Context Values</h3></div></div></div><p>

The following table describes how <acronym class="acronym">XOC</acronym> values are interpreted
by an output method.
The first column lists the <acronym class="acronym">XOC</acronym> 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 <acronym class="acronym">XOC</acronym> values is treated.
</p><p>
The following keys apply to this table.
</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Key</th><th align="left">Explanation</th></tr></thead><tbody><tr><td align="left">C</td><td align="left">This value must be set with <a class="xref" href="#XCreateOC"><code class="function">XCreateOC</code></a>.</td></tr><tr><td align="left">D</td><td align="left">This value may be set using <a class="xref" href="#XCreateOC"><code class="function">XCreateOC</code></a>.
      If it is not set,a default is provided.</td></tr><tr><td align="left">G</td><td align="left">This value may be read using <a class="xref" href="#XGetOCValues"><code class="function">XGetOCValues</code></a>.</td></tr><tr><td align="left">S</td><td align="left">This value must be set using <a class="xref" href="#XSetOCValues"><code class="function">XSetOCValues</code></a>.</td></tr></tbody></table></div><p></p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left"><acronym class="acronym">XOC</acronym> Value</th><th align="left">Alternative Interface</th><th align="left">Key</th></tr></thead><tbody><tr><td align="left">BaseFontName</td><td align="left"><a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a></td><td align="left">C-G</td></tr><tr><td align="left">MissingCharSet</td><td align="left"><a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a></td><td align="left">G</td></tr><tr><td align="left">DefaultString</td><td align="left"><a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a></td><td align="left">G</td></tr><tr><td align="left">Orientation</td><td align="left">-</td><td align="left">D-S-G</td></tr><tr><td align="left">ResourceName</td><td align="left">-</td><td align="left">S-G</td></tr><tr><td align="left">ResourceClass</td><td align="left">-</td><td align="left">S-G</td></tr><tr><td align="left">FontInfo</td><td align="left"><a class="xref" href="#XFontsOfFontSet"><code class="function">XFontsOfFontSet</code></a></td><td align="left">G</td></tr><tr><td align="left">OMAutomatic</td><td align="left">-</td><td align="left">G</td></tr></tbody></table></div><p>

</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Base_Font_Name"></a>Base Font Name</h4></div></div></div><p>

The
<span class="symbol">XNBaseFontName</span>
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.
</p><p>

Use of <acronym class="acronym">XLFD</acronym> 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.
</p><p>

An <acronym class="acronym">XLFD</acronym> 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.
</p><p>

If a base font name is not an <acronym class="acronym">XLFD</acronym> name,
Xlib will attempt to obtain an <acronym class="acronym">XLFD</acronym> name from the font properties
for the font.
If Xlib is successful, the
<a class="xref" href="#XGetOCValues"><code class="function">XGetOCValues</code></a>
function will return this <acronym class="acronym">XLFD</acronym> name instead of the client-supplied name.
</p><p>

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,
<a class="xref" href="#XCreateOC"><code class="function">XCreateOC</code></a>
returns NULL.
</p><p>

When querying for the
<span class="symbol">XNBaseFontName</span>
<acronym class="acronym">XOC</acronym> value,
<a class="xref" href="#XGetOCValues"><code class="function">XGetOCValues</code></a>
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
<a class="xref" href="#XDestroyOC"><code class="function">XDestroyOC</code></a>
with the associated
<span class="type">XOC</span>.
Until freed, the string contents will not be modified by Xlib.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Missing_CharSet"></a>Missing CharSet</h4></div></div></div><p>

The
<span class="symbol">XNMissingCharSet</span>
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
<span class="structname">XOMCharSetList</span>.
</p><p>

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.
</p><p>

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 
<a class="xref" href="#XDestroyOC"><code class="function">XDestroyOC</code></a>
with the associated
<span class="type">XOC</span>.
Until freed, its contents will not be modified by Xlib.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Default_String"></a>Default String</h4></div></div></div><p>

When a drawing or measuring function is called with an
<span class="type">XOC</span>
that has missing charsets, some characters in the locale will not be
drawable.
The
<span class="symbol">XNDefaultString</span>
argument returns a pointer to a string that represents the glyphs
that are drawn with this
<span class="type">XOC</span>
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
<span class="type">XOC</span>.
</p><p>

If the
<span class="symbol">XNDefaultString</span>
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
<a class="xref" href="#XDestroyOC"><code class="function">XDestroyOC</code></a>
with the associated
<span class="type">XOC</span>.
Until freed, its contents will not be modified by Xlib.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Orientation"></a>Orientation</h4></div></div></div><p>

The
<span class="symbol">XNOrientation</span>
argument specifies the current orientation of text when drawn.  The value of
this argument is one of the values returned by the
<a class="xref" href="#XGetOMValues"><code class="function">XGetOMValues</code></a>
function with the
<span class="symbol">XNQueryOrientation</span>
argument specified in the
<span class="type">XOrientation</span>
list.
The value of the argument is of type
<span class="type">XOrientation</span>.
When
<span class="symbol">XNOrientation</span>
is queried, the value specifies the current orientation.  
When
<span class="symbol">XNOrientation</span>
is set, a value is used to set the current orientation.
</p><p>

When 
<code class="constant">XOMOrientation_Context</code>
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
<code class="constant">XOMOrientation_LTR_TTB</code>.
</p><p>

The
<span class="symbol">XNOrientation</span>
value does not change the prime drawing direction 
for Xlib drawing functions.  
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Resource_Name_and_Class"></a>Resource Name and Class</h4></div></div></div><p>

The
<span class="symbol">XNResourceName</span>
and
<span class="symbol">XNResourceClass</span>
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.
</p><p>

It is not intended that values that can be set as <acronym class="acronym">XOM</acronym> values be
set as resources.
</p><p>

When querying for the
<span class="symbol">XNResourceName</span>
or
<span class="symbol">XNResourceClass</span>
<acronym class="acronym">XOC</acronym> value,
<a class="xref" href="#XGetOCValues"><code class="function">XGetOCValues</code></a>
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
<a class="xref" href="#XDestroyOC"><code class="function">XDestroyOC</code></a>
with the associated
<span class="type">XOC</span>
or when the associated value is changed via
<a class="xref" href="#XSetOCValues"><code class="function">XSetOCValues</code></a>.
Until freed, the string contents will not be modified by Xlib.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Font_Info"></a>Font Info</h4></div></div></div><p>

The
<span class="symbol">XNFontInfo</span>
argument specifies a list of one or more 
<span class="structname">XFontStruct</span>
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
<span class="structname">XOMFontInfo</span>.
</p><p>


</p><pre class="literallayout">


typedef struct {
     int         num_font;
     XFontStruct **font_struct_list;
     char        **font_name_list;
} XOMFontInfo;
</pre><p>
</p><p>


A list of pointers to the
<span class="structname">XFontStruct</span>
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
<span class="structname">XFontStruct</span>
structures and font names is returned to num_font.
</p><p>

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 
<span class="structname">XFontStruct</span>
list to obtain these values for all the fonts currently in use.
</p><p>

Xlib does not guarantee that fonts are loaded from the server
at the creation of an 
<span class="type">XOC</span>.
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 
<span class="structname">XFontStruct</span>
structures in the
<span class="structname">XFontStructSet</span>
is undefined.
Also, note that all properties in the 
<span class="structname">XFontStruct</span>
structures are in the STRING encoding.
</p><p>

The client must not free the 
<span class="structname">XOMFontInfo</span>
struct itself; it will be freed when the
<span class="type">XOC</span>
is closed.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="OM_Automatic"></a>OM Automatic</h4></div></div></div><p>

The
<span class="symbol">XNOMAutomatic</span>
argument returns whether the associated output context was created by
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>
or not.  Because the
<a class="xref" href="#XFreeFontSet"><code class="function">XFreeFontSet</code></a>
function not only destroys the output context but also closes the implicit
output method associated with it,
<a class="xref" href="#XFreeFontSet"><code class="function">XFreeFontSet</code></a>
should be used with any output context created by 
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>.
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
<span class="symbol">XNOMAutomatic</span>
is set to determine whether 
<a class="xref" href="#XFreeFontSet"><code class="function">XFreeFontSet</code></a>
or 
<a class="xref" href="#XDestroyOC"><code class="function">XDestroyOC</code></a>
should be used to destroy the output context.
</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Creating_and_Freeing_a_Font_Set"></a>Creating and Freeing a Font Set</h3></div></div></div><p>

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
<span class="type">XFontSet</span>
is an opaque type representing the state of a particular output thread
and is equivalent to the type
<span class="type">XOC</span>.
</p><p>


The 
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>
function is a convenience function for creating an output context using
only default values.  The returned
<span class="type">XFontSet</span>
has an implicitly created
<span class="type">XOM</span>.
This
<span class="type">XOM</span>
has an OM value
<span class="symbol">XNOMAutomatic</span>
automatically set to
<span class="symbol">True</span>
so that the output context self indicates whether it was created by
<a class="xref" href="#XCreateOC"><code class="function">XCreateOC</code></a>
or
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>.
</p><a id="idp51286740" class="indexterm"></a><div class="funcsynopsis"><a id="XCreateFontSet"></a><p><code class="funcdef">XFontSet <strong class="fsfunc">XCreateFontSet</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> *base_font_name_list</var>, char<var class="pdparam"> ***missing_charset_list_return</var>, int<var class="pdparam"> *missing_charset_count_return</var>, char<var class="pdparam"> **def_string_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>base_font_name_list</em></span>
    </span></p></td><td><p>
Specifies the base font names.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>missing_charset_list_return</em></span>
    </span></p></td><td><p>
Returns the missing charsets.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>missing_charset_count_return</em></span>
    </span></p></td><td><p>
Returns the number of missing charsets.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>def_string_return</em></span>
    </span></p></td><td><p>
Returns the string drawn for missing charsets.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>
function creates a font set for the specified display.
The font set is bound to the current locale when 
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>
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.
</p><p>

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.
</p><p>

Use of <acronym class="acronym">XLFD</acronym> 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.
</p><p>

An <acronym class="acronym">XLFD</acronym> 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.
</p><p>

If a base font name is not an <acronym class="acronym">XLFD</acronym> name,
Xlib will attempt to obtain an <acronym class="acronym">XLFD</acronym> name from the font properties
for the font.
If this action is successful in obtaining an <acronym class="acronym">XLFD</acronym> name, the
<a class="xref" href="#XBaseFontNameListOfFontSet"><code class="function">XBaseFontNameListOfFontSet</code></a>
function will return this <acronym class="acronym">XLFD</acronym> name instead of the client-supplied name.
</p><p>

Xlib uses the following algorithm to select the fonts
that will be used to display text with the 
<span class="type">XFontSet</span>.
</p><p>

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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The first <acronym class="acronym">XLFD</acronym>-conforming base font name that specifies the required
charset or a superset of the required charset in its 
<em class="structfield"><code>CharSetRegistry</code></em>
and 
<em class="structfield"><code>CharSetEncoding</code></em>
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.
    </p></li><li class="listitem"><p>
The first set of one or more <acronym class="acronym">XLFD</acronym>-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.
    </p></li><li class="listitem"><p>
The first <acronym class="acronym">XLFD</acronym>-conforming font name or the first non-<acronym class="acronym">XLFD</acronym> font name
for which an <acronym class="acronym">XLFD</acronym> font name can be obtained, combined with the
required charset (replacing the 
<em class="structfield"><code>CharSetRegistry</code></em>
and
<em class="structfield"><code>CharSetEncoding</code></em>
fields in the <acronym class="acronym">XLFD</acronym> font name).
As in case 1,
the implementation may use a charset that is a superset
of the required charset.
    </p></li><li class="listitem"><p>
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.
    </p></li></ul></div><p>

For example, assume that a locale required the charsets:
</p><p>

</p><pre class="literallayout">
ISO8859-1
JISX0208.1983
JISX0201.1976
GB2312-1980.0
</pre><p>
</p><p>

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:
</p><p>

</p><pre class="literallayout">
"-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"
</pre><p>
</p><p>

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:
</p><p>

</p><pre class="literallayout">
"-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"
</pre><p>
</p><p>

Alternatively, the user could simply supply a single base font name
that allows Xlib to select from all available fonts
that meet certain minimum <acronym class="acronym">XLFD</acronym> property requirements.
For example:
</p><p>

</p><pre class="literallayout">
"-*-*-*-R-Normal--*-180-100-100-*-*"
</pre><p>
</p><p>

If 
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>
is unable to create the font set, 
either because there is insufficient memory or because the current locale
is not supported,
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>
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,
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>
returns a valid
<span class="type">XFontSet</span>,
missing_charset_list_return is set to NULL,
and missing_charset_count_return is set to zero.
</p><p>

If no font exists for one or more of the required charsets,
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>
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.
</p><p>

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, 
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>
returns NULL.
Otherwise, 
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>
returns a valid 
<span class="type">XFontSet</span>
to font_set.
</p><p>

When an Xmb/wc drawing or measuring function is called with an
<span class="type">XFontSet</span>
that has missing charsets, some characters in the locale will not be
drawable.
If def_string_return is non-NULL,
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>
returns a pointer to a string that represents the glyphs
that are drawn with this 
<span class="type">XFontSet</span>
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 
<span class="type">XFontSet</span>.
</p><p>

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 
<a class="xref" href="#XFreeFontSet"><code class="function">XFreeFontSet</code></a>
with the associated 
<span class="type">XFontSet</span>.
Until freed, its contents will not be modified by Xlib.
</p><p>

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.
</p><p>

The returned 
<span class="type">XFontSet</span>
and missing charset list should be freed with 
<a class="xref" href="#XFreeFontSet"><code class="function">XFreeFontSet</code></a>
and
<a class="xref" href="#XFreeStringList"><code class="function">XFreeStringList</code></a>,
respectively.
The client-supplied base_font_name_list may be freed 
by the client after calling 
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>.
</p><p>


To obtain a list of 
<span class="structname">XFontStruct</span>
structures and full font names given an 
<span class="type">XFontSet</span>,
use
<a class="xref" href="#XFontsOfFontSet"><code class="function">XFontsOfFontSet</code></a>.
</p><a id="idp51329772" class="indexterm"></a><div class="funcsynopsis"><a id="XFontsOfFontSet"></a><p><code class="funcdef">int <strong class="fsfunc">XFontsOfFontSet</strong>(</code>XFontSet<var class="pdparam"> font_set</var>, XFontStruct<var class="pdparam"> ***font_struct_list_return</var>, char<var class="pdparam"> ***font_name_list_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>font_set</em></span>
    </span></p></td><td><p>
Specifies the font set.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>font_struct_list_return</em></span>
    </span></p></td><td><p>
Returns the list of font structs.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>font_name_list_return</em></span>
    </span></p></td><td><p>
Returns the list of font names.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFontsOfFontSet"><code class="function">XFontsOfFontSet</code></a>
function returns a list of one or more 
<span class="structname">XFontStruct</span>s
and font names for the fonts used by the Xmb and Xwc layers
for the given font set.
A list of pointers to the
<span class="structname">XFontStruct</span>
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
<span class="structname">XFontStruct</span>
structures and font names is returned as the value of the function.
</p><p>

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 
<span class="structname">XFontStruct</span>
list to obtain these values for all the fonts currently in use.
</p><p>

Xlib does not guarantee that fonts are loaded from the server
at the creation of an 
<span class="type">XFontSet</span>.
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 
<span class="structname">XFontStruct</span>
structures in the
<span class="structname">XFontStructSet</span>
is undefined.
Also, note that all properties in the 
<span class="structname">XFontStruct</span>
structures are in the STRING encoding.
</p><p>

The 
<span class="structname">XFontStruct</span>
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
<a class="xref" href="#XFreeFontSet"><code class="function">XFreeFontSet</code></a>
with the associated
<span class="type">XFontSet</span>.
Until freed, their contents will not be modified by Xlib.
</p><p>


To obtain the base font name list and the selected font name list given an
<span class="type">XFontSet</span>,
use
<a class="xref" href="#XBaseFontNameListOfFontSet"><code class="function">XBaseFontNameListOfFontSet</code></a>.
</p><a id="idp51344748" class="indexterm"></a><div class="funcsynopsis"><a id="XBaseFontNameListOfFontSet"></a><p><code class="funcdef">char *<strong class="fsfunc">XBaseFontNameListOfFontSet</strong>(</code>XFontSet<var class="pdparam"> font_set</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>font_set</em></span>
    </span></p></td><td><p>
Specifies the font set.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XBaseFontNameListOfFontSet"><code class="function">XBaseFontNameListOfFontSet</code></a>
function returns the original base font name list supplied
by the client when the 
<span class="type">XFontSet</span>
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.
</p><p>

If 
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>
obtained an <acronym class="acronym">XLFD</acronym> name from the font properties for the font specified
by a non-<acronym class="acronym">XLFD</acronym> base name, the
<a class="xref" href="#XBaseFontNameListOfFontSet"><code class="function">XBaseFontNameListOfFontSet</code></a>
function will return the <acronym class="acronym">XLFD</acronym> name instead of the non-<acronym class="acronym">XLFD</acronym> base name.
</p><p>

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 
<a class="xref" href="#XFreeFontSet"><code class="function">XFreeFontSet</code></a>
with the associated 
<span class="type">XFontSet</span>.
Until freed, its contents will not be modified by Xlib.
</p><p>


To obtain the locale name given an 
<span class="type">XFontSet</span>,
use
<a class="xref" href="#XLocaleOfFontSet"><code class="function">XLocaleOfFontSet</code></a>.
</p><a id="idp51354932" class="indexterm"></a><div class="funcsynopsis"><a id="XLocaleOfFontSet"></a><p><code class="funcdef">char *<strong class="fsfunc">XLocaleOfFontSet</strong>(</code>XFontSet<var class="pdparam"> font_set</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>font_set</em></span>
    </span></p></td><td><p>
Specifies the font set.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XLocaleOfFontSet"><code class="function">XLocaleOfFontSet</code></a>
function
returns the name of the locale bound to the specified
<span class="type">XFontSet</span>,
as a null-terminated string.
</p><p>

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
<a class="xref" href="#XFreeFontSet"><code class="function">XFreeFontSet</code></a>
with the associated 
<span class="type">XFontSet</span>.
Until freed, it will not be modified by Xlib.
</p><p>


The 
<a class="xref" href="#XFreeFontSet"><code class="function">XFreeFontSet</code></a>
function is a convenience function for freeing an output context.
<a class="xref" href="#XFreeFontSet"><code class="function">XFreeFontSet</code></a>
also frees its associated 
<span class="type">XOM</span>
if the output context was created by
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>.
</p><a id="idp51363556" class="indexterm"></a><div class="funcsynopsis"><a id="XFreeFontSet"></a><p><code class="funcdef">void <strong class="fsfunc">XFreeFontSet</strong>(</code>Display<var class="pdparam"> *display</var>, XFontSet<var class="pdparam"> font_set</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>font_set</em></span>
    </span></p></td><td><p>
Specifies the font set.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFreeFontSet"><code class="function">XFreeFontSet</code></a>
function frees the specified font set.
The associated base font name list, font name list, 
<span class="structname">XFontStruct</span>
list, and 
<span class="structname">XFontSetExtents</span>,
if any, are freed.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Obtaining_Font_Set_Metrics"></a>Obtaining Font Set Metrics</h3></div></div></div><p>

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.
</p><p>

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.
</p><p>

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
<a class="xref" href="#XmbTextPerCharExtents"><code class="function">XmbTextPerCharExtents</code></a>
or
<a class="xref" href="#XwcTextPerCharExtents"><code class="function">XwcTextPerCharExtents</code></a>.
</p><p>

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 
<a class="xref" href="#XmbDrawString"><code class="function">XmbDrawString</code></a>
may render differently than if the two characters 
were drawn with separate calls to
<a class="xref" href="#XmbDrawString"><code class="function">XmbDrawString</code></a>.
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.
</p><p>


To find out about direction-dependent rendering, use
<a class="xref" href="#XDirectionalDependentDrawing"><code class="function">XDirectionalDependentDrawing</code></a>.
</p><a id="idp51377940" class="indexterm"></a><div class="funcsynopsis"><a id="XDirectionalDependentDrawing"></a><p><code class="funcdef">Bool <strong class="fsfunc">XDirectionalDependentDrawing</strong>(</code>XFontSet<var class="pdparam"> font_set</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>font_set</em></span>
    </span></p></td><td><p>
Specifies the font set.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDirectionalDependentDrawing"><code class="function">XDirectionalDependentDrawing</code></a>
function returns
<span class="symbol">True</span>
if the drawing functions implement implicit text directionality;
otherwise, it returns
<span class="symbol">False</span>.
</p><p>


To find out about context-dependent rendering, use
<a class="xref" href="#XContextualDrawing"><code class="function">XContextualDrawing</code></a>.
</p><a id="idp51384516" class="indexterm"></a><div class="funcsynopsis"><a id="XContextualDrawing"></a><p><code class="funcdef">Bool <strong class="fsfunc">XContextualDrawing</strong>(</code>XFontSet<var class="pdparam"> font_set</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>font_set</em></span>
    </span></p></td><td><p>
Specifies the font set.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XContextualDrawing"><code class="function">XContextualDrawing</code></a>
function returns
<span class="symbol">True</span>
if text drawn with the font set might include context-dependent drawing;
otherwise, it returns
<span class="symbol">False</span>.
</p><p>


To find out about context-dependent or direction-dependent rendering, use
<a class="xref" href="#XContextDependentDrawing"><code class="function">XContextDependentDrawing</code></a>.
</p><a id="idp51391036" class="indexterm"></a><div class="funcsynopsis"><a id="XContextDependentDrawing"></a><p><code class="funcdef">Bool <strong class="fsfunc">XContextDependentDrawing</strong>(</code>XFontSet<var class="pdparam"> font_set</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>font_set</em></span>
    </span></p></td><td><p>
Specifies the font set.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XContextDependentDrawing"><code class="function">XContextDependentDrawing</code></a>
function returns
<span class="symbol">True</span>
if the drawing functions implement implicit text directionality or
if text drawn with the font_set might include context-dependent drawing;
otherwise, it returns
<span class="symbol">False</span>.
</p><p>

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.
</p><p>

The maximum character extents for the fonts that are used by the text
drawing layers can be accessed by the 
<span class="structname">XFontSetExtents</span>
structure:
<a id="idp51397900" class="indexterm"></a>
</p><p>

</p><pre class="literallayout">


typedef struct {
     XRectangle max_ink_extent;     /* over all drawable characters */
     XRectangle max_logical_extent; /* over all drawable characters */
} XFontSetExtents;
</pre><p>
</p><p>

The 
<span class="structname">XRectangle</span>
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.
</p><p>

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 
<a class="xref" href="#XmbTextExtents"><code class="function">XmbTextExtents</code></a>
and
<code class="function">XwcTextExtents</code>
for detailed semantics.
</p><p>

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.
</p><p>

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.
</p><p>

The rectangles for a given character in a string can be obtained from
<a class="xref" href="#XmbTextPerCharExtents"><code class="function">XmbTextPerCharExtents</code></a>
or
<a class="xref" href="#XwcTextPerCharExtents"><code class="function">XwcTextPerCharExtents</code></a>.
</p><p>


To obtain the maximum extents structure given an
<span class="type">XFontSet</span>,
use
<a class="xref" href="#XExtentsOfFontSet"><code class="function">XExtentsOfFontSet</code></a>.
</p><a id="idp51405972" class="indexterm"></a><div class="funcsynopsis"><a id="XExtentsOfFontSet"></a><p><code class="funcdef">XFontSetExtents *<strong class="fsfunc">XExtentsOfFontSet</strong>(</code>XFontSet<var class="pdparam"> font_set</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>font_set</em></span>
    </span></p></td><td><p>
Specifies the font set.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XExtentsOfFontSet"><code class="function">XExtentsOfFontSet</code></a>
function returns an
<span class="structname">XFontSetExtents</span>
structure for the fonts used by the Xmb and Xwc layers
for the given font set.
</p><p>

The 
<span class="structname">XFontSetExtents</span>
structure is owned by Xlib and should not be modified
or freed by the client.
It will be freed by a call to 
<a class="xref" href="#XFreeFontSet"><code class="function">XFreeFontSet</code></a>
with the associated 
<span class="type">XFontSet</span>.
Until freed, its contents will not be modified by Xlib.
</p><p>


To obtain the escapement in pixels of the specified text as a value,
use
<a class="xref" href="#XmbTextEscapement"><code class="function">XmbTextEscapement</code></a>
or 
<a class="xref" href="#XwcTextEscapement"><code class="function">XwcTextEscapement</code></a>.
</p><a id="idp51414140" class="indexterm"></a><a id="idp51414572" class="indexterm"></a><div class="funcsynopsis"><a id="XmbTextEscapement"></a><p><code class="funcdef">int <strong class="fsfunc">XmbTextEscapement</strong>(</code>XFontSet<var class="pdparam"> font_set</var>, char<var class="pdparam"> *string</var>, int<var class="pdparam"> num_bytes</var><code>)</code>;</p></div><div class="funcsynopsis"><a id="XwcTextEscapement"></a><p><code class="funcdef">int <strong class="fsfunc">XwcTextEscapement</strong>(</code>XFontSet<var class="pdparam"> font_set</var>, wchar_t<var class="pdparam"> *string</var>, int<var class="pdparam"> num_wchars</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>font_set</em></span>
    </span></p></td><td><p>
Specifies the font set.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the character string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>num_bytes</em></span>
    </span></p></td><td><p>
Specifies the number of bytes in the string argument.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>num_wchars</em></span>
    </span></p></td><td><p>
Specifies the number of characters in the string argument.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XmbTextEscapement"><code class="function">XmbTextEscapement</code></a>
and
<a class="xref" href="#XwcTextEscapement"><code class="function">XwcTextEscapement</code></a>
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.
</p><p>

Regardless of the character rendering order,
the escapement is always positive.
</p><p>


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
<a class="xref" href="#XmbTextExtents"><code class="function">XmbTextExtents</code></a>
 or
<code class="function">XwcTextExtents</code>.
</p><a id="idp51430020" class="indexterm"></a><a id="idp51430452" class="indexterm"></a><div class="funcsynopsis"><a id="XmbTextExtents"></a><p><code class="funcdef">int <strong class="fsfunc">XmbTextExtents</strong>(</code>XFontSet<var class="pdparam"> font_set</var>, char<var class="pdparam"> *string</var>, int<var class="pdparam"> num_bytes</var>, XRectangle<var class="pdparam"> *overall_ink_return</var>, XRectangle<var class="pdparam"> *overall_logical_return</var><code>)</code>;</p></div><div class="funcsynopsis"><p><code class="funcdef">int <strong class="fsfunc">XwcTextExtents</strong>(</code>XFontSet<var class="pdparam"> font_set</var>, wchar_t<var class="pdparam"> *string</var>, int<var class="pdparam"> num_wchars</var>, XRectangle<var class="pdparam"> *overall_ink_return</var>, XRectangle<var class="pdparam"> *overall_logical_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>font_set</em></span>
    </span></p></td><td><p>
Specifies the font set.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the character string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>num_bytes</em></span>
    </span></p></td><td><p>
Specifies the number of bytes in the string argument.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>num_wchars</em></span>
    </span></p></td><td><p>
Specifies the number of characters in the string argument.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>overall_ink_return</em></span>
    </span></p></td><td><p>
Returns the overall ink dimensions.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>overall_logical_return</em></span>
    </span></p></td><td><p>
Returns the overall logical dimensions.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XmbTextExtents"><code class="function">XmbTextExtents</code></a>
and
<code class="function">XwcTextExtents</code>
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 
<a class="xref" href="#XmbTextEscapement"><code class="function">XmbTextEscapement</code></a>
or
<a class="xref" href="#XwcTextEscapement"><code class="function">XwcTextEscapement</code></a>.
These metrics are relative to the drawing origin of the string,
using the fonts loaded for the specified font set.
</p><p>

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 &lt;= -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 &gt;= 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.
</p><p>

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.
</p><p>

When the 
<span class="type">XFontSet</span>
has missing charsets,
metrics for each unavailable character are taken 
from the default string returned by 
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>
so that the metrics represent the text as it will actually be drawn.
The behavior for an invalid codepoint is undefined.
</p><p>

To determine the effective drawing origin for a character in a drawn string,
the client should call 
<a class="xref" href="#XmbTextPerCharExtents"><code class="function">XmbTextPerCharExtents</code></a>
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.
</p><p>


To obtain per-character information for a text string,
use
<a class="xref" href="#XmbTextPerCharExtents"><code class="function">XmbTextPerCharExtents</code></a>
or
<a class="xref" href="#XwcTextPerCharExtents"><code class="function">XwcTextPerCharExtents</code></a>.
</p><a id="idp51454988" class="indexterm"></a><a id="idp51455428" class="indexterm"></a><div class="funcsynopsis"><a id="XmbTextPerCharExtents"></a><p><code class="funcdef">Status <strong class="fsfunc">XmbTextPerCharExtents</strong>(</code>XFontSet<var class="pdparam"> font_set</var>, char<var class="pdparam"> *string</var>, int<var class="pdparam"> num_bytes</var>, XRectangle<var class="pdparam"> *ink_array_return</var>, XRectangle<var class="pdparam"> *logical_array_return</var>, int<var class="pdparam"> array_size</var>, int<var class="pdparam"> *num_chars_return</var>, XRectangle<var class="pdparam"> *overall_ink_return</var>, XRectangle<var class="pdparam"> *overall_logical_return</var><code>)</code>;</p></div><div class="funcsynopsis"><a id="XwcTextPerCharExtents"></a><p><code class="funcdef">Status <strong class="fsfunc">XwcTextPerCharExtents</strong>(</code>XFontSet<var class="pdparam"> font_set</var>, wchar_t<var class="pdparam"> *string</var>, int<var class="pdparam"> num_wchars</var>, XRectangle<var class="pdparam"> *ink_array_return</var>, XRectangle<var class="pdparam"> *logical_array_return</var>, int<var class="pdparam"> array_size</var>, int<var class="pdparam"> *num_chars_return</var>, XRectangle<var class="pdparam"> *overall_ink_return</var>, XRectangle<var class="pdparam"> *overall_logical_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>font_set</em></span>
    </span></p></td><td><p>
Specifies the font set.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the character string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>num_bytes</em></span>
    </span></p></td><td><p>
Specifies the number of bytes in the string argument.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>num_wchars</em></span>
    </span></p></td><td><p>
Specifies the number of characters in the string argument.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>ink_array_return</em></span>
    </span></p></td><td><p>
Returns the ink dimensions for each character.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>logical_array_return</em></span>
    </span></p></td><td><p>
Returns the logical dimensions for each character.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>array_size</em></span>
    </span></p></td><td><p>
Specifies the size of ink_array_return and logical_array_return.
The caller must pass in arrays of this size.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>num_chars_return</em></span>
    </span></p></td><td><p>
Returns the number of characters in the string argument.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>overall_ink_return</em></span>
    </span></p></td><td><p>
Returns the overall ink dimensions.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>overall_logical_return</em></span>
    </span></p></td><td><p>
Returns the overall logical dimensions.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XmbTextPerCharExtents"><code class="function">XmbTextPerCharExtents</code></a>
and
<a class="xref" href="#XwcTextPerCharExtents"><code class="function">XwcTextPerCharExtents</code></a>
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.
</p><p>

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.
</p><p>

Note that an 
<span class="structname">XRectangle</span>
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 
<span class="structname">XRectangle</span>s
of those characters are the same.
</p><p>

When the 
<span class="type">XFontSet</span>
has missing charsets, metrics for each unavailable
character are taken from the default string returned by 
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>
so that the metrics represent the text as it will actually be drawn.
The behavior for an invalid codepoint is undefined.
</p><p>

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.
</p><p>

If the overall_ink_return or overall_logical_return argument is non-NULL,
<a class="xref" href="#XmbTextPerCharExtents"><code class="function">XmbTextPerCharExtents</code></a>
and 
<a class="xref" href="#XwcTextPerCharExtents"><code class="function">XwcTextPerCharExtents</code></a>
return the maximum extent of the string's metrics to overall_ink_return
or overall_logical_return, as returned by 
<a class="xref" href="#XmbTextExtents"><code class="function">XmbTextExtents</code></a>
or 
<code class="function">XwcTextExtents</code>.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Drawing_Text_Using_Font_Sets"></a>Drawing Text Using Font Sets</h3></div></div></div><p>

The functions defined in this section
draw text at a specified location in a drawable.
They are similar to the functions
<a class="xref" href="#XDrawText"><code class="function">XDrawText</code></a>,
<a class="xref" href="#XDrawString"><code class="function">XDrawString</code></a>,
and
<a class="xref" href="#XDrawImageString"><code class="function">XDrawImageString</code></a>
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 <a class="link" href="#Drawing_Text" title="Drawing Text">section 8.6</a> for details
of the use of Graphics Contexts (GCs)
and possible protocol errors.
If a 
<span class="errorname">BadFont</span>
error is generated,
characters prior to the offending character may have been drawn.
</p><p>

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.
</p><p>

The text functions
<a class="xref" href="#XmbDrawText"><code class="function">XmbDrawText</code></a>
and
<a class="xref" href="#XwcDrawText"><code class="function">XwcDrawText</code></a>
use the following structures:
</p><p>

<a id="idp51495308" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     char     *chars;    /* pointer to string */
     int      nchars;    /* number of bytes */
     int      delta;     /* pixel delta between strings */
     XFontSet font_set;  /* fonts, None means don't change */
} XmbTextItem;
</pre><p>
</p><p>

<a id="idp51497356" class="indexterm"></a>
</p><pre class="literallayout">


typedef struct {
     wchar_t *chars;     /* pointer to wide char string */
     int nchars;     /* number of wide characters */
     int delta;     /* pixel delta between strings */
     XFontSet font_set;     /* fonts, None means don't change */
} XwcTextItem;
</pre><p>
</p><p>



To draw text using multiple font sets in a given drawable, use
<a class="xref" href="#XmbDrawText"><code class="function">XmbDrawText</code></a>
or
<a class="xref" href="#XwcDrawText"><code class="function">XwcDrawText</code></a>.
</p><a id="idp51500564" class="indexterm"></a><a id="idp51500988" class="indexterm"></a><div class="funcsynopsis"><a id="XmbDrawText"></a><p><code class="funcdef">void <strong class="fsfunc">XmbDrawText</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, intx,<var class="pdparam"> y</var>, XmbTextItem<var class="pdparam"> *items</var>, int<var class="pdparam"> nitems</var><code>)</code>;</p></div><div class="funcsynopsis"><a id="XwcDrawText"></a><p><code class="funcdef">void <strong class="fsfunc">XwcDrawText</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, intx,<var class="pdparam"> y</var>, XwcTextItem<var class="pdparam"> *items</var>, int<var class="pdparam"> nitems</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.

      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates of the position in the new parent window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>items</em></span>
    </span></p></td><td><p>
Specifies an array of text items.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nitems</em></span>
    </span></p></td><td><p>
Specifies the number of text items in the array.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XmbDrawText"><code class="function">XmbDrawText</code></a>
and 
<a class="xref" href="#XwcDrawText"><code class="function">XwcDrawText</code></a>
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 
<span class="symbol">None</span>
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
<span class="symbol">None</span>
will not be drawn.
</p><p>

<a class="xref" href="#XmbDrawText"><code class="function">XmbDrawText</code></a>
and
<a class="xref" href="#XwcDrawText"><code class="function">XwcDrawText</code></a>
do not perform any context-dependent rendering between text segments.
Clients may compute the drawing metrics by passing each text segment to
<a class="xref" href="#XmbTextExtents"><code class="function">XmbTextExtents</code></a>
and
<code class="function">XwcTextExtents</code>
or 
<a class="xref" href="#XmbTextPerCharExtents"><code class="function">XmbTextPerCharExtents</code></a>
and
<a class="xref" href="#XwcTextPerCharExtents"><code class="function">XwcTextPerCharExtents</code></a>.
When the 
<span class="type">XFontSet</span>
has missing charsets, each unavailable character is drawn 
with the default string returned by 
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>.
The behavior for an invalid codepoint is undefined.
</p><p>


To draw text using a single font set in a given drawable, use
<a class="xref" href="#XmbDrawString"><code class="function">XmbDrawString</code></a>
or
<a class="xref" href="#XwcDrawString"><code class="function">XwcDrawString</code></a>.
</p><a id="idp51527644" class="indexterm"></a><a id="idp51528076" class="indexterm"></a><div class="funcsynopsis"><a id="XmbDrawString"></a><p><code class="funcdef">void <strong class="fsfunc">XmbDrawString</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, XFontSet<var class="pdparam"> font_set</var>, GC<var class="pdparam"> gc</var>, intx,<var class="pdparam"> y</var>, char<var class="pdparam"> *string</var>, int<var class="pdparam"> num_bytes</var><code>)</code>;</p></div><div class="funcsynopsis"><a id="XwcDrawString"></a><p><code class="funcdef">void <strong class="fsfunc">XwcDrawString</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, XFontSet<var class="pdparam"> font_set</var>, GC<var class="pdparam"> gc</var>, intx,<var class="pdparam"> y</var>, wchar_t<var class="pdparam"> *string</var>, int<var class="pdparam"> num_wchars</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>font_set</em></span>
    </span></p></td><td><p>
Specifies the font set.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.

      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates of the position in the new parent window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the character string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>num_bytes</em></span>
    </span></p></td><td><p>
Specifies the number of bytes in the string argument.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>num_wchars</em></span>
    </span></p></td><td><p>
Specifies the number of characters in the string argument.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XmbDrawString"><code class="function">XmbDrawString</code></a>
and
<a class="xref" href="#XwcDrawString"><code class="function">XwcDrawString</code></a>
functions draw the specified text with the foreground pixel.
When the 
<span class="type">XFontSet</span>
has missing charsets, each unavailable character is drawn 
with the default string returned by 
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>.
The behavior for an invalid codepoint is undefined.
</p><p>


To draw image text using a single font set in a given drawable, use
<a class="xref" href="#XmbDrawImageString"><code class="function">XmbDrawImageString</code></a>
or
<a class="xref" href="#XwcDrawImageString"><code class="function">XwcDrawImageString</code></a>.
</p><a id="idp51554452" class="indexterm"></a><a id="idp51554884" class="indexterm"></a><div class="funcsynopsis"><a id="XmbDrawImageString"></a><p><code class="funcdef">void <strong class="fsfunc">XmbDrawImageString</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, XFontSet<var class="pdparam"> font_set</var>, GC<var class="pdparam"> gc</var>, intx,<var class="pdparam"> y</var>, char<var class="pdparam"> *string</var>, int<var class="pdparam"> num_bytes</var><code>)</code>;</p></div><div class="funcsynopsis"><a id="XwcDrawImageString"></a><p><code class="funcdef">void <strong class="fsfunc">XwcDrawImageString</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, XFontSet<var class="pdparam"> font_set</var>, GC<var class="pdparam"> gc</var>, intx,<var class="pdparam"> y</var>, wchar_t<var class="pdparam"> *string</var>, int<var class="pdparam"> num_wchars</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>font_set</em></span>
    </span></p></td><td><p>
Specifies the font set.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.

      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates of the position in the new parent window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the character string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>num_bytes</em></span>
    </span></p></td><td><p>
Specifies the number of bytes in the string argument.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>num_wchars</em></span>
    </span></p></td><td><p>
Specifies the number of characters in the string argument.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XmbDrawImageString"><code class="function">XmbDrawImageString</code></a>
and
<a class="xref" href="#XwcDrawImageString"><code class="function">XwcDrawImageString</code></a>
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
<a class="xref" href="#XmbTextExtents"><code class="function">XmbTextExtents</code></a>
or 
<code class="function">XwcTextExtents</code>
for the same text and 
<span class="type">XFontSet</span>.
</p><p>

When the 
<span class="type">XFontSet</span>
has missing charsets, each unavailable character is drawn 
with the default string returned by 
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>.
The behavior for an invalid codepoint is undefined.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Input_Methods"></a>Input Methods</h2></div></div></div><p>

This section provides discussions of the following X Input Method
(<acronym class="acronym">XIM</acronym>) topics:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Input method overview
    </p></li><li class="listitem"><p>
Input method management
    </p></li><li class="listitem"><p>
Input method functions
    </p></li><li class="listitem"><p>
Input method values
    </p></li><li class="listitem"><p>
Input context functions
    </p></li><li class="listitem"><p>
Input context values
    </p></li><li class="listitem"><p>
Input method callback semantics
    </p></li><li class="listitem"><p>
Event filtering
    </p></li><li class="listitem"><p>
Getting keyboard input
    </p></li><li class="listitem"><p>
Input method conventions
    </p></li></ul></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Input_Method_Overview"></a>Input Method Overview</h3></div></div></div><p>

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.
</p><p>

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.
</p><p>

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.
</p><p>

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.
</p><p>

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.
</p><p>

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.
</p><p>

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.
</p><p>

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.
</p><p>

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.
</p><p>

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.
</p><p>

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. 
</p><p>

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.
</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Input_Method_Architecture"></a>Input Method Architecture</h4></div></div></div><p>

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
<span class="emphasis"><em>preediting</em></span>.
It may require complex algorithms and large dictionaries 
involving substantial computer resources.
</p><p>

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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The <span class="emphasis"><em>status</em></span> 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.
    </p></li><li class="listitem"><p>
The <span class="emphasis"><em>preedit</em></span> area displays the
intermediate text for those languages that are composing prior to 
the client handling the data.   
    </p></li><li class="listitem"><p>
The <span class="emphasis"><em>auxiliary</em></span> 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.
    </p></li></ul></div><p>

There are various user interaction styles used for preediting.
The ones supported by Xlib are as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
For <span class="emphasis"><em>on-the-spot</em></span> 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.
    </p></li><li class="listitem"><p>
<span class="emphasis"><em>Over-the-spot</em></span> preediting means that the data is displayed in
a preedit window that is placed over the point of insertion.
    </p></li><li class="listitem"><p>
<span class="emphasis"><em>Off-the-spot</em></span> 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.
    </p></li><li class="listitem"><p>
<span class="emphasis"><em>Root-window</em></span> preediting refers to input methods that use a preedit
window that is the child of 
<code class="function">RootWindow</code>.
    </p></li></ul></div><p>

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 <span class="emphasis"><em>input server</em></span>.
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 <span class="emphasis"><em>locale-dependent</em></span>.
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).
</p><p>

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.
</p><p>

An input method may be based on a <span class="emphasis"><em>front-end</em></span> or a <span class="emphasis"><em>back-end</em></span>
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.
</p><p>

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.
</p><p>

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.
</p><p>

The abstraction used by a client to communicate with an input method
is an opaque data structure represented by the 
<span class="type">XIM</span>
data type.
This data structure is returned by the 
<a class="xref" href="#XOpenIM"><code class="function">XOpenIM</code></a>
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.
</p><p>

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
<span class="type">XIM</span>
object.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Input_Contexts"></a>Input Contexts</h4></div></div></div><p>

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 <span class="emphasis"><em>input context</em></span>.
The Xlib representation of an input context is an 
<span class="type">XIC</span>.
</p><p>

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.
</p><p>

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 
<span class="type">XIC</span>
is created with the
<a class="xref" href="#XCreateIC"><code class="function">XCreateIC</code></a>
function, providing an 
<span class="type">XIM</span>
argument and affiliating the input context to the input method
for its lifetime. 
When an input method is closed with 
<a class="xref" href="#XCloseIM"><code class="function">XCloseIM</code></a>,
all of its affiliated input contexts should not be used any more
(and should preferably be destroyed before closing the input method).
</p><p>

Considering the example of a client window with multiple text entry areas,
the application programmer could, for example, choose to implement as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
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.
    </p></li></ul></div><p>

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.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Getting_Keyboard_Input"></a>Getting Keyboard Input</h4></div></div></div><p>

To obtain characters from an input method,
a client must call the function
<a class="xref" href="#XmbLookupString"><code class="function">XmbLookupString</code></a>
or 
<a class="xref" href="#XwcLookupString"><code class="function">XwcLookupString</code></a>
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 
<a class="xref" href="#XmbLookupString"><code class="function">XmbLookupString</code></a>
or
<a class="xref" href="#XwcLookupString"><code class="function">XwcLookupString</code></a>
will be encoded in that locale. 
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Focus_Management"></a>Focus Management</h4></div></div></div><p>

For each text entry area in which the
<a class="xref" href="#XmbLookupString"><code class="function">XmbLookupString</code></a>
or
<a class="xref" href="#XwcLookupString"><code class="function">XwcLookupString</code></a>
functions are used,
there will be an associated input context.
</p><p>

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 
<a class="xref" href="#XSetICFocus"><code class="function">XSetICFocus</code></a>
with the appropriate input context.
</p><p>

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
<a class="xref" href="#XUnsetICFocus"><code class="function">XUnsetICFocus</code></a>.
As an optimization, if
<a class="xref" href="#XSetICFocus"><code class="function">XSetICFocus</code></a>
is called successively on two different input contexts,
setting the focus on the second 
will automatically unset the focus on the first.
</p><p>

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.
</p><p>

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 <a class="link" href="#Focus_Window" title="Focus Window">section 13.5.6.3</a>).
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Geometry_Management"></a>Geometry Management</h4></div></div></div><p>

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.
</p><p>

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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The client is responsible for the geometry of the input method window.
    </p></li><li class="listitem"><p>
The input method is responsible for the contents of the input method window.
    </p></li></ul></div><p>

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.
</p><p>

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 
<span class="symbol">XIMPreeditArea</span>
or 
<span class="symbol">XIMStatusArea</span>
in its 
<span class="structname">XIMStyles</span>
value returned by 
<a class="xref" href="#XGetIMValues"><code class="function">XGetIMValues</code></a>.
When a client has decided that it will provide geometry management
for an input method, 
it indicates that decision by setting the
<span class="symbol">XNInputStyle</span>
value in the 
<span class="type">XIC</span>.
</p><p>

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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The client suggests an area to the input method by setting the
<span class="symbol">XNAreaNeeded</span>
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.
    </p></li><li class="listitem"><p>
The client will get the <acronym class="acronym">XIC</acronym> value 
<span class="symbol">XNAreaNeeded</span>.
The input method will return its suggested size in this value.
The input method should pay attention to any constraints suggested
by the client.
    </p></li><li class="listitem"><p>
The client sets the <acronym class="acronym">XIC</acronym> value
<span class="symbol">XNArea</span>
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.
    </p></li></ul></div><p>

Clients doing geometry management must be aware that setting other
<acronym class="acronym">XIC</acronym> values may affect the geometry desired by an input method.
For example, 
<span class="symbol">XNFontSet</span>
and
<span class="symbol">XNLineSpace</span>
may change the geometry desired by the input method.  
</p><p>

The table of <acronym class="acronym">XIC</acronym> values
(see <a class="link" href="#Input_Context_Values" title="Input Context Values">section 13.5.6</a>)
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.
</p><p>

In addition,
a geometry management callback is provided
by which an input method can initiate a geometry change.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Event_Filtering"></a>Event Filtering</h4></div></div></div><p>

A filtering mechanism is provided to allow input methods
to capture X events transparently to clients.
It is expected that toolkits (or clients) using
<a class="xref" href="#XmbLookupString"><code class="function">XmbLookupString</code></a>
or
<a class="xref" href="#XwcLookupString"><code class="function">XwcLookupString</code></a>
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.
</p><p>

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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Expose events on preedit window in local mode.
    </p></li><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
Key events can be sent to a filter before they are bound
to translations such as those the X Toolkit Intrinsics library provides.
    </p></li></ul></div><p>

Clients are expected to get the <acronym class="acronym">XIC</acronym> value 
<span class="symbol">XNFilterEvents</span>
and augment the event mask for the client window with that event mask.
This mask may be zero.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Callbacks"></a>Callbacks</h4></div></div></div><p>

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.
</p><p>

When the user enters a keystroke,
the client calls
<a class="xref" href="#XmbLookupString"><code class="function">XmbLookupString</code></a>
or
<a class="xref" href="#XwcLookupString"><code class="function">XwcLookupString</code></a>.
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.
</p><p>

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.
</p><p>

There are also callbacks provided for feedback of status information
and a callback to initiate a geometry request for an input method.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Visible_Position_Feedback_Masks"></a>Visible Position Feedback Masks</h4></div></div></div><p>

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
<span class="structname">XIMText</span>
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.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Preedit_String_Management"></a>Preedit String Management</h4></div></div></div><p>

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 
<a class="xref" href="#XmbLookupString"><code class="function">XmbLookupString</code></a>
or
<a class="xref" href="#XwcLookupString"><code class="function">XwcLookupString</code></a>.
This provides the basics for input methods.
</p><p>

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 
<span class="emphasis"><em>string conversion</em></span> and is provided using <acronym class="acronym">XIC</acronym> 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.
</p><p>

The need for string conversion is based on 
language needs and input method capabilities.
The following are some examples of string conversion:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
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.

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.
    </p></li><li class="listitem"><p>
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.  
    </p></li><li class="listitem"><p>
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.

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.

For this reason, an input method supporting this type of conversion
should take notice of when the client calls
<a class="xref" href="#XmbResetIC"><code class="function">XmbResetIC</code></a>
or
<a class="xref" href="#XwcResetIC"><code class="function">XwcResetIC</code></a>,
which is usually an indication of a context change.  
    </p></li></ul></div><p>

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
<a class="xref" href="#XmbLookupString"><code class="function">XmbLookupString</code></a>
and
<a class="xref" href="#XwcLookupString"><code class="function">XwcLookupString</code></a>
functions.
</p><p>

String conversion support is dependent on the availability of the 
<span class="symbol">XNStringConversion</span>
or 
<span class="symbol">XNStringConversionCallback</span>
<acronym class="acronym">XIC</acronym> values.
Because the input method may not support string conversions,
clients have to query the availability of string conversion
operations by checking the supported <acronym class="acronym">XIC</acronym> values list by calling
<a class="xref" href="#XGetIMValues"><code class="function">XGetIMValues</code></a>
with the
<span class="symbol">XNQueryICValuesList</span>
IM value.
</p><p>

The difference between these two values is whether the
conversion is invoked by the client or the input method.  
The 
<span class="symbol">XNStringConversion</span>
<acronym class="acronym">XIC</acronym> 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
<span class="symbol">XNStringConversionCallback</span>
will be issued when this value is set; thus, the client need
only set one of these values.
</p><p>

The
<span class="symbol">XNStringConversionCallback</span>
<acronym class="acronym">XIC</acronym> 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
<span class="structname">XIMStringConversionCallbackStruct</span>
specifies which text should be passed back to the input method.
</p><p>

Finally, the input method may call the client's 
<span class="symbol">XNStringConversionCallback</span>
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.
</p><p>

</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Input_Method_Management"></a>Input Method Management</h3></div></div></div><p>

The interface to input methods might appear to be simply creating
an input method
(<a class="xref" href="#XOpenIM"><code class="function">XOpenIM</code></a>)
and freeing an input method
(<a class="xref" href="#XCloseIM"><code class="function">XCloseIM</code></a>).
However, input methods may 
require complex communication with input method servers (IM servers),
for example:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
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.
    </p></li></ul></div><p>

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).
</p><p>

</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Some input methods may allow the underlying IM server to be switched. 
Such customization may be desired without restarting the entire client.
    </p></li></ul></div><p>

To support management of input methods in these cases, the following 
functions are provided:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left"><a class="xref" href="#XRegisterIMInstantiateCallback"><code class="function">XRegisterIMInstantiateCallback</code></a></td><td align="left">This function allows clients to register a callback procedure
      to be called when Xlib detects that an IM server is up and available.</td></tr><tr><td align="left"><a class="xref" href="#XOpenIM"><code class="function">XOpenIM</code></a></td><td align="left">A client calls this function as a result of the callback procedure
      being called.</td></tr><tr><td align="left"><a class="xref" href="#XSetIMValues"><code class="function">XSetIMValues</code></a>, <a class="xref" href="#XSetICValues"><code class="function">XSetICValues</code></a></td><td align="left">These functions use the <acronym class="acronym">XIM</acronym> and <acronym class="acronym">XIC</acronym> values,
      <span class="symbol">XNDestroyCallback</span>,
      to allow a client 
      to register a callback procedure to be called when Xlib detects that
      an IM server that was associated with an opened 
      input method is no longer available.
      In addition, this function can be used to switch IM servers for those input 
      methods that support such functionality.  The IM value for switching IM 
      servers is implementation-dependent; see the description below about
      switching IM servers.</td></tr><tr><td align="left"><a class="xref" href="#XUnregisterIMInstantiateCallback"><code class="function">XUnregisterIMInstantiateCallback</code></a></td><td align="left">This function removes a callback procedure registered by the client.</td></tr></tbody></table></div><p>

Input methods that support switching of IM servers may exhibit some
side-effects:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
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.
    </p></li></ul></div><p>

</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Geometry management requests on previously created input contexts
may be initiated by the new IM server.
    </p></li></ul></div><p>

</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Hot_Keys"></a>Hot Keys</h4></div></div></div><p>

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 <acronym class="acronym">XIC</acronym> values list by calling
<a class="xref" href="#XGetIMValues"><code class="function">XGetIMValues</code></a>
with the
<span class="symbol">XNQueryICValuesList</span>
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.
</p><p>

</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Preedit_State_Operation"></a>Preedit State Operation</h4></div></div></div><p>

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
<a class="xref" href="#XGetICValues"><code class="function">XGetICValues</code></a>
with the
<span class="symbol">XNPreeditState</span>
<acronym class="acronym">XIC</acronym> 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
<a class="xref" href="#XSetICValues"><code class="function">XSetICValues</code></a>
with the
<span class="symbol">XNPreeditStateNotifyCallback</span>
<acronym class="acronym">XIC</acronym> value. 
In order to change the preedit state programmatically, an application 
needs to call 
<a class="xref" href="#XSetICValues"><code class="function">XSetICValues</code></a>
with
<span class="symbol">XNPreeditState</span>.
</p><p>

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 <acronym class="acronym">XIC</acronym> values list by calling
<a class="xref" href="#XGetIMValues"><code class="function">XGetIMValues</code></a>
with the
<span class="symbol">XNQueryICValuesList</span>
IM value.
</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Input_Method_Functions"></a>Input Method Functions</h3></div></div></div><p>

To open a connection, use
<a class="xref" href="#XOpenIM"><code class="function">XOpenIM</code></a>.
</p><a id="idp51711140" class="indexterm"></a><div class="funcsynopsis"><a id="XOpenIM"></a><p><code class="funcdef">XIM <strong class="fsfunc">XOpenIM</strong>(</code>Display<var class="pdparam"> *display</var>, XrmDatabase<var class="pdparam"> db</var>, char<var class="pdparam"> *res_name</var>, char<var class="pdparam"> *res_class</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>db</em></span>
    </span></p></td><td><p>
Specifies a pointer to the resource database.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>res_name</em></span>
    </span></p></td><td><p>
Specifies the full resource name of the application.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>res_class</em></span>
    </span></p></td><td><p>
Specifies the full class name of the application.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XOpenIM"><code class="function">XOpenIM</code></a>
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
<a class="xref" href="#XmbLookupString"><code class="function">XmbLookupString</code></a>
or
<a class="xref" href="#XwcLookupString"><code class="function">XwcLookupString</code></a>,
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.
</p><p>

The specific input method to which this call will be routed
is identified on the basis of the current locale. 
<a class="xref" href="#XOpenIM"><code class="function">XOpenIM</code></a>
will identify a default input method corresponding to the
current locale.
That default can be modified using 
<a class="xref" href="#XSetLocaleModifiers"><code class="function">XSetLocaleModifiers</code></a>
for the input method modifier.
</p><p>

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.
</p><p>

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.
</p><p>

The res_name and res_class arguments are not assumed to exist beyond
the call to
<a class="xref" href="#XOpenIM"><code class="function">XOpenIM</code></a>.
The specified resource database is assumed to exist for the lifetime
of the input method.
</p><p>

<a class="xref" href="#XOpenIM"><code class="function">XOpenIM</code></a>
returns NULL if no input method could be opened.
</p><p>


To close a connection, use
<a class="xref" href="#XCloseIM"><code class="function">XCloseIM</code></a>.
</p><a id="idp51728532" class="indexterm"></a><div class="funcsynopsis"><a id="XCloseIM"></a><p><code class="funcdef">Status <strong class="fsfunc">XCloseIM</strong>(</code>XIM<var class="pdparam"> im</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>im</em></span>
    </span></p></td><td><p>
Specifies the input method.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCloseIM"><code class="function">XCloseIM</code></a>
function closes the specified input method.
</p><p>


To set input method attributes, use
<a class="xref" href="#XSetIMValues"><code class="function">XSetIMValues</code></a>.
</p><a id="idp51734468" class="indexterm"></a><div class="funcsynopsis"><a id="XSetIMValues"></a><p><code class="funcdef">char *<strong class="fsfunc">XSetIMValues</strong>(</code>XIM<var class="pdparam"> im</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>im</em></span>
    </span></p></td><td><p>
Specifies the input method.
      </p></td></tr><tr><td><p><span class="term">
      ...
    </span></p></td><td><p>
Specifies the variable-length argument list to set <acronym class="acronym">XIM</acronym>
values.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetIMValues"><code class="function">XSetIMValues</code></a>
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.
</p><p>


To query an input method, use 
<a class="xref" href="#XGetIMValues"><code class="function">XGetIMValues</code></a>.
</p><a id="idp51741948" class="indexterm"></a><div class="funcsynopsis"><a id="XGetIMValues"></a><p><code class="funcdef">char *<strong class="fsfunc">XGetIMValues</strong>(</code>XIM<var class="pdparam"> im</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>im</em></span>
    </span></p></td><td><p>
Specifies the input method.
      </p></td></tr><tr><td><p><span class="term">
      ...
    </span></p></td><td><p>
Specifies the variable length argument list to get XIM values.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetIMValues"><code class="function">XGetIMValues</code></a>
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.
</p><p>

Each <acronym class="acronym">XIM</acronym> value argument (following a name) must point to
a location where the <acronym class="acronym">XIM</acronym> value is to be stored.
That is, if the <acronym class="acronym">XIM</acronym> value is of type T,
the argument must be of type T*.
If T itself is a pointer type,
then
<a class="xref" href="#XGetIMValues"><code class="function">XGetIMValues</code></a>
allocates memory to store the actual data,
and the client is responsible for freeing this data by calling
<a class="xref" href="#XFree"></a>
with the returned pointer.
</p><p>


To obtain the display associated with an input method, use
<a class="xref" href="#XDisplayOfIM"><code class="function">XDisplayOfIM</code></a>.
</p><a id="idp51751332" class="indexterm"></a><div class="funcsynopsis"><a id="XDisplayOfIM"></a><p><code class="funcdef">Display *<strong class="fsfunc">XDisplayOfIM</strong>(</code>XIM<var class="pdparam"> im</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>im</em></span>
    </span></p></td><td><p>
Specifies the input method.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDisplayOfIM"><code class="function">XDisplayOfIM</code></a>
function returns the display associated with the specified input method.
</p><p>


To get the locale associated with an input method, use
<a class="xref" href="#XLocaleOfIM"><code class="function">XLocaleOfIM</code></a>.
</p><a id="idp51757340" class="indexterm"></a><div class="funcsynopsis"><a id="XLocaleOfIM"></a><p><code class="funcdef">char *<strong class="fsfunc">XLocaleOfIM</strong>(</code>XIM<var class="pdparam"> im</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>im</em></span>
    </span></p></td><td><p>
Specifies the input method.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XLocaleOfIM"><code class="function">XLocaleOfIM</code></a>
function returns the locale associated with the specified input method.
</p><p>


To register an input method instantiate callback, use
<a class="xref" href="#XRegisterIMInstantiateCallback"><code class="function">XRegisterIMInstantiateCallback</code></a>.
</p><a id="idp51763332" class="indexterm"></a><div class="funcsynopsis"><a id="XRegisterIMInstantiateCallback"></a><p><code class="funcdef">Bool <strong class="fsfunc">XRegisterIMInstantiateCallback</strong>(</code>Display<var class="pdparam"> *display</var>, XrmDatabase<var class="pdparam"> db</var>, char<var class="pdparam"> *res_name</var>, char<var class="pdparam"> *res_class</var>, XIMProc<var class="pdparam"> callback</var>, XPointer<var class="pdparam"> *client_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>db</em></span>
    </span></p></td><td><p>
Specifies a pointer to the resource database.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>res_name</em></span>
    </span></p></td><td><p>
Specifies the full resource name of the application.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>res_class</em></span>
    </span></p></td><td><p>
Specifies the full class name of the application.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>callback</em></span>
    </span></p></td><td><p>
Specifies a pointer to the input method instantiate callback.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies the additional client data.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XRegisterIMInstantiateCallback"><code class="function">XRegisterIMInstantiateCallback</code></a>
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.
</p><p>

The function returns 
<span class="symbol">True</span>
 if it succeeds; otherwise, it returns 
<span class="symbol">False</span>.
</p><p>

The generic prototype is as follows:
</p><a id="idp51778836" class="indexterm"></a><div class="funcsynopsis"><a id="IMInstantiateCallback"></a><p><code class="funcdef">void <strong class="fsfunc">IMInstantiateCallback</strong>(</code>Display<var class="pdparam"> *display</var>, XPointer<var class="pdparam"> client_data</var>, XPointer<var class="pdparam"> call_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies the additional client data.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>call_data</em></span>
    </span></p></td><td><p>
Not used for this callback and always passed as NULL.
    </p></td></tr></tbody></table></div><p>


To unregister an input method instantiation callback, use
<a class="xref" href="#XUnregisterIMInstantiateCallback"><code class="function">XUnregisterIMInstantiateCallback</code></a>.
</p><a id="idp51787556" class="indexterm"></a><div class="funcsynopsis"><a id="XUnregisterIMInstantiateCallback"></a><p><code class="funcdef">Bool <strong class="fsfunc">XUnregisterIMInstantiateCallback</strong>(</code>Display<var class="pdparam"> *display</var>, XrmDatabase<var class="pdparam"> db</var>, char<var class="pdparam"> *res_name</var>, char<var class="pdparam"> *res_class</var>, XIMProc<var class="pdparam"> callback</var>, XPointer<var class="pdparam"> *client_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>db</em></span>
    </span></p></td><td><p>
Specifies a pointer to the resource database.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>res_name</em></span>
    </span></p></td><td><p>
Specifies the full resource name of the application.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>res_class</em></span>
    </span></p></td><td><p>
Specifies the full class name of the application.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>callback</em></span>
    </span></p></td><td><p>
Specifies a pointer to the input method instantiate callback.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies the additional client data.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XUnregisterIMInstantiateCallback"><code class="function">XUnregisterIMInstantiateCallback</code></a>
function removes an input method instantiation callback previously
registered.
The function returns
<span class="symbol">True</span>
if it succeeds; otherwise, it returns 
<span class="symbol">False</span>.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Input_Method_Values"></a>Input Method Values</h3></div></div></div><p>

The following table describes how <acronym class="acronym">XIM</acronym> values are interpreted
by an input method.
The first column lists the <acronym class="acronym">XIM</acronym> values.
The second column indicates how each of the <acronym class="acronym">XIM</acronym> values 
are treated by that input style.
</p><p>

</p><p>

The following keys apply to this table.
</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Key</th><th align="left">Explanation</th></tr></thead><tbody><tr><td align="left">D</td><td align="left">This value may be set using
      <a class="xref" href="#XSetIMValues"><code class="function">XSetIMValues</code></a>.
      If it is not set,
      a default is provided.</td></tr><tr><td align="left">S</td><td align="left">This value may be set using <a class="xref" href="#XSetIMValues"><code class="function">XSetIMValues</code></a>.</td></tr><tr><td align="left">G</td><td align="left">This value may be read using <a class="xref" href="#XGetIMValues"><code class="function">XGetIMValues</code></a>.</td></tr></tbody></table></div><p></p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left"><acronym class="acronym">XIM</acronym> Value</th><th align="left">Key</th></tr></thead><tbody><tr><td align="left"><span class="symbol">XNQueryInputStyle</span></td><td align="left">G</td></tr><tr><td align="left"><span class="symbol">XNResourceName</span></td><td align="left">D-S-G</td></tr><tr><td align="left"><span class="symbol">XNResourceClass</span></td><td align="left">D-S-G</td></tr><tr><td align="left"><span class="symbol">XNDestroyCallback</span></td><td align="left">D-S-G</td></tr><tr><td align="left"><span class="symbol">XNQueryIMValuesList</span></td><td align="left">G</td></tr><tr><td align="left"><span class="symbol">XNQueryICValuesList</span></td><td align="left">G</td></tr><tr><td align="left"><span class="symbol">XNVisiblePosition</span></td><td align="left">G</td></tr><tr><td align="left"><span class="symbol">XNR6PreeditCallback</span></td><td align="left">D-S-G</td></tr></tbody></table></div><p>

<span class="symbol">XNR6PreeditCallback</span>
is obsolete and its use is not recommended
(see <a class="link" href="#Preedit_Callback_Behavior" title="Preedit Callback Behavior">section 13.5.4.6</a>).
</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Query_Input_Style"></a>Query Input Style</h4></div></div></div><p>

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.
</p><p>

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).
</p><p>

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
<span class="structname">XIMStyles</span>.
Clients are responsible for freeing the 
<span class="structname">XIMStyles</span>
structure.
To do so, use
<a class="xref" href="#XFree"></a>.
</p><p>

The
<span class="structname">XIMStyles</span>
structure is defined as follows:
</p><a id="idp51827324" class="indexterm"></a><a id="idp51827748" class="indexterm"></a><a id="idp51828180" class="indexterm"></a><a id="idp51828612" class="indexterm"></a><a id="idp51829044" class="indexterm"></a><a id="idp51829476" class="indexterm"></a><a id="idp51829908" class="indexterm"></a><a id="idp51830340" class="indexterm"></a><a id="idp51830772" class="indexterm"></a><a id="idp51831204" class="indexterm"></a><a id="idp51831636" class="indexterm"></a><pre class="literallayout">
typedef unsigned long XIMStyle;


#define     XIMPreeditArea             0x0001L
#define     XIMPreeditCallbacks        0x0002L
#define     XIMPreeditPosition         0x0004L
#define     XIMPreeditNothing          0x0008L
#define     XIMPreeditNone             0x0010L

#define     XIMStatusArea              0x0100L
#define     XIMStatusCallbacks         0x0200L
#define     XIMStatusNothing           0x0400L
#define     XIMStatusNone              0x0800L

typedef struct {
      unsigned short count_styles;
      XIMStyle * supported_styles;
} XIMStyles;

</pre><p>


An 
<span class="structname">XIMStyles</span>
structure contains the number of input styles supported
in its count_styles field.
This is also the size of the supported_styles array.
</p><p>

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.
</p><p>

The preedit category defines what type of support is provided
by the input method for preedit information.
</p><a id="idp51835404" class="indexterm"></a><a id="idp51835836" class="indexterm"></a><a id="idp51836268" class="indexterm"></a><a id="idp51836700" class="indexterm"></a><a id="idp51837132" class="indexterm"></a><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left"><span class="symbol">XIMPreeditArea</span></td><td align="left">If chosen,
      the input method would require the client to provide some area values
      for it to do its preediting.
      Refer to <acronym class="acronym">XIC</acronym> values 
      <span class="symbol">XNArea</span>
      and
      <span class="symbol">XNAreaNeeded</span>.</td></tr><tr><td align="left"><span class="symbol">XIMPreeditPosition</span></td><td align="left">If chosen,
      the input method would require the client to provide positional values. 
      Refer to <acronym class="acronym">XIC</acronym> values 
      <span class="symbol">XNSpotLocation</span>
      and
      <span class="symbol">XNFocusWindow</span>.</td></tr><tr><td align="left"><span class="symbol">XIMPreeditCallbacks</span></td><td align="left">If chosen,
      the input method would require the client to define the set of preedit callbacks.
      Refer to <acronym class="acronym">XIC</acronym> values 
      <span class="symbol">XNPreeditStartCallback</span>,
      <span class="symbol">XNPreeditDoneCallback</span>,
      <span class="symbol">XNPreeditDrawCallback</span>,
      and
      <span class="symbol">XNPreeditCaretCallback</span>.</td></tr><tr><td align="left"><span class="symbol">XIMPreeditNothing</span></td><td align="left">If chosen, the input method can function without any preedit values.</td></tr><tr><td align="left"><span class="symbol">XIMPreeditNone</span></td><td align="left">The input method does not provide any preedit feedback.
      Any preedit value is ignored.
      This style is mutually exclusive with the other preedit styles.</td></tr></tbody></table></div><p>

The status category defines what type of support is provided
by the input method for status information.
</p><a id="idp51847268" class="indexterm"></a><a id="idp51847700" class="indexterm"></a><a id="idp51848132" class="indexterm"></a><a id="idp51848564" class="indexterm"></a><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left"><span class="symbol">XIMStatusArea</span></td><td align="left">The input method requires the client to provide
      some area values for it to do its status feedback.
      See
      <span class="symbol">XNArea</span>
      and
      <span class="symbol">XNAreaNeeded</span>.</td></tr><tr><td align="left"><span class="symbol">XIMStatusCallbacks</span></td><td align="left">The input method requires the client to define the set of status callbacks,
      <span class="symbol">XNStatusStartCallback</span>,
      <span class="symbol">XNStatusDoneCallback</span>,
      and
      <span class="symbol">XNStatusDrawCallback</span>.</td></tr><tr><td align="left"><span class="symbol">XIMStatusNothing</span></td><td align="left">The input method can function without any status values.</td></tr><tr><td align="left"><span class="symbol">XIMStatusNone</span></td><td align="left">The input method does not provide any status feedback.
      If chosen, any status value is ignored.
      This style is mutually exclusive with the other status styles.</td></tr></tbody></table></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Resource_Name_and_Class_c"></a>Resource Name and Class</h4></div></div></div><p>

The
<span class="symbol">XNResourceName</span>
and
<span class="symbol">XNResourceClass</span>
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.
</p><p>

It is not intended that values that can be set as <acronym class="acronym">XIM</acronym> values be
set as resources.
</p><p>

</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Destroy_Callback"></a>Destroy Callback</h4></div></div></div><p>

The 
<span class="symbol">XNDestroyCallback</span>
argument is a pointer to a structure of type
<span class="structname">XIMCallback</span>.
<span class="symbol">XNDestroyCallback</span>
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
<a class="xref" href="#XCloseIM"><code class="function">XCloseIM</code></a>
or
<a class="xref" href="#XDestroyIC"><code class="function">XDestroyIC</code></a>.
</p><p>

The generic prototype of this callback function is as follows:
</p><a id="idp51863124" class="indexterm"></a><div class="funcsynopsis"><a id="DestroyCallback"></a><p><code class="funcdef">void <strong class="fsfunc">DestroyCallback</strong>(</code>XIM<var class="pdparam"> im</var>, XPointer<var class="pdparam"> client_data</var>, XPointer<var class="pdparam"> call_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>im</em></span>
    </span></p></td><td><p>
Specifies the input method.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies the additional client data.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>call_data</em></span>
    </span></p></td><td><p>
Not used for this callback and always passed as NULL.
    </p></td></tr></tbody></table></div><p>


A DestroyCallback is always called with a NULL call_data argument.
</p><p>

</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Query_IMIC_Values_List"></a>Query IM/IC Values List</h4></div></div></div><p>

<span class="symbol">XNQueryIMValuesList</span>
and
<span class="symbol">XNQueryICValuesList</span>
are used to query about <acronym class="acronym">XIM</acronym> and <acronym class="acronym">XIC</acronym> values supported by the input method.
</p><p>

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
<span class="structname">XIMValuesList</span>.
Clients are responsible for freeing the 
<span class="structname">XIMValuesList</span>
structure.
To do so, use
<a class="xref" href="#XFree"></a>.
</p><p>

The
<span class="structname">XIMValuesList</span>
structure is defined as follows:

</p><pre class="literallayout">


typedef struct {
     unsigned short count_values;
     char **supported_values;
} XIMValuesList;
</pre><p>
</p><p>


</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Visible_Position"></a>Visible Position</h4></div></div></div><p>

The 
<span class="symbol">XNVisiblePosition</span>
argument indicates whether the visible position masks of 
<span class="type">XIMFeedback</span>
in
<span class="structname">XIMText</span>
are available.
</p><p>

The argument value must be a pointer to a location where the returned
value will be stored.  The returned value is of type
<span class="type">Bool</span>.
If the returned value is
<span class="symbol">True</span>,
the input method uses the visible position masks of
<span class="type">XIMFeedback</span>
in
<span class="structname">XIMText</span>;
otherwise, the input method does not use the masks.
</p><p>

Because this <acronym class="acronym">XIM</acronym> value is optional, a client should call
<a class="xref" href="#XGetIMValues"><code class="function">XGetIMValues</code></a>
with argument
<span class="symbol">XNQueryIMValuesList</span>
before using this argument.
If the 
<span class="symbol">XNVisiblePosition</span>
does not exist in the IM values list returned from 
<span class="symbol">XNQueryIMValuesList</span>,
the visible position masks of
<span class="type">XIMFeedback</span>
in
<span class="structname">XIMText</span>
are not used to indicate the visible position.
</p><p>

</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Preedit_Callback_Behavior"></a>Preedit Callback Behavior</h4></div></div></div><p>

The
<span class="symbol">XNR6PreeditCallback</span>
argument originally included in the X11R6 specification has been
deprecated.\(dg



During formulation of the X11R6 specification, the behavior of
the R6 PreeditDrawCallbacks was going to differ significantly from
that of the R5 callbacks.
Late changes to the specification converged the R5 and R6 behaviors,
eliminating the need for
<span class="symbol">XNR6PreeditCallback</span>.
Unfortunately, this argument was not removed from the R6 specification
before it was published.

</p><p>

The 
<span class="symbol">XNR6PreeditCallback</span>
argument indicates whether the behavior of preedit callbacks regarding
<span class="structname">XIMPreeditDrawCallbackStruct</span>
values follows Release 5 or Release 6 semantics.
</p><p>

The value is of type
<span class="type">Bool</span>.
When querying for
<span class="symbol">XNR6PreeditCallback</span>,
if the returned value is
<span class="symbol">True</span>,
the input method uses the Release 6 behavior;
otherwise, it uses the Release 5 behavior.
The default value is
<span class="symbol">False</span>.
In order to use Release 6 semantics, the value of
<span class="symbol">XNR6PreeditCallback</span>
must be set to
<span class="symbol">True</span>.
</p><p>

Because this <acronym class="acronym">XIM</acronym> value is optional, a client should call
<a class="xref" href="#XGetIMValues"><code class="function">XGetIMValues</code></a>
with argument
<span class="symbol">XNQueryIMValuesList</span>
before using this argument.
If the
<span class="symbol">XNR6PreeditCallback</span>
does not exist in the IM values list returned from
<span class="symbol">XNQueryIMValuesList</span>,
the PreeditCallback behavior is Release 5 semantics.
</p><p>

</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Input_Context_Functions"></a>Input Context Functions</h3></div></div></div><p>

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 <acronym class="acronym">XIC</acronym> values.
It is intended that input methods be controlled by these <acronym class="acronym">XIC</acronym> values.
As new <acronym class="acronym">XIC</acronym> values are created,
they should be registered with the X Consortium.
</p><p>


To create an input context, use
<a class="xref" href="#XCreateIC"><code class="function">XCreateIC</code></a>.
</p><a id="idp51896892" class="indexterm"></a><div class="funcsynopsis"><a id="XCreateIC"></a><p><code class="funcdef">XIC <strong class="fsfunc">XCreateIC</strong>(</code>XIM<var class="pdparam"> im</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>im</em></span>
    </span></p></td><td><p>
Specifies the input method.
      </p></td></tr><tr><td><p><span class="term">
      ...
    </span></p></td><td><p>
Specifies the variable length argument list to set <acronym class="acronym">XIC</acronym>
values.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCreateIC"><code class="function">XCreateIC</code></a>
function creates a context within the specified input method.
</p><p>

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.
</p><p>

<a class="xref" href="#XCreateIC"><code class="function">XCreateIC</code></a>
returns a NULL value if no input context could be created.
A NULL value could be returned for any of the following reasons:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
A required argument was not set.
    </p></li><li class="listitem"><p>
A read-only argument was set (for example,
<span class="symbol">XNFilterEvents</span>).
    </p></li><li class="listitem"><p>
The argument name is not recognized.
    </p></li><li class="listitem"><p>
The input method encountered an input method implementation-dependent error.
    </p></li></ul></div><p>

<a class="xref" href="#XCreateIC"><code class="function">XCreateIC</code></a>
can generate
<span class="errorname">BadAtom</span>,
<span class="errorname">BadColor</span>,
<span class="errorname">BadPixmap</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To destroy an input context, use
<a class="xref" href="#XDestroyIC"><code class="function">XDestroyIC</code></a>.
</p><a id="idp51909756" class="indexterm"></a><div class="funcsynopsis"><a id="XDestroyIC"></a><p><code class="funcdef">void <strong class="fsfunc">XDestroyIC</strong>(</code>XIC<var class="pdparam"> ic</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input context.
    </p></td></tr></tbody></table></div><p>


<a class="xref" href="#XDestroyIC"><code class="function">XDestroyIC</code></a>
destroys the specified input context.
</p><p>


To communicate to and synchronize with input method
for any changes in keyboard focus from the client side,
use 
<a class="xref" href="#XSetICFocus"><code class="function">XSetICFocus</code></a>
and
<a class="xref" href="#XUnsetICFocus"><code class="function">XUnsetICFocus</code></a>.
</p><a id="idp51916180" class="indexterm"></a><div class="funcsynopsis"><a id="XSetICFocus"></a><p><code class="funcdef">void <strong class="fsfunc">XSetICFocus</strong>(</code>XIC<var class="pdparam"> ic</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input context.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetICFocus"><code class="function">XSetICFocus</code></a>
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.
</p><p>

Calling
<a class="xref" href="#XSetICFocus"><code class="function">XSetICFocus</code></a>
does not affect the focus window value.
</p><a id="idp51922180" class="indexterm"></a><div class="funcsynopsis"><a id="XUnsetICFocus"></a><p><code class="funcdef">void <strong class="fsfunc">XUnsetICFocus</strong>(</code>XIC<var class="pdparam"> ic</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input context.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XUnsetICFocus"><code class="function">XUnsetICFocus</code></a>
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.
</p><p>

Calling
<a class="xref" href="#XUnsetICFocus"><code class="function">XUnsetICFocus</code></a>
does not affect the focus window value;
the client may still receive 
events from the input method that are directed to the focus window.
</p><p>


To reset the state of an input context to its initial state, use
<a class="xref" href="#XmbResetIC"><code class="function">XmbResetIC</code></a>
or
<a class="xref" href="#XwcResetIC"><code class="function">XwcResetIC</code></a>.
</p><a id="idp51929828" class="indexterm"></a><a id="idp51930252" class="indexterm"></a><div class="funcsynopsis"><a id="XmbResetIC"></a><p><code class="funcdef">char *<strong class="fsfunc">XmbResetIC</strong>(</code>XIC<var class="pdparam"> ic</var><code>)</code>;</p></div><div class="funcsynopsis"><a id="XwcResetIC"></a><p><code class="funcdef">wchar_t *<strong class="fsfunc">XwcResetIC</strong>(</code>XIC<var class="pdparam"> ic</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input context.
    </p></td></tr></tbody></table></div><p>


When
<span class="symbol">XNResetState</span>
is set to
<span class="symbol">XIMInitialState</span>,
<a class="xref" href="#XmbResetIC"><code class="function">XmbResetIC</code></a>
and
<a class="xref" href="#XwcResetIC"><code class="function">XwcResetIC</code></a>
reset an input context to its initial state;
when
<span class="symbol">XNResetState</span>
is set to
<span class="symbol">XIMPreserveState</span>,
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 
<a class="xref" href="#XmbResetIC"><code class="function">XmbResetIC</code></a>
or
<a class="xref" href="#XwcResetIC"><code class="function">XwcResetIC</code></a>
does not change the focus.
</p><p>

The return value of
<a class="xref" href="#XmbResetIC"><code class="function">XmbResetIC</code></a>
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.
</p><p>

The client should free the returned string by calling
<a class="xref" href="#XFree"></a>.
</p><p>


To get the input method associated with an input context, use
<a class="xref" href="#XIMOfIC"><code class="function">XIMOfIC</code></a>.
</p><a id="idp51942420" class="indexterm"></a><div class="funcsynopsis"><a id="XIMOfIC"></a><p><code class="funcdef">XIM <strong class="fsfunc">XIMOfIC</strong>(</code>XIC<var class="pdparam"> ic</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input context.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XIMOfIC"><code class="function">XIMOfIC</code></a>
function returns the input method associated with the specified input context.
</p><p>


Xlib provides two functions for setting and reading <acronym class="acronym">XIC</acronym> values, respectively,
<a class="xref" href="#XSetICValues"><code class="function">XSetICValues</code></a>
and
<a class="xref" href="#XGetICValues"><code class="function">XGetICValues</code></a>.
Both functions have a variable-length argument list.
In that argument list, any <acronym class="acronym">XIC</acronym> value's name must be denoted
with a character string using the X Portable Character Set.
</p><p>


To set <acronym class="acronym">XIC</acronym> values, use
<a class="xref" href="#XSetICValues"><code class="function">XSetICValues</code></a>.
</p><a id="idp51950660" class="indexterm"></a><div class="funcsynopsis"><a id="XSetICValues"></a><p><code class="funcdef">char *<strong class="fsfunc">XSetICValues</strong>(</code>XIC<var class="pdparam"> ic</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input context.
      </p></td></tr><tr><td><p><span class="term">
      ...
    </span></p></td><td><p>
Specifies the variable length argument list to set <acronym class="acronym">XIC</acronym>
values.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetICValues"><code class="function">XSetICValues</code></a>
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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The argument is read-only (for example,
<span class="symbol">XNFilterEvents</span>).
    </p></li><li class="listitem"><p>
The argument name is not recognized.
    </p></li><li class="listitem"><p>
An implementation-dependent error occurs.
    </p></li></ul></div><p>

Each value to be set must be an appropriate datum,
matching the data type imposed by the semantics of the argument.
</p><p>

<a class="xref" href="#XSetICValues"><code class="function">XSetICValues</code></a>
can generate
<span class="errorname">BadAtom</span>,
<span class="errorname">BadColor</span>,
<span class="errorname">BadCursor</span>,
<span class="errorname">BadPixmap</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To obtain <acronym class="acronym">XIC</acronym> values, use
<a class="xref" href="#XGetICValues"><code class="function">XGetICValues</code></a>.
</p><a id="idp51962508" class="indexterm"></a><div class="funcsynopsis"><a id="XGetICValues"></a><p><code class="funcdef">char *<strong class="fsfunc">XGetICValues</strong>(</code>XIC<var class="pdparam"> ic</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input context.
      </p></td></tr><tr><td><p><span class="term">
      ...
    </span></p></td><td><p>
Specifies the variable length argument list to get XIC values.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetICValues"><code class="function">XGetICValues</code></a>
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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The argument name is not recognized.
    </p></li><li class="listitem"><p>
The input method encountered an implementation-dependent error.
    </p></li></ul></div><p>

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
<a class="xref" href="#XGetICValues"><code class="function">XGetICValues</code></a>
allocates memory to store the actual data,
and the client is responsible for freeing this data by calling
<a class="xref" href="#XFree"></a>
with the returned pointer.
The exception to this rule is for an IC value of type
<span class="type">XVaNestedList</span>
(for preedit and status attributes).
In this case,  the argument must also be of type
<span class="type">XVaNestedList</span>.
Then, the rule of changing type T to T* and freeing the allocated data
applies to each element of the nested list.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Input_Context_Values"></a>Input Context Values</h3></div></div></div><p>

The following tables describe how <acronym class="acronym">XIC</acronym> values are interpreted
by an input method depending on the input style chosen by the 
user.
</p><p>

The first column lists the <acronym class="acronym">XIC</acronym> 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 <acronym class="acronym">XIC</acronym> values 
are treated by that input style.
</p><p>

The following keys apply to these tables.
</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Key</th><th align="left">Explanation</th></tr></thead><tbody><tr><td align="left">C</td><td align="left">This value must be set with <a class="xref" href="#XCreateIC"><code class="function">XCreateIC</code></a>.</td></tr><tr><td align="left">D</td><td align="left">This value may be set using 
      <a class="xref" href="#XCreateIC"><code class="function">XCreateIC</code></a>.&gt;
      If it is not set,&gt;
      a default is provided.</td></tr><tr><td align="left">G</td><td align="left">This value may be read using 
      <a class="xref" href="#XGetICValues"><code class="function">XGetICValues</code></a>.</td></tr><tr><td align="left">GN</td><td align="left">This value may cause geometry negotiation when its value is set by means of
      <a class="xref" href="#XCreateIC"><code class="function">XCreateIC</code></a>
      or
      <a class="xref" href="#XSetICValues"><code class="function">XSetICValues</code></a>.</td></tr><tr><td align="left">GR</td><td align="left">This value will be the response of the input method when any 
      GN value is changed.</td></tr><tr><td align="left">GS</td><td align="left">This value will cause the geometry of the input method window to be set.</td></tr><tr><td align="left">O</td><td align="left">This value must be set once and only once.
      It need not be set at create time.</td></tr><tr><td align="left">S</td><td align="left">This value may be set with
      <a class="xref" href="#XSetICValues"><code class="function">XSetICValues</code></a>.</td></tr><tr><td align="left">Ignored</td><td align="left">This value is ignored by the input method for the given input style.</td></tr></tbody></table></div><p></p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /><col align="left" class="c5" /><col align="left" class="c6" /><col align="left" class="c7" /></colgroup><thead><tr><th align="left"><acronym class="acronym">XIC</acronym> Value</th><th align="left">Geometry Mangement</th><th align="left">Preedit Callback</th><th align="left">Preedit Position</th><th align="left">Input Style Preedit Area</th><th align="left">Preedit Nothing</th><th align="left">Preedit None</th></tr></thead><tbody><tr><td align="left">Input Style</td><td align="left"> </td><td align="left">C-G</td><td align="left">C-G</td><td align="left">C-G</td><td align="left">C-G</td><td align="left">C-G</td></tr><tr><td align="left">Client Window</td><td align="left"> </td><td align="left">O-G</td><td align="left">O-G</td><td align="left">O-G</td><td align="left">O-G</td><td align="left">Ignored</td></tr><tr><td align="left">Focus Window</td><td align="left">GN</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Resource Name</td><td align="left"> </td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Resource Class</td><td align="left"> </td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Geometry Callback</td><td align="left"> </td><td align="left">Ignored</td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">Ignored</td><td align="left">Ignored</td></tr><tr><td align="left">Filter Events</td><td align="left"> </td><td align="left">G</td><td align="left">G</td><td align="left">G</td><td align="left">G</td><td align="left">Ignored</td></tr><tr><td align="left">Destroy Callback</td><td align="left"> </td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td></tr><tr><td align="left">String Conversion Callback</td><td align="left"> </td><td align="left">S-G</td><td align="left">S-G</td><td align="left">S-G</td><td align="left">S-G</td><td align="left">S-G</td></tr><tr><td align="left">String Conversion</td><td align="left"> </td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td></tr><tr><td align="left">Reset State</td><td align="left"> </td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">HotKey</td><td align="left"> </td><td align="left">S-G</td><td align="left">S-G</td><td align="left">S-G</td><td align="left">S-G</td><td align="left">Ignored</td></tr><tr><td align="left">HotKeyState</td><td align="left"> </td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left"><code class="function">Preedit</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td><td class="auto-generated"> </td><td class="auto-generated"> </td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr><tr><td align="left">Area</td><td align="left">GS</td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td><td align="left">Ignored</td></tr><tr><td align="left">Area Needed</td><td align="left">GN-GR</td><td align="left">Ignored</td><td align="left">Ignored</td><td align="left">S-G</td><td align="left">Ignored</td><td align="left">Ignored</td></tr><tr><td align="left">Spot Location</td><td align="left"> </td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">Ignored</td><td align="left">Ignored</td><td align="left">Ignored</td></tr><tr><td align="left">Colormap</td><td align="left"> </td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Foreground</td><td align="left"> </td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Background</td><td align="left"> </td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Background Pixmap</td><td align="left"> </td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Font Set</td><td align="left">GN</td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Line Spacing</td><td align="left">GN</td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Cursor</td><td align="left"> </td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Preedit State</td><td align="left"> </td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Preedit State Notify Callback</td><td align="left"> </td><td align="left">S-G</td><td align="left">S-G</td><td align="left">S-G</td><td align="left">S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Preedit Callbacks</td><td align="left"> </td><td align="left">C-S-G</td><td align="left">Ignored</td><td align="left">Ignored</td><td align="left">Ignored</td><td align="left">Ignored</td></tr></tbody></table></div><p></p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /><col align="left" class="c5" /><col align="left" class="c6" /></colgroup><thead><tr><th align="left"><acronym class="acronym">XIC</acronym> Value</th><th align="left">Geomentry Management</th><th align="left">Status Callback</th><th align="left">Status Area</th><th align="left">Status Nothing</th><th align="left">Status None</th></tr></thead><tbody><tr><td align="left">Input Style</td><td align="left"> </td><td align="left">C-G</td><td align="left">C-G</td><td align="left">C-G</td><td align="left">C-G</td></tr><tr><td align="left">Client Window</td><td align="left"> </td><td align="left">O-G</td><td align="left">O-G</td><td align="left">O-G</td><td align="left">Ignored</td></tr><tr><td align="left">Focus Window</td><td align="left">GN</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Resource Name</td><td align="left"> </td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Resource Class</td><td align="left"> </td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Geometry Callback</td><td align="left"> </td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">Ignored</td><td align="left">Ignored</td></tr><tr><td align="left">Filter Events</td><td align="left"> </td><td align="left">G</td><td align="left">G</td><td align="left">G</td><td align="left">G</td></tr><tr><td align="left"><span class="type">Status</span></td><td class="auto-generated"> </td><td class="auto-generated"> </td><td class="auto-generated"> </td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr><tr><td align="left">Area</td><td align="left">GS</td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">Ignored</td><td align="left">Ignored</td></tr><tr><td align="left">Area Needed</td><td align="left">GN-GR</td><td align="left">Ignored</td><td align="left">S-G</td><td align="left">Ignored</td><td align="left">Ignored</td></tr><tr><td align="left">Colormap</td><td align="left"> </td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Foreground</td><td align="left"> </td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Background</td><td align="left"> </td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Background Pixmap</td><td align="left"> </td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Font Set</td><td align="left">GN</td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Line Spacing</td><td align="left">GN</td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Cursor</td><td align="left"> </td><td align="left">Ignored</td><td align="left">D-S-G</td><td align="left">D-S-G</td><td align="left">Ignored</td></tr><tr><td align="left">Status Callbacks</td><td align="left"> </td><td align="left">C-S-G</td><td align="left">Ignored</td><td align="left">Ignored</td><td align="left">Ignored</td></tr></tbody></table></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Input_Style"></a>Input Style</h4></div></div></div><p>

The
<span class="symbol">XNInputStyle</span>
argument specifies the input style to be used.
The value of this argument must be one of the values returned by the
<a class="xref" href="#XGetIMValues"><code class="function">XGetIMValues</code></a>
function with the
<span class="symbol">XNQueryInputStyle</span>
argument specified in the supported_styles list.
</p><p>

Note that this argument must be set at creation time
and cannot be changed.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Client_Window"></a>Client Window</h4></div></div></div><p>

<a id="idp52078356" class="indexterm"></a>
The
<span class="symbol">XNClientWindow</span>
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.
</p><p>

If an attempt is made to set this value a second time with
<a class="xref" href="#XSetICValues"><code class="function">XSetICValues</code></a>,
the string
<span class="symbol">XNClientWindow</span>
will be returned by
<a class="xref" href="#XSetICValues"><code class="function">XSetICValues</code></a>,
and the client window will not be changed.
</p><p>

If the client window is not a valid window ID on the display
attached to the input method,
a 
<span class="errorname">BadWindow</span>
error can be generated when this value is used by the input method.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Focus_Window"></a>Focus Window</h4></div></div></div><p>

<a id="idp52083356" class="indexterm"></a>
The
<span class="symbol">XNFocusWindow</span>
argument specifies the focus window.
The primary purpose of the 
<span class="symbol">XNFocusWindow</span>
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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Select events on it
    </p></li><li class="listitem"><p>
Send events to it
    </p></li><li class="listitem"><p>
Modify its properties
    </p></li><li class="listitem"><p>
Grab the keyboard within that window  
    </p></li></ul></div><p>

The associated value must be of type 
<span class="type">Window</span>.
If the focus window is not a valid window ID on the display 
attached to the input method,
a 
<span class="errorname">BadWindow</span>
error can be generated when this value is used by the input method.
</p><p>

When this <acronym class="acronym">XIC</acronym> value is left unspecified,
the input method will use the client window as the default focus window.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Resource_Name_and_Class_b"></a>Resource Name and Class</h4></div></div></div><p>

<a id="idp52089884" class="indexterm"></a>
<a id="idp52090316" class="indexterm"></a>
The
<span class="symbol">XNResourceName</span>
and
<span class="symbol">XNResourceClass</span>
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.
</p><p>

It is not intended that values that can be set as <acronym class="acronym">XIC</acronym> values be
set as resources.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Geometry_Callback"></a>Geometry Callback</h4></div></div></div><p>

<a id="idp52093772" class="indexterm"></a>
The 
<span class="symbol">XNGeometryCallback</span>
argument is a structure of type 
<span class="structname">XIMCallback</span>
(see <a class="link" href="#Preedit_and_Status_Callbacks" title="Preedit and Status Callbacks">section 13.5.6.13.12</a>).
</p><p>

The 
<span class="symbol">XNGeometryCallback</span>
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.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Filter_Events"></a>Filter Events</h4></div></div></div><p>

<a id="idp52097660" class="indexterm"></a>
The 
<span class="symbol">XNFilterEvents</span>
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.
</p><p>

This argument is read-only, is set by the input method at create time,
and is never changed.
</p><p>

The type of this argument is 
<span class="type">unsigned</span>
<span class="type">long</span>.
Setting this value will cause an error.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Destroy_Callback_b"></a>Destroy Callback</h4></div></div></div><p>

The 
<span class="symbol">XNDestroyCallback</span>
argument is a pointer to a structure of type
<span class="structname">XIMCallback</span>
(see <a class="link" href="#Preedit_and_Status_Callbacks" title="Preedit and Status Callbacks">section 13.5.6.13.12</a>).
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 
<a class="xref" href="#XDestroyIC"><code class="function">XDestroyIC</code></a>
and
<a class="xref" href="#XCloseIM"><code class="function">XCloseIM</code></a>.
</p><p>

</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="String_Conversion_Callback"></a>String Conversion Callback</h4></div></div></div><p>

The
<span class="symbol">XNStringConversionCallback</span>
argument is a structure of type
<span class="structname">XIMCallback</span>
(see <a class="link" href="#Preedit_and_Status_Callbacks" title="Preedit and Status Callbacks">section 13.5.6.13.12</a>).
</p><p>

The
<span class="symbol">XNStringConversionCallback</span>
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.
</p><p>

Because this <acronym class="acronym">XIC</acronym> value is optional, a client should call
<a class="xref" href="#XGetIMValues"><code class="function">XGetIMValues</code></a>
with argument
<span class="symbol">XNQueryICValuesList</span>
before using this argument.
</p><p>

</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="String_Conversion"></a>String Conversion</h4></div></div></div><p>

The
<span class="symbol">XNStringConversion</span>
argument is a structure of type
<span class="structname">XIMStringConversionText</span>.
</p><p>

The
<span class="symbol">XNStringConversion</span>
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.
</p><p>

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.
</p><p>

Because this <acronym class="acronym">XIC</acronym> value is optional, a client should call
<a class="xref" href="#XGetIMValues"><code class="function">XGetIMValues</code></a>
with argument
<span class="symbol">XNQueryICValuesList</span>
before using this argument.
</p><p>

The
<span class="structname">XIMStringConversionText</span>
structure is defined as follows:
</p><p>


</p><pre class="literallayout">

typedef struct _XIMStringConversionText {
     unsigned short              length;
     XIMStringConversionFeedback *feedback;
     Bool                        encoding_is_wchar;
     union {
          char     *mbs;
          wchar_t  *wcs;
     } string;
} XIMStringConversionText;

typedef unsigned long XIMStringConversionFeedback;
</pre><p>
</p><p>


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.
</p><p>

</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Reset_State"></a>Reset State</h4></div></div></div><p>

The
<span class="symbol">XNResetState</span>
argument specifies the state the input context will return to after calling
<a class="xref" href="#XmbResetIC"><code class="function">XmbResetIC</code></a>
or
<a class="xref" href="#XwcResetIC"><code class="function">XwcResetIC</code></a>.
</p><p>

The <acronym class="acronym">XIC</acronym> state may be set to its initial state, as specified by the
<span class="symbol">XNPreeditState</span>
value when
<a class="xref" href="#XCreateIC"><code class="function">XCreateIC</code></a>
was called, or it may be set to preserve the current state.
</p><p>

The valid masks for
<span class="type">XIMResetState</span>
are as follows:
</p><p>

<a id="idp52122148" class="indexterm"></a>
<a id="idp52122580" class="indexterm"></a>

</p><pre class="literallayout">
typedef unsigned long XIMResetState;

#define XIMInitialState  (1L)
#define XIMPreserveState (1L&lt;&lt;1)

</pre><p>


If
<span class="symbol">XIMInitialState</span>
is set, then
<a class="xref" href="#XmbResetIC"><code class="function">XmbResetIC</code></a>
and
<a class="xref" href="#XwcResetIC"><code class="function">XwcResetIC</code></a>
will return to the initial
<span class="symbol">XNPreeditState</span>
state of the <acronym class="acronym">XIC</acronym>.
</p><p>

If
<span class="symbol">XIMPreserveState</span>
is set, then 
<a class="xref" href="#XmbResetIC"><code class="function">XmbResetIC</code></a>
and
<a class="xref" href="#XwcResetIC"><code class="function">XwcResetIC</code></a>
will preserve the current state of the <acronym class="acronym">XIC</acronym>.
</p><p>

If
<span class="symbol">XNResetState</span>
is left unspecified, the default is
<span class="symbol">XIMInitialState</span>.
</p><p>

<span class="type">XIMResetState</span>
values other than those specified above will default to
<span class="symbol">XIMInitialState</span>.
</p><p>

Because this <acronym class="acronym">XIC</acronym> value is optional, a client should call
<a class="xref" href="#XGetIMValues"><code class="function">XGetIMValues</code></a>
with argument
<span class="symbol">XNQueryICValuesList</span>
before using this argument.
</p><p>

</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Hot_Keys_b"></a>Hot Keys</h4></div></div></div><p>

The
<span class="symbol">XNHotKey</span>
argument specifies the hot key list to the <acronym class="acronym">XIC</acronym>.
The hot key list is a pointer to the structure of type
<span class="structname">XIMHotKeyTriggers</span>,
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
<span class="symbol">XNHotKeyState</span>
to
<span class="symbol">XIMHotKeyStateON</span>.
</p><p>

Because this <acronym class="acronym">XIC</acronym> value is optional, a client should call
<a class="xref" href="#XGetIMValues"><code class="function">XGetIMValues</code></a>
with argument
<span class="symbol">XNQueryICValuesList</span>
before using this functionality.
</p><p>

The value of the argument is a pointer to a structure of type
<span class="structname">XIMHotKeyTriggers</span>.
</p><p>

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.
</p><p>


</p><pre class="literallayout">


typedef struct {
     KeySym keysym;
     unsigned int modifier;
     unsigned int modifier_mask;
} XIMHotKeyTrigger;

typedef struct {
     int num_hot_key;
     XIMHotKeyTrigger *key;
} XIMHotKeyTriggers;
</pre><p>
</p><p>


</p><p>

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.
</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /></colgroup><thead><tr><th align="left">Modifier Bit</th><th align="left">Mask Bit</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left">0</td><td align="left">1</td><td align="left">The modifier must be off.</td></tr><tr><td align="left">1</td><td align="left">1</td><td align="left">The modifier must be on.</td></tr><tr><td align="left">n/a</td><td align="left">0</td><td align="left">Do not care if the modifier is on or off.</td></tr></tbody></table></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Hot_Key_State"></a>Hot Key State</h4></div></div></div><p>

The
<span class="symbol">XNHotKeyState</span>
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.
</p><p>

The value of the argument is a pointer to a structure of type
XIMHotKeyState .
</p><pre class="literallayout">
typedef unsigned long XIMHotKeyState;

#define XIMHotKeyStateON            (0x0001L)
#define XIMHotKeyStateOFF           (0x0002L)

</pre><p>


</p><p>

If not specified, the default is
<span class="symbol">XIMHotKeyStateOFF</span>.
</p><p>

</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Preedit_and_Status_Attributes"></a>Preedit and Status Attributes</h4></div></div></div><p>

<a id="idp52152476" class="indexterm"></a>
<a id="idp52152908" class="indexterm"></a>
The
<span class="symbol">XNPreeditAttributes</span>
and
<span class="symbol">XNStatusAttributes</span>
arguments specify to an input method the attributes to be used for the 
preedit and status areas,
if any.
Those attributes are passed to 
<a class="xref" href="#XSetICValues"><code class="function">XSetICValues</code></a>
or
<a class="xref" href="#XGetICValues"><code class="function">XGetICValues</code></a>
as a nested variable-length list.
The names to be used in these lists are described in the following sections.
</p><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="Area"></a>Area</h5></div></div></div><p>

<a id="idp52156348" class="indexterm"></a>
The value of the
<span class="symbol">XNArea</span>
argument must be a pointer to a structure of type
<span class="structname">XRectangle</span>.
The interpretation of the
<span class="symbol">XNArea</span>
argument is dependent on the input method style that has been set.
</p><p>

If the input method style is 
<span class="symbol">XIMPreeditPosition</span>,
<span class="symbol">XNArea</span>
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.
</p><p>

If 
<span class="symbol">XNArea</span>
is not specified, is set to NULL, or is invalid,
the input method will default the clipping region
to the geometry of the
<span class="symbol">XNFocusWindow</span>.
If the area specified is NULL or invalid,
the results are undefined.
</p><p>

If the input style is 
<span class="symbol">XIMPreeditArea</span>
or 
<span class="symbol">XIMStatusArea</span>,
<span class="symbol">XNArea</span>
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
<span class="symbol">XNArea</span>.
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 
<span class="symbol">XNArea</span>
is not specified, is set to NULL, or is invalid,
the results are undefined.
</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="Area_Needed"></a>Area Needed</h5></div></div></div><p>

<a id="idp52163348" class="indexterm"></a>
When set, the
<span class="symbol">XNAreaNeeded</span>
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 
<span class="structname">XRectangle</span>.
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.
</p><p>

When read, the
<span class="symbol">XNAreaNeeded</span>
argument specifies the preferred geometry desired by the input method
for the area.
</p><p>

This argument is only valid if the input style is 
<span class="symbol">XIMPreeditArea</span>
or 
<span class="symbol">XIMStatusArea</span>.
It is used for geometry negotiation between the client and the input method
and has no other effect on the input method 
(see <a class="link" href="#Geometry_Management" title="Geometry Management">section 13.5.1.5</a>).
</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="Spot_Location"></a>Spot Location</h5></div></div></div><p>

<a id="idp52168220" class="indexterm"></a>
The
<span class="symbol">XNSpotLocation</span>
argument specifies to the input method the coordinates of the spot
to be used by an input method executing with 
<span class="symbol">XNInputStyle</span>
set to 
<span class="symbol">XIMPreeditPosition</span>.
When specified to any input method other than 
<span class="symbol">XIMPreeditPosition</span>,
this <acronym class="acronym">XIC</acronym> value is ignored.
</p><p>

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.
</p><p>

The value of the argument is a pointer to a structure of type
<span class="structname">XPoint</span>.
</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="Colormap"></a>Colormap</h5></div></div></div><p>

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.
</p><p>

<a id="idp52173468" class="indexterm"></a>
The
<span class="symbol">XNColormap</span>
argument is used to specify a colormap ID.
The argument value is of type
<span class="type">Colormap</span>.
An invalid argument may generate a 
<span class="errorname">BadColor</span>
error when it is used by the input method.
</p><p>

<a id="idp52175084" class="indexterm"></a>
The
<span class="symbol">XNStdColormap</span>
argument is used to indicate the name of the standard colormap
in which the input method should allocate colors.
The argument value is an 
<span class="type">Atom</span>
that should be a valid atom for calling
<a class="xref" href="#XGetRGBColormaps"><code class="function">XGetRGBColormaps</code></a>.
An invalid argument may generate a
<span class="errorname">BadAtom</span>
error when it is used by the input method.
</p><p>

If the colormap is left unspecified,
the client window colormap becomes the default.
</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="Foreground_and_Background"></a>Foreground and Background</h5></div></div></div><p>

<a id="idp52178932" class="indexterm"></a>
<a id="idp52179364" class="indexterm"></a>
The
<span class="symbol">XNForeground</span>
and
<span class="symbol">XNBackground</span>
arguments specify the foreground and background pixel, respectively.
The argument value is of type
<span class="type">unsigned</span>
<span class="type">long</span>.
It must be a valid pixel in the input method colormap.
</p><p>

If these values are left unspecified,
the default is determined by the input method.
</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="Background_Pixmap"></a>Background Pixmap</h5></div></div></div><p>

The
<span class="symbol">XNBackgroundPixmap</span>
argument specifies a background pixmap to be used as the background of the
window.
The value must be of type 
<span class="type">Pixmap</span>.
An invalid argument may generate a
<span class="errorname">BadPixmap</span>
error when it is used by the input method.
</p><p>

If this value is left unspecified,
the default is determined by the input method.
</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="Font_Set"></a>Font Set</h5></div></div></div><p>

<a id="idp52185732" class="indexterm"></a>
The
<span class="symbol">XNFontSet</span>
argument specifies to the input method what font set is to be used.
The argument value is of type
<span class="type">XFontSet</span>.
</p><p>

If this value is left unspecified,
the default is determined by the input method.
</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="Line_Spacing"></a>Line Spacing</h5></div></div></div><p>

The
<span class="symbol">XNLineSpace</span>
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
<span class="type">int</span>.
</p><p>

If this value is left unspecified,
the default is determined by the input method.
</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="Cursor"></a>Cursor</h5></div></div></div><p>

<a id="idp52191300" class="indexterm"></a>
The
<span class="symbol">XNCursor</span>
argument specifies to the input method what cursor is to be used
in the specified window.
This argument is of type 
<span class="type">Cursor</span>.
</p><p>

An invalid argument may generate a
<span class="errorname">BadCursor</span>
error when it is used by the input method.
If this value is left unspecified,
the default is determined by the input method.
</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="Preedit_State"></a>Preedit State</h5></div></div></div><p>

The
<span class="symbol">XNPreeditState</span>
argument specifies the state of input preediting for the input method.
Input preediting can be on or off.
</p><p>

The valid mask names for
<span class="symbol">XNPreeditState</span>
are as follows:
</p><p>

<a id="idp52195956" class="indexterm"></a>
<a id="idp52196388" class="indexterm"></a>
<a id="idp52196820" class="indexterm"></a>

</p><pre class="literallayout">
typedef unsigned long XIMPreeditState;

#define XIMPreeditUnknown    0L
#define XIMPreeditEnable     1L
#define XIMPreeditDisable    (1L&lt;&lt;1)

</pre><p>


If a value of
<span class="symbol">XIMPreeditEnable</span>
is set, then input preediting is turned on by the input method.
</p><p>

If a value of
<span class="symbol">XIMPreeditDisable</span>
is set, then input preediting is turned off by the input method.
</p><p>

If
<span class="symbol">XNPreeditState</span>
is left unspecified, then the state will be implementation-dependent.
</p><p>

When
<span class="symbol">XNResetState</span>
is set to
<span class="symbol">XIMInitialState</span>,
the
<span class="symbol">XNPreeditState</span>
value specified at the creation time will be reflected as the initial state for
<a class="xref" href="#XmbResetIC"><code class="function">XmbResetIC</code></a>
and
<a class="xref" href="#XwcResetIC"><code class="function">XwcResetIC</code></a>.
</p><p>

Because this <acronym class="acronym">XIC</acronym> value is optional, a client should call
<a class="xref" href="#XGetIMValues"><code class="function">XGetIMValues</code></a>
with argument
<span class="symbol">XNQueryICValuesList</span>
before using this argument.
</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="Preedit_State_Notify_Callback"></a>Preedit State Notify Callback</h5></div></div></div><p>

The preedit state notify callback is triggered by the input method
when the preediting state has changed.
The value of the
<span class="symbol">XNPreeditStateNotifyCallback</span>
argument is a pointer to a structure of type
<span class="structname">XIMCallback</span>.
The generic prototype is as follows:
</p><a id="idp52206124" class="indexterm"></a><div class="funcsynopsis"><a id="PreeditStateNotifyCallback"></a><p><code class="funcdef">void <strong class="fsfunc">PreeditStateNotifyCallback</strong>(</code>XIC<var class="pdparam"> ic</var>, XPointer<var class="pdparam"> client_data</var>, XIMPreeditStateNotifyCallbackStruct<var class="pdparam"> *call_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input context.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies the additional client data.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>call_data</em></span>
    </span></p></td><td><p>
Specifies the current preedit state.
    </p></td></tr></tbody></table></div><p>


The
<span class="structname">XIMPreeditStateNotifyCallbackStruct</span>
structure is defined as follows:
</p><p>

<a id="idp52214924" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct _XIMPreeditStateNotifyCallbackStruct {
     XIMPreeditState state;
} XIMPreeditStateNotifyCallbackStruct;
</pre><p>
</p><p>


</p><p>

Because this <acronym class="acronym">XIC</acronym> value is optional, a client should call
<a class="xref" href="#XGetIMValues"><code class="function">XGetIMValues</code></a>
with argument
<span class="symbol">XNQueryICValuesList</span>
before using this argument.
</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="Preedit_and_Status_Callbacks"></a>Preedit and Status Callbacks</h5></div></div></div><p>

A client that wants to support the input style
<span class="symbol">XIMPreeditCallbacks</span>
must provide a set of preedit callbacks to the input method.
The set of preedit callbacks is as follows:
</p><a id="idp52220444" class="indexterm"></a><a id="idp52220884" class="indexterm"></a><a id="idp52221324" class="indexterm"></a><a id="idp52221764" class="indexterm"></a><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left"><span class="symbol">XNPreeditStartCallback</span></td><td align="left">This is called when the input method starts preedit.</td></tr><tr><td align="left"><span class="symbol">XNPreeditDoneCallback</span></td><td align="left">This is called when the input method stops preedit.</td></tr><tr><td align="left"><span class="symbol">XNPreeditDrawCallback</span></td><td align="left">This is called when a number of preedit keystrokes should be echoed.</td></tr><tr><td align="left"><span class="symbol">XNPreeditCaretCallback</span></td><td align="left">This is called to move the text insertion point within the preedit string.</td></tr></tbody></table></div><p>

A client that wants to support the input style
<span class="symbol">XIMStatusCallbacks</span>
must provide a set of status callbacks to the input method.
The set of status callbacks is as follows:
</p><a id="idp52228540" class="indexterm"></a><a id="idp52228980" class="indexterm"></a><a id="idp52229420" class="indexterm"></a><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left"><span class="symbol">XNStatusStartCallback</span></td><td align="left">This is called when the input method initializes the status area.</td></tr><tr><td align="left"><span class="symbol">XNStatusDoneCallback</span></td><td align="left">This is called when the input method no longer needs the status area.</td></tr><tr><td align="left"><span class="symbol">XNStatusDrawCallback</span></td><td align="left">This is called when updating of the status area is required.</td></tr></tbody></table></div><p>

The value of any status or preedit argument is a pointer
to a structure of type
<span class="structname">XIMCallback</span>.
<a id="idp52235252" class="indexterm"></a>
<a id="idp52235676" class="indexterm"></a>

</p><p>

</p><pre class="literallayout">


typedef void (*XIMProc)();

typedef struct {
     XPointer client_data;
     XIMProc callback;
} XIMCallback;
</pre><p>
</p><p>


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.
</p><p>

Setting any of these values while doing preedit
may cause unexpected results.
</p></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Input_Method_Callback_Semantics"></a>Input Method Callback Semantics</h3></div></div></div><p>

<acronym class="acronym">XIM</acronym> 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.
</p><p>

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.
</p><p>

All callback procedures follow the generic prototype:
</p><a id="idp52242636" class="indexterm"></a><div class="funcsynopsis"><p><code class="funcdef">void <strong class="fsfunc">CallbackPrototype</strong>(</code>XIC<var class="pdparam"> ic</var>, XPointer<var class="pdparam"> client_data</var>, SomeType<var class="pdparam"> call_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input context.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies the additional client data.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>call_data</em></span>
    </span></p></td><td><p>
Specifies data specific to the callback.
    </p></td></tr></tbody></table></div><p>


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.
</p><p>

The following paragraphs describe the programming semantics
and specific data structure associated with the different reasons.
</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Geometry_Callback_b"></a>Geometry Callback</h4></div></div></div><p>

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:
</p><a id="idp52253172" class="indexterm"></a><div class="funcsynopsis"><p><code class="funcdef">void <strong class="fsfunc">GeometryCallback</strong>(</code>XIC<var class="pdparam"> ic</var>, XPointer<var class="pdparam"> client_data</var>, XPointer<var class="pdparam"> call_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input context.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies the additional client data.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>call_data</em></span>
    </span></p></td><td><p>
Not used for this callback and always passed as NULL.
    </p></td></tr></tbody></table></div><p>


The callback is called with a NULL call_data argument.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Destroy_Callback_c"></a>Destroy Callback</h4></div></div></div><p>

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:
</p><a id="idp52262932" class="indexterm"></a><div class="funcsynopsis"><a id="DestroyCallback_2"></a><p><code class="funcdef">void <strong class="fsfunc">DestroyCallback</strong>(</code>XIC<var class="pdparam"> ic</var>, XPointer<var class="pdparam"> client_data</var>, XPointer<var class="pdparam"> call_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input context.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies the additional client data.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>call_data</em></span>
    </span></p></td><td><p>
Not used for this callback and always passed as NULL.
    </p></td></tr></tbody></table></div><p>


The callback is called with a NULL call_data argument.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="String_Conversion_Callback_b"></a>String Conversion Callback</h4></div></div></div><p>

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:
</p><a id="idp52273076" class="indexterm"></a><div class="funcsynopsis"><a id="StringConversionCallback"></a><p><code class="funcdef">void <strong class="fsfunc">StringConversionCallback</strong>(</code>XIC<var class="pdparam"> ic</var>, XPointer<var class="pdparam"> client_data</var>, XIMStringConversionCallbackStruct<var class="pdparam"> *call_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input method.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies the additional client data.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>call_data</em></span>
    </span></p></td><td><p>
Specifies the amount of the string to be converted.
    </p></td></tr></tbody></table></div><p>


The callback is passed an
<span class="structname">XIMStringConversionCallbackStruct</span>
structure in the call_data argument.
The text member is an
<span class="structname">XIMStringConversionText</span>
structure (see <a class="link" href="#String_Conversion" title="String Conversion">section 13.5.6.9</a>)
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
<span class="structname">XIMStringConversionText</span>
structure will be freed using
<a class="xref" href="#XFree"></a>
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.
</p><p>

The 
<span class="structname">XIMStringConversionCallbackStruct</span>
structure is defined as follows:
</p><p>

<a id="idp52284356" class="indexterm"></a>

</p><pre class="literallayout">
typedef struct _XIMStringConversionCallbackStruct {
     XIMStringConversionPosition position;          
     XIMCaretDirection direction;
     short factor;
     XIMStringConversionOperation operation;
     XIMStringConversionText *text;
} XIMStringConversionCallbackStruct;

typedef short XIMStringConversionPosition;

typedef unsigned short XIMStringConversionOperation;

#define XIMStringConversionSubstitution       (0x0001)
#define XIMStringConversionRetrieval          (0x0001)

</pre><p>


<span class="type">XIMStringConversionPosition</span>
specifies the starting position of the string to be returned
in the
<span class="structname">XIMStringConversionText</span>
structure.  The value identifies a position, in units of characters,
relative to the client's cursor position in the client's buffer.
</p><p>

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
<span class="structname">XIMCaretDirection</span>.
The factor member of 
<span class="structname">XIMStringConversionCallbackStruct</span>
specifies the number of
<span class="structname">XIMCaretDirection</span>
positions to be applied.  For example, if the direction specifies
<code class="constant">XIMLineEnd</code>
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
<code class="constant">XIMForwardChar</code>
or
<code class="constant">XIMBackwardChar</code>,
then the factor specifies a relative position, indicated in characters, 
from the starting position.
</p><p>

<span class="type">XIMStringConversionOperation</span>
specifies whether the string to be converted should be 
deleted (substitution) or copied (retrieval) from the client's
buffer.  When the
<span class="type">XIMStringConversionOperation</span>
is
<span class="symbol">XIMStringConversionSubstitution</span>,
the client must delete the string to be converted from its own buffer.
When the
<span class="type">XIMStringConversionOperation</span>
is
<span class="symbol">XIMStringConversionRetrieval</span>,
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.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Preedit_State_Callbacks"></a>Preedit State Callbacks</h4></div></div></div><p>

When the input method turns preediting on or off, a
<a class="xref" href="#PreeditStartCallback"><code class="function"><em class="replaceable"><code>PreeditStartCallback</code></em></code></a>
or
<a class="xref" href="#PreeditDoneCallback"><code class="function"><em class="replaceable"><code>PreeditDoneCallback</code></em></code></a>
callback is triggered to let the toolkit do the setup
or the cleanup for the preedit region.
</p><a id="idp52294356" class="indexterm"></a><div class="funcsynopsis"><a id="PreeditStartCallback"></a><p><code class="funcdef">int <strong class="fsfunc">PreeditStartCallback</strong>(</code>XIC<var class="pdparam"> ic</var>, XPointer<var class="pdparam"> client_data</var>, XPointer<var class="pdparam"> call_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input context.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies the additional client data.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>call_data</em></span>
    </span></p></td><td><p>
Not used for this callback and always passed as NULL.
    </p></td></tr></tbody></table></div><p>


When preedit starts on the specified input context,
the callback is called with a NULL call_data argument.
<a class="xref" href="#PreeditStartCallback"><code class="function"><em class="replaceable"><code>PreeditStartCallback</code></em></code></a>
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.
</p><a id="idp52303300" class="indexterm"></a><div class="funcsynopsis"><a id="PreeditDoneCallback"></a><p><code class="funcdef">void <strong class="fsfunc">PreeditDoneCallback</strong>(</code>XIC<var class="pdparam"> ic</var>, XPointer<var class="pdparam"> client_data</var>, XPointer<var class="pdparam"> call_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input context.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies the additional client data.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>call_data</em></span>
    </span></p></td><td><p>
Not used for this callback and always passed as NULL.
    </p></td></tr></tbody></table></div><p>


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
<a class="xref" href="#PreeditStartCallback"><code class="function"><em class="replaceable"><code>PreeditStartCallback</code></em></code></a>.
</p><p>

<a class="xref" href="#PreeditStartCallback"><code class="function"><em class="replaceable"><code>PreeditStartCallback</code></em></code></a>
should initialize appropriate data needed for
displaying preedit information and for handling further 
<a class="xref" href="#PreeditDrawCallback"><code class="function"><em class="replaceable"><code>PreeditDrawCallback</code></em></code></a>
calls.
Once
<a class="xref" href="#PreeditStartCallback"><code class="function"><em class="replaceable"><code>PreeditStartCallback</code></em></code></a>
is called, it will not be called again before
<a class="xref" href="#PreeditDoneCallback"><code class="function"><em class="replaceable"><code>PreeditDoneCallback</code></em></code></a>
has been called.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Preedit_Draw_Callback"></a>Preedit Draw Callback</h4></div></div></div><p>

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:
</p><a id="idp52316348" class="indexterm"></a><div class="funcsynopsis"><a id="PreeditDrawCallback"></a><p><code class="funcdef">void <strong class="fsfunc">PreeditDrawCallback</strong>(</code>XIC<var class="pdparam"> ic</var>, XPointer<var class="pdparam"> client_data</var>, XIMPreeditDrawCallbackStruct<var class="pdparam"> *call_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input context.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies the additional client data.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>call_data</em></span>
    </span></p></td><td><p>
Specifies the preedit drawing information.
    </p></td></tr></tbody></table></div><p>


The callback is passed an 
<span class="structname">XIMPreeditDrawCallbackStruct</span>
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.
</p><p>

The 
<span class="structname">XIMPreeditDrawCallbackStruct</span>
structure is defined as follows:
</p><p>

<a id="idp52325964" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct _XIMPreeditDrawCallbackStruct {
     int caret;     /* Cursor offset within preedit string */
     int chg_first;     /* Starting change position */
     int chg_length;     /* Length of the change in character count */
     XIMText *text;
} XIMPreeditDrawCallbackStruct;
</pre><p>
</p><p>


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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
When text is non-NULL,
it indicates insertion or replacement of text in the buffer.
    </p></li><li class="listitem"><p>
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
<span class="structname">XIMText</span>
structure.
    </p></li><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
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
<span class="structname">XIMText</span>
structure. For example, suppose the preedit buffer contains the string "ABCDE".
    </p></li><li class="listitem"><p>
</p><pre class="literallayout">

Text:      A B C D E
          ^ ^ ^ ^ ^ ^
CharPos:  0 1 2 3 4 5


</pre><p>
The CharPos in the diagram shows the location of the character position
relative to the character.
    </p></li><li class="listitem"><p>
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
<span class="structname">XIMText</span>
structure.
Hence, <acronym class="acronym">BCD</acronym> would be replaced by the value in the structure.
    </p></li><li class="listitem"><p>
Though chg_length and chg_first are both signed integers they will
never have a negative value.
    </p></li><li class="listitem"><p>
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.
    </p></li></ul></div><p>

<a id="idp52336756" class="indexterm"></a>

</p><pre class="literallayout">

typedef struct _XIMText {
     unsigned short length;
     XIMFeedback * feedback;
     Bool encoding_is_wchar; 
     union {
          char * multi_byte;
          wchar_t * wide_char;
     } string; 
} XIMText;
</pre><p>
</p><p>


The text string passed is actually a structure specifying as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The length member is the text length in characters.
    </p></li><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
The string member is the text string.
    </p></li><li class="listitem"><p>
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.
    </p></li></ul></div><p>

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.
</p><p>

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 
<span class="symbol">XIMVisibleToForward</span>,
<span class="symbol">XIMVisibleToBackword</span>,
and
<span class="symbol">XIMVisibleToCenter</span>
masks are exclusively used for these visibility hints.
The 
<span class="symbol">XIMVisibleToForward</span>
mask
indicates that the preedit text is preferably displayed in the
primary draw direction from the
caret position in the preedit area forward.
The 
<span class="symbol">XIMVisibleToBackword</span>
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 
<span class="symbol">XIMVisibleToCenter</span>
mask
indicates that the preedit text is preferably displayed with
the caret position in the preedit area centered.
</p><p>

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
<span class="symbol">XIMReverse</span>).
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.
</p><p>

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.
</p><p>

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
<span class="structname">XIMText</span>
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 
<span class="type">XIMFeedback</span>.
</p><p>

Each element in the feedback array is a bitmask represented by a value of type
<span class="type">XIMFeedback</span>.
The valid mask names are as follows:
</p><p>

<a id="idp52349028" class="indexterm"></a>
<a id="idp52349452" class="indexterm"></a>
<a id="idp52349884" class="indexterm"></a>
<a id="idp52350316" class="indexterm"></a>
<a id="idp52350740" class="indexterm"></a>
<a id="idp52351172" class="indexterm"></a>
<a id="idp52351596" class="indexterm"></a>
<a id="idp52352028" class="indexterm"></a>
<a id="idp52352468" class="indexterm"></a>

</p><pre class="literallayout">
typedef unsigned long XIMFeedback;

#define     XIMReverse                     1L
#define     XIMUnderline                   (1L&lt;&lt;1)
#define     XIMHighlight                   (1L&lt;&lt;2)
#define     XIMPrimary                     (1L&lt;&lt;5)*
#define     XIMSecondary                   (1L&lt;&lt;6)*
#define     XIMTertiary                    (1L&lt;&lt;7)*
#define     XIMVisibleToForward            (1L&lt;&lt;8)
#define     XIMVisibleToBackward           (1L&lt;&lt;9)
#define     XIMVisibleToCenter               (1L&lt;&lt;10)

*† The values for XIMPrimary, XIMSecondary, and XIMTertiary were incorrectly defined in
the R5 specification. The X Consortium’s X11R5 implementation correctly
implemented the values for these highlights. The value of these highlights has
been corrected in this specification to agree with the values in the
Consortium’s X11R5 and X11R6 implementations.

</pre><p>

Characters drawn with the
<span class="symbol">XIMReverse</span>
highlight should be drawn by swapping the foreground and background colors
used to draw normal, unhighlighted characters.
Characters drawn with the
<span class="symbol">XIMUnderline</span>
highlight should be underlined.
Characters drawn with the
<span class="symbol">XIMHighlight</span>,
<span class="symbol">XIMPrimary</span>,
<span class="symbol">XIMSecondary</span>,
and
<span class="symbol">XIMTertiary</span>
highlights should be drawn in some unique manner that must be different
from
<span class="symbol">XIMReverse</span>
and
<span class="symbol">XIMUnderline</span>.

The values for
<span class="symbol">XIMPrimary</span>,
<span class="symbol">XIMSecondary</span>,
and
<span class="symbol">XIMTertiary</span>
were incorrectly defined in the R5 specification.
The X Consortium's X11R5
implementation correctly implemented the values for these highlights.
The value of these highlights has been corrected in this specification
to agree with the values in the Consortium's X11R5 and X11R6 implementations.

</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Preedit_Caret_Callback"></a>Preedit Caret Callback</h4></div></div></div><p>

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.
</p><a id="idp52360180" class="indexterm"></a><div class="funcsynopsis"><a id="PreeditCaretCallback"></a><p><code class="funcdef">void <strong class="fsfunc">PreeditCaretCallback</strong>(</code>XIC<var class="pdparam"> ic</var>, XPointer<var class="pdparam"> client_data</var>, XIMPreeditCaretCallbackStruct<var class="pdparam"> *call_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input context.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies the additional client data.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>call_data</em></span>
    </span></p></td><td><p>
Specifies the preedit caret information.
    </p></td></tr></tbody></table></div><p>


The input method will trigger PreeditCaretCallback
to move the text insertion point during preedit.
The call_data argument contains a pointer to an 
<span class="structname">XIMPreeditCaretCallbackStruct</span>
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.  
</p><p>

The
<span class="structname">XIMPreeditCaretCallbackStruct</span>
structure is defined as follows:
<a id="idp52369580" class="indexterm"></a>
</p><p>


</p><pre class="literallayout">


typedef struct _XIMPreeditCaretCallbackStruct {
     int position;     /* Caret offset within preedit string */
     XIMCaretDirection direction;     /* Caret moves direction */
     XIMCaretStyle style;     /* Feedback of the caret */
} XIMPreeditCaretCallbackStruct;
</pre><p>
</p><p>


The
<span class="structname">XIMCaretStyle</span>
structure is defined as follows:
</p><p>

<a id="idp52372860" class="indexterm"></a>

</p><pre class="literallayout">


typedef enum {
     XIMIsInvisible,     /* Disable caret feedback */ 
     XIMIsPrimary,     /* <acronym class="acronym">UI</acronym> defined caret feedback */
     XIMIsSecondary,     /* <acronym class="acronym">UI</acronym> defined caret feedback */
} XIMCaretStyle;
</pre><p>
</p><p>


The
<span class="structname">XIMCaretDirection</span>
structure is defined as follows:
<a id="idp52375716" class="indexterm"></a>
</p><p>


</p><pre class="literallayout">


typedef enum {
     XIMForwardChar, XIMBackwardChar,
     XIMForwardWord, XIMBackwardWord,
     XIMCaretUp, XIMCaretDown,
     XIMNextLine, XIMPreviousLine,
     XIMLineStart, XIMLineEnd, 
     XIMAbsolutePosition,
     XIMDontChange,
 } XIMCaretDirection;
</pre><p>
</p><p>


These values are defined as follows:
</p><a id="idp52378436" class="indexterm"></a><a id="idp52378868" class="indexterm"></a><a id="idp52379300" class="indexterm"></a><a id="idp52379732" class="indexterm"></a><a id="idp52380164" class="indexterm"></a><a id="idp52380588" class="indexterm"></a><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left"><code class="constant">XIMForwardChar</code></td><td align="left">Move the caret forward one character position.</td></tr><tr><td align="left"><code class="constant">XIMBackwardChar</code></td><td align="left">Move the caret backward one character position.</td></tr><tr><td align="left"><code class="constant">XIMForwardWord</code></td><td align="left">Move the caret forward one word.</td></tr><tr><td align="left"><code class="constant">XIMBackwardWord</code></td><td align="left">Move the caret backward one word.</td></tr><tr><td align="left"><code class="constant">XIMCaretUp</code></td><td align="left">Move the caret up one line keeping the current horizontal offset.</td></tr><tr><td align="left"><code class="constant">XIMCaretDown</code></td><td align="left">Move the caret down one line keeping the current horizontal offset.</td></tr><tr><td align="left"><code class="constant">XIMPreviousLine</code></td><td align="left">Move the caret to the beginning of the previous line.</td></tr><tr><td align="left"><code class="constant">XIMNextLine</code></td><td align="left">Move the caret to the beginning of the next line.</td></tr><tr><td align="left"><code class="constant">XIMLineStart</code></td><td align="left">Move the caret to the beginning of the current display line that contains the caret.</td></tr><tr><td align="left"><code class="constant">XIMLineEnd</code></td><td align="left">Move the caret to the end of the current display line that contains the caret.</td></tr><tr><td align="left"><code class="constant">XIMAbsolutePosition</code></td><td align="left">The callback must move to the location specified by the position field
      of the callback data, indicated in characters, starting from the beginning
      of the preedit text.
      Hence, a value of zero means move back to the beginning of the preedit text.</td></tr><tr><td align="left"><code class="constant">XIMDontChange</code></td><td align="left">The caret position does not change.</td></tr></tbody></table></div><a id="idp52393044" class="indexterm"></a><a id="idp52393468" class="indexterm"></a><a id="idp52393900" class="indexterm"></a><a id="idp52394332" class="indexterm"></a><a id="idp52394756" class="indexterm"></a><a id="idp52395188" class="indexterm"></a></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Status_Callbacks"></a>Status Callbacks</h4></div></div></div><p>

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.
</p><p>


When the input context is created or gains focus, 
the input method calls the StatusStartCallback callback.
</p><a id="idp52398052" class="indexterm"></a><div class="funcsynopsis"><a id="StatusStartCallback"></a><p><code class="funcdef">void <strong class="fsfunc">StatusStartCallback</strong>(</code>XIC<var class="pdparam"> ic</var>, XPointer<var class="pdparam"> client_data</var>, XPointer<var class="pdparam"> call_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input context.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies the additional client data.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>call_data</em></span>
    </span></p></td><td><p>
Not used for this callback and always passed as NULL.
    </p></td></tr></tbody></table></div><p>


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.
</p><p>


When an input context
is destroyed or when it loses focus, the input method calls StatusDoneCallback.
</p><a id="idp52407100" class="indexterm"></a><div class="funcsynopsis"><a id="StatusDoneCallback"></a><p><code class="funcdef">void <strong class="fsfunc">StatusDoneCallback</strong>(</code>XIC<var class="pdparam"> ic</var>, XPointer<var class="pdparam"> client_data</var>, XPointer<var class="pdparam"> call_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input context.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies the additional client data.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>call_data</em></span>
    </span></p></td><td><p>
Not used for this callback and always passed as NULL.
    </p></td></tr></tbody></table></div><p>


The callback may release any data allocated on 
<code class="function">StatusStart</code>.
</p><p>


When an input context status has to be updated, the input method calls
StatusDrawCallback.
</p><a id="idp52416316" class="indexterm"></a><div class="funcsynopsis"><a id="StatusDrawCallback"></a><p><code class="funcdef">void <strong class="fsfunc">StatusDrawCallback</strong>(</code>XIC<var class="pdparam"> ic</var>, XPointer<var class="pdparam"> client_data</var>, XIMStatusDrawCallbackStruct<var class="pdparam"> *call_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input context.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>client_data</em></span>
    </span></p></td><td><p>
Specifies the additional client data.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>call_data</em></span>
    </span></p></td><td><p>
Specifies the status drawing information.
    </p></td></tr></tbody></table></div><p>


The callback should update the status area by either drawing a string
or imaging a bitmap in the status area.
</p><p>

The
<span class="structname">XIMStatusDataType</span>
and
<span class="structname">XIMStatusDrawCallbackStruct</span>
structures are defined as follows:
<a id="idp52425420" class="indexterm"></a>
<a id="idp52425852" class="indexterm"></a>
</p><p>


</p><pre class="literallayout">


typedef enum {
     XIMTextType,
     XIMBitmapType,
} XIMStatusDataType;

typedef struct _XIMStatusDrawCallbackStruct {
     XIMStatusDataType type;
     union {
          XIMText *text;
          Pixmap  bitmap;
     } data;
} XIMStatusDrawCallbackStruct;
</pre><p>
</p><p>


</p><p>

The feedback styles
<span class="symbol">XIMVisibleToForward</span>,
<span class="symbol">XIMVisibleToBackword</span>,
and
<span class="symbol">XIMVisibleToCenter</span>
are not relevant and will not appear in the
<span class="type">XIMFeedback</span>
element of the
<span class="structname">XIMText</span>
structure.
</p><p>

</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Event_Filtering_b"></a>Event Filtering</h3></div></div></div><p>

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
<a class="xref" href="#XFilterEvent"><code class="function">XFilterEvent</code></a>
after calling 
<a class="xref" href="#XNextEvent"><code class="function">XNextEvent</code></a>.
Any client that uses the 
<span class="type">XIM</span>
interface should call
<a class="xref" href="#XFilterEvent"><code class="function">XFilterEvent</code></a>
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).
</p><p>

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 
<a class="xref" href="#XFilterEvent"><code class="function">XFilterEvent</code></a>.
Clients should discard filtered events.

</p><p>

To filter an event, use
<a class="xref" href="#XFilterEvent"><code class="function">XFilterEvent</code></a>.
</p><a id="idp52436100" class="indexterm"></a><div class="funcsynopsis"><a id="XFilterEvent"></a><p><code class="funcdef">Bool <strong class="fsfunc">XFilterEvent</strong>(</code>XEvent<var class="pdparam"> *event</var>, Window<var class="pdparam"> w</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>event</em></span>
    </span></p></td><td><p>
Specifies the event to filter.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window for which the filter is to be applied.
    </p></td></tr></tbody></table></div><p>


If the window argument is
<span class="symbol">None</span>,
<a class="xref" href="#XFilterEvent"><code class="function">XFilterEvent</code></a>
applies the filter to the window specified in the
<span class="structname">XEvent</span>
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.
</p><p>

If
<a class="xref" href="#XFilterEvent"><code class="function">XFilterEvent</code></a>
returns
<span class="symbol">True</span>,
then some input method has filtered the event,
and the client should discard the event.
If
<a class="xref" href="#XFilterEvent"><code class="function">XFilterEvent</code></a>
returns
<span class="symbol">False</span>,
then the client should continue processing the event.
</p><p>

If a grab has occurred in the client and
<a class="xref" href="#XFilterEvent"><code class="function">XFilterEvent</code></a>
returns
<span class="symbol">True</span>,
the client should ungrab the keyboard.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Getting_Keyboard_Input_b"></a>Getting Keyboard Input</h3></div></div></div><p>

To get composed input from an input method,
use
<a class="xref" href="#XmbLookupString"><code class="function">XmbLookupString</code></a>
or
<a class="xref" href="#XwcLookupString"><code class="function">XwcLookupString</code></a>.
</p><a id="idp52448940" class="indexterm"></a><a id="idp52449372" class="indexterm"></a><div class="funcsynopsis"><a id="XmbLookupString"></a><p><code class="funcdef">int <strong class="fsfunc">XmbLookupString</strong>(</code>XIC<var class="pdparam"> ic</var>, XKeyPressedEvent<var class="pdparam"> *event</var>, char<var class="pdparam"> *buffer_return</var>, int<var class="pdparam"> bytes_buffer</var>, KeySym<var class="pdparam"> *keysym_return</var>, Status<var class="pdparam"> *status_return</var><code>)</code>;</p></div><div class="funcsynopsis"><a id="XwcLookupString"></a><p><code class="funcdef">int <strong class="fsfunc">XwcLookupString</strong>(</code>XIC<var class="pdparam"> ic</var>, XKeyPressedEvent<var class="pdparam"> *event</var>, wchar_t<var class="pdparam"> *buffer_return</var>, int<var class="pdparam"> wchars_buffer</var>, KeySym<var class="pdparam"> *keysym_return</var>, Status<var class="pdparam"> *status_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ic</em></span>
    </span></p></td><td><p>
Specifies the input context.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event</em></span>
    </span></p></td><td><p>
Specifies the key event to be used.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>buffer_return</em></span>
    </span></p></td><td><p>
Returns a multibyte string or wide character string (if any)
from the input method.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>bytes_buffer</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>wchars_buffer</em></span>
    </span></p></td><td><p>
Specifies space available in the return buffer.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>keysym_return</em></span>
    </span></p></td><td><p>
Returns the KeySym computed from the event if this argument is not NULL.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>status_return</em></span>
    </span></p></td><td><p>
Returns a value indicating what kind of data is returned.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XmbLookupString"><code class="function">XmbLookupString</code></a>
and
<a class="xref" href="#XwcLookupString"><code class="function">XwcLookupString</code></a>
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.
</p><p>

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.
</p><p>

<a class="xref" href="#XmbLookupString"><code class="function">XmbLookupString</code></a>
returns the length of the string in bytes, and
<a class="xref" href="#XwcLookupString"><code class="function">XwcLookupString</code></a>
returns the length of the string in characters.
Both
<a class="xref" href="#XmbLookupString"><code class="function">XmbLookupString</code></a>
and
<a class="xref" href="#XwcLookupString"><code class="function">XwcLookupString</code></a>
return text in the encoding of the locale bound to the input method
of the specified input context.
</p><p>

Each string returned by
<a class="xref" href="#XmbLookupString"><code class="function">XmbLookupString</code></a>
and
<a class="xref" href="#XwcLookupString"><code class="function">XwcLookupString</code></a>
begins in the initial state of the encoding of the locale
(if the encoding of the locale is state-dependent).

</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
To insure proper input processing,
it is essential that the client pass only 
<span class="symbol">KeyPress</span>
events to
<a class="xref" href="#XmbLookupString"><code class="function">XmbLookupString</code></a>
and
<a class="xref" href="#XwcLookupString"><code class="function">XwcLookupString</code></a>.
Their behavior when a client passes a 
<span class="symbol">KeyRelease</span>
event is undefined.
</p></div><p>

</p><p>

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:
</p><div class="informaltable"><table border="0"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><tbody><tr><td align="left"><span class="symbol">XBufferOverflow</span></td><td align="left">The input string to be returned is too large for the supplied buffer_return.
      The required size
      (<a class="xref" href="#XmbLookupString"><code class="function">XmbLookupString</code></a>
      in bytes;
      <a class="xref" href="#XwcLookupString"><code class="function">XwcLookupString</code></a>
      in characters) is returned as the value of the function,
      and the contents of buffer_return and keysym_return are not modified.
      The client should recall the function with the same event
      and a buffer of adequate size to obtain the string.</td></tr><tr><td align="left"><span class="symbol">XLookupNone</span></td><td align="left">No consistent input has been composed so far.
      The contents of buffer_return and keysym_return are not modified, 
      and the function returns zero.</td></tr><tr><td align="left"><span class="symbol">XLookupChars</span></td><td align="left">Some input characters have been composed.
      They are placed in the buffer_return argument,
      and the string length is returned as the value of the function.
      The string is encoded in the locale bound to the input context.
      The content of the keysym_return argument is not modified.</td></tr><tr><td align="left"><span class="symbol">XLookupKeySym</span></td><td align="left">A KeySym has been returned instead of a string
      and is returned in keysym_return.
      The content of the buffer_return argument is not modified,
      and the function returns zero.</td></tr><tr><td align="left"><span class="symbol">XLookupBoth</span></td><td align="left">Both a KeySym and a string are returned;
      <span class="symbol">XLookupChars</span>
      and
      <span class="symbol">XLookupKeySym</span>
      occur simultaneously.</td></tr></tbody></table></div><p>

It does not make any difference if the input context passed as an argument to
<a class="xref" href="#XmbLookupString"><code class="function">XmbLookupString</code></a>
and
<a class="xref" href="#XwcLookupString"><code class="function">XwcLookupString</code></a>
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
<a class="xref" href="#XmbLookupString"><code class="function">XmbLookupString</code></a>
or
<a class="xref" href="#XwcLookupString"><code class="function">XwcLookupString</code></a>
even though it does not have any more keyboard focus.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Input_Method_Conventions"></a>Input Method Conventions</h3></div></div></div><p>

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.
</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Client_Conventions"></a>Client Conventions</h4></div></div></div><p>

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.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Synchronization_Conventions"></a>Synchronization Conventions</h4></div></div></div><p>

A 
<span class="symbol">KeyPress</span>
event with a KeyCode of zero is used exclusively as a
signal that an input method has composed input that can be returned by
<a class="xref" href="#XmbLookupString"><code class="function">XmbLookupString</code></a>
or
<a class="xref" href="#XwcLookupString"><code class="function">XwcLookupString</code></a>.
No other use is made of a 
<span class="symbol">KeyPress</span>
event with KeyCode of zero.
</p><p>

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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
A synthetic event sent by an input method server
    </p></li><li class="listitem"><p>
An artificial event created by a input method filter and pushed
onto a client's event queue
    </p></li><li class="listitem"><p>
A 
<span class="symbol">KeyPress</span>
event whose KeyCode value is modified by an input method filter
    </p></li></ul></div><p>

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).
</p></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="String_Constants"></a>String Constants</h2></div></div></div><p>

The following symbols for string constants are defined in
<code class="filename">&lt;X11/Xlib.h&gt;</code>.
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.
</p><pre class="literallayout">
#define XNVaNestedList                       "XNVaNestedList"
#define XNSeparatorofNestedList              "separatorofNestedList"
#define XNQueryInputStyle                    "queryInputStyle"
#define XNClientWindow                       "clientWindow"
#define XNInputStyle                         "inputStyle"
#define XNFocusWindow                        "focusWindow"
#define XNResourceName                       "resourceName"
#define XNResourceClass                      "resourceClass"
#define XNGeometryCallback                   "geometryCallback"
#define XNDestroyCallback                    "destroyCallback"
#define XNFilterEvents                       "filterEvents"
#define XNPreeditStartCallback               "preeditStartCallback"
#define XNPreeditDoneCallback                "preeditDoneCallback"
#define XNPreeditDrawCallback                "preeditDrawCallback"
#define XNPreeditCaretCallback               "preeditCaretCallback"
#define XNPreeditStateNotifyCallback         "preeditStateNotifyCallback"
#define XNPreeditAttributes                  "preeditAttributes"
#define XNStatusStartCallback                "statusStartCallback"
#define XNStatusDoneCallback                 "statusDoneCallback"
#define XNStatusDrawCallback                 "statusDrawCallback"
#define XNStatusAttributes                   "statusAttributes"
#define XNArea                               "area"
#define XNAreaNeeded                         "areaNeeded"
#define XNSpotLocation                       "spotLocation"
#define XNColormap                           "colorMap"
#define XNStdColormap                        "stdColorMap"
#define XNForeground                         "foreground"
#define XNBackground                         "background"
#define XNBackgroundPixmap                   "backgroundPixmap"
#define XNFontSet                            "fontSet"
#define XNLineSpace                          "lineSpace"
#define XNCursor                             "cursor"
#define XNQueryIMValuesList                  "queryIMValuesList"
#define XNQueryICValuesList                  "queryICValuesList"
#define XNStringConversionCallback           "stringConversionCallback"
#define XNStringConversion                   "stringConversion"
#define XNResetState                         "resetState"
#define XNHotKey                             "hotkey"
#define XNHotKeyState                        "hotkeyState"
#define XNPreeditState                       "preeditState"
#define XNVisiblePosition                    "visiblePosition"
#define XNR6PreeditCallbackBehavior          "r6PreeditCallback"
#define XNRequiredCharSet                    "requiredCharSet"
#define XNQueryOrientation                   "queryOrientation"
#define XNDirectionalDependentDrawing        "directionalDependentDrawing"
#define XNContextualDrawing                  "contextualDrawing"
#define XNBaseFontName                       "baseFontName"
#define XNMissingCharSet                     "missingCharSet"
#define XNDefaultString                      "defaultString"
#define XNOrientation                        "orientation"
#define XNFontInfo                           "fontInfo"
#define XNOMAutomatic                        "omAutomatic"

</pre></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Inter_Client_Communication_Functions"></a>Chapter 14. Inter-Client Communication Functions</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Client_to_Window_Manager_Communication">Client to Window Manager Communication</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Manipulating_Top_Level_Windows">Manipulating Top-Level Windows</a></span></dt><dt><span class="sect2"><a href="#Converting_String_Lists">Converting String Lists</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_Text_Properties">Setting and Reading Text Properties</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_NAME_Property">Setting and Reading the WM_NAME Property</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_ICON_NAME_Property">Setting and Reading the WM_ICON_NAME Property</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_HINTS_Property">Setting and Reading the WM_HINTS Property</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_NORMAL_HINTS_Property">Setting and Reading the WM_NORMAL_HINTS Property</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_CLASS_Property">Setting and Reading the WM_CLASS Property</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_TRANSIENT_FOR_Property">Setting and Reading the WM_TRANSIENT_FOR Property</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_PROTOCOLS_Property">Setting and Reading the WM_PROTOCOLS Property</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_COLORMAP_WINDOWS_Property">Setting and Reading the WM_COLORMAP_WINDOWS Property</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_ICON_SIZE_Property">Setting and Reading the WM_ICON_SIZE Property</a></span></dt><dt><span class="sect2"><a href="#Using_Window_Manager_Convenience_Functions">Using Window Manager Convenience Functions</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Client_to_Session_Manager_Communication">Client to Session Manager Communication</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_COMMAND_Property">Setting and Reading the WM_COMMAND Property</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Reading_the_WM_CLIENT_MACHINE_Property">Setting and Reading the WM_CLIENT_MACHINE Property</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Standard_Colormaps">Standard Colormaps</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Standard_Colormap_Properties_and_Atoms">Standard Colormap Properties and Atoms</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Obtaining_Standard_Colormaps">Setting and Obtaining Standard Colormaps</a></span></dt></dl></dd></dl></div><p>
The <em class="citetitle">Inter-Client Communication Conventions Manual</em>,
hereafter referred to as the <acronym class="acronym">ICCCM</acronym>,
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 <span class="olink"><em class="citetitle">Inter-Client Communication Conventions Manual</em></span>.
</p><p>
Xlib provides a number of standard properties and programming interfaces that are <acronym class="acronym">ICCCM</acronym>
compliant. The predefined atoms for some of these properties are defined in the &lt;X11/Xatom.h&gt;
header file, where to avoid name conflicts with user symbols their #define name has an XA_ prefix.
For further information about atoms and properties,
see <a class="link" href="#Properties_and_Atoms" title="Properties and Atoms">section 4.3</a>.
</p><p>
Xlib’s selection and cut buffer mechanisms provide the primary programming interfaces by which
peer client applications communicate with each other
(see sections <a class="link" href="#Selections" title="Selections">4.5</a> and
<a class="link" href="#Using_Cut_Buffers" title="Using Cut Buffers">16.6</a>). 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.
</p><p>
The standard properties that are of special interest for communicating with window and session
managers are:
</p><div class="informaltable"><table border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">Name</th><th align="left">Type</th><th align="left">Format</th><th align="left">Description</th></tr></thead><tbody><tr><td align="left"><span class="property">WM_CLASS</span></td><td align="left">STRING</td><td align="left">8</td><td align="left">Set by application programs to allow
      window and session managers to
      obtain the application’s resources
      from the resource database.
      </td></tr><tr><td align="left"><span class="property">WM_CLIENT_MACHINE</span></td><td align="left">TEXT</td><td align="left"> </td><td align="left">The string name of the machine on
      which the client application is running.
      </td></tr><tr><td align="left"><span class="property">WM_COLORMAP_WINDOWS</span></td><td align="left">WINDOWS</td><td align="left">32</td><td align="left">The list of window IDs that may
      need a different colormap from that
      of their top-level window.
      </td></tr><tr><td align="left"><span class="property">WM_COMMAND</span></td><td align="left">TEXT</td><td align="left"> </td><td align="left">The command and arguments, null
      separated, used to invoke the application.
      </td></tr><tr><td align="left"><span class="property">WM_HINTS</span></td><td align="left"><span class="property">WM_HINTS</span></td><td align="left">32</td><td align="left">Additional hints set by the client for
      use by the window manager. The C
      type of this property is XWMHints.
      </td></tr><tr><td align="left"><span class="property">WM_ICON_NAME</span></td><td align="left">TEXT</td><td align="left"> </td><td align="left">The name to be used in an icon.</td></tr><tr><td align="left"><span class="property">WM_ICON_SIZE</span></td><td align="left"><span class="property">WM_ICON_SIZE</span></td><td align="left">32</td><td align="left">The window manager may set this
      property on the root window to
      specify the icon sizes it supports.
      The C type of this property is
      XIconSize.
      </td></tr><tr><td align="left"><span class="property">WM_NAME</span></td><td align="left">TEXT</td><td align="left"> </td><td align="left">The name of the application.</td></tr><tr><td align="left"><span class="property">WM_NORMAL_HINTS</span></td><td align="left"><span class="property">WM_NORMAL_HINTS</span></td><td align="left">32</td><td align="left">Size hints for a window in its
      normal state. The C type of this
      property is XSizeHints.
      </td></tr><tr><td align="left"><span class="property">WM_PROTOCOLS</span></td><td align="left">ATOM</td><td align="left">32</td><td align="left">List of atoms that identify the 
      communications protocols between the
      client and window manager in
      which the client is willing to participate.
      </td></tr><tr><td align="left"><span class="property">WM_STATE</span></td><td align="left"><span class="property">WM_STATE</span></td><td align="left">32</td><td align="left">Intended for communication
      between window and session managers only.
      </td></tr><tr><td align="left"><span class="property">WM_TRANSIENT_FOR</span></td><td align="left">WINDOW</td><td align="left">32</td><td align="left">Set by application programs to 
      indicate to the window manager that a
      transient top-level window, such as a
      dialog box.
      </td></tr></tbody></table></div><p>
The remainder of this chapter discusses:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Client to window manager communication</p></li><li class="listitem"><p>Client to session manager communication</p></li><li class="listitem"><p>Standard colormaps</p></li></ul></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Client_to_Window_Manager_Communication"></a>Client to Window Manager Communication</h2></div></div></div><p>

This section discusses how to:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Manipulate top-level windows
    </p></li><li class="listitem"><p>
Convert string lists
    </p></li><li class="listitem"><p>
Set and read text properties
    </p></li><li class="listitem"><p>
Set and read the <span class="property">WM_NAME</span> property
    </p></li><li class="listitem"><p>
Set and read the <span class="property">WM_ICON_NAME</span> property
    </p></li><li class="listitem"><p>
Set and read the <span class="property">WM_HINTS</span> property
    </p></li><li class="listitem"><p>
Set and read the <span class="property">WM_NORMAL_HINTS</span> property
    </p></li><li class="listitem"><p>
Set and read the <span class="property">WM_CLASS</span> property
    </p></li><li class="listitem"><p>
Set and read the <span class="property">WM_TRANSIENT_FOR</span> property
    </p></li><li class="listitem"><p>
Set and read the <span class="property">WM_PROTOCOLS</span> property
    </p></li><li class="listitem"><p>
Set and read the <span class="property">WM_COLORMAP_WINDOWS</span> property
    </p></li><li class="listitem"><p>
Set and read the <span class="property">WM_ICON_SIZE</span> property
    </p></li><li class="listitem"><p>
Use window manager convenience functions
    </p></li></ul></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Manipulating_Top_Level_Windows"></a>Manipulating Top-Level Windows</h3></div></div></div><p>

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
<a class="link" href="#Window_Functions" title="Chapter 3. Window Functions">chapter 3</a>
to manipulate your application's subwindows.
</p><p>

To request that a top-level window be iconified, use
<a class="xref" href="#XIconifyWindow"><code class="function">XIconifyWindow</code></a>.
</p><a id="idp48686692" class="indexterm"></a><div class="funcsynopsis"><a id="XIconifyWindow"></a><p><code class="funcdef">Status <strong class="fsfunc">XIconifyWindow</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, int<var class="pdparam"> screen_number</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XIconifyWindow"><code class="function">XIconifyWindow</code></a>
function sends a <span class="property">WM_CHANGE_STATE</span> 
<span class="symbol">ClientMessage</span>
event with a format of 32 and a first data element of 
<span class="symbol">IconicState</span>
(as described in <span class="olink">section 4.1.4 of the
<em class="citetitle">Inter-Client Communication Conventions Manual</em></span>)
and a window of w
to the root window of the specified screen
with an event mask set to
<span class="symbol">SubstructureNotifyMask</span> |
<span class="symbol">SubstructureRedirectMask</span>.
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 <span class="property">WM_CHANGE_STATE</span> property cannot be interned, 
<a class="xref" href="#XIconifyWindow"><code class="function">XIconifyWindow</code></a>
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.

</p><p>

To request that a top-level window be withdrawn, use
<a class="xref" href="#XWithdrawWindow"><code class="function">XWithdrawWindow</code></a>.
</p><a id="idp48699316" class="indexterm"></a><div class="funcsynopsis"><a id="XWithdrawWindow"></a><p><code class="funcdef">Status <strong class="fsfunc">XWithdrawWindow</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, int<var class="pdparam"> screen_number</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XWithdrawWindow"><code class="function">XWithdrawWindow</code></a>
function unmaps the specified window 
and sends a synthetic 
<span class="symbol">UnmapNotify</span>
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 
<span class="symbol">UnmapNotify</span>
event is successfully sent; 
otherwise, it returns a zero status.
</p><p>

<a class="xref" href="#XWithdrawWindow"><code class="function">XWithdrawWindow</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.

</p><p>

To request that a top-level window be reconfigured, use
<a class="xref" href="#XReconfigureWMWindow"><code class="function">XReconfigureWMWindow</code></a>.
</p><a id="idp50514228" class="indexterm"></a><div class="funcsynopsis"><a id="XReconfigureWMWindow"></a><p><code class="funcdef">Status <strong class="fsfunc">XReconfigureWMWindow</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, int<var class="pdparam"> screen_number</var>, unsignedint<var class="pdparam"> value_mask</var>, XWindowChanges<var class="pdparam"> *values</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen_number</em></span>
    </span></p></td><td><p>
Specifies the appropriate screen number on the host server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>value_mask</em></span>
    </span></p></td><td><p>
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.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>values</em></span>
    </span></p></td><td><p>
Specifies the 
<span class="structname">XWindowChanges</span>
structure.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XReconfigureWMWindow"><code class="function">XReconfigureWMWindow</code></a>
function issues a 
<code class="systemitem">ConfigureWindow</code>
request on the specified top-level window.
If the stacking mode is changed and the request fails with a 
<span class="errorname">BadMatch</span>
error, 
the error is trapped by Xlib and a synthetic 
<code class="systemitem">ConfigureRequestEvent</code>
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.
</p><p>

<a class="xref" href="#XReconfigureWMWindow"><code class="function">XReconfigureWMWindow</code></a>
can generate
<span class="errorname">BadValue</span>
and 
<span class="errorname">BadWindow</span>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Converting_String_Lists"></a>Converting String Lists</h3></div></div></div><p>

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
<span class="structname">XTextProperty</span>
structure is used to describe the encoding, type, and length of the text 
as well as its value.
The
<span class="structname">XTextProperty</span>
structure contains:
<a id="idp50531260" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
	unsigned char *value;	/* property data */
	Atom encoding;	/* type of property */
	int format;	/* 8, 16, or 32 */
	unsigned long nitems;	/* number of items in value */
} XTextProperty;
</pre><p>
</p><p>


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.
</p><p>

The functions for localized text return a signed integer error status 
that encodes 
<span class="symbol">Success</span>
as zero, specific error conditions as negative numbers, and partial conversion
as a count of unconvertible characters.
</p><pre class="literallayout">

#define #XNoMemory           -1
#define #XLocaleNotSupported -2
#define #XConverterNotFound  -3

typedef enum {
	XStringStyle,		/* STRING */
	XCompoundTextStyle,	/* COMPOUND_TEXT */
	XTextStyle,		/* text in owner's encoding (current locale) */
	XStdICCTextStyle	/* STRING, else COMPOUND_TEXT */
} XICCEncodingStyle;
</pre><p>



</p><p>

To convert a list of text strings to an 
<span class="structname">XTextProperty</span>
structure, use
<a class="xref" href="#XmbTextListToTextProperty"><code class="function">XmbTextListToTextProperty</code></a>
or
<a class="xref" href="#XwcTextListToTextProperty"><code class="function">XwcTextListToTextProperty</code></a>.
</p><a id="idp50537524" class="indexterm"></a><a id="idp50537932" class="indexterm"></a><div class="funcsynopsis"><a id="XmbTextListToTextProperty"></a><p><code class="funcdef">int <strong class="fsfunc">XmbTextListToTextProperty</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> **list</var>, int<var class="pdparam"> count</var>, XICCEncodingStyle<var class="pdparam"> style</var>, XTextProperty<var class="pdparam"> *text_prop_return</var><code>)</code>;</p></div><div class="funcsynopsis"><a id="XwcTextListToTextProperty"></a><p><code class="funcdef">int <strong class="fsfunc">XwcTextListToTextProperty</strong>(</code>Display<var class="pdparam"> *display</var>, wchar_t<var class="pdparam"> **list</var>, int<var class="pdparam"> count</var>, XICCEncodingStyle<var class="pdparam"> style</var>, XTextProperty<var class="pdparam"> *text_prop_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>list</em></span>
    </span></p></td><td><p>
Specifies a list of null-terminated character strings.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count</em></span>
    </span></p></td><td><p>
Specifies the number of strings specified.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>style</em></span>
    </span></p></td><td><p>
Specifies the manner in which the property is encoded.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>text_prop_return</em></span>
    </span></p></td><td><p>
Returns the
<span class="structname">XTextProperty</span>
structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XmbTextListToTextProperty"><code class="function">XmbTextListToTextProperty</code></a>
and
<a class="xref" href="#XwcTextListToTextProperty"><code class="function">XwcTextListToTextProperty</code></a>
functions set the specified 
<span class="structname">XTextProperty</span>
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.
</p><p>

The functions set the encoding field of text_prop_return to an
<span class="type">Atom</span>
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 
<code class="constant">XStringStyle</code>
or 
<code class="constant">XCompoundTextStyle</code>
is specified,
this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively.
If the style 
<code class="constant">XTextStyle</code>
is specified,
this encoding is the encoding of the current locale.
If the style 
<code class="constant">XStdICCTextStyle</code>
is specified,
this encoding is ``STRING'' if the text is fully convertible to STRING,
else ``COMPOUND_TEXT''.
</p><p>

If insufficient memory is available for the new value string,
the functions return 
<span class="symbol">XNoMemory</span>.
If the current locale is not supported,
the functions return 
<span class="symbol">XLocaleNotSupported</span>.
In both of these error cases,
the functions do not set text_prop_return.
</p><p>

To determine if the functions are guaranteed not to return
<span class="symbol">XLocaleNotSupported</span>,
use
<code class="function">XSupportsLocale</code>.
</p><p>

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 
<span class="symbol">Success</span>.
Note that full convertibility to all styles except 
<code class="constant">XStringStyle</code>
is guaranteed.
</p><p>

To free the storage for the value field, use
<a class="xref" href="#XFree"></a>.

</p><p>

To obtain a list of text strings from an 
<span class="structname">XTextProperty</span>
structure, use
<a class="xref" href="#XmbTextPropertyToTextList"><code class="function">XmbTextPropertyToTextList</code></a>
or
<a class="xref" href="#XwcTextPropertyToTextList"><code class="function">XwcTextPropertyToTextList</code></a>.
</p><a id="idp50562516" class="indexterm"></a><a id="idp50562924" class="indexterm"></a><div class="funcsynopsis"><a id="XmbTextPropertyToTextList"></a><p><code class="funcdef">int <strong class="fsfunc">XmbTextPropertyToTextList</strong>(</code>Display<var class="pdparam"> *display</var>, XTextProperty<var class="pdparam"> *text_prop</var>, char<var class="pdparam"> ***list_return</var>, int<var class="pdparam"> *count_return</var><code>)</code>;</p></div><div class="funcsynopsis"><a id="XwcTextPropertyToTextList"></a><p><code class="funcdef">int <strong class="fsfunc">XwcTextPropertyToTextList</strong>(</code>Display<var class="pdparam"> *display</var>, XTextProperty<var class="pdparam"> *text_prop</var>, wchar_t<var class="pdparam"> ***list_return</var>, int<var class="pdparam"> *count_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>text_prop</em></span>
    </span></p></td><td><p>
Specifies the
<span class="structname">XTextProperty</span>
structure to be used.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>list_return</em></span>
    </span></p></td><td><p>
Returns a list of null-terminated character strings.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count_return</em></span>
    </span></p></td><td><p>
Returns the number of strings.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XmbTextPropertyToTextList"><code class="function">XmbTextPropertyToTextList</code></a>
and 
<a class="xref" href="#XwcTextPropertyToTextList"><code class="function">XwcTextPropertyToTextList</code></a>
functions return a list of text strings in the current locale representing the
null-separated elements of the specified
<span class="structname">XTextProperty</span>
structure.
The data in text_prop must be format 8.
</p><p>

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.
</p><p>

If insufficient memory is available for the list and its elements,
<a class="xref" href="#XmbTextPropertyToTextList"><code class="function">XmbTextPropertyToTextList</code></a>
and
<a class="xref" href="#XwcTextPropertyToTextList"><code class="function">XwcTextPropertyToTextList</code></a>
return 
<span class="symbol">XNoMemory</span>.
If the current locale is not supported,
the functions return
<span class="symbol">XLocaleNotSupported</span>.
Otherwise, if the encoding field of text_prop is not convertible 
to the encoding of the current locale,
the functions return
<span class="symbol">XConverterNotFound</span>.
For supported locales,
existence of a converter from COMPOUND_TEXT, STRING
or the encoding of the current locale is guaranteed if
<code class="function">XSupportsLocale</code>
returns 
<span class="symbol">True</span>
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.
</p><p>

Otherwise, 
<a class="xref" href="#XmbTextPropertyToTextList"><code class="function">XmbTextPropertyToTextList</code></a>
and
<a class="xref" href="#XwcTextPropertyToTextList"><code class="function">XwcTextPropertyToTextList</code></a>
return the list of null-terminated text strings to list_return
and the number of text strings to count_return.
</p><p>

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
<code class="function">XDefaultString</code>.
Otherwise,
<a class="xref" href="#XmbTextPropertyToTextList"><code class="function">XmbTextPropertyToTextList</code></a>
and
<a class="xref" href="#XwcTextPropertyToTextList"><code class="function">XwcTextPropertyToTextList</code></a>
return 
<span class="symbol">Success</span>.
</p><p>

To free the storage for the list and its contents returned by
<a class="xref" href="#XmbTextPropertyToTextList"><code class="function">XmbTextPropertyToTextList</code></a>,
use
<a class="xref" href="#XFreeStringList"><code class="function">XFreeStringList</code></a>.
To free the storage for the list and its contents returned by
<a class="xref" href="#XwcTextPropertyToTextList"><code class="function">XwcTextPropertyToTextList</code></a>,
use
<a class="xref" href="#XwcFreeStringList"><code class="function">XwcFreeStringList</code></a>.

</p><p>

To free the in-memory data associated with the specified
wide character string list, use
<a class="xref" href="#XwcFreeStringList"><code class="function">XwcFreeStringList</code></a>.
</p><a id="idp50918820" class="indexterm"></a><div class="funcsynopsis"><a id="XwcFreeStringList"></a><p><code class="funcdef">void <strong class="fsfunc">XwcFreeStringList</strong>(</code>wchar_t<var class="pdparam"> **list</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>list</em></span>
    </span></p></td><td><p>
Specifies the list of strings to be freed.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XwcFreeStringList"><code class="function">XwcFreeStringList</code></a>
function frees memory allocated by
<a class="xref" href="#XwcTextPropertyToTextList"><code class="function">XwcTextPropertyToTextList</code></a>.

</p><p>

To obtain the default string for text conversion in the current locale,
use</p><p>char *XDefaultString()</p><p>


The
<code class="function">XDefaultString</code>
function returns the default string used by Xlib for text conversion
(for example, in 
<a class="xref" href="#XmbTextPropertyToTextList"><code class="function">XmbTextPropertyToTextList</code></a>).
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
<code class="function">XDefaultString</code>
is the empty string (""),
no character is output in the converted text.
<code class="function">XDefaultString</code>
does not return NULL.
</p><p>

The string returned by 
<code class="function">XDefaultString</code>
is independent of the default string for text drawing;
see 
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>
to obtain the default string for an
<span class="type">XFontSet</span>.
</p><p>

The behavior when an invalid codepoint is supplied to any Xlib function is
undefined.
</p><p>

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.

</p><p>

To set the specified list of strings in the STRING encoding to a 
<span class="structname">XTextProperty</span>
structure, use
<a class="xref" href="#XStringListToTextProperty"><code class="function">XStringListToTextProperty</code></a>.
</p><a id="idp50931084" class="indexterm"></a><div class="funcsynopsis"><a id="XStringListToTextProperty"></a><p><code class="funcdef">Status <strong class="fsfunc">XStringListToTextProperty</strong>(</code>char<var class="pdparam"> **list</var>, int<var class="pdparam"> count</var>, XTextProperty<var class="pdparam"> *text_prop_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>list</em></span>
    </span></p></td><td><p>
Specifies a list of null-terminated character strings.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count</em></span>
    </span></p></td><td><p>
Specifies the number of strings.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>text_prop_return</em></span>
    </span></p></td><td><p>
Returns the
<span class="structname">XTextProperty</span>
structure.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XStringListToTextProperty"><code class="function">XStringListToTextProperty</code></a>
function sets the specified 
<span class="structname">XTextProperty</span>
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, 
<a class="xref" href="#XStringListToTextProperty"><code class="function">XStringListToTextProperty</code></a>
does not set any fields in the
<span class="structname">XTextProperty</span>
structure and returns a zero status.
Otherwise, it returns a nonzero status.
To free the storage for the value field, use 
<a class="xref" href="#XFree"></a>.

</p><p>

To obtain a list of strings from a specified
<span class="structname">XTextProperty</span>
structure in the STRING encoding, use
<a class="xref" href="#XTextPropertyToStringList"><code class="function">XTextPropertyToStringList</code></a>.
</p><a id="idp50942796" class="indexterm"></a><div class="funcsynopsis"><a id="XTextPropertyToStringList"></a><p><code class="funcdef">Status <strong class="fsfunc">XTextPropertyToStringList</strong>(</code>XTextProperty<var class="pdparam"> *text_prop</var>, char<var class="pdparam"> ***list_return</var>, int<var class="pdparam"> *count_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>text_prop</em></span>
    </span></p></td><td><p>
Specifies the
<span class="structname">XTextProperty</span>
structure to be used.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>list_return</em></span>
    </span></p></td><td><p>
Returns a list of null-terminated character strings.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count_return</em></span>
    </span></p></td><td><p>
Returns the number of strings.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XTextPropertyToStringList"><code class="function">XTextPropertyToStringList</code></a>
function returns a list of strings representing the null-separated elements 
of the specified
<span class="structname">XTextProperty</span>
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, 
<a class="xref" href="#XTextPropertyToStringList"><code class="function">XTextPropertyToStringList</code></a>
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 
<a class="xref" href="#XFreeStringList"><code class="function">XFreeStringList</code></a>.

</p><p>

To free the in-memory data associated with the specified string list, use
<a class="xref" href="#XFreeStringList"><code class="function">XFreeStringList</code></a>.
</p><a id="idp50954068" class="indexterm"></a><div class="funcsynopsis"><a id="XFreeStringList"></a><p><code class="funcdef">void <strong class="fsfunc">XFreeStringList</strong>(</code>char<var class="pdparam"> **list</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>list</em></span>
    </span></p></td><td><p>
Specifies the list of strings to be freed.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XFreeStringList"><code class="function">XFreeStringList</code></a>
function releases memory allocated by 
<a class="xref" href="#XmbTextPropertyToTextList"><code class="function">XmbTextPropertyToTextList</code></a>
and
<a class="xref" href="#XTextPropertyToStringList"><code class="function">XTextPropertyToStringList</code></a>
and the missing charset list allocated by 
<a class="xref" href="#XCreateFontSet"><code class="function">XCreateFontSet</code></a>.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_and_Reading_Text_Properties"></a>Setting and Reading Text Properties</h3></div></div></div><p>

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
(<span class="property">WM_NAME</span>, <span class="property">WM_ICON_NAME</span>, <span class="property">WM_COMMAND</span>, and <span class="property">WM_CLIENT_MACHINE</span>).
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
<a class="link" href="#Setting_and_Reading_the_WM_NAME_Property" title="Setting and Reading the WM_NAME Property">14.1.4</a>,
<a class="link" href="#Setting_and_Reading_the_WM_ICON_NAME_Property" title="Setting and Reading the WM_ICON_NAME Property">14.1.5</a>,
<a class="link" href="#Setting_and_Reading_the_WM_COMMAND_Property" title="Setting and Reading the WM_COMMAND Property">14.2.1</a>, and
<a class="link" href="#Setting_and_Reading_the_WM_CLIENT_MACHINE_Property" title="Setting and Reading the WM_CLIENT_MACHINE Property">14.2.2</a>,
respectively.

</p><p>

To set one of a window's text properties, use
<a class="xref" href="#XSetTextProperty"><code class="function">XSetTextProperty</code></a>.
</p><a id="idp50966244" class="indexterm"></a><div class="funcsynopsis"><a id="XSetTextProperty"></a><p><code class="funcdef">void <strong class="fsfunc">XSetTextProperty</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XTextProperty<var class="pdparam"> *text_prop</var>, Atom<var class="pdparam"> property</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>text_prop</em></span>
    </span></p></td><td><p>
Specifies the
<span class="structname">XTextProperty</span>
structure to be used.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>property</em></span>
    </span></p></td><td><p>
Specifies the property name.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetTextProperty"><code class="function">XSetTextProperty</code></a>
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
<span class="structname">XTextProperty</span>
structure.
If the property does not already exist,
<a class="xref" href="#XSetTextProperty"><code class="function">XSetTextProperty</code></a>
sets it for the specified window.
</p><p>

<a class="xref" href="#XSetTextProperty"><code class="function">XSetTextProperty</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadAtom</span>,
<span class="errorname">BadValue</span>,
and 
<span class="errorname">BadWindow</span>
errors.

</p><p>

To read one of a window's text properties, use
<a class="xref" href="#XGetTextProperty"><code class="function">XGetTextProperty</code></a>.
</p><a id="idp50980436" class="indexterm"></a><div class="funcsynopsis"><a id="XGetTextProperty"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetTextProperty</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XTextProperty<var class="pdparam"> *text_prop_return</var>, Atom<var class="pdparam"> property</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>text_prop_return</em></span>
    </span></p></td><td><p>
Returns the
<span class="structname">XTextProperty</span>
structure.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>property</em></span>
    </span></p></td><td><p>
Specifies the property name.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetTextProperty"><code class="function">XGetTextProperty</code></a>
function reads the specified property from the window
and stores the data in the returned
<span class="structname">XTextProperty</span>
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,
<a class="xref" href="#XGetTextProperty"><code class="function">XGetTextProperty</code></a>
sets the value field to NULL, 
the encoding field to
<span class="symbol">None</span>,
the format field to zero, 
and the nitems field to zero.
</p><p>

If it was able to read and store the data in the
<span class="structname">XTextProperty</span>
structure,
<a class="xref" href="#XGetTextProperty"><code class="function">XGetTextProperty</code></a>
returns a nonzero status; 
otherwise, it returns a zero status.
</p><p>

<a class="xref" href="#XGetTextProperty"><code class="function">XGetTextProperty</code></a>
can generate
<span class="errorname">BadAtom</span>
and 
<span class="errorname">BadWindow</span>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_and_Reading_the_WM_NAME_Property"></a>Setting and Reading the WM_NAME Property</h3></div></div></div><p>

Xlib provides convenience functions that you can use to set and read 
the <span class="property">WM_NAME</span> property for a given window.

</p><p>

To set a window's <span class="property">WM_NAME</span> property with the supplied convenience function, use
<a class="xref" href="#XSetWMName"><code class="function">XSetWMName</code></a>.
</p><a id="idp50998324" class="indexterm"></a><div class="funcsynopsis"><a id="XSetWMName"></a><p><code class="funcdef">void <strong class="fsfunc">XSetWMName</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XTextProperty<var class="pdparam"> *text_prop</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>text_prop</em></span>
    </span></p></td><td><p>
Specifies the
<span class="structname">XTextProperty</span>
structure to be used.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetWMName"><code class="function">XSetWMName</code></a>
convenience function calls
<a class="xref" href="#XSetTextProperty"><code class="function">XSetTextProperty</code></a>
to set the <span class="property">WM_NAME</span> property.

</p><p>

To read a window's <span class="property">WM_NAME</span> property with the supplied convenience function, use
<a class="xref" href="#XGetWMName"><code class="function">XGetWMName</code></a>.
</p><a id="idp51009124" class="indexterm"></a><div class="funcsynopsis"><a id="XGetWMName"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetWMName</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XTextProperty<var class="pdparam"> *text_prop_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>text_prop_return</em></span>
    </span></p></td><td><p>
Returns the
<span class="structname">XTextProperty</span>
structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetWMName"><code class="function">XGetWMName</code></a>
convenience function calls
<a class="xref" href="#XGetTextProperty"><code class="function">XGetTextProperty</code></a>
to obtain the <span class="property">WM_NAME</span> property.
It returns a nonzero status on success;
otherwise, it returns a zero status.
</p><p>

The following two functions have been superseded by
<a class="xref" href="#XSetWMName"><code class="function">XSetWMName</code></a>
and
<a class="xref" href="#XGetWMName"><code class="function">XGetWMName</code></a>,
respectively. 
You can use these additional convenience functions 
for window names that are encoded as STRING properties.

</p><p>

To assign a name to a window, use
<a class="xref" href="#XStoreName"><code class="function">XStoreName</code></a>.
</p><a id="idp51021076" class="indexterm"></a><a id="idp51021644" class="indexterm"></a><div class="funcsynopsis"><a id="XStoreName"></a><p><code class="funcdef"><strong class="fsfunc">XStoreName</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, char<var class="pdparam"> *window_name</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>window_name</em></span>
    </span></p></td><td><p>
Specifies the window name,
which should be a null-terminated string.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XStoreName"><code class="function">XStoreName</code></a>
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.
</p><p>

<a class="xref" href="#XStoreName"><code class="function">XStoreName</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To get the name of a window, use
<a class="xref" href="#XFetchName"><code class="function">XFetchName</code></a>.
</p><a id="idp50578860" class="indexterm"></a><div class="funcsynopsis"><a id="XFetchName"></a><p><code class="funcdef">Status <strong class="fsfunc">XFetchName</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, char<var class="pdparam"> **window_name_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>window_name_return</em></span>
    </span></p></td><td><p>
Returns the window name, which is a null-terminated string.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFetchName"><code class="function">XFetchName</code></a>
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 <span class="property">WM_NAME</span> property has not been set for this window,
<a class="xref" href="#XFetchName"><code class="function">XFetchName</code></a>
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
<a class="xref" href="#XFree"></a>.
</p><p>

<a class="xref" href="#XFetchName"><code class="function">XFetchName</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_and_Reading_the_WM_ICON_NAME_Property"></a>Setting and Reading the WM_ICON_NAME Property</h3></div></div></div><p>

Xlib provides convenience functions that you can use to set and read 
the <span class="property">WM_ICON_NAME</span> property for a given window.
</p><p>


To set a window's <span class="property">WM_ICON_NAME</span> property,
use
<a class="xref" href="#XSetWMIconName"><code class="function">XSetWMIconName</code></a>.
</p><a id="idp50593484" class="indexterm"></a><div class="funcsynopsis"><a id="XSetWMIconName"></a><p><code class="funcdef">void <strong class="fsfunc">XSetWMIconName</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XTextProperty<var class="pdparam"> *text_prop</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>text_prop</em></span>
    </span></p></td><td><p>
Specifies the
<span class="structname">XTextProperty</span>
structure to be used.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetWMIconName"><code class="function">XSetWMIconName</code></a>
convenience function calls
<a class="xref" href="#XSetTextProperty"><code class="function">XSetTextProperty</code></a>
to set the <span class="property">WM_ICON_NAME</span> property.

</p><p>

To read a window's <span class="property">WM_ICON_NAME</span> property,
use
<a class="xref" href="#XGetWMIconName"><code class="function">XGetWMIconName</code></a>.
</p><a id="idp50604308" class="indexterm"></a><div class="funcsynopsis"><a id="XGetWMIconName"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetWMIconName</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XTextProperty<var class="pdparam"> *text_prop_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>text_prop_return</em></span>
    </span></p></td><td><p>
Returns the
<span class="structname">XTextProperty</span>
structure.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XGetWMIconName"><code class="function">XGetWMIconName</code></a>
convenience function calls
<a class="xref" href="#XGetTextProperty"><code class="function">XGetTextProperty</code></a>
to obtain the <span class="property">WM_ICON_NAME</span> property.
It returns a nonzero status on success;
otherwise, it returns a zero status.
</p><p>

The next two functions have been superseded by
<a class="xref" href="#XSetWMIconName"><code class="function">XSetWMIconName</code></a>
and
<a class="xref" href="#XGetWMIconName"><code class="function">XGetWMIconName</code></a>,
respectively.
You can use these additional convenience functions 
for window names that are encoded as STRING properties.

</p><p>


To set the name to be displayed in a window's icon, use
<a class="xref" href="#XSetIconName"><code class="function">XSetIconName</code></a>.
</p><a id="idp50616508" class="indexterm"></a><a id="idp50617076" class="indexterm"></a><div class="funcsynopsis"><a id="XSetIconName"></a><p><code class="funcdef"><strong class="fsfunc">XSetIconName</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, char<var class="pdparam"> *icon_name</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>icon_name</em></span>
    </span></p></td><td><p>
Specifies the icon name,
which should be a null-terminated string.
    </p></td></tr></tbody></table></div><p>


If the string is not in the Host Portable Character Encoding,
the result is implementation-dependent.
<a class="xref" href="#XSetIconName"><code class="function">XSetIconName</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To get the name a window wants displayed in its icon, use
<a class="xref" href="#XGetIconName"><code class="function">XGetIconName</code></a>.
</p><a id="idp50627060" class="indexterm"></a><div class="funcsynopsis"><a id="XGetIconName"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetIconName</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, char<var class="pdparam"> **icon_name_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>icon_name_return</em></span>
    </span></p></td><td><p>
Returns the window's icon name,
which is a null-terminated string.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetIconName"><code class="function">XGetIconName</code></a>
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,
<a class="xref" href="#XGetIconName"><code class="function">XGetIconName</code></a>
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
<a class="xref" href="#XFree"></a>.
</p><p>

<a class="xref" href="#XGetIconName"><code class="function">XGetIconName</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_and_Reading_the_WM_HINTS_Property"></a>Setting and Reading the WM_HINTS Property</h3></div></div></div><p>

Xlib provides functions that you can use to set and read 
the <span class="property">WM_HINTS</span> property for a given window.
These functions use the flags and the
<span class="structname">XWMHints</span>
structure, as defined in the
<code class="filename">&lt;X11/Xutil.h&gt;</code>
<a id="idp50640700" class="indexterm"></a>
<a id="idp50641596" class="indexterm"></a>
<a id="idp50642508" class="indexterm"></a>
header file.

</p><p>

To allocate an
<span class="structname">XWMHints</span>
structure, use
<code class="function">XAllocWMHints</code>.
</p><p>
  XWMHints *XAllocWMHints()
</p><p>


The
<code class="function">XAllocWMHints</code>
function allocates and returns a pointer to an
<span class="structname">XWMHints</span>
structure.
Note that all fields in the
<span class="structname">XWMHints</span>
structure are initially set to zero.
If insufficient memory is available, 
<code class="function">XAllocWMHints</code>
returns NULL.
To free the memory allocated to this structure,
use
<a class="xref" href="#XFree"></a>.
</p><p>

The
<span class="structname">XWMHints</span>
structure contains:
</p><pre class="literallayout">
/* Window manager hints mask bits */

#define         InputHint             (1L&lt;&lt;0)
#define         StateHint             (1L&lt;&lt;1)
#define         IconPixmapHint        (1L&lt;&lt;2)
#define         IconWindowHint        (1L&lt;&lt;3)
#define         IconPositionHint      (1L&lt;&lt;4)
#define         IconMaskHint          (1L&lt;&lt;5)
#define         WindowGroupHint       (1L&lt;&lt;6)
#define         UrgencyHint           (1L&lt;&lt;8)
#define         AllHints              (InputHint|StateHint|IconPixmapHint|
                                       IconWIndowHint|IconPositionHint|
                                       IconMaskHint|WindowGroupHint)


/* Values */

typedef struct {
	long flags;	        /* marks which fields in this structure are defined */
	Bool input;	        /* does this application rely on the window manager to
			           get keyboard input? */
	int initial_state;	/* see below */
	Pixmap icon_pixmap;	/* pixmap to be used as icon */
	Window icon_window;	/* window to be used as icon */
	int icon_x, icon_y;	/* initial position of icon */
	Pixmap icon_mask;	/* pixmap to be used as mask for icon_pixmap */
	XID window_group;	/* id of related window group */
	/* this structure may be extended in the future */
} XWMHints;
</pre><p>


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 
<span class="symbol">True</span>.
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 
<span class="symbol">True</span>.
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 
<span class="symbol">False</span>.
Applications that never expect any keyboard input also should set this member
to 
<span class="symbol">False</span>.
</p><p>

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 
<span class="symbol">True</span>.
Push model window managers should
make sure that pull model applications do not break them 
by resetting input focus to 
<span class="symbol">PointerRoot</span>
when it is appropriate (for example, whenever an application whose
input member is 
<span class="symbol">False</span>
sets input focus to one of its subwindows).
</p><p>

The definitions for the initial_state flag are:
</p><pre class="literallayout">
#define      WithdrawnState 0
#define      NormalState    1   /* most applications start this way */
#define      IconicState    2   /* application wants to start as an icon */

</pre><p>
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.
</p><p>

The
<span class="symbol">UrgencyHint</span>
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.
</p><p>


To set a window's <span class="property">WM_HINTS</span> property, use
<a class="xref" href="#XSetWMHints"><code class="function">XSetWMHints</code></a>.
</p><a id="idp50657580" class="indexterm"></a><div class="funcsynopsis"><a id="XSetWMHints"></a><p><code class="funcdef"><strong class="fsfunc">XSetWMHints</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XWMHints<var class="pdparam"> *wmhints</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>wmhints</em></span>
    </span></p></td><td><p>
Specifies the 
<span class="structname">XWMHints</span>
structure to be used.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetWMHints"><code class="function">XSetWMHints</code></a>
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.
</p><p>

<a class="xref" href="#XSetWMHints"><code class="function">XSetWMHints</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To read a window's <span class="property">WM_HINTS</span> property, use
<a class="xref" href="#XGetWMHints"><code class="function">XGetWMHints</code></a>.
</p><a id="idp50668876" class="indexterm"></a><div class="funcsynopsis"><a id="XGetWMHints"></a><p><code class="funcdef">XWMHints *<strong class="fsfunc">XGetWMHints</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetWMHints"><code class="function">XGetWMHints</code></a>
function reads the window manager hints and 
returns NULL if no <span class="property">WM_HINTS</span> property was set on the window 
or returns a pointer to an 
<span class="structname">XWMHints</span>
structure if it succeeds.
When finished with the data,
free the space used for it by calling
<a class="xref" href="#XFree"></a>.
</p><p>

<a class="xref" href="#XGetWMHints"><code class="function">XGetWMHints</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_and_Reading_the_WM_NORMAL_HINTS_Property"></a>Setting and Reading the WM_NORMAL_HINTS Property</h3></div></div></div><p>

Xlib provides functions that you can use to set or read 
the <span class="property">WM_NORMAL_HINTS</span> property for a given window.
The functions use the flags and the
<span class="structname">XSizeHints</span>
structure, as defined in the
<code class="filename">&lt;X11/Xutil.h&gt;</code>
<a id="idp50680492" class="indexterm"></a>
<a id="idp50681388" class="indexterm"></a>
<a id="idp50682300" class="indexterm"></a>
header file.
</p><p>

The size of the
<span class="structname">XSizeHints</span>
structure may grow in future releases, as new components are
added to support new <acronym class="acronym">ICCCM</acronym> 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.

</p><p>

To allocate an
<span class="structname">XSizeHints</span>
structure, use
<code class="function">XAllocSizeHints</code>.
</p><p>
XSizeHints *XAllocSizeHints()
</p><p>


The
<code class="function">XAllocSizeHints</code>
function allocates and returns a pointer to an
<span class="structname">XSizeHints</span>
structure.
Note that all fields in the
<span class="structname">XSizeHints</span>
structure are initially set to zero.
If insufficient memory is available, 
<code class="function">XAllocSizeHints</code>
returns NULL.
To free the memory allocated to this structure,
use
<a class="xref" href="#XFree"></a>.
</p><p>

The
<span class="structname">XSizeHints</span>
structure contains:
</p><pre class="literallayout">
/* Size hints mask bits */

#define           USPosition         (1L&lt;&lt;0)  /* user specified x,y */
#define           USSize             (1L&lt;&lt;1)  /* user specified width,height */
#define           PPosition          (1L&lt;&lt;2)  /* program specified posistion */
#define           PSize              (1L&lt;&lt;3)  /* program specified size */
#define           PMinSize           (1L&lt;&lt;4)  /* program specified minimum size */
#define           PMaxSize           (1L&lt;&lt;5)  /* program specified maximum size */
#define           PResizeInc         (1L&lt;&lt;5)  /* program specified resize increments */
#define           PAspect            (1L&lt;&lt;6)  /* program specified min and max aspect ratios */
#define           PBaseSize          (1L&lt;&lt;8)
#define           PWinGravity        (1L&lt;&lt;9)
#define           PAllHints          (PPosition|Psize|
                                      PMinSize|PMaxSize|
                                      PResizeInc|PAspect)


/* Values */

typedef struct {
	long flags;	        /* marks which fields in this structure are defined */
	int x, y;	        /* Obsolete */
	int width, height;	/* Obsolete */
	int min_width, min_height;
	int max_width, max_height;
	int width_inc, height_inc;
	struct {
	       int x;	        /* numerator */
	       int y;	        /* denominator */
	} min_aspect, max_aspect;
	int base_width, base_height;
	int win_gravity;
	/* this structure may be extended in the future */
} XSizeHints;
</pre><p>


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.
</p><p>

Note that use of the
<span class="symbol">PAllHints</span>
macro is highly discouraged.

</p><p>

To set a window's <span class="property">WM_NORMAL_HINTS</span> property, use
<a class="xref" href="#XSetWMNormalHints"><code class="function">XSetWMNormalHints</code></a>.
</p><a id="idp50694468" class="indexterm"></a><div class="funcsynopsis"><a id="XSetWMNormalHints"></a><p><code class="funcdef">void <strong class="fsfunc">XSetWMNormalHints</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XSizeHints<var class="pdparam"> *hints</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hints</em></span>
    </span></p></td><td><p>
Specifies the size hints for the window in its normal state.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XSetWMNormalHints"><code class="function">XSetWMNormalHints</code></a>
function replaces the size hints for the <span class="property">WM_NORMAL_HINTS</span> property 
on the specified window.
If the property does not already exist,
<a class="xref" href="#XSetWMNormalHints"><code class="function">XSetWMNormalHints</code></a>
sets the size hints for the <span class="property">WM_NORMAL_HINTS</span> property on the specified window.
The property is stored with a type of <span class="property">WM_SIZE_HINTS</span> and a format of 32.
</p><p>

<a class="xref" href="#XSetWMNormalHints"><code class="function">XSetWMNormalHints</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadWindow</span>
errors.

</p><p>

To read a window's <span class="property">WM_NORMAL_HINTS</span> property, use
<a class="xref" href="#XGetWMNormalHints"><code class="function">XGetWMNormalHints</code></a>.
</p><a id="idp50707268" class="indexterm"></a><div class="funcsynopsis"><a id="XGetWMNormalHints"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetWMNormalHints</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XSizeHints<var class="pdparam"> *hints_return</var>, long<var class="pdparam"> *supplied_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hints_return</em></span>
    </span></p></td><td><p>
Returns the size hints for the window in its normal state.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>supplied_return</em></span>
    </span></p></td><td><p>
Returns the hints that were supplied by the user.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XGetWMNormalHints"><code class="function">XGetWMNormalHints</code></a>
function returns the size hints stored in the <span class="property">WM_NORMAL_HINTS</span> property 
on the specified window.
If the property is of type <span class="property">WM_SIZE_HINTS</span>, is of format 32,
and is long enough to contain either an old (pre-<acronym class="acronym">ICCCM</acronym>) 
or new size hints structure, 
<a class="xref" href="#XGetWMNormalHints"><code class="function">XGetWMNormalHints</code></a>
sets the various fields of the 
<span class="structname">XSizeHints</span>
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.
</p><p>

If 
<a class="xref" href="#XGetWMNormalHints"><code class="function">XGetWMNormalHints</code></a>
returns successfully and a pre-<acronym class="acronym">ICCCM</acronym> size hints property is read, 
the supplied_return argument will contain the following bits:
</p><p>

</p><pre class="literallayout">
(USPosition|USSize|PPosition|PSize|PMinSize|
 PMaxSize|PResizeInc|PAspect)
</pre><p>
</p><p>

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:
</p><p>

</p><pre class="literallayout">
PBaseSize|PWinGravity
</pre><p>
</p><p>

<a class="xref" href="#XGetWMNormalHints"><code class="function">XGetWMNormalHints</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.

</p><p>

To set a window's <span class="property">WM_SIZE_HINTS</span> property, use
<a class="xref" href="#XSetWMSizeHints"><code class="function">XSetWMSizeHints</code></a>.
</p><a id="idp50725548" class="indexterm"></a><div class="funcsynopsis"><a id="XSetWMSizeHints"></a><p><code class="funcdef">void <strong class="fsfunc">XSetWMSizeHints</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XSizeHints<var class="pdparam"> *hints</var>, Atom<var class="pdparam"> property</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hints</em></span>
    </span></p></td><td><p>
Specifies the
<span class="structname">XSizeHints</span>
structure to be used.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>property</em></span>
    </span></p></td><td><p>
Specifies the property name.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XSetWMSizeHints"><code class="function">XSetWMSizeHints</code></a>
function replaces the size hints for the specified property 
on the named window.
If the specified property does not already exist,
<a class="xref" href="#XSetWMSizeHints"><code class="function">XSetWMSizeHints</code></a>
sets the size hints for the specified property
on the named window.
The property is stored with a type of <span class="property">WM_SIZE_HINTS</span> and a format of 32.
To set a window's normal size hints, 
you can use the 
<a class="xref" href="#XSetWMNormalHints"><code class="function">XSetWMNormalHints</code></a>
function.
</p><p>

<a class="xref" href="#XSetWMSizeHints"><code class="function">XSetWMSizeHints</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadAtom</span>,
and 
<span class="errorname">BadWindow</span>
errors.

</p><p>

To read a window's <span class="property">WM_SIZE_HINTS</span> property, use
<a class="xref" href="#XGetWMSizeHints"><code class="function">XGetWMSizeHints</code></a>.
</p><a id="idp50740372" class="indexterm"></a><div class="funcsynopsis"><a id="XGetWMSizeHints"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetWMSizeHints</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XSizeHints<var class="pdparam"> *hints_return</var>, long<var class="pdparam"> *supplied_return</var>, Atom<var class="pdparam"> property</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hints_return</em></span>
    </span></p></td><td><p>
Returns the
<span class="structname">XSizeHints</span>
structure.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>supplied_return</em></span>
    </span></p></td><td><p>
Returns the hints that were supplied by the user.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>property</em></span>
    </span></p></td><td><p>
Specifies the property name.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XGetWMSizeHints"><code class="function">XGetWMSizeHints</code></a>
function returns the size hints stored in the specified property 
on the named window.
If the property is of type <span class="property">WM_SIZE_HINTS</span>, is of format 32, 
and is long enough to contain either an old (pre-<acronym class="acronym">ICCCM</acronym>) 
or new size hints structure, 
<a class="xref" href="#XGetWMSizeHints"><code class="function">XGetWMSizeHints</code></a>
sets the various fields of the 
<span class="structname">XSizeHints</span>
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 
<a class="xref" href="#XGetWMNormalHints"><code class="function">XGetWMNormalHints</code></a>
function.
</p><p>

If 
<a class="xref" href="#XGetWMSizeHints"><code class="function">XGetWMSizeHints</code></a>
returns successfully and a pre-<acronym class="acronym">ICCCM</acronym> size hints property is read, 
the supplied_return argument will contain the following bits:
</p><p>

</p><pre class="literallayout">
(USPosition|USSize|PPosition|PSize|PMinSize|
 PMaxSize|PResizeInc|PAspect)
</pre><p>
</p><p>

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:
</p><p>

</p><pre class="literallayout">
PBaseSize|PWinGravity
</pre><p>
</p><p>

<a class="xref" href="#XGetWMSizeHints"><code class="function">XGetWMSizeHints</code></a>
can generate
<span class="errorname">BadAtom</span>
and 
<span class="errorname">BadWindow</span>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_and_Reading_the_WM_CLASS_Property"></a>Setting and Reading the WM_CLASS Property</h3></div></div></div><p>

Xlib provides functions that you can use to set and get 
the <span class="property">WM_CLASS</span> property for a given window.
These functions use the
<span class="structname">XClassHint</span>
structure, which is defined in the
<code class="filename">&lt;X11/Xutil.h&gt;</code>
<a id="idp50762356" class="indexterm"></a>
<a id="idp50763252" class="indexterm"></a>
<a id="idp50764164" class="indexterm"></a>
header file.

</p><p>

To allocate an
<span class="structname">XClassHint</span>
structure, use
<code class="function">XAllocClassHint</code>.
<a id="idp50766236" class="indexterm"></a>

</p><p>

  XClassHint *XAllocClassHint()
</p><p>


The
<code class="function">XAllocClassHint</code>
function allocates and returns a pointer to an
<span class="structname">XClassHint</span>
structure.
Note that the pointer fields in the
<span class="structname">XClassHint</span>
structure are initially set to NULL.
If insufficient memory is available, 
<code class="function">XAllocClassHint</code>
returns NULL.
To free the memory allocated to this structure,
use
<a class="xref" href="#XFree"></a>.
</p><p>

The
<span class="structname">XClassHint</span>
contains:
</p><p>


<a id="idp50770588" class="indexterm"></a>
</p><pre class="literallayout">


typedef struct {
	char *res_name;
	char *res_class;
} XClassHint;
</pre><p>
</p><p>


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 <span class="property">WM_NAME</span>.
That is, <span class="property">WM_NAME</span> 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 <span class="property">WM_CLASS</span> is the formal name of the application
that should be used when retrieving the application's resources from the 
resource database.
</p><p>


To set a window's <span class="property">WM_CLASS</span> property, use
<a class="xref" href="#XSetClassHint"><code class="function">XSetClassHint</code></a>.
</p><a id="idp50775460" class="indexterm"></a><div class="funcsynopsis"><a id="XSetClassHint"></a><p><code class="funcdef"><strong class="fsfunc">XSetClassHint</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XClassHint<var class="pdparam"> *class_hints</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>class_hints</em></span>
    </span></p></td><td><p>
Specifies the
<span class="structname">XClassHint</span>
structure that is to be used.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetClassHint"><code class="function">XSetClassHint</code></a>
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.
</p><p>

<a class="xref" href="#XSetClassHint"><code class="function">XSetClassHint</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadWindow</span>
errors. 
</p><p>


To read a window's <span class="property">WM_CLASS</span> property, use
<a class="xref" href="#XGetClassHint"><code class="function">XGetClassHint</code></a>.
</p><a id="idp50786820" class="indexterm"></a><div class="funcsynopsis"><a id="XGetClassHint"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetClassHint</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XClassHint<var class="pdparam"> *class_hints_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>class_hints_return</em></span>
    </span></p></td><td><p>
Returns the 
<span class="structname">XClassHint</span>
structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetClassHint"><code class="function">XGetClassHint</code></a>
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
<a class="xref" href="#XFree"></a>
on each individually.
</p><p>

<a class="xref" href="#XGetClassHint"><code class="function">XGetClassHint</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_and_Reading_the_WM_TRANSIENT_FOR_Property"></a>Setting and Reading the WM_TRANSIENT_FOR Property</h3></div></div></div><p>

Xlib provides functions that you can use to set and read
the <span class="property">WM_TRANSIENT_FOR</span> property for a given window.
</p><p>


To set a window's <span class="property">WM_TRANSIENT_FOR</span> property, use
<a class="xref" href="#XSetTransientForHint"><code class="function">XSetTransientForHint</code></a>.
</p><a id="idp50800788" class="indexterm"></a><div class="funcsynopsis"><a id="XSetTransientForHint"></a><p><code class="funcdef"><strong class="fsfunc">XSetTransientForHint</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, Window<var class="pdparam"> prop_window</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>prop_window</em></span>
    </span></p></td><td><p>
Specifies the window that the <span class="property">WM_TRANSIENT_FOR</span> property is to be set to.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetTransientForHint"><code class="function">XSetTransientForHint</code></a>
function sets the <span class="property">WM_TRANSIENT_FOR</span> property of the specified window to the 
specified prop_window.
</p><p>

<a class="xref" href="#XSetTransientForHint"><code class="function">XSetTransientForHint</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To read a window's <span class="property">WM_TRANSIENT_FOR</span> property, use
<a class="xref" href="#XGetTransientForHint"><code class="function">XGetTransientForHint</code></a>.
</p><a id="idp50812428" class="indexterm"></a><div class="funcsynopsis"><a id="XGetTransientForHint"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetTransientForHint</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, Window<var class="pdparam"> *prop_window_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>prop_window_return</em></span>
    </span></p></td><td><p>
Returns the <span class="property">WM_TRANSIENT_FOR</span> property of the specified window.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetTransientForHint"><code class="function">XGetTransientForHint</code></a>
function returns the <span class="property">WM_TRANSIENT_FOR</span> property for the specified window.
It returns a nonzero status on success;
otherwise, it returns a zero status.
</p><p>

<a class="xref" href="#XGetTransientForHint"><code class="function">XGetTransientForHint</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_and_Reading_the_WM_PROTOCOLS_Property"></a>Setting and Reading the WM_PROTOCOLS Property</h3></div></div></div><p>

Xlib provides functions that you can use to set and read
the <span class="property">WM_PROTOCOLS</span> property for a given window.
</p><p>


To set a window's <span class="property">WM_PROTOCOLS</span> property, use
<a class="xref" href="#XSetWMProtocols"><code class="function">XSetWMProtocols</code></a>.
</p><a id="idp50826044" class="indexterm"></a><div class="funcsynopsis"><a id="XSetWMProtocols"></a><p><code class="funcdef">Status <strong class="fsfunc">XSetWMProtocols</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, Atom<var class="pdparam"> *protocols</var>, int<var class="pdparam"> count</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>protocols</em></span>
    </span></p></td><td><p>
Specifies the list of protocols.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count</em></span>
    </span></p></td><td><p>
Specifies the number of protocols in the list.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XSetWMProtocols"><code class="function">XSetWMProtocols</code></a>
function replaces the <span class="property">WM_PROTOCOLS</span> property on the specified window 
with the list of atoms specified by the protocols argument.
If the property does not already exist,
<a class="xref" href="#XSetWMProtocols"><code class="function">XSetWMProtocols</code></a>
sets the <span class="property">WM_PROTOCOLS</span> 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 <span class="property">WM_PROTOCOLS</span> atom, 
<a class="xref" href="#XSetWMProtocols"><code class="function">XSetWMProtocols</code></a>
returns a zero status.
Otherwise, it returns a nonzero status.
</p><p>

<a class="xref" href="#XSetWMProtocols"><code class="function">XSetWMProtocols</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadWindow</span>
errors.

</p><p>

To read a window's <span class="property">WM_PROTOCOLS</span> property, use
<a class="xref" href="#XGetWMProtocols"><code class="function">XGetWMProtocols</code></a>.
</p><a id="idp50841220" class="indexterm"></a><div class="funcsynopsis"><a id="XGetWMProtocols"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetWMProtocols</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, Atom<var class="pdparam"> **protocols_return</var>, int<var class="pdparam"> *count_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>protocols_return</em></span>
    </span></p></td><td><p>
Returns the list of protocols.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count_return</em></span>
    </span></p></td><td><p>
Returns the number of protocols in the list.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XGetWMProtocols"><code class="function">XGetWMProtocols</code></a>
function returns the list of atoms stored in the <span class="property">WM_PROTOCOLS</span> 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 <span class="property">WM_PROTOCOLS</span> can be interned, 
<a class="xref" href="#XGetWMProtocols"><code class="function">XGetWMProtocols</code></a>
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
<a class="xref" href="#XFree"></a>.
</p><p>

<a class="xref" href="#XGetWMProtocols"><code class="function">XGetWMProtocols</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_and_Reading_the_WM_COLORMAP_WINDOWS_Property"></a>Setting and Reading the WM_COLORMAP_WINDOWS Property</h3></div></div></div><p>

Xlib provides functions that you can use to set and read
the <span class="property">WM_COLORMAP_WINDOWS</span> property for a given window.

</p><p>

To set a window's <span class="property">WM_COLORMAP_WINDOWS</span> property, use
<a class="xref" href="#XSetWMColormapWindows"><code class="function">XSetWMColormapWindows</code></a>.
</p><a id="idp50858108" class="indexterm"></a><div class="funcsynopsis"><a id="XSetWMColormapWindows"></a><p><code class="funcdef">Status <strong class="fsfunc">XSetWMColormapWindows</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, Window<var class="pdparam"> *colormap_windows</var>, int<var class="pdparam"> count</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap_windows</em></span>
    </span></p></td><td><p>
Specifies the list of windows.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count</em></span>
    </span></p></td><td><p>
Specifies the number of windows in the list.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XSetWMColormapWindows"><code class="function">XSetWMColormapWindows</code></a>
function replaces the <span class="property">WM_COLORMAP_WINDOWS</span> property on the specified
window with the list of windows specified by the colormap_windows argument.
If the property does not already exist,
<a class="xref" href="#XSetWMColormapWindows"><code class="function">XSetWMColormapWindows</code></a>
sets the <span class="property">WM_COLORMAP_WINDOWS</span> 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 <span class="property">WM_COLORMAP_WINDOWS</span> atom,
<a class="xref" href="#XSetWMColormapWindows"><code class="function">XSetWMColormapWindows</code></a>
returns a zero status.
Otherwise, it returns a nonzero status.
</p><p>

<a class="xref" href="#XSetWMColormapWindows"><code class="function">XSetWMColormapWindows</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadWindow</span>
errors.

</p><p>

To read a window's <span class="property">WM_COLORMAP_WINDOWS</span> property, use
<a class="xref" href="#XGetWMColormapWindows"><code class="function">XGetWMColormapWindows</code></a>.
</p><a id="idp50873100" class="indexterm"></a><div class="funcsynopsis"><a id="XGetWMColormapWindows"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetWMColormapWindows</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, Window<var class="pdparam"> **colormap_windows_return</var>, int<var class="pdparam"> *count_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap_windows_return</em></span>
    </span></p></td><td><p>
Returns the list of windows.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count_return</em></span>
    </span></p></td><td><p>
Returns the number of windows in the list.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XGetWMColormapWindows"><code class="function">XGetWMColormapWindows</code></a>
function returns the list of window identifiers stored 
in the <span class="property">WM_COLORMAP_WINDOWS</span> 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 <span class="property">WM_COLORMAP_WINDOWS</span> can be interned, 
<a class="xref" href="#XGetWMColormapWindows"><code class="function">XGetWMColormapWindows</code></a>
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
<a class="xref" href="#XFree"></a>.
</p><p>

<a class="xref" href="#XGetWMColormapWindows"><code class="function">XGetWMColormapWindows</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_and_Reading_the_WM_ICON_SIZE_Property"></a>Setting and Reading the WM_ICON_SIZE Property</h3></div></div></div><p>

Xlib provides functions that you can use to set and read 
the <span class="property">WM_ICON_SIZE</span> property for a given window.
These functions use the 
<span class="structname">XIconSize</span>
<a id="idp50888604" class="indexterm"></a>
structure, which is defined in the
<code class="filename">&lt;X11/Xutil.h&gt;</code>
<a id="idp50889564" class="indexterm"></a>
<a id="idp50890460" class="indexterm"></a>
<a id="idp50891372" class="indexterm"></a>
header file.

</p><p>

To allocate an
<span class="structname">XIconSize</span>
structure, use
<code class="function">XAllocIconSize</code>.
</p><p>
  XIconSize *XAllocIconSize()
</p><p>


The
<code class="function">XAllocIconSize</code>
function allocates and returns a pointer to an
<span class="structname">XIconSize</span>
structure.
Note that all fields in the
<span class="structname">XIconSize</span>
structure are initially set to zero.
If insufficient memory is available, 
<code class="function">XAllocIconSize</code>
returns NULL.
To free the memory allocated to this structure,
use
<a class="xref" href="#XFree"></a>.
</p><p>

The
<span class="structname">XIconSize</span>
structure contains:
</p><p>


<a id="idp50897180" class="indexterm"></a>
</p><pre class="literallayout">


typedef struct {
	int min_width, min_height;
	int max_width, max_height;
	int width_inc, height_inc;
} XIconSize;
</pre><p>
</p><p>


The width_inc and height_inc members define an arithmetic progression of
sizes (minimum to maximum) that represent the supported icon sizes.
</p><p>


To set a window's <span class="property">WM_ICON_SIZE</span> property, use
<a class="xref" href="#XSetIconSizes"><code class="function">XSetIconSizes</code></a>.
</p><a id="idp50900668" class="indexterm"></a><div class="funcsynopsis"><a id="XSetIconSizes"></a><p><code class="funcdef"><strong class="fsfunc">XSetIconSizes</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XIconSize<var class="pdparam"> *size_list</var>, int<var class="pdparam"> count</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>size_list</em></span>
    </span></p></td><td><p>
Specifies the size list.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count</em></span>
    </span></p></td><td><p>
Specifies the number of items in the size list.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetIconSizes"><code class="function">XSetIconSizes</code></a>
function is used only by window managers to set the supported icon sizes.
</p><p>

<a class="xref" href="#XSetIconSizes"><code class="function">XSetIconSizes</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To read a window's <span class="property">WM_ICON_SIZE</span> property, use
<a class="xref" href="#XGetIconSizes"><code class="function">XGetIconSizes</code></a>.
</p><a id="idp52515156" class="indexterm"></a><div class="funcsynopsis"><a id="XGetIconSizes"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetIconSizes</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XIconSize<var class="pdparam"> **size_list_return</var>, int<var class="pdparam"> *count_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>size_list_return</em></span>
    </span></p></td><td><p>
Returns the size list.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count_return</em></span>
    </span></p></td><td><p>
Returns the number of items in the size list.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetIconSizes"><code class="function">XGetIconSizes</code></a>
function returns zero if a window manager has not set icon sizes;
otherwise, it returns nonzero.
<a class="xref" href="#XGetIconSizes"><code class="function">XGetIconSizes</code></a>
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
<a class="xref" href="#XSetWMHints"><code class="function">XSetWMHints</code></a>
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
<a class="xref" href="#XFree"></a>.
</p><p>

<a class="xref" href="#XGetIconSizes"><code class="function">XGetIconSizes</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Using_Window_Manager_Convenience_Functions"></a>Using Window Manager Convenience Functions</h3></div></div></div><p>

The 
<a class="xref" href="#XmbSetWMProperties"><code class="function">XmbSetWMProperties</code></a>
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
<span class="property">WM_NAME</span>, <span class="property">WM_ICON_NAME</span>, <span class="property">WM_HINTS</span>, <span class="property">WM_NORMAL_HINTS</span>, <span class="property">WM_CLASS</span>,
<span class="property">WM_COMMAND</span>, <span class="property">WM_CLIENT_MACHINE</span>, and <span class="property">WM_LOCALE_NAME</span>.
</p><a id="idp52530940" class="indexterm"></a><div class="funcsynopsis"><a id="XmbSetWMProperties"></a><p><code class="funcdef">void <strong class="fsfunc">XmbSetWMProperties</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, char<var class="pdparam"> *window_name</var>, char<var class="pdparam"> *icon_name</var>, char<var class="pdparam"> *argv[]</var>, int<var class="pdparam"> argc</var>, XSizeHints<var class="pdparam"> *normal_hints</var>, XWMHints<var class="pdparam"> *wm_hints</var>, XClassHint<var class="pdparam"> *class_hints</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>window_name</em></span>
    </span></p></td><td><p>
Specifies the window name,
which should be a null-terminated string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>icon_name</em></span>
    </span></p></td><td><p>
Specifies the icon name,
which should be a null-terminated string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>argv</em></span>
    </span></p></td><td><p>
Specifies the application's argument list.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>argc</em></span>
    </span></p></td><td><p>
Specifies the number of arguments.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hints</em></span>
    </span></p></td><td><p>
Specifies the size hints for the window in its normal state.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>wm_hints</em></span>
    </span></p></td><td><p>
Specifies the
<span class="structname">XWMHints</span>
structure to be used.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>class_hints</em></span>
    </span></p></td><td><p>
Specifies the
<span class="structname">XClassHint</span>
structure to be used.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XmbSetWMProperties"><code class="function">XmbSetWMProperties</code></a>
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).
</p><p>

If the window_name argument is non-NULL,
<a class="xref" href="#XmbSetWMProperties"><code class="function">XmbSetWMProperties</code></a>
sets the <span class="property">WM_NAME</span> property.
If the icon_name argument is non-NULL,
<a class="xref" href="#XmbSetWMProperties"><code class="function">XmbSetWMProperties</code></a>
sets the <span class="property">WM_ICON_NAME</span> 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''.
</p><p>

If the normal_hints argument is non-NULL,
<a class="xref" href="#XmbSetWMProperties"><code class="function">XmbSetWMProperties</code></a>
calls
<a class="xref" href="#XSetWMNormalHints"><code class="function">XSetWMNormalHints</code></a>,
which sets the <span class="property">WM_NORMAL_HINTS</span> property
(see <a class="link" href="#Setting_and_Reading_the_WM_NORMAL_HINTS_Property" title="Setting and Reading the WM_NORMAL_HINTS Property">section 14.1.7</a>).
If the wm_hints argument is non-NULL, 
<a class="xref" href="#XmbSetWMProperties"><code class="function">XmbSetWMProperties</code></a>
calls
<a class="xref" href="#XSetWMHints"><code class="function">XSetWMHints</code></a>,
which sets the <span class="property">WM_HINTS</span> property
(see <a class="link" href="#Setting_and_Reading_the_WM_HINTS_Property" title="Setting and Reading the WM_HINTS Property">section 14.1.6</a>).
</p><p>

If the argv argument is non-NULL,
<a class="xref" href="#XmbSetWMProperties"><code class="function">XmbSetWMProperties</code></a>
sets the <span class="property">WM_COMMAND</span> property from argv and argc.
An argc of zero indicates a zero-length command.
</p><p>

The hostname of the machine is stored using 
<a class="xref" href="#XSetWMClientMachine"><code class="function">XSetWMClientMachine</code></a>
(see <a class="link" href="#Setting_and_Reading_the_WM_CLIENT_MACHINE_Property" title="Setting and Reading the WM_CLIENT_MACHINE Property">section 14.2.2</a>).
</p><p>

If the class_hints argument is non-NULL,
<a class="xref" href="#XmbSetWMProperties"><code class="function">XmbSetWMProperties</code></a>
sets the <span class="property">WM_CLASS</span> property.
If the res_name member in the 
<span class="structname">XClassHint</span>
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.
</p><p>

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 <acronym class="acronym">POSIX</acronym>-compliant systems, the LC_CTYPE, else LANG environment variable).
The corresponding <span class="property">WM_CLASS</span>, <span class="property">WM_COMMAND</span>, and <span class="property">WM_CLIENT_MACHINE</span> properties
are typed according to the local host locale announcer.
No encoding conversion is performed prior to storage in the properties.
</p><p>

For clients that need to process the property text in a locale,
<a class="xref" href="#XmbSetWMProperties"><code class="function">XmbSetWMProperties</code></a>
sets the <span class="property">WM_LOCALE_NAME</span> 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.
</p><p>

<a class="xref" href="#XmbSetWMProperties"><code class="function">XmbSetWMProperties</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadWindow</span>
errors.

</p><p>

To set a window's standard window manager properties
with strings in client-specified encodings, use
<a class="xref" href="#XSetWMProperties"><code class="function">XSetWMProperties</code></a>.
The standard window manager properties for a given window are
<span class="property">WM_NAME</span>, <span class="property">WM_ICON_NAME</span>, <span class="property">WM_HINTS</span>, <span class="property">WM_NORMAL_HINTS</span>, <span class="property">WM_CLASS</span>,
<span class="property">WM_COMMAND</span>, and <span class="property">WM_CLIENT_MACHINE</span>.
</p><a id="idp52564972" class="indexterm"></a><div class="funcsynopsis"><a id="XSetWMProperties"></a><p><code class="funcdef">void <strong class="fsfunc">XSetWMProperties</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XTextProperty<var class="pdparam"> *window_name</var>, XTextProperty<var class="pdparam"> *icon_name</var>, char<var class="pdparam"> **argv</var>, int<var class="pdparam"> argc</var>, XSizeHints<var class="pdparam"> *normal_hints</var>, XWMHints<var class="pdparam"> *wm_hints</var>, XClassHint<var class="pdparam"> *class_hints</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>window_name</em></span>
    </span></p></td><td><p>
Specifies the window name,
which should be a null-terminated string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>icon_name</em></span>
    </span></p></td><td><p>
Specifies the icon name,
which should be a null-terminated string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>argv</em></span>
    </span></p></td><td><p>
Specifies the application's argument list.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>argc</em></span>
    </span></p></td><td><p>
Specifies the number of arguments.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>normal_hints</em></span>
    </span></p></td><td><p>
Specifies the size hints for the window in its normal state.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>wm_hints</em></span>
    </span></p></td><td><p>
Specifies the
<span class="structname">XWMHints</span>
structure to be used.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>class_hints</em></span>
    </span></p></td><td><p>
Specifies the
<span class="structname">XClassHint</span>
structure to be used.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XSetWMProperties"><code class="function">XSetWMProperties</code></a>
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).
</p><p>

If the window_name argument is non-NULL, 
<a class="xref" href="#XSetWMProperties"><code class="function">XSetWMProperties</code></a>
calls
<a class="xref" href="#XSetWMName"><code class="function">XSetWMName</code></a>,
which, in turn, sets the <span class="property">WM_NAME</span> property
(see <a class="link" href="#Setting_and_Reading_the_WM_NAME_Property" title="Setting and Reading the WM_NAME Property">section 14.1.4</a>).
If the icon_name argument is non-NULL,
<a class="xref" href="#XSetWMProperties"><code class="function">XSetWMProperties</code></a>
calls
<a class="xref" href="#XSetWMIconName"><code class="function">XSetWMIconName</code></a>,
which sets the <span class="property">WM_ICON_NAME</span> property
(see <a class="link" href="#Setting_and_Reading_the_WM_ICON_NAME_Property" title="Setting and Reading the WM_ICON_NAME Property">section 14.1.5</a>).
If the argv argument is non-NULL, 
<a class="xref" href="#XSetWMProperties"><code class="function">XSetWMProperties</code></a>
calls
<a class="xref" href="#XSetCommand"><code class="function">XSetCommand</code></a>,
which sets the <span class="property">WM_COMMAND</span> property
(see <a class="link" href="#Setting_and_Reading_the_WM_COMMAND_Property" title="Setting and Reading the WM_COMMAND Property">section 14.2.1</a>).
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
<a class="xref" href="#XSetWMClientMachine"><code class="function">XSetWMClientMachine</code></a>
(see <a class="link" href="#Setting_and_Reading_the_WM_CLIENT_MACHINE_Property" title="Setting and Reading the WM_CLIENT_MACHINE Property">section 14.2.2</a>).
</p><p>

If the normal_hints argument is non-NULL, 
<a class="xref" href="#XSetWMProperties"><code class="function">XSetWMProperties</code></a>
calls
<a class="xref" href="#XSetWMNormalHints"><code class="function">XSetWMNormalHints</code></a>,
which sets the <span class="property">WM_NORMAL_HINTS</span> property
(see <a class="link" href="#Setting_and_Reading_the_WM_NORMAL_HINTS_Property" title="Setting and Reading the WM_NORMAL_HINTS Property">section 14.1.7</a>).
If the wm_hints argument is non-NULL, 
<a class="xref" href="#XSetWMProperties"><code class="function">XSetWMProperties</code></a>
calls
<a class="xref" href="#XSetWMHints"><code class="function">XSetWMHints</code></a>,
which sets the <span class="property">WM_HINTS</span> property
(see <a class="link" href="#Setting_and_Reading_the_WM_HINTS_Property" title="Setting and Reading the WM_HINTS Property">section 14.1.6</a>).
</p><p>

If the class_hints argument is non-NULL, 
<a class="xref" href="#XSetWMProperties"><code class="function">XSetWMProperties</code></a>
calls
<a class="xref" href="#XSetClassHint"><code class="function">XSetClassHint</code></a>,
which sets the <span class="property">WM_CLASS</span> property
(see <a class="link" href="#Setting_and_Reading_the_WM_CLASS_Property" title="Setting and Reading the WM_CLASS Property">section 14.1.8</a>).
If the res_name member in the
<span class="structname">XClassHint</span>
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.
</p><p>

<a class="xref" href="#XSetWMProperties"><code class="function">XSetWMProperties</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadWindow</span>
errors.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Client_to_Session_Manager_Communication"></a>Client to Session Manager Communication</h2></div></div></div><p>

This section discusses how to:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Set and read the <span class="property">WM_COMMAND</span> property
    </p></li><li class="listitem"><p>
Set and read the <span class="property">WM_CLIENT_MACHINE</span> property
    </p></li></ul></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_and_Reading_the_WM_COMMAND_Property"></a>Setting and Reading the WM_COMMAND Property</h3></div></div></div><p>

Xlib provides functions that you can use to set and read
the <span class="property">WM_COMMAND</span> property for a given window.

</p><p>

To set a window's <span class="property">WM_COMMAND</span> property, use
<a class="xref" href="#XSetCommand"><code class="function">XSetCommand</code></a>.
</p><a id="idp52600588" class="indexterm"></a><div class="funcsynopsis"><a id="XSetCommand"></a><p><code class="funcdef"><strong class="fsfunc">XSetCommand</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, char<var class="pdparam"> **argv</var>, int<var class="pdparam"> argc</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>argv</em></span>
    </span></p></td><td><p>
Specifies the application's argument list.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>argc</em></span>
    </span></p></td><td><p>
Specifies the number of arguments.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetCommand"><code class="function">XSetCommand</code></a>
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.
</p><p>

<a class="xref" href="#XSetCommand"><code class="function">XSetCommand</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadWindow</span>
errors.

</p><p>

To read a window's <span class="property">WM_COMMAND</span> property, use
<a class="xref" href="#XGetCommand"><code class="function">XGetCommand</code></a>.
</p><a id="idp52611828" class="indexterm"></a><div class="funcsynopsis"><a id="XGetCommand"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetCommand</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, char<var class="pdparam"> ***argv_return</var>, int<var class="pdparam"> *argc_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>argv_return</em></span>
    </span></p></td><td><p>
Returns the application's argument list.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>argc_return</em></span>
    </span></p></td><td><p>
Returns the number of arguments returned.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XGetCommand"><code class="function">XGetCommand</code></a>
function reads the <span class="property">WM_COMMAND</span> property from the specified window 
and returns a string list.
If the <span class="property">WM_COMMAND</span> property exists, 
it is of type STRING and format 8.
If sufficient memory can be allocated to contain the string list, 
<a class="xref" href="#XGetCommand"><code class="function">XGetCommand</code></a>
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
<a class="xref" href="#XFreeStringList"><code class="function">XFreeStringList</code></a>.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_and_Reading_the_WM_CLIENT_MACHINE_Property"></a>Setting and Reading the WM_CLIENT_MACHINE Property</h3></div></div></div><p>

Xlib provides functions that you can use to set and read 
the <span class="property">WM_CLIENT_MACHINE</span> property for a given window.

</p><p>

To set a window's <span class="property">WM_CLIENT_MACHINE</span> property, use
<a class="xref" href="#XSetWMClientMachine"><code class="function">XSetWMClientMachine</code></a>.
</p><a id="idp52625644" class="indexterm"></a><div class="funcsynopsis"><a id="XSetWMClientMachine"></a><p><code class="funcdef">void <strong class="fsfunc">XSetWMClientMachine</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XTextProperty<var class="pdparam"> *text_prop</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>text_prop</em></span>
    </span></p></td><td><p>
Specifies the
<span class="structname">XTextProperty</span>
structure to be used.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetWMClientMachine"><code class="function">XSetWMClientMachine</code></a>
convenience function calls
<a class="xref" href="#XSetTextProperty"><code class="function">XSetTextProperty</code></a>
to set the <span class="property">WM_CLIENT_MACHINE</span> property.

</p><p>

To read a window's <span class="property">WM_CLIENT_MACHINE</span> property, use
<a class="xref" href="#XGetWMClientMachine"><code class="function">XGetWMClientMachine</code></a>.
</p><a id="idp52634924" class="indexterm"></a><div class="funcsynopsis"><a id="XGetWMClientMachine"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetWMClientMachine</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XTextProperty<var class="pdparam"> *text_prop_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>text_prop_return</em></span>
    </span></p></td><td><p>
Returns the
<span class="structname">XTextProperty</span>
structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetWMClientMachine"><code class="function">XGetWMClientMachine</code></a>
convenience function performs an 
<a class="xref" href="#XGetTextProperty"><code class="function">XGetTextProperty</code></a>
on the <span class="property">WM_CLIENT_MACHINE</span> property.
It returns a nonzero status on success;
otherwise, it returns a zero status.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Standard_Colormaps"></a>Standard Colormaps</h2></div></div></div><p>

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.
</p><p>

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 (<acronym class="acronym">RGB</acronym>)
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 <acronym class="acronym">RGB</acronym> triples into pixel values very quickly,
because drawing the entire sphere requires many such
conversions.
</p><p>

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.
</p><p>

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.
</p><p>

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.
</p><p>

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.
</p><p>

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.
</p><p>

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.
</p><p>

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.
</p><p>

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.

</p><p>

To allocate an
<span class="structname">XStandardColormap</span>
structure, use
<code class="function">XAllocStandardColormap</code>.
</p><p>
XStandardColormap *XAllocStandardColormap()
</p><p>


The
<code class="function">XAllocStandardColormap</code>
function allocates and returns a pointer to an
<span class="structname">XStandardColormap</span>
structure.
Note that all fields in the
<span class="structname">XStandardColormap</span>
structure are initially set to zero.
If insufficient memory is available, 
<code class="function">XAllocStandardColormap</code>
returns NULL.
To free the memory allocated to this structure,
use
<a class="xref" href="#XFree"></a>.
</p><p>

The 
<span class="structname">XStandardColormap</span>
structure contains:
</p><pre class="literallayout">
/* Hints */

#define       ReeaseByFreeingColormap  ((XID)1L)

/* Values */

typedef struct {
	Colormap colormap;
	unsigned long red_max;
	unsigned long red_mult;
	unsigned long green_max;
	unsigned long green_mult;
	unsigned long blue_max;
	unsigned long blue_mult;
	unsigned long base_pixel;
	VisualID visualid;
	XID killid;
} XStandardColormap;
</pre><p>


The colormap member is the colormap created by the
<a class="xref" href="#XCreateColormap"><code class="function">XCreateColormap</code></a>
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.
</p><p>

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.
</p><p>

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 
<a class="xref" href="#XAllocColorPlanes"><code class="function">XAllocColorPlanes</code></a>
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:
</p><p>

</p><pre class="literallayout">


(r * red_mult + g * green_mult + b * blue_mult + base_pixel) &amp; 0xFFFFFFFF
</pre><p>
</p><p>

For 
<span class="symbol">GrayScale</span>
colormaps, 
only the colormap, red_max, red_mult, 
and base_pixel members are defined. 
The other members are ignored.  
To compute a 
<span class="symbol">GrayScale</span>
pixel value, use the following expression:
</p><p>

</p><pre class="literallayout">


(gray * red_mult + base_pixel) &amp; 0xFFFFFFFF
</pre><p>
</p><p>

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.
</p><p>

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
<a class="xref" href="#XKillClient"><code class="function">XKillClient</code></a>
function on the indicated resource.
(Note that this method is necessary for allocating out of an existing colormap.)
</p><p>

The properties containing the 
<span class="structname">XStandardColormap</span>
information have 
the type RGB_COLOR_MAP.
</p><p>

The remainder of this section discusses standard colormap properties and atoms
as well as how to manipulate standard colormaps.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Standard_Colormap_Properties_and_Atoms"></a>Standard Colormap Properties and Atoms</h3></div></div></div><p>

<a id="idp52666172" class="indexterm"></a>
<a id="idp52666548" class="indexterm"></a>
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
<code class="filename">&lt;X11/Xatom.h&gt;</code>
<a id="idp52667732" class="indexterm"></a>
<a id="idp52668532" class="indexterm"></a>
<a id="idp52669340" class="indexterm"></a>
header file contains the definitions for each of the following atoms,
which are prefixed with XA_.
</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">RGB_DEFAULT_MAP</span></p></td><td><p>
This atom names a property.
The value of the property is an array of
<span class="structname">XStandardColormap</span>
structures.
Each entry in the array describes an <acronym class="acronym">RGB</acronym> subset of the default color
map for the Visual specified by visual_id.
      </p><p>
Some applications only need a few <acronym class="acronym">RGB</acronym> 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.
      </p><p>
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.
      </p></td></tr><tr><td><p><span class="term">RGB_BEST_MAP</span></p></td><td><p>
This atom names a property.  The value of the property is an 
<span class="structname">XStandardColormap</span>.
      </p><p>
The property defines the best <acronym class="acronym">RGB</acronym> 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.
      </p><p>
For an 8-plane 
<span class="symbol">PseudoColor</span>
visual, 
RGB_BEST_MAP is likely to be a 3/3/2 allocation.  
For a 24-plane 
<span class="symbol">DirectColor</span>
visual, 
RGB_BEST_MAP is normally an 8/8/8 allocation.  
      </p></td></tr><tr><td><p><span class="term">RGB_RED_MAP,RGB_GREEN_MAP,RGB_BLUE_MAP</span></p></td><td><p>
These atoms name properties.
The value of each property is an
<span class="structname">XStandardColormap</span>.
      </p><p>
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.
      </p></td></tr><tr><td><p><span class="term">RGB_GRAY_MAP</span></p></td><td><p>
This atom names a property.
The value of the property is an 
<span class="structname">XStandardColormap</span>.
      </p><p>
The property describes the best 
<span class="symbol">GrayScale</span>
colormap available on the screen.  
As previously mentioned, 
only the colormap, red_max, red_mult, and base_pixel members of the
<span class="structname">XStandardColormap</span>
structure are used for 
<span class="symbol">GrayScale</span>
colormaps.
      </p></td></tr></tbody></table></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_and_Obtaining_Standard_Colormaps"></a>Setting and Obtaining Standard Colormaps</h3></div></div></div><p>

Xlib provides functions that you can use to set and obtain an
<span class="structname">XStandardColormap</span>
structure.

</p><p>

To set an
<span class="structname">XStandardColormap</span>
structure, use
<a class="xref" href="#XSetRGBColormaps"><code class="function">XSetRGBColormaps</code></a>.
</p><a id="idp52682004" class="indexterm"></a><div class="funcsynopsis"><a id="XSetRGBColormaps"></a><p><code class="funcdef">void <strong class="fsfunc">XSetRGBColormaps</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XStandardColormap<var class="pdparam"> *std_colormap</var>, int<var class="pdparam"> count</var>, Atom<var class="pdparam"> property</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>std_colormap</em></span>
    </span></p></td><td><p>
Specifies the
<span class="structname">XStandardColormap</span>
structure to be used.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count</em></span>
    </span></p></td><td><p>
Specifies the number of colormaps.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>property</em></span>
    </span></p></td><td><p>
Specifies the property name.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XSetRGBColormaps"><code class="function">XSetRGBColormaps</code></a>
function replaces the <acronym class="acronym">RGB</acronym> colormap definition in the specified property 
on the named window.
If the property does not already exist,
<a class="xref" href="#XSetRGBColormaps"><code class="function">XSetRGBColormaps</code></a>
sets the <acronym class="acronym">RGB</acronym> 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 <acronym class="acronym">ICCCM</acronym>
restriction that only RGB_DEFAULT_MAP contain more than one definition.
</p><p>

The
<a class="xref" href="#XSetRGBColormaps"><code class="function">XSetRGBColormaps</code></a>
function usually is only used by window or session managers.
To create a standard colormap, 
follow this procedure:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Open a new connection to the same server.
    </p></li><li class="listitem"><p>
Grab the server.
    </p></li><li class="listitem"><p>
See if the property is on the property list of the root window for the screen.
    </p></li><li class="listitem"><p>
If the desired property is not present:

    </p></li><li class="listitem"><p>
Create a colormap (unless you are using the default colormap of the screen).
    </p></li><li class="listitem"><p>
Determine the color characteristics of the visual.
    </p></li><li class="listitem"><p>
Allocate cells in the colormap (or create it with
<span class="symbol">AllocAll</span>).
    </p></li><li class="listitem"><p>
Call 
<a class="xref" href="#XStoreColors"><code class="function">XStoreColors</code></a>
to store appropriate color values in the colormap.
    </p></li><li class="listitem"><p>
Fill in the descriptive members in the 
<span class="structname">XStandardColormap</span>
structure.
    </p></li><li class="listitem"><p>
Attach the property to the root window.
    </p></li><li class="listitem"><p>
Use
<a class="xref" href="#XSetCloseDownMode"></a>
to make the resource permanent.

    </p></li><li class="listitem"><p>
Ungrab the server.
    </p></li></ul></div><p>

<a class="xref" href="#XSetRGBColormaps"><code class="function">XSetRGBColormaps</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadAtom</span>,
and
<span class="errorname">BadWindow</span>
errors.

</p><p>

To obtain the 
<span class="structname">XStandardColormap</span>
structure associated with the specified property, use
<a class="xref" href="#XGetRGBColormaps"><code class="function">XGetRGBColormaps</code></a>.
</p><a id="idp52703900" class="indexterm"></a><div class="funcsynopsis"><a id="XGetRGBColormaps"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetRGBColormaps</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XStandardColormap<var class="pdparam"> **std_colormap_return</var>, int<var class="pdparam"> *count_return</var>, Atom<var class="pdparam"> property</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>std_colormap_return</em></span>
    </span></p></td><td><p>
Returns the
<span class="structname">XStandardColormap</span>
structure.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>count_return</em></span>
    </span></p></td><td><p>
Returns the number of colormaps.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>property</em></span>
    </span></p></td><td><p>
Specifies the property name.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XGetRGBColormaps"><code class="function">XGetRGBColormaps</code></a>
function returns the <acronym class="acronym">RGB</acronym> 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,
<a class="xref" href="#XGetRGBColormaps"><code class="function">XGetRGBColormaps</code></a>
allocates and fills in space for the returned colormaps
and returns a nonzero status.
If the visualid is not present, 
<a class="xref" href="#XGetRGBColormaps"><code class="function">XGetRGBColormaps</code></a>
assumes the default visual for the screen on which the window is located; 
if the killid is not present, 
<span class="symbol">None</span>
is assumed, which indicates that the resources cannot be released.
Otherwise, 
none of the fields are set, and 
<a class="xref" href="#XGetRGBColormaps"><code class="function">XGetRGBColormaps</code></a>
returns a zero status.
Note that it is the caller's responsibility to honor the <acronym class="acronym">ICCCM</acronym>
restriction that only RGB_DEFAULT_MAP contain more than one definition.
</p><p>

<a class="xref" href="#XGetRGBColormaps"><code class="function">XGetRGBColormaps</code></a>
can generate
<span class="errorname">BadAtom</span>
and
<span class="errorname">BadWindow</span>
errors.


</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Resource_Manager_Functions"></a>Chapter 15. Resource Manager Functions</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Resource_File_Syntax">Resource File Syntax</a></span></dt><dt><span class="sect1"><a href="#Resource_Manager_Matching_Rules">Resource Manager Matching Rules</a></span></dt><dt><span class="sect1"><a href="#Quarks">Quarks</a></span></dt><dt><span class="sect1"><a href="#Creating_and_Storing_Databases">Creating and Storing Databases</a></span></dt><dt><span class="sect1"><a href="#Merging_Resource_Databases">Merging Resource Databases</a></span></dt><dt><span class="sect1"><a href="#Looking_Up_Resources">Looking Up Resources</a></span></dt><dt><span class="sect1"><a href="#Storing_into_a_Resource_Database">Storing into a Resource Database</a></span></dt><dt><span class="sect1"><a href="#Enumerating_Database_Entries">Enumerating Database Entries</a></span></dt><dt><span class="sect1"><a href="#Parsing_Command_Line_Options">Parsing Command Line Options</a></span></dt></dl></div><p>




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.
</p><p>

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.
</p><p>

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.
</p><p>

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.
</p><p>

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.
</p><p>

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.
</p><p>

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".
</p><p>

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.
</p><p>

The definitions for the resource manager are contained in
<code class="filename">&lt;X11/Xresource.h&gt;</code>.
<a id="idp49690356" class="indexterm"></a>
<a id="idp49691204" class="indexterm"></a>
<a id="idp49692116" class="indexterm"></a>
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Resource_File_Syntax"></a>Resource File Syntax</h2></div></div></div><p>

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:
</p><p>


</p><pre class="literallayout">


ResourceLine     =     Comment | IncludeFile | ResourceSpec | &lt;empty line&gt;
Comment     =     "!" {&lt;any character except null or newline&gt;}
IncludeFile     =     "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace
FileName     =     &lt;valid filename for operating system&gt;
ResourceSpec     =     WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value
ResourceName     =     [Binding] {Component Binding} ComponentName
Binding     =     "." | "*"
WhiteSpace     =     {&lt;space&gt; | &lt;horizontal tab&gt;}
Component     =     "?" | ComponentName
ComponentName     =     NameChar {NameChar}
NameChar     =     "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-"
Value     =     {&lt;any character except null or unescaped newline&gt;}
</pre><p>

</p><p>

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.
</p><p>

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).
</p><p>

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.
</p><p>

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.
</p><p>

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 "\\<span class="emphasis"><em>space</em></span>" (backslash followed by space)
is recognized and replaced by a space character,
and the two-character sequence "\\<span class="emphasis"><em>tab</em></span>"
(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 "\\<span class="emphasis"><em>newline</em></span>"
(backslash followed by newline) is
recognized and removed from the value.
To allow a Value to contain arbitrary character codes,
the four-character sequence "\\<span class="emphasis"><em>nnn</em></span>",
where each <span class="emphasis"><em>n</em></span> 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 "\newline" is recognized
and replaced with a single backslash.
</p><p>

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:
</p><pre class="literallayout">
magic.values: \\000\
z\n
</pre><p>
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Resource_Manager_Matching_Rules"></a>Resource Manager Matching Rules</h2></div></div></div><p>

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.
</p><p>

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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
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).
    </p></li><li class="listitem"><p>
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 "?".
    </p></li><li class="listitem"><p>
An entry preceded by a tight binding takes precedence over entries
preceded by a loose binding.
    </p></li></ul></div><p>

To illustrate these rules,
consider the following resource database entries:
</p><pre class="literallayout">


xmh*Paned*activeForeground:     red     <span class="emphasis"><em>(entry A)</em></span>
*incorporate.Foreground:     blue     <span class="emphasis"><em>(entry B)</em></span>
xmh.toc*Command*activeForeground:     green     <span class="emphasis"><em>(entry C)</em></span>
xmh.toc*?.Foreground:     white     <span class="emphasis"><em>(entry D)</em></span>
xmh.toc*Command.activeForeground:     black     <span class="emphasis"><em>(entry E)</em></span>
</pre><p>
</p><p>

Consider a query for the resource:
</p><p>

</p><pre class="literallayout">


xmh.toc.messagefunctions.incorporate.activeForeground     <span class="emphasis"><em>(name)</em></span>
Xmh.Paned.Box.Command.Foreground     <span class="emphasis"><em>(class)</em></span>
</pre><p>
</p><p>

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.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Quarks"></a>Quarks</h2></div></div></div><p>

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 
<span class="type">XrmQuark</span>.
On some occasions,
you may want to allocate a quark that has no string equivalent.
</p><p>

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.
</p><p>


To allocate a new quark, use
<code class="function">XrmUniqueQuark</code>.
</p><a id="idp48492716" class="indexterm"></a><p>XrmQuark XrmUniqueQuark()</p><p>


The
<code class="function">XrmUniqueQuark</code>
function allocates a quark that is guaranteed not to represent any string that
is known to the resource manager.
</p><p>


Each name, class, and representation type is typedef'd as an
<span class="type">XrmQuark</span>.
</p><p>


</p><pre class="literallayout">
typedef int XrmQuark, *XrmQuarkList;
typedef XrmQuark XrmName;
typedef XrmQuark XrmClass;
typedef XrmQuark XrmRepresentation;
#define NULLQUARK ((XrmQuark) 0)
</pre><p>
</p><p>


Lists are represented as null-terminated arrays of quarks.
The size of the array must be large enough for the number of components used.
</p><p>


</p><pre class="literallayout">
typedef XrmQuarkList XrmNameList;
typedef XrmQuarkList XrmClassList;
</pre><p>
</p><p>



To convert a string to a quark, use
<a class="xref" href="#XrmStringToQuark"><code class="function">XrmStringToQuark</code></a>
or
<code class="function">XrmPermStringToQuark</code>.
</p><pre class="literallayout">
#define XrmStringToName(string) XrmStringToQuark(string)
#define XrmStringToClass(string) XrmStringToQuark(string)
#define XrmStringToRepresentation(string) XrmStringToQuark(string)
</pre><a id="idp48597348" class="indexterm"></a><a id="idp48597780" class="indexterm"></a><div class="funcsynopsis"><a id="XrmStringToQuark"></a><p><code class="funcdef">XrmQuark <strong class="fsfunc">XrmStringToQuark</strong>(</code>char<var class="pdparam"> *string</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the string for which a quark(Ql is to be allocated.
    </p></td></tr></tbody></table></div><p>


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
<a class="xref" href="#XrmStringToQuark"><code class="function">XrmStringToQuark</code></a>
need not be permanently allocated storage.
<code class="function">XrmPermStringToQuark</code>
is just like
<a class="xref" href="#XrmStringToQuark"><code class="function">XrmStringToQuark</code></a>,
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
<a class="xref" href="#XrmQuarkToString"><code class="function">XrmQuarkToString</code></a>.
</p><p>

For any given quark, if
<a class="xref" href="#XrmStringToQuark"><code class="function">XrmStringToQuark</code></a>
returns a non-NULL value,
all future calls will return the same value (identical address).
</p><p>


To convert a quark to a string, use 
<a class="xref" href="#XrmQuarkToString"><code class="function">XrmQuarkToString</code></a>.
</p><pre class="literallayout">
#define XrmNameToString(name)  XrmQuarkToString(name)
#define XrmClassToString(class)  XrmQuarkToString(name)
#define XrmRepresentationToString(type)  XrmQuarkToString(type)
</pre><a id="idp49549932" class="indexterm"></a><div class="funcsynopsis"><a id="XrmQuarkToString"></a><p><code class="funcdef">char *<strong class="fsfunc">XrmQuarkToString</strong>(</code>XrmQuark<var class="pdparam"> quark</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>quark</em></span>
    </span></p></td><td><p>
Specifies the quark for which the equivalent string is desired.
    </p></td></tr></tbody></table></div><p>
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,
<a class="xref" href="#XrmQuarkToString"><code class="function">XrmQuarkToString</code></a>
returns NULL.
For any given quark, if
<a class="xref" href="#XrmQuarkToString"><code class="function">XrmQuarkToString</code></a>
returns a non-NULL value,
all future calls will return the same value (identical address).
</p><p>


To convert a string with one or more components to a quark list, use
<a class="xref" href="#XrmStringToQuarkList"><code class="function">XrmStringToQuarkList</code></a>.
</p><pre class="literallayout">
#define XrmStringToNameList(str,name)  XrmStringToQuarkList((str), (name))
#define XrmStringToClassList(str,class)  XrmStringToQuarkList((str), (class))
</pre><a id="idp49557188" class="indexterm"></a><div class="funcsynopsis"><a id="XrmStringToQuarkList"></a><p><code class="funcdef">void <strong class="fsfunc">XrmStringToQuarkList</strong>(</code>char<var class="pdparam"> *string</var>, XrmQuarkList<var class="pdparam"> quarks_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the string for which a quark list is to be allocated.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>quarks_return</em></span>
    </span></p></td><td><p>
Returns the list of quarks.
The caller must allocate sufficient space for the quarks list before calling 
<a class="xref" href="#XrmStringToQuarkList"><code class="function">XrmStringToQuarkList</code></a>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XrmStringToQuarkList"><code class="function">XrmStringToQuarkList</code></a>
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 <a class="link" href="#Resource_File_Syntax" title="Resource File Syntax">section 15.1</a>).
If the string is not in the Host Portable Character Encoding,
the conversion is implementation-dependent.
</p><p>

A binding list is a list of type
<span class="type">XrmBindingList</span>
and indicates if components of name or class lists are bound tightly or loosely
(that is, if wildcarding of intermediate components is specified).
</p><p>

</p><pre class="literallayout">
typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList;
</pre><p>
</p><p>

<code class="constant">XrmBindTightly</code>
indicates that a period separates the components, and
<code class="constant">XrmBindLoosely</code>
indicates that an asterisk separates the components.
</p><p>


To convert a string with one or more components to a binding list
and a quark list, use
<a class="xref" href="#XrmStringToBindingQuarkList"><code class="function">XrmStringToBindingQuarkList</code></a>.
</p><a id="idp49485332" class="indexterm"></a><div class="funcsynopsis"><a id="XrmStringToBindingQuarkList"></a><p><code class="funcdef"><strong class="fsfunc">XrmStringToBindingQuarkList</strong>(</code>char<var class="pdparam"> *string</var>, XrmBindingList<var class="pdparam"> bindings_return</var>, XrmQuarkList<var class="pdparam"> quarks_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the string for which a quark list is to be allocated.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>bindings_return</em></span>
    </span></p></td><td><p>
Returns the binding list.
The caller must allocate sufficient space for the binding list before calling 
<a class="xref" href="#XrmStringToBindingQuarkList"><code class="function">XrmStringToBindingQuarkList</code></a>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>quarks_return</em></span>
    </span></p></td><td><p>
Returns the list of quarks.
The caller must allocate sufficient space for the quarks list before calling 
<a class="xref" href="#XrmStringToBindingQuarkList"><code class="function">XrmStringToBindingQuarkList</code></a>.
    </p></td></tr></tbody></table></div><p>


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 <a class="link" href="#Resource_File_Syntax" title="Resource File Syntax">section 15.1</a>).
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:
</p><p>

</p><pre class="literallayout">


quarks:       a         b         c
bindings:     loose     tight     loose
</pre><p>
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Creating_and_Storing_Databases"></a>Creating and Storing Databases</h2></div></div></div><p>

<a id="idp49670068" class="indexterm"></a>
A resource database is an opaque type,
<span class="type">XrmDatabase</span>.
Each database value is stored in an
<span class="type">XrmValue</span>
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
<span class="type">XrmValue</span>
structure is defined as:
</p><p>

<a id="idp49614372" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     unsigned int size;
     XPointer addr;
} XrmValue, *XrmValuePtr;
</pre><p>
</p><p>



To initialize the resource manager, use
<a class="xref" href="#XrmInitialize"><code class="function">XrmInitialize</code></a>.
<a id="idp49617044" class="indexterm"></a>

</p><div class="funcsynopsis"><a id="XrmInitialize"></a><p><code class="funcdef">void <strong class="fsfunc">XrmInitialize</strong>(</code>void<var class="pdparam"> XrmInitialize(\|)</var><code>)</code>;</p></div><p>

</p><p>


To retrieve a database from disk, use
<a class="xref" href="#XrmGetFileDatabase"><code class="function">XrmGetFileDatabase</code></a>.
</p><a id="idp49620524" class="indexterm"></a><div class="funcsynopsis"><a id="XrmGetFileDatabase"></a><p><code class="funcdef">XrmDatabase <strong class="fsfunc">XrmGetFileDatabase</strong>(</code>char<var class="pdparam"> *filename</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>filename</em></span>
    </span></p></td><td><p>
Specifies the resource database file name.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XrmGetFileDatabase"><code class="function">XrmGetFileDatabase</code></a>
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 <a class="link" href="#Resource_File_Syntax" title="Resource File Syntax">section 15.1</a>);
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,
<a class="xref" href="#XrmGetFileDatabase"><code class="function">XrmGetFileDatabase</code></a>
returns NULL.
</p><p>


To store a copy of a database to disk, use
<a class="xref" href="#XrmPutFileDatabase"><code class="function">XrmPutFileDatabase</code></a>.
</p><a id="idp48653444" class="indexterm"></a><div class="funcsynopsis"><a id="XrmPutFileDatabase"></a><p><code class="funcdef">void <strong class="fsfunc">XrmPutFileDatabase</strong>(</code>XrmDatabase<var class="pdparam"> database</var>, char<var class="pdparam"> *stored_db</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>database</em></span>
    </span></p></td><td><p>
Specifies the database that is to be used.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>stored_db</em></span>
    </span></p></td><td><p>
Specifies the file name for the stored database.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XrmPutFileDatabase"><code class="function">XrmPutFileDatabase</code></a>
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 <a class="link" href="#Resource_File_Syntax" title="Resource File Syntax">section 15.1</a>).
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.
</p><p>


To obtain a pointer to the screen-independent resources of a display, use
<a class="xref" href="#XResourceManagerString"><code class="function">XResourceManagerString</code></a>.
</p><a id="idp48662044" class="indexterm"></a><div class="funcsynopsis"><a id="XResourceManagerString"></a><p><code class="funcdef">char *<strong class="fsfunc">XResourceManagerString</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XResourceManagerString"><code class="function">XResourceManagerString</code></a>
function returns the RESOURCE_MANAGER property from the server's root
window of screen zero, which was returned when the connection was opened using
<a class="xref" href="#XOpenDisplay"><code class="function">XOpenDisplay</code></a>.
The property is converted from type STRING to the current locale.
The conversion is identical to that produced by 
<a class="xref" href="#XmbTextPropertyToTextList"><code class="function">XmbTextPropertyToTextList</code></a>
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
<a class="xref" href="#XrmGetStringDatabase"><code class="function">XrmGetStringDatabase</code></a>.
If no property exists, NULL is returned.
</p><p>


To obtain a pointer to the screen-specific resources of a screen, use
<a class="xref" href="#XScreenResourceString"><code class="function">XScreenResourceString</code></a>.
</p><a id="idp49677964" class="indexterm"></a><div class="funcsynopsis"><a id="XScreenResourceString"></a><p><code class="funcdef">char *<strong class="fsfunc">XScreenResourceString</strong>(</code>Screen<var class="pdparam"> *screen</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the screen.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XScreenResourceString"><code class="function">XScreenResourceString</code></a>
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 
<a class="xref" href="#XmbTextPropertyToTextList"><code class="function">XmbTextPropertyToTextList</code></a>
for a single element STRING property.
The property value must be in a format that is acceptable to
<a class="xref" href="#XrmGetStringDatabase"><code class="function">XrmGetStringDatabase</code></a>.
If no property exists, NULL is returned.
The caller is responsible for freeing the returned string by using
<a class="xref" href="#XFree"></a>.
</p><p>


To create a database from a string, use
<a class="xref" href="#XrmGetStringDatabase"><code class="function">XrmGetStringDatabase</code></a>.
</p><a id="idp48672116" class="indexterm"></a><div class="funcsynopsis"><a id="XrmGetStringDatabase"></a><p><code class="funcdef">XrmDatabase <strong class="fsfunc">XrmGetStringDatabase</strong>(</code>char<var class="pdparam"> *data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>data</em></span>
    </span></p></td><td><p>
Specifies the database contents using a string.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XrmGetStringDatabase"><code class="function">XrmGetStringDatabase</code></a>
function creates a new database and stores the resources specified
in the specified null-terminated string.
<a class="xref" href="#XrmGetStringDatabase"><code class="function">XrmGetStringDatabase</code></a>
is similar to
<a class="xref" href="#XrmGetFileDatabase"><code class="function">XrmGetFileDatabase</code></a>
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 <a class="link" href="#Resource_File_Syntax" title="Resource File Syntax">section 15.1</a>)
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.
</p><p>


To obtain the locale name of a database, use
<a class="xref" href="#XrmLocaleOfDatabase"><code class="function">XrmLocaleOfDatabase</code></a>.
</p><a id="idp48679580" class="indexterm"></a><div class="funcsynopsis"><a id="XrmLocaleOfDatabase"></a><p><code class="funcdef">char *<strong class="fsfunc">XrmLocaleOfDatabase</strong>(</code>XrmDatabase<var class="pdparam"> database</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>database</em></span>
    </span></p></td><td><p>
Specifies the resource database.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XrmLocaleOfDatabase"><code class="function">XrmLocaleOfDatabase</code></a>
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.
</p><p>


To destroy a resource database and free its allocated memory, use
<a class="xref" href="#XrmDestroyDatabase"><code class="function">XrmDestroyDatabase</code></a>.
</p><a id="idp48685812" class="indexterm"></a><div class="funcsynopsis"><a id="XrmDestroyDatabase"></a><p><code class="funcdef">void <strong class="fsfunc">XrmDestroyDatabase</strong>(</code>XrmDatabase<var class="pdparam"> database</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>database</em></span>
    </span></p></td><td><p>
Specifies the resource database.
    </p></td></tr></tbody></table></div><p>


If database is NULL,
<a class="xref" href="#XrmDestroyDatabase"><code class="function">XrmDestroyDatabase</code></a>
returns immediately.
</p><p>


To associate a resource database with a display, use
<a class="xref" href="#XrmSetDatabase"><code class="function">XrmSetDatabase</code></a>.
</p><a id="idp51089620" class="indexterm"></a><div class="funcsynopsis"><a id="XrmSetDatabase"></a><p><code class="funcdef">void <strong class="fsfunc">XrmSetDatabase</strong>(</code>Display<var class="pdparam"> *display</var>, XrmDatabase<var class="pdparam"> database</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>database</em></span>
    </span></p></td><td><p>
Specifies the resource database.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XrmSetDatabase"><code class="function">XrmSetDatabase</code></a>
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.
</p><p>


To get the resource database associated with a display, use
<a class="xref" href="#XrmGetDatabase"><code class="function">XrmGetDatabase</code></a>.
</p><a id="idp51097588" class="indexterm"></a><div class="funcsynopsis"><a id="XrmGetDatabase"></a><p><code class="funcdef">XrmDatabase <strong class="fsfunc">XrmGetDatabase</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XrmGetDatabase"><code class="function">XrmGetDatabase</code></a>
function returns the database associated with the specified display.
It returns NULL if a database has not yet been set.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Merging_Resource_Databases"></a>Merging Resource Databases</h2></div></div></div><p>

To merge the contents of a resource file into a database, use
<a class="xref" href="#XrmCombineFileDatabase"><code class="function">XrmCombineFileDatabase</code></a>.
</p><a id="idp48641756" class="indexterm"></a><div class="funcsynopsis"><a id="XrmCombineFileDatabase"></a><p><code class="funcdef">Status <strong class="fsfunc">XrmCombineFileDatabase</strong>(</code>char<var class="pdparam"> *filename</var>, XrmDatabase<var class="pdparam"> *target_db</var>, Bool<var class="pdparam"> override</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>filename</em></span>
    </span></p></td><td><p>
Specifies the resource database file name.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>target_db</em></span>
    </span></p></td><td><p>
Specifies the resource database into which the source 
database is to be merged.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>override</em></span>
    </span></p></td><td><p>
Specifies whether source entries override target ones.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XrmCombineFileDatabase"><code class="function">XrmCombineFileDatabase</code></a>
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
<span class="symbol">True</span>;
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,
<a class="xref" href="#XrmCombineFileDatabase"><code class="function">XrmCombineFileDatabase</code></a>
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.
</p><p>


To merge the contents of one database into another database, use
<a class="xref" href="#XrmCombineDatabase"><code class="function">XrmCombineDatabase</code></a>.
</p><a id="idp49567860" class="indexterm"></a><div class="funcsynopsis"><a id="XrmCombineDatabase"></a><p><code class="funcdef">void <strong class="fsfunc">XrmCombineDatabase</strong>(</code>XrmDatabasesource_db,<var class="pdparam"> *target_db</var>, Bool<var class="pdparam"> override</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>source_db</em></span>
    </span></p></td><td><p>
Specifies the resource database that is to be merged into the target database.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>target_db</em></span>
    </span></p></td><td><p>
Specifies the resource database into which the source 
database is to be merged.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>override</em></span>
    </span></p></td><td><p>
Specifies whether source entries override target ones.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XrmCombineDatabase"><code class="function">XrmCombineDatabase</code></a>
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
<span class="symbol">True</span>;
otherwise, the entry in source_db is discarded.
If target_db contains NULL,
<a class="xref" href="#XrmCombineDatabase"><code class="function">XrmCombineDatabase</code></a>
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.
</p><p>


To merge the contents of one database into another database with override
semantics, use
<a class="xref" href="#XrmMergeDatabases"><code class="function">XrmMergeDatabases</code></a>.
</p><a id="idp49578196" class="indexterm"></a><div class="funcsynopsis"><a id="XrmMergeDatabases"></a><p><code class="funcdef">void <strong class="fsfunc">XrmMergeDatabases</strong>(</code>XrmDatabasesource_db,<var class="pdparam"> *target_db</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>source_db</em></span>
    </span></p></td><td><p>
Specifies the resource database that is to be merged into the target database.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>target_db</em></span>
    </span></p></td><td><p>
Specifies the resource database into which the source 
database is to be merged.
    </p></td></tr></tbody></table></div><p>


Calling the
<a class="xref" href="#XrmMergeDatabases"><code class="function">XrmMergeDatabases</code></a>
function is equivalent to calling the
<a class="xref" href="#XrmCombineDatabase"><code class="function">XrmCombineDatabase</code></a>
function with an override argument of
<span class="symbol">True</span>.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Looking_Up_Resources"></a>Looking Up Resources</h2></div></div></div><p>

To retrieve a resource from a resource database, use
<a class="xref" href="#XrmGetResource"><code class="function">XrmGetResource</code></a>,
<a class="xref" href="#XrmQGetResource"><code class="function">XrmQGetResource</code></a>,
or
<a class="xref" href="#XrmQGetSearchResource"><code class="function">XrmQGetSearchResource</code></a>.
</p><a id="idp49496076" class="indexterm"></a><div class="funcsynopsis"><a id="XrmGetResource"></a><p><code class="funcdef">Bool <strong class="fsfunc">XrmGetResource</strong>(</code>XrmDatabase<var class="pdparam"> database</var>, char<var class="pdparam"> *str_name</var>, char<var class="pdparam"> *str_class</var>, char<var class="pdparam"> **str_type_return</var>, XrmValue<var class="pdparam"> *value_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>database</em></span>
    </span></p></td><td><p>
Specifies the database that is to be used.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>str_name</em></span>
    </span></p></td><td><p>
Specifies the fully qualified name of the value being retrieved (as a string).
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>str_class</em></span>
    </span></p></td><td><p>
Specifies the fully qualified class of the value being retrieved (as a string).
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>str_type_return</em></span>
    </span></p></td><td><p>
Returns the representation type of the destination (as a string).
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>value_return</em></span>
    </span></p></td><td><p>
Returns the value in the database.
    </p></td></tr></tbody></table></div><a id="idp49507308" class="indexterm"></a><div class="funcsynopsis"><a id="XrmQGetResource"></a><p><code class="funcdef">Bool <strong class="fsfunc">XrmQGetResource</strong>(</code>XrmDatabase<var class="pdparam"> database</var>, XrmNameList<var class="pdparam"> quark_name</var>, XrmClassList<var class="pdparam"> quark_class</var>, XrmRepresentation<var class="pdparam"> *quark_type_return</var>, XrmValue<var class="pdparam"> *value_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>database</em></span>
    </span></p></td><td><p>
Specifies the database that is to be used.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>quark_name</em></span>
    </span></p></td><td><p>
Specifies the fully qualified name of the value being retrieved (as a quark).
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>quark_class</em></span>
    </span></p></td><td><p>
Specifies the fully qualified class of the value being retrieved (as a quark).
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>quark_type_return</em></span>
    </span></p></td><td><p>
Returns the representation type of the destination (as a quark).
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>value_return</em></span>
    </span></p></td><td><p>
Returns the value in the database.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XrmGetResource"><code class="function">XrmGetResource</code></a>
and 
<a class="xref" href="#XrmQGetResource"><code class="function">XrmQGetResource</code></a>
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.
</p><p>

The database only frees or overwrites entries on
<a class="xref" href="#XrmPutResource"><code class="function">XrmPutResource</code></a>,
<a class="xref" href="#XrmQPutResource"><code class="function">XrmQPutResource</code></a>,
or 
<a class="xref" href="#XrmMergeDatabases"><code class="function">XrmMergeDatabases</code></a>.
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
<a class="xref" href="#XrmGetResource"><code class="function">XrmGetResource</code></a>
and
<a class="xref" href="#XrmQGetResource"><code class="function">XrmQGetResource</code></a>
return 
<span class="symbol">True</span>;
otherwise, they return 
<span class="symbol">False</span>.
</p><p>


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 
<a class="xref" href="#XrmGetResource"><code class="function">XrmGetResource</code></a>
function is at worst a
2<sup><span class="emphasis"><em>n</em></span></sup> algorithm,
where <span class="emphasis"><em>n</em></span> 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.
</p><p>


To obtain a list of database levels, use
<code class="function">XrmQGetSearchList</code>.
</p><a id="idp51112380" class="indexterm"></a><div class="funcsynopsis"><a id="XrmQGetSearchResource"></a><p><code class="funcdef">Bool <strong class="fsfunc">XrmQGetSearchResource</strong>(</code>XrmDatabase<var class="pdparam"> database</var>, XrmNameList<var class="pdparam"> names</var>, XrmClassList<var class="pdparam"> classes</var>, XrmSearchList<var class="pdparam"> list_return</var>, int<var class="pdparam"> list_length</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>database</em></span>
    </span></p></td><td><p>
Specifies the database that is to be used.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>names</em></span>
    </span></p></td><td><p>
Specifies a list of resource names.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>classes</em></span>
    </span></p></td><td><p>
Specifies a list of resource classes.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>list_return</em></span>
    </span></p></td><td><p>
Returns a search list for further use.
The caller must allocate sufficient space for the list before calling 
<code class="function">XrmQGetSearchList</code>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>list_length</em></span>
    </span></p></td><td><p>
Specifies the number of entries (not the byte size) allocated for list_return.
    </p></td></tr></tbody></table></div><p>


The
<code class="function">XrmQGetSearchList</code>
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 
<a class="xref" href="#XrmGetResource"><code class="function">XrmGetResource</code></a>
for determining precedence.
If list_return was large enough for the search list,
<code class="function">XrmQGetSearchList</code>
returns 
<span class="symbol">True</span>;
otherwise, it returns
<span class="symbol">False</span>.
</p><p>

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
3<sup><span class="emphasis"><em>n</em></span></sup>,
where <span class="emphasis"><em>n</em></span> is the number of name or class
components in names or classes.
</p><p>

When using 
<code class="function">XrmQGetSearchList</code>
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 
<code class="function">XrmQGetSearchList</code>.
</p><p>


To search resource database levels for a given resource, use
<a class="xref" href="#XrmQGetSearchResource"><code class="function">XrmQGetSearchResource</code></a>.
</p><a id="idp51129996" class="indexterm"></a><div class="funcsynopsis"><a id="XrmQGetSearchResource_2"></a><p><code class="funcdef">Bool <strong class="fsfunc">XrmQGetSearchResource</strong>(</code>XrmSearchList<var class="pdparam"> list</var>, XrmName<var class="pdparam"> name</var>, XrmClass<var class="pdparam"> class</var>, XrmRepresentation<var class="pdparam"> *type_return</var>, XrmValue<var class="pdparam"> *value_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>list</em></span>
    </span></p></td><td><p>
Specifies the search list returned by
<code class="function">XrmQGetSearchList</code>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>name</em></span>
    </span></p></td><td><p>
Specifies the resource name.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>class</em></span>
    </span></p></td><td><p>
Specifies the resource class.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>type_return</em></span>
    </span></p></td><td><p>
Returns data representation type.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>value_return</em></span>
    </span></p></td><td><p>
Returns the value in the database.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XrmQGetSearchResource"><code class="function">XrmQGetSearchResource</code></a>
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.
<a class="xref" href="#XrmQGetSearchResource"><code class="function">XrmQGetSearchResource</code></a>
returns 
<span class="symbol">True</span>
if the resource was found;
otherwise, it returns
<span class="symbol">False</span>.
</p><p>

A call to 
<code class="function">XrmQGetSearchList</code>
with a name and class list containing all but the last component 
of a resource name followed by a call to 
<a class="xref" href="#XrmQGetSearchResource"><code class="function">XrmQGetSearchResource</code></a>
with the last component name and class returns the same database entry as 
<a class="xref" href="#XrmGetResource"><code class="function">XrmGetResource</code></a>
and 
<a class="xref" href="#XrmQGetResource"><code class="function">XrmQGetResource</code></a>
with the fully qualified name and class.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Storing_into_a_Resource_Database"></a>Storing into a Resource Database</h2></div></div></div><p>

To store resources into the database, use
<a class="xref" href="#XrmPutResource"><code class="function">XrmPutResource</code></a>
or
<a class="xref" href="#XrmQPutResource"><code class="function">XrmQPutResource</code></a>.
Both functions take a partial resource specification, a
representation type, and a value.
This value is copied into the specified database.
</p><a id="idp50476204" class="indexterm"></a><div class="funcsynopsis"><a id="XrmPutResource"></a><p><code class="funcdef">void <strong class="fsfunc">XrmPutResource</strong>(</code>XrmDatabase<var class="pdparam"> *database</var>, char<var class="pdparam"> *specifier</var>, char<var class="pdparam"> *type</var>, XrmValue<var class="pdparam"> *value</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>database</em></span>
    </span></p></td><td><p>
Specifies the resource database.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>specifier</em></span>
    </span></p></td><td><p>
Specifies a complete or partial specification of the resource.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>type</em></span>
    </span></p></td><td><p>
Specifies the type of the resource.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>value</em></span>
    </span></p></td><td><p>
Specifies the value of the resource, which is specified as a string.
    </p></td></tr></tbody></table></div><p>


If database contains NULL,
<a class="xref" href="#XrmPutResource"><code class="function">XrmPutResource</code></a>
creates a new database and returns a pointer to it.
<a class="xref" href="#XrmPutResource"><code class="function">XrmPutResource</code></a>
is a convenience function that calls
<a class="xref" href="#XrmStringToBindingQuarkList"><code class="function">XrmStringToBindingQuarkList</code></a>
followed by:
</p><p>

</p><pre class="literallayout">
XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), value)
</pre><p>
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.
</p><a id="idp50488876" class="indexterm"></a><div class="funcsynopsis"><a id="XrmQPutResource"></a><p><code class="funcdef">void <strong class="fsfunc">XrmQPutResource</strong>(</code>XrmDatabase<var class="pdparam"> *database</var>, XrmBindingList<var class="pdparam"> bindings</var>, XrmQuarkList<var class="pdparam"> quarks</var>, XrmRepresentation<var class="pdparam"> type</var>, XrmValue<var class="pdparam"> *value</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>database</em></span>
    </span></p></td><td><p>
Specifies the resource database.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>bindings</em></span>
    </span></p></td><td><p>
Specifies a list of bindings.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>quarks</em></span>
    </span></p></td><td><p>
Specifies the complete or partial name or the class list of the resource.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>type</em></span>
    </span></p></td><td><p>
Specifies the type of the resource.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>value</em></span>
    </span></p></td><td><p>
Specifies the value of the resource, which is specified as a string.
    </p></td></tr></tbody></table></div><p>


If database contains NULL,
<a class="xref" href="#XrmQPutResource"><code class="function">XrmQPutResource</code></a>
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.
</p><p>


To add a resource that is specified as a string, use
<a class="xref" href="#XrmPutStringResource"><code class="function">XrmPutStringResource</code></a>.
</p><a id="idp50502268" class="indexterm"></a><div class="funcsynopsis"><a id="XrmPutStringResource"></a><p><code class="funcdef">void <strong class="fsfunc">XrmPutStringResource</strong>(</code>XrmDatabase<var class="pdparam"> *database</var>, char<var class="pdparam"> *specifier</var>, char<var class="pdparam"> *value</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>database</em></span>
    </span></p></td><td><p>
Specifies the resource database.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>specifier</em></span>
    </span></p></td><td><p>
Specifies a complete or partial specification of the resource.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>value</em></span>
    </span></p></td><td><p>
Specifies the value of the resource, which is specified as a string.
    </p></td></tr></tbody></table></div><p>


If database contains NULL,
<a class="xref" href="#XrmPutStringResource"><code class="function">XrmPutStringResource</code></a>
creates a new database and returns a pointer to it.
<a class="xref" href="#XrmPutStringResource"><code class="function">XrmPutStringResource</code></a>
adds a resource with the specified value to the specified database.
<a class="xref" href="#XrmPutStringResource"><code class="function">XrmPutStringResource</code></a>
is a convenience function that first calls
<a class="xref" href="#XrmStringToBindingQuarkList"><code class="function">XrmStringToBindingQuarkList</code></a>
on the specifier and then calls
<a class="xref" href="#XrmQPutResource"><code class="function">XrmQPutResource</code></a>,
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.
</p><p>


To add a string resource using quarks as a specification, use
<a class="xref" href="#XrmQPutStringResource"><code class="function">XrmQPutStringResource</code></a>.
</p><a id="idp49441508" class="indexterm"></a><div class="funcsynopsis"><a id="XrmQPutStringResource"></a><p><code class="funcdef">void <strong class="fsfunc">XrmQPutStringResource</strong>(</code>XrmDatabase<var class="pdparam"> *database</var>, XrmBindingList<var class="pdparam"> bindings</var>, XrmQuarkList<var class="pdparam"> quarks</var>, char<var class="pdparam"> *value</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>database</em></span>
    </span></p></td><td><p>
Specifies the resource database.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>bindings</em></span>
    </span></p></td><td><p>
Specifies a list of bindings.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>quarks</em></span>
    </span></p></td><td><p>
Specifies the complete or partial name or the class list of the resource.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>value</em></span>
    </span></p></td><td><p>
Specifies the value of the resource, which is specified as a string.
    </p></td></tr></tbody></table></div><p>


If database contains NULL,
<a class="xref" href="#XrmQPutStringResource"><code class="function">XrmQPutStringResource</code></a>
creates a new database and returns a pointer to it.
<a class="xref" href="#XrmQPutStringResource"><code class="function">XrmQPutStringResource</code></a>
is a convenience routine that constructs an
<span class="type">XrmValue</span>
for the value string (by calling
<code class="function">strlen</code>
to compute the size) and
then calls
<a class="xref" href="#XrmQPutResource"><code class="function">XrmQPutResource</code></a>,
using a ``String'' representation type.
The value is stored in the database without modification.
</p><p>


To add a single resource entry that is specified as a string that contains
both a name and a value, use
<a class="xref" href="#XrmPutLineResource"><code class="function">XrmPutLineResource</code></a>.
</p><a id="idp49454404" class="indexterm"></a><div class="funcsynopsis"><a id="XrmPutLineResource"></a><p><code class="funcdef">void <strong class="fsfunc">XrmPutLineResource</strong>(</code>XrmDatabase<var class="pdparam"> *database</var>, char<var class="pdparam"> *line</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>database</em></span>
    </span></p></td><td><p>
Specifies the resource database.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>line</em></span>
    </span></p></td><td><p>
Specifies the resource name and value pair as a single string.
    </p></td></tr></tbody></table></div><p>


If database contains NULL,
<a class="xref" href="#XrmPutLineResource"><code class="function">XrmPutLineResource</code></a>
creates a new database and returns a pointer to it.
<a class="xref" href="#XrmPutLineResource"><code class="function">XrmPutLineResource</code></a>
adds a single resource entry to the specified database.
The line should be in valid ResourceLine format
(see <a class="link" href="#Resource_File_Syntax" title="Resource File Syntax">section 15.1</a>)
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
<em class="replaceable"><code>ResourceName</code></em>
is not in the Host Portable Character Encoding,
the result is implementation-dependent.
Note that comment lines are not stored.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Enumerating_Database_Entries"></a>Enumerating Database Entries</h2></div></div></div><p>

To enumerate the entries of a database, use
<a class="xref" href="#XrmEnumerateDatabase"><code class="function">XrmEnumerateDatabase</code></a>.
<a id="idp49464332" class="indexterm"></a>

</p><pre class="literallayout">
#define       XrmEnumAllLevels       0
#define       XrmEnumOneLevel        0
</pre><div class="funcsynopsis"><a id="XrmEnumerateDatabase"></a><p><code class="funcdef">Bool <strong class="fsfunc">XrmEnumerateDatabase</strong>(</code>XrmDatabase<var class="pdparam"> database</var>, XrmNameList<var class="pdparam"> name_prefix</var>, XrmClassList<var class="pdparam"> class_prefix</var>, int<var class="pdparam"> mode</var>, Bool<var class="pdparam"> (*proc)()</var>, XPointer<var class="pdparam"> arg</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>database</em></span>
    </span></p></td><td><p>
Specifies the resource database.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>name_prefix</em></span>
    </span></p></td><td><p>
Specifies the resource name prefix.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>class_prefix</em></span>
    </span></p></td><td><p>
Specifies the resource class prefix.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>mode</em></span>
    </span></p></td><td><p>
Specifies the number of levels to enumerate.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>proc</em></span>
    </span></p></td><td><p>
Specifies the procedure that is to be called for each matching entry.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>arg</em></span>
    </span></p></td><td><p>
Specifies the user-supplied argument that will be passed to the procedure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XrmEnumerateDatabase"><code class="function">XrmEnumerateDatabase</code></a>
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
<span class="symbol">XrmEnumOneLevel</span>,
a resource must match the given name/class prefix with
just a single name and class appended.  If mode is
<span class="symbol">XrmEnumAllLevels</span>,
the resource must match the given name/class prefix with one or more names and
classes appended.
If the procedure returns
<span class="symbol">True</span>,
the enumeration terminates and the function returns
<span class="symbol">True</span>.
If the procedure always returns
<span class="symbol">False</span>,
all matching resources are enumerated and the function returns
<span class="symbol">False</span>.
</p><p>

The procedure is called with the following arguments:
</p><p>


</p><pre class="literallayout">


(*<span class="emphasis"><em>proc</em></span>)(<span class="emphasis"><em>database</em></span>, <span class="emphasis"><em>bindings</em></span>, <span class="emphasis"><em>quarks</em></span>, <span class="emphasis"><em>type</em></span>, <span class="emphasis"><em>value</em></span>, <span class="emphasis"><em>arg</em></span>)
     XrmDatabase *<span class="emphasis"><em>database</em></span>;
     XrmBindingList <span class="emphasis"><em>bindings</em></span>;
     XrmQuarkList <span class="emphasis"><em>quarks</em></span>;
     XrmRepresentation *<span class="emphasis"><em>type</em></span>;
     XrmValue *<span class="emphasis"><em>value</em></span>;
     XPointer <span class="emphasis"><em>arg</em></span>;
</pre><p>

</p><p>

The bindings and quarks lists are terminated by
<span class="symbol">NULLQUARK</span>.
Note that pointers
to the database and type are passed, but these values should not be modified.
</p><p>

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.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Parsing_Command_Line_Options"></a>Parsing Command Line Options</h2></div></div></div><p>

The
<a class="xref" href="#XrmParseCommand"><code class="function">XrmParseCommand</code></a>
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.
</p><p>

<a id="idp51038652" class="indexterm"></a>

</p><pre class="literallayout">


typedef enum {
     XrmoptionNoArg,     /* Value is specified in XrmOptionDescRec.value */
     XrmoptionIsArg,     /* Value is the option string itself */
     XrmoptionStickyArg,     /* Value is characters immediately following option */
     XrmoptionSepArg,     /* Value is next argument in argv */
     XrmoptionResArg,     /* Resource and value in next argument in argv */
     XrmoptionSkipArg,     /* Ignore this option and the next argument in argv */
     XrmoptionSkipLine,     /* Ignore this option and the rest of argv */
     XrmoptionSkipNArgs     /* Ignore this option and the next
          \ \ \ XrmOptionDescRec.value arguments in argv */
} XrmOptionKind;
</pre><p>
</p><p>


Note that
<code class="constant">XrmoptionSkipArg</code>
is equivalent to 
<code class="constant">XrmoptionSkipNArgs</code>
with the
<span class="structname">XrmOptionDescRec</span>.<em class="structfield"><code>value</code></em>
field containing the value one.
Note also that the value zero for
<code class="constant">XrmoptionSkipNArgs</code>
indicates that only the option itself is to be skipped.
</p><p>

<a id="idp51042948" class="indexterm"></a>

</p><pre class="literallayout">


typedef struct {
     char *option;     /* Option specification string in argv              */
     char *specifier;     /* Binding and resource name (sans application name)    */
     XrmOptionKind argKind;     /* Which style of option it is         */
     XPointer value;     /* Value to provide if XrmoptionNoArg or 
          \ \ \ XrmoptionSkipNArgs   */
} XrmOptionDescRec, *XrmOptionDescList;
</pre><p>
</p><p>



To load a resource database from a C command line, use
<a class="xref" href="#XrmParseCommand"><code class="function">XrmParseCommand</code></a>.
</p><a id="idp51046036" class="indexterm"></a><div class="funcsynopsis"><a id="XrmParseCommand"></a><p><code class="funcdef">void <strong class="fsfunc">XrmParseCommand</strong>(</code>XrmDatabase<var class="pdparam"> *database</var>, XrmOptionDescList<var class="pdparam"> table</var>, int<var class="pdparam"> table_count</var>, char<var class="pdparam"> *name</var>, int<var class="pdparam"> *argc_in_out</var>, char<var class="pdparam"> **argv_in_out</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>database</em></span>
    </span></p></td><td><p>
Specifies the resource database.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>table</em></span>
    </span></p></td><td><p>
Specifies the table of command line arguments to be parsed.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>table_count</em></span>
    </span></p></td><td><p>
Specifies the number of entries in the table.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>name</em></span>
    </span></p></td><td><p>
Specifies the application name.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>argc_in_out</em></span>
    </span></p></td><td><p>
Specifies the number of arguments and returns the number of remaining arguments.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>argv_in_out</em></span>
    </span></p></td><td><p>
Specifies the command line arguments
and returns the remaining arguments.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XrmParseCommand"><code class="function">XrmParseCommand</code></a>
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,
<a class="xref" href="#XrmParseCommand"><code class="function">XrmParseCommand</code></a>
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.
</p><p>

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 
<code class="constant">XrmoptionNoArg</code>.
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.
</p><p>

The following provides a sample option table:
</p><p>

</p><pre class="literallayout">


static XrmOptionDescRec opTable[] = {
{"-background",     "*background",                 XrmoptionSepArg,    (XPointer) NULL},
{"-bd",             "*borderColor",                XrmoptionSepArg,    (XPointer) NULL},
{"-bg",             "*background",                 XrmoptionSepArg,    (XPointer) NULL},
{"-borderwidth",    "*TopLevelShell.borderWidth",  XrmoptionSepArg,    (XPointer) NULL},
{"-bordercolor",    "*borderColor",                XrmoptionSepArg,    (XPointer) NULL},
{"-bw",             "*TopLevelShell.borderWidth",  XrmoptionSepArg,    (XPointer) NULL},
{"-display",        ".display",                    XrmoptionSepArg,    (XPointer) NULL},
{"-fg",             "*foreground",                 XrmoptionSepArg,    (XPointer) NULL},
{"-fn",             "*font",                       XrmoptionSepArg,    (XPointer) NULL},
{"-font",           "*font",                       XrmoptionSepArg,    (XPointer) NULL},
{"-foreground",     "*foreground",                 XrmoptionSepArg,    (XPointer) NULL},
{"-geometry",       ".TopLevelShell.geometry",     XrmoptionSepArg,    (XPointer) NULL},
{"-iconic",         ".TopLevelShell.iconic",       XrmoptionNoArg,     (XPointer) "on"},
{"-name",           ".name",                       XrmoptionSepArg,    (XPointer) NULL},
{"-reverse",        "*reverseVideo",               XrmoptionNoArg,     (XPointer) "on"},
{"-rv",             "*reverseVideo",               XrmoptionNoArg,     (XPointer) "on"},
{"-synchronous",    "*synchronous",                XrmoptionNoArg,     (XPointer) "on"},
{"-title",          ".TopLevelShell.title",        XrmoptionSepArg,    (XPointer) NULL},
{"-xrm",            NULL,                          XrmoptionResArg,    (XPointer) NULL},
};
</pre><p>
</p><p>

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.
</p><p>

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.


</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Application_Utility_Functions"></a>Chapter 16. Application Utility Functions</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Using_Keyboard_Utility_Functions">Using Keyboard Utility Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#KeySym_Classification_Macros">KeySym Classification Macros</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Using_Latin_1_Keyboard_Event_Functions">Using Latin-1 Keyboard Event Functions</a></span></dt><dt><span class="sect1"><a href="#Allocating_Permanent_Storage">Allocating Permanent Storage</a></span></dt><dt><span class="sect1"><a href="#Parsing_the_Window_Geometry">Parsing the Window Geometry</a></span></dt><dt><span class="sect1"><a href="#Manipulating_Regions">Manipulating Regions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Creating_Copying_or_Destroying_Regions">Creating, Copying, or Destroying Regions</a></span></dt><dt><span class="sect2"><a href="#Moving_or_Shrinking_Regions">Moving or Shrinking Regions</a></span></dt><dt><span class="sect2"><a href="#Computing_with_Regions">Computing with Regions</a></span></dt><dt><span class="sect2"><a href="#Determining_if_Regions_Are_Empty_or_Equal">Determining if Regions Are Empty or Equal</a></span></dt><dt><span class="sect2"><a href="#Locating_a_Point_or_a_Rectangle_in_a_Region">Locating a Point or a Rectangle in a Region</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Using_Cut_Buffers">Using Cut Buffers</a></span></dt><dt><span class="sect1"><a href="#Determining_the_Appropriate_Visual_Type">Determining the Appropriate Visual Type</a></span></dt><dt><span class="sect1"><a href="#Manipulating_Images">Manipulating Images</a></span></dt><dt><span class="sect1"><a href="#Manipulating_Bitmaps">Manipulating Bitmaps</a></span></dt><dt><span class="sect1"><a href="#Using_the_Context_Manager">Using the Context Manager</a></span></dt></dl></div><p>




Once you have initialized the X system,
you can use the Xlib utility functions to:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Use keyboard utility functions
    </p></li><li class="listitem"><p>
Use Latin-1 keyboard event functions
    </p></li><li class="listitem"><p>
Allocate permanent storage
    </p></li><li class="listitem"><p>
Parse the window geometry
    </p></li><li class="listitem"><p>
Manipulate regions
    </p></li><li class="listitem"><p>
Use cut buffers
    </p></li><li class="listitem"><p>
Determine the appropriate visual type
    </p></li><li class="listitem"><p>
Manipulate images
    </p></li><li class="listitem"><p>
Manipulate bitmaps
    </p></li><li class="listitem"><p>
Use the context manager
    </p></li></ul></div><p>

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.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Using_Keyboard_Utility_Functions"></a>Using Keyboard Utility Functions</h2></div></div></div><p>

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.
</p><p>


To obtain a KeySym for the KeyCode of an event, use
<a class="xref" href="#XLookupKeysym"><code class="function">XLookupKeysym</code></a>.
</p><a id="idp51150324" class="indexterm"></a><div class="funcsynopsis"><a id="XLookupKeysym"></a><p><code class="funcdef">KeySym <strong class="fsfunc">XLookupKeysym</strong>(</code>XKeyEvent<var class="pdparam"> *key_event</var>, int<var class="pdparam"> index</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>key_event</em></span>
    </span></p></td><td><p>
Specifies the 
<span class="symbol">KeyPress</span>
or
<span class="symbol">KeyRelease</span>
event.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>index</em></span>
    </span></p></td><td><p>
Specifies the index into the KeySyms list for the event's KeyCode.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XLookupKeysym"><code class="function">XLookupKeysym</code></a>
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
<span class="type">XKeyPressedEvent</span>
or
<span class="type">XKeyReleasedEvent</span>
structure.
If no KeySym is defined for the KeyCode of the event,
<a class="xref" href="#XLookupKeysym"><code class="function">XLookupKeysym</code></a>
returns
<span class="symbol">NoSymbol</span>.
</p><p>


To obtain a KeySym for a specific KeyCode, use
<a class="xref" href="#XKeycodeToKeysym"><code class="function">XKeycodeToKeysym</code></a>.
</p><a id="idp45628220" class="indexterm"></a><div class="funcsynopsis"><a id="XKeycodeToKeysym"></a><p><code class="funcdef">KeySym <strong class="fsfunc">XKeycodeToKeysym</strong>(</code>Display<var class="pdparam"> *display</var>, KeyCode<var class="pdparam"> keycode</var>, int<var class="pdparam"> index</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>keycode</em></span>
    </span></p></td><td><p>
Specifies the KeyCode.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>index</em></span>
    </span></p></td><td><p>
Specifies the element of KeyCode vector.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XKeycodeToKeysym"><code class="function">XKeycodeToKeysym</code></a>
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,
<a class="xref" href="#XKeycodeToKeysym"><code class="function">XKeycodeToKeysym</code></a>
returns
<span class="symbol">NoSymbol</span>.
</p><p>


To obtain a KeyCode for a key having a specific KeySym, use
<a class="xref" href="#XKeysymToKeycode"><code class="function">XKeysymToKeycode</code></a>.
</p><a id="idp50459388" class="indexterm"></a><div class="funcsynopsis"><a id="XKeysymToKeycode"></a><p><code class="funcdef">KeyCode <strong class="fsfunc">XKeysymToKeycode</strong>(</code>Display<var class="pdparam"> *display</var>, KeySym<var class="pdparam"> keysym</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>keysym</em></span>
    </span></p></td><td><p>
Specifies the KeySym that is to be searched for.
    </p></td></tr></tbody></table></div><p>


If the specified KeySym is not defined for any KeyCode,
<a class="xref" href="#XKeysymToKeycode"><code class="function">XKeysymToKeycode</code></a>
returns zero.
</p><p>


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
<a class="xref" href="#XRefreshKeyboardMapping"><code class="function">XRefreshKeyboardMapping</code></a>.
</p><a id="idp49249868" class="indexterm"></a><div class="funcsynopsis"><a id="XRefreshKeyboardMapping"></a><p><code class="funcdef"><strong class="fsfunc">XRefreshKeyboardMapping</strong>(</code>XMappingEvent<var class="pdparam"> *event_map</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>event_map</em></span>
    </span></p></td><td><p>
Specifies the mapping event that is to be used.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XRefreshKeyboardMapping"><code class="function">XRefreshKeyboardMapping</code></a>
function refreshes the stored modifier and keymap information.
You usually call this function when a
<span class="symbol">MappingNotify</span>
event with a request member of
<span class="symbol">MappingKeyboard</span>
or
<span class="symbol">MappingModifier</span>
occurs.
The result is to update Xlib's knowledge of the keyboard.
</p><p>


To obtain the uppercase and lowercase forms of a KeySym, use
<a class="xref" href="#XConvertCase"><code class="function">XConvertCase</code></a>.
</p><a id="idp49256428" class="indexterm"></a><div class="funcsynopsis"><a id="XConvertCase"></a><p><code class="funcdef">void <strong class="fsfunc">XConvertCase</strong>(</code>KeySym<var class="pdparam"> keysym</var>, KeySym<var class="pdparam"> *lower_return</var>, KeySym<var class="pdparam"> *upper_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>keysym</em></span>
    </span></p></td><td><p>
Specifies the KeySym that is to be converted.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>lower_return</em></span>
    </span></p></td><td><p>
Returns the lowercase form of keysym, or keysym.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>upper_return</em></span>
    </span></p></td><td><p>
Returns the uppercase form of keysym, or keysym.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XConvertCase"><code class="function">XConvertCase</code></a>
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.
</p><p>


KeySyms have string names as well as numeric codes.
To convert the name of the KeySym to the KeySym code, use
<a class="xref" href="#XStringToKeysym"><code class="function">XStringToKeysym</code></a>.
</p><a id="idp50168404" class="indexterm"></a><div class="funcsynopsis"><a id="XStringToKeysym"></a><p><code class="funcdef">KeySym <strong class="fsfunc">XStringToKeysym</strong>(</code>char<var class="pdparam"> *string</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the name of the KeySym that is to be converted.
    </p></td></tr></tbody></table></div><p>


Standard KeySym names are obtained from
<code class="filename">&lt;X11/keysymdef.h&gt;</code>
<a id="idp50173276" class="indexterm"></a>
<a id="idp50174180" class="indexterm"></a>
<a id="idp50175092" class="indexterm"></a>
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.
</p><p>

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,
<a class="xref" href="#XStringToKeysym"><code class="function">XStringToKeysym</code></a>
returns
<span class="symbol">NoSymbol</span>.
</p><p>


To convert a KeySym code to the name of the KeySym, use
<a class="xref" href="#XKeysymToString"><code class="function">XKeysymToString</code></a>.
</p><a id="idp50178556" class="indexterm"></a><div class="funcsynopsis"><a id="XKeysymToString"></a><p><code class="funcdef">char *<strong class="fsfunc">XKeysymToString</strong>(</code>KeySym<var class="pdparam"> keysym</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>keysym</em></span>
    </span></p></td><td><p>
Specifies the KeySym that is to be converted.
    </p></td></tr></tbody></table></div><p>


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,
<a class="xref" href="#XKeysymToString"><code class="function">XKeysymToString</code></a>
returns a NULL.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="KeySym_Classification_Macros"></a>KeySym Classification Macros</h3></div></div></div><p>

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.
</p><p>IsCursorKey(<span class="emphasis"><em>keysym</em></span>)</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>keysym</em></span>
    </span></p></td><td><p>
Specifies the KeySym that is to be tested.
    </p></td></tr></tbody></table></div><p>


<a id="idp50187812" class="indexterm"></a>
Returns
<span class="symbol">True</span>
if the specified KeySym is a cursor key.
</p><p>IsFunctionKey(<span class="emphasis"><em>keysym</em></span>)</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>keysym</em></span>
    </span></p></td><td><p>
Specifies the KeySym that is to be tested.
    </p></td></tr></tbody></table></div><p>


<a id="idp50191740" class="indexterm"></a>
Returns 
<span class="symbol">True</span>
if the specified KeySym is a function key.
</p><p>IsKeypadKey(<span class="emphasis"><em>keysym</em></span>)</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>keysym</em></span>
    </span></p></td><td><p>
Specifies the KeySym that is to be tested.
    </p></td></tr></tbody></table></div><p>


<a id="idp50195732" class="indexterm"></a>
Returns
<span class="symbol">True</span>
if the specified KeySym is a standard keypad key.
</p><p>IsPrivateKeypadKey(<span class="emphasis"><em>keysym</em></span>)</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>keysym</em></span>
    </span></p></td><td><p>
Specifies the KeySym that is to be tested.
    </p></td></tr></tbody></table></div><p>


<a id="idp50199556" class="indexterm"></a>
Returns
<span class="symbol">True</span>
if the specified KeySym is a vendor-private keypad key.
</p><p>IsMiscFunctionKey(<span class="emphasis"><em>keysym</em></span>)</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>keysym</em></span>
    </span></p></td><td><p>
Specifies the KeySym that is to be tested.
    </p></td></tr></tbody></table></div><p>


<a id="idp50203556" class="indexterm"></a>
Returns 
<span class="symbol">True</span>
if the specified KeySym is a miscellaneous function key.
</p><p>IsModifierKey(<span class="emphasis"><em>keysym</em></span>)</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>keysym</em></span>
    </span></p></td><td><p>
Specifies the KeySym that is to be tested.
    </p></td></tr></tbody></table></div><p>


<a id="idp50207396" class="indexterm"></a>
Returns 
<span class="symbol">True</span>
if the specified KeySym is a modifier key.
</p><p>IsPFKey(<span class="emphasis"><em>keysym</em></span>)</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>keysym</em></span>
    </span></p></td><td><p>
Specifies the KeySym that is to be tested.
    </p></td></tr></tbody></table></div><p>


<a id="idp50210740" class="indexterm"></a>
Returns 
<span class="symbol">True</span>
if the specified KeySym is a PF key.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Using_Latin_1_Keyboard_Event_Functions"></a>Using Latin-1 Keyboard Event Functions</h2></div></div></div><p>

<a class="link" href="#Locales_and_Internationalized_Text_Functions" title="Chapter 13. Locales and Internationalized Text Functions">Chapter 13</a>
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.
<a class="xref" href="#XLookupString"><code class="function">XLookupString</code></a>
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.
</p><p>


To map a key event to an ISO Latin-1 string, use
<a class="xref" href="#XLookupString"><code class="function">XLookupString</code></a>.
</p><a id="idp50215236" class="indexterm"></a><div class="funcsynopsis"><a id="XLookupString"></a><p><code class="funcdef">int <strong class="fsfunc">XLookupString</strong>(</code>XKeyEvent<var class="pdparam"> *event_struct</var>, char<var class="pdparam"> *buffer_return</var>, int<var class="pdparam"> bytes_buffer</var>, KeySym<var class="pdparam"> *keysym_return</var>, XComposeStatus<var class="pdparam"> *status_in_out</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>event_struct</em></span>
    </span></p></td><td><p>
Specifies the key event structure to be used.
You can pass
<span class="type">XKeyPressedEvent</span>
or
<span class="type">XKeyReleasedEvent</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>buffer_return</em></span>
    </span></p></td><td><p>
Returns the translated characters.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>bytes_buffer</em></span>
    </span></p></td><td><p>
Specifies the length of the buffer.
No more than bytes_buffer of translation are returned.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>keysym_return</em></span>
    </span></p></td><td><p>
Returns the KeySym computed from the event if this argument is not NULL.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>status_in_out</em></span>
    </span></p></td><td><p>
Specifies or returns the 
<span class="structname">XComposeStatus</span>
structure or NULL.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XLookupString"><code class="function">XLookupString</code></a>
function translates a key event to a KeySym and a string.
The KeySym is obtained by using the standard interpretation of the
<span class="symbol">Shift</span>,
<span class="symbol">Lock</span>,
group, and numlock modifiers as defined in the X Protocol specification.
If the KeySym has been rebound (see
<a class="xref" href="#XRebindKeysym"><code class="function">XRebindKeysym</code></a>),
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.
<a class="xref" href="#XLookupString"><code class="function">XLookupString</code></a>
returns the number of characters that are stored in the buffer.
</p><p>

If present (non-NULL),
the
<span class="structname">XComposeStatus</span>
structure records the state,
which is private to Xlib,
that needs preservation across calls to
<a class="xref" href="#XLookupString"><code class="function">XLookupString</code></a>
to implement compose processing.
The creation of
<span class="structname">XComposeStatus</span>
structures is implementation-dependent;
a portable program must pass NULL for this argument.
</p><p>

<a class="xref" href="#XLookupString"><code class="function">XLookupString</code></a>
depends on the cached keyboard information mentioned in the
previous section, so it is necessary to use
<a class="xref" href="#XRefreshKeyboardMapping"><code class="function">XRefreshKeyboardMapping</code></a>
to keep this information up-to-date.
</p><p>


To rebind the meaning of a KeySym for
<a class="xref" href="#XLookupString"><code class="function">XLookupString</code></a>,
use
<a class="xref" href="#XRebindKeysym"><code class="function">XRebindKeysym</code></a>.
</p><a id="idp50234060" class="indexterm"></a><div class="funcsynopsis"><a id="XRebindKeysym"></a><p><code class="funcdef"><strong class="fsfunc">XRebindKeysym</strong>(</code>Display<var class="pdparam"> *display</var>, KeySym<var class="pdparam"> keysym</var>, KeySym<var class="pdparam"> list[ ]</var>, int<var class="pdparam"> mod_count</var>, unsignedchar<var class="pdparam"> *string</var>, int<var class="pdparam"> num_bytes</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>keysym</em></span>
    </span></p></td><td><p>
Specifies the KeySym that is to be rebound.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>list</em></span>
    </span></p></td><td><p>
Specifies the KeySyms to be used as modifiers.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>mod_count</em></span>
    </span></p></td><td><p>
Specifies the number of modifiers in the modifier list.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>string</em></span>
    </span></p></td><td><p>
Specifies the string that is copied and will be returned by 
<a class="xref" href="#XLookupString"><code class="function">XLookupString</code></a>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>num_bytes</em></span>
    </span></p></td><td><p>
Specifies the number of bytes in the string argument.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XRebindKeysym"><code class="function">XRebindKeysym</code></a>
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.
<a class="xref" href="#XLookupString"><code class="function">XLookupString</code></a>
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.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Allocating_Permanent_Storage"></a>Allocating Permanent Storage</h2></div></div></div><p>

To allocate some memory you will never give back, use
<a class="xref" href="#Xpermalloc"><code class="function">Xpermalloc</code></a>.
<a id="idp50251044" class="indexterm"></a>

</p><div class="funcsynopsis"><a id="Xpermalloc"></a><p><code class="funcdef">char *<strong class="fsfunc">Xpermalloc</strong>(</code>unsignedint<var class="pdparam"> size</var><code>)</code>;</p></div><p>

</p><p>


The
<a class="xref" href="#Xpermalloc"><code class="function">Xpermalloc</code></a>
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.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Parsing_the_Window_Geometry"></a>Parsing the Window Geometry</h2></div></div></div><p>

To parse standard window geometry strings, use
<a class="xref" href="#XParseGeometry"><code class="function">XParseGeometry</code></a>.
<a id="idp50256484" class="indexterm"></a>
<a id="idp50257036" class="indexterm"></a>
</p><div class="funcsynopsis"><a id="XParseGeometry"></a><p><code class="funcdef">int <strong class="fsfunc">XParseGeometry</strong>(</code>char<var class="pdparam"> *parsestring</var>, int*x_return,<var class="pdparam"> *y_return</var>, unsignedint*width_return,<var class="pdparam"> *height_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>parsestring</em></span>
    </span></p></td><td><p>
Specifies the string you want to parse.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y_return</em></span>
    </span></p></td><td><p>
Return the x and y offsets.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height_return</em></span>
    </span></p></td><td><p>
Return the width and height determined.
    </p></td></tr></tbody></table></div><p>


By convention,
X applications use a standard string to indicate window size and placement.
<a class="xref" href="#XParseGeometry"><code class="function">XParseGeometry</code></a>
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:
</p><p>


</p><pre class="literallayout">
[=][&lt;<span class="emphasis"><em>width</em></span>&gt;{xX}&lt;<span class="emphasis"><em>height</em></span>&gt;][{+-}&lt;<span class="emphasis"><em>xoffset</em></span>&gt;{+-}&lt;<span class="emphasis"><em>yoffset</em></span>&gt;] 
</pre><p>

</p><p>

The fields map into the arguments associated with this function.
(Items enclosed in &lt; &gt; 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.
</p><p>

The
<a class="xref" href="#XParseGeometry"><code class="function">XParseGeometry</code></a>
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
<span class="symbol">XValue</span>,
<span class="symbol">YValue</span>,
<span class="symbol">WidthValue</span>,
<span class="symbol">HeightValue</span>,
<span class="symbol">XNegative</span>,
or
<span class="symbol">YNegative</span>
and are defined in 
<code class="filename">&lt;X11/Xutil.h&gt;</code>.
<a id="idp50275516" class="indexterm"></a>
<a id="idp50276412" class="indexterm"></a>
<a id="idp50277324" class="indexterm"></a>
They will be set whenever one of the values is defined 
or one of the signs is set.
</p><p>

If the function returns either the 
<span class="symbol">XValue</span>
or 
<span class="symbol">YValue</span>
flag,
you should place the window at the requested position.

</p><p>

To construct a window's geometry information, use
<a class="xref" href="#XWMGeometry"><code class="function">XWMGeometry</code></a>.
</p><a id="idp50280276" class="indexterm"></a><div class="funcsynopsis"><a id="XWMGeometry"></a><p><code class="funcdef">int <strong class="fsfunc">XWMGeometry</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen</var>, char<var class="pdparam"> *user_geom</var>, char<var class="pdparam"> *def_geom</var>, unsignedint<var class="pdparam"> bwidth</var>, XSizeHints<var class="pdparam"> *hints</var>, int*x_return,<var class="pdparam"> *y_return</var>, int<var class="pdparam"> *width_return</var>, int<var class="pdparam"> *height_return</var>, int<var class="pdparam"> *gravity_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the screen.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>user_geom</em></span>
    </span></p></td><td><p>
Specifies the user-specified geometry or NULL.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>def_geom</em></span>
    </span></p></td><td><p>
Specifies the application's default geometry or NULL.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>bwidth</em></span>
    </span></p></td><td><p>
Specifies the border width.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hints</em></span>
    </span></p></td><td><p>
Specifies the size hints for the window in its normal state.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y_return</em></span>
    </span></p></td><td><p>
Return the x and y offsets.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height_return</em></span>
    </span></p></td><td><p>
Return the width and height determined.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gravity_return</em></span>
    </span></p></td><td><p>
Returns the window gravity.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XWMGeometry"><code class="function">XWMGeometry</code></a>
function combines any geometry information (given in the format used by 
<a class="xref" href="#XParseGeometry"><code class="function">XParseGeometry</code></a>)
specified by the user and by the calling program with size hints 
(usually the ones to be stored in <span class="property">WM_NORMAL_HINTS</span>) and returns the position, 
size, and gravity
(<span class="symbol">NorthWestGravity</span>,
<span class="symbol">NorthEastGravity</span>,
<span class="symbol">SouthEastGravity</span>,
or
<span class="symbol">SouthWestGravity</span>)
that describe the window.
If the base size is not set in the 
<span class="structname">XSizeHints</span>
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 
<a class="xref" href="#XParseGeometry"><code class="function">XParseGeometry</code></a>)
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.
</p><p>

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.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Manipulating_Regions"></a>Manipulating Regions</h2></div></div></div><p>
Regions are arbitrary sets of pixel locations.
Xlib provides functions for manipulating regions.
The opaque type 
<span class="structname">Region</span>
is defined in 
<code class="filename">&lt;X11/Xutil.h&gt;</code>.
<a id="idp53155588" class="indexterm"></a>
<a id="idp53156388" class="indexterm"></a>
<a id="idp53157196" class="indexterm"></a>
Xlib provides functions that you can use to manipulate regions.
This section discusses how to:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Create, copy, or destroy regions
    </p></li><li class="listitem"><p>
Move or shrink regions
    </p></li><li class="listitem"><p>
Compute with regions
    </p></li><li class="listitem"><p>
Determine if regions are empty or equal
    </p></li><li class="listitem"><p>
Locate a point or rectangle in a region
    </p></li></ul></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Creating_Copying_or_Destroying_Regions"></a>Creating, Copying, or Destroying Regions</h3></div></div></div><p>

To create a new empty region, use
<code class="function">XCreateRegion</code>.
</p><p>Region XCreateRegion()</p><p>



To generate a region from a polygon, use
<a class="xref" href="#XPolygonRegion"><code class="function">XPolygonRegion</code></a>.
</p><a id="idp53163044" class="indexterm"></a><div class="funcsynopsis"><a id="XPolygonRegion"></a><p><code class="funcdef">Region <strong class="fsfunc">XPolygonRegion</strong>(</code>XPoint<var class="pdparam"> points[]</var>, int<var class="pdparam"> n</var>, int<var class="pdparam"> fill_rule</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>points</em></span>
    </span></p></td><td><p>
Specifies an array of points.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>n</em></span>
    </span></p></td><td><p>
Specifies the number of points in the polygon. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>fill_rule</em></span>
    </span></p></td><td><p>
Specifies the fill-rule you want to set for the specified GC.
You can pass 
<span class="symbol">EvenOddRule</span>
or
<span class="symbol">WindingRule</span>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XPolygonRegion"><code class="function">XPolygonRegion</code></a>
function returns a region for the polygon defined by the points array.
For an explanation of fill_rule,
see
<a class="xref" href="#XCreateGC"><code class="function">XCreateGC</code></a>.
</p><p>


To set the clip-mask of a GC to a region, use
<a class="xref" href="#XSetRegion"><code class="function">XSetRegion</code></a>.
</p><a id="idp53172084" class="indexterm"></a><div class="funcsynopsis"><a id="XSetRegion"></a><p><code class="funcdef"><strong class="fsfunc">XSetRegion</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var>, Region<var class="pdparam"> r</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>r</em></span>
    </span></p></td><td><p>
Specifies the region.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetRegion"><code class="function">XSetRegion</code></a>
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.
</p><p>


To deallocate the storage associated with a specified region, use
<a class="xref" href="#XDestroyRegion"><code class="function">XDestroyRegion</code></a>.
</p><a id="idp53180356" class="indexterm"></a><div class="funcsynopsis"><a id="XDestroyRegion"></a><p><code class="funcdef"><strong class="fsfunc">XDestroyRegion</strong>(</code>Region<var class="pdparam"> r</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>r</em></span>
    </span></p></td><td><p>
Specifies the region.
    </p></td></tr></tbody></table></div><p>


</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Moving_or_Shrinking_Regions"></a>Moving or Shrinking Regions</h3></div></div></div><p>

To move a region by a specified amount, use 
<a class="xref" href="#XOffsetRegion"><code class="function">XOffsetRegion</code></a>.
</p><a id="idp53185660" class="indexterm"></a><div class="funcsynopsis"><a id="XOffsetRegion"></a><p><code class="funcdef"><strong class="fsfunc">XOffsetRegion</strong>(</code>Region<var class="pdparam"> r</var>, intdx,<var class="pdparam"> dy</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>r</em></span>
    </span></p></td><td><p>
Specifies the region.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dx</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dy</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates,
which define the amount you want to move the specified region.
    </p></td></tr></tbody></table></div><p>



To reduce a region by a specified amount, use
<a class="xref" href="#XShrinkRegion"><code class="function">XShrinkRegion</code></a>.
</p><a id="idp53192852" class="indexterm"></a><div class="funcsynopsis"><a id="XShrinkRegion"></a><p><code class="funcdef"><strong class="fsfunc">XShrinkRegion</strong>(</code>Region<var class="pdparam"> r</var>, intdx,<var class="pdparam"> dy</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>r</em></span>
    </span></p></td><td><p>
Specifies the region.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dx</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dy</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates,
which define the amount you want to shrink the specified region.
    </p></td></tr></tbody></table></div><p>


Positive values shrink the size of the region, 
and negative values expand the region.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Computing_with_Regions"></a>Computing with Regions</h3></div></div></div><p>


To generate the smallest rectangle enclosing a region, use
<a class="xref" href="#XClipBox"><code class="function">XClipBox</code></a>.
</p><a id="idp53201364" class="indexterm"></a><div class="funcsynopsis"><a id="XClipBox"></a><p><code class="funcdef"><strong class="fsfunc">XClipBox</strong>(</code>Region<var class="pdparam"> r</var>, XRectangle<var class="pdparam"> *rect_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>r</em></span>
    </span></p></td><td><p>
Specifies the region.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>rect_return</em></span>
    </span></p></td><td><p>
Returns the smallest enclosing rectangle.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XClipBox"><code class="function">XClipBox</code></a>
function returns the smallest rectangle enclosing the specified region.

</p><p>

To compute the intersection of two regions, use
<a class="xref" href="#XIntersectRegion"><code class="function">XIntersectRegion</code></a>.
</p><a id="idp53207932" class="indexterm"></a><div class="funcsynopsis"><a id="XIntersectRegion"></a><p><code class="funcdef"><strong class="fsfunc">XIntersectRegion</strong>(</code>Regionsra,srb,<var class="pdparam"> dr_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>sra</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>srb</em></span>
    </span></p></td><td><p>
Specify the two regions with which you want to perform the computation.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dr_return</em></span>
    </span></p></td><td><p>
Returns the result of the computation.
    </p></td></tr></tbody></table></div><p>



To compute the union of two regions, use
<a class="xref" href="#XUnionRegion"><code class="function">XUnionRegion</code></a>.
</p><a id="idp53214660" class="indexterm"></a><div class="funcsynopsis"><a id="XUnionRegion"></a><p><code class="funcdef"><strong class="fsfunc">XUnionRegion</strong>(</code>Regionsra,srb,<var class="pdparam"> dr_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>sra</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>srb</em></span>
    </span></p></td><td><p>
Specify the two regions with which you want to perform the computation.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dr_return</em></span>
    </span></p></td><td><p>
Returns the result of the computation.
    </p></td></tr></tbody></table></div><p>



To create a union of a source region and a rectangle, use
<a class="xref" href="#XUnionRectWithRegion"><code class="function">XUnionRectWithRegion</code></a>.
</p><a id="idp53221452" class="indexterm"></a><div class="funcsynopsis"><a id="XUnionRectWithRegion"></a><p><code class="funcdef"><strong class="fsfunc">XUnionRectWithRegion</strong>(</code>XRectangle<var class="pdparam"> *rectangle</var>, Region<var class="pdparam"> src_region</var>, Region<var class="pdparam"> dest_region_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>rectangle</em></span>
    </span></p></td><td><p>
Specifies the rectangle.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>src_region</em></span>
    </span></p></td><td><p>
Specifies the source region to be used.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dest_region_return</em></span>
    </span></p></td><td><p>
Returns the destination region.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XUnionRectWithRegion"><code class="function">XUnionRectWithRegion</code></a>
function updates the destination region from a union of the specified rectangle
and the specified source region.
</p><p>


To subtract two regions, use
<a class="xref" href="#XSubtractRegion"><code class="function">XSubtractRegion</code></a>.
</p><a id="idp53229524" class="indexterm"></a><div class="funcsynopsis"><a id="XSubtractRegion"></a><p><code class="funcdef"><strong class="fsfunc">XSubtractRegion</strong>(</code>Regionsra,srb,<var class="pdparam"> dr_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>sra</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>srb</em></span>
    </span></p></td><td><p>
Specify the two regions with which you want to perform the computation.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dr_return</em></span>
    </span></p></td><td><p>
Returns the result of the computation.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSubtractRegion"><code class="function">XSubtractRegion</code></a>
function subtracts srb from sra and stores the results in dr_return.
</p><p>


To calculate the difference between the union and intersection 
of two regions, use
<a class="xref" href="#XXorRegion"><code class="function">XXorRegion</code></a>.
</p><a id="idp53237116" class="indexterm"></a><div class="funcsynopsis"><a id="XXorRegion"></a><p><code class="funcdef"><strong class="fsfunc">XXorRegion</strong>(</code>Regionsra,srb,<var class="pdparam"> dr_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>sra</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>srb</em></span>
    </span></p></td><td><p>
Specify the two regions with which you want to perform the computation.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>dr_return</em></span>
    </span></p></td><td><p>
Returns the result of the computation.
    </p></td></tr></tbody></table></div><p>


</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Determining_if_Regions_Are_Empty_or_Equal"></a>Determining if Regions Are Empty or Equal</h3></div></div></div><p>

To determine if the specified region is empty, use
<a class="xref" href="#XEmptyRegion"><code class="function">XEmptyRegion</code></a>.
</p><a id="idp53245140" class="indexterm"></a><div class="funcsynopsis"><a id="XEmptyRegion"></a><p><code class="funcdef">Bool <strong class="fsfunc">XEmptyRegion</strong>(</code>Region<var class="pdparam"> r</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>r</em></span>
    </span></p></td><td><p>
Specifies the region.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XEmptyRegion"><code class="function">XEmptyRegion</code></a>
function returns
<span class="symbol">True</span>
if the region is empty.
</p><p>


To determine if two regions have the same offset, size, and shape, use
<a class="xref" href="#XEqualRegion"><code class="function">XEqualRegion</code></a>.
</p><a id="idp53250332" class="indexterm"></a><div class="funcsynopsis"><a id="XEqualRegion"></a><p><code class="funcdef">Bool <strong class="fsfunc">XEqualRegion</strong>(</code>Regionr1,<var class="pdparam"> r2</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>r1</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>r2</em></span>
    </span></p></td><td><p>
Specify the two regions.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XEqualRegion"><code class="function">XEqualRegion</code></a>
function returns
<span class="symbol">True</span>
if the two regions have the same offset, size, and shape.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Locating_a_Point_or_a_Rectangle_in_a_Region"></a>Locating a Point or a Rectangle in a Region</h3></div></div></div><p>

To determine if a specified point resides in a specified region, use
<a class="xref" href="#XPointInRegion"><code class="function">XPointInRegion</code></a>.
</p><a id="idp53257884" class="indexterm"></a><div class="funcsynopsis"><a id="XPointInRegion"></a><p><code class="funcdef">Bool <strong class="fsfunc">XPointInRegion</strong>(</code>Region<var class="pdparam"> r</var>, intx,<var class="pdparam"> y</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>r</em></span>
    </span></p></td><td><p>
Specifies the region.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, which define the point.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XPointInRegion"><code class="function">XPointInRegion</code></a>
function returns 
<span class="symbol">True</span>
if the point (x, y) is contained in the region r.
</p><p>


To determine if a specified rectangle is inside a region, use
<a class="xref" href="#XRectInRegion"><code class="function">XRectInRegion</code></a>.
</p><a id="idp53266052" class="indexterm"></a><div class="funcsynopsis"><a id="XRectInRegion"></a><p><code class="funcdef">int <strong class="fsfunc">XRectInRegion</strong>(</code>Region<var class="pdparam"> r</var>, intx,<var class="pdparam"> y</var>, unsignedintwidth,<var class="pdparam"> height</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>r</em></span>
    </span></p></td><td><p>
Specifies the region.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates, which define the coordinates of the
upper-left corner of the rectangle.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height, which define the rectangle.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XRectInRegion"><code class="function">XRectInRegion</code></a>
function returns
<span class="symbol">RectangleIn</span>
if the rectangle is entirely in the specified region,
<span class="symbol">RectangleOut</span>
if the rectangle is entirely out of the specified region,
and
<span class="symbol">RectanglePart</span>
if the rectangle is partially in the specified region.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Using_Cut_Buffers"></a>Using Cut Buffers</h2></div></div></div><p>

<a id="idp53278044" class="indexterm"></a>
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 client
(see <a class="link" href="#Selections" title="Selections">section 4.5</a>)
and generally should be used instead of cut buffers.
</p><p>

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).
</p><p>


To store data in cut buffer 0, use 
<a class="xref" href="#XStoreBytes"><code class="function">XStoreBytes</code></a>.
</p><a id="idp53280588" class="indexterm"></a><div class="funcsynopsis"><a id="XStoreBytes"></a><p><code class="funcdef"><strong class="fsfunc">XStoreBytes</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> *bytes</var>, int<var class="pdparam"> nbytes</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>bytes</em></span>
    </span></p></td><td><p>
Specifies the bytes, which are not necessarily ASCII or null-terminated.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nbytes</em></span>
    </span></p></td><td><p>
Specifies the number of bytes to be stored.
    </p></td></tr></tbody></table></div><p>


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
<a class="xref" href="#XFetchBytes"><code class="function">XFetchBytes</code></a>.
</p><p>

<a class="xref" href="#XStoreBytes"><code class="function">XStoreBytes</code></a>
can generate a
<span class="errorname">BadAlloc</span>
error.
</p><p>


To store data in a specified cut buffer, use
<a class="xref" href="#XStoreBuffer"><code class="function">XStoreBuffer</code></a>.
</p><a id="idp53289780" class="indexterm"></a><div class="funcsynopsis"><a id="XStoreBuffer"></a><p><code class="funcdef"><strong class="fsfunc">XStoreBuffer</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> *bytes</var>, int<var class="pdparam"> nbytes</var>, int<var class="pdparam"> buffer</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>bytes</em></span>
    </span></p></td><td><p>
Specifies the bytes, which are not necessarily ASCII or null-terminated.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nbytes</em></span>
    </span></p></td><td><p>
Specifies the number of bytes to be stored.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>buffer</em></span>
    </span></p></td><td><p>
Specifies the buffer in which you want to store the bytes.
    </p></td></tr></tbody></table></div><p>


If an invalid buffer is specified, the call has no effect.
The data can have embedded null characters
and need not be null-terminated.
</p><p>

<a class="xref" href="#XStoreBuffer"><code class="function">XStoreBuffer</code></a>
can generate a
<span class="errorname">BadAlloc</span>
error.
</p><p>


To return data from cut buffer 0, use 
<a class="xref" href="#XFetchBytes"><code class="function">XFetchBytes</code></a>.
</p><a id="idp53300172" class="indexterm"></a><div class="funcsynopsis"><a id="XFetchBytes"></a><p><code class="funcdef">char *<strong class="fsfunc">XFetchBytes</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> *nbytes_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nbytes_return</em></span>
    </span></p></td><td><p>
Returns the number of bytes in the buffer.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFetchBytes"><code class="function">XFetchBytes</code></a>
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
<a class="xref" href="#XFree"></a>.
</p><p>


To return data from a specified cut buffer, use 
<a class="xref" href="#XFetchBuffer"><code class="function">XFetchBuffer</code></a>.
</p><a id="idp53307452" class="indexterm"></a><div class="funcsynopsis"><a id="XFetchBuffer"></a><p><code class="funcdef">char *<strong class="fsfunc">XFetchBuffer</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> *nbytes_return</var>, int<var class="pdparam"> buffer</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nbytes_return</em></span>
    </span></p></td><td><p>
Returns the number of bytes in the buffer.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>buffer</em></span>
    </span></p></td><td><p>
Specifies the buffer from which you want the stored data returned.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFetchBuffer"><code class="function">XFetchBuffer</code></a>
function returns zero to the nbytes_return argument 
if there is no data in the buffer or if an invalid
buffer is specified.
</p><p>


To rotate the cut buffers, use 
<a class="xref" href="#XRotateBuffers"><code class="function">XRotateBuffers</code></a>.
</p><a id="idp53315740" class="indexterm"></a><div class="funcsynopsis"><a id="XRotateBuffers"></a><p><code class="funcdef"><strong class="fsfunc">XRotateBuffers</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> rotate</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>rotate</em></span>
    </span></p></td><td><p>
Specifies how much to rotate the cut buffers.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XRotateBuffers"><code class="function">XRotateBuffers</code></a>
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
<a class="xref" href="#XRotateBuffers"><code class="function">XRotateBuffers</code></a>
generates
<span class="errorname">BadMatch</span>
errors if any of the eight buffers have not been created.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Determining_the_Appropriate_Visual_Type"></a>Determining the Appropriate Visual Type</h2></div></div></div><p>

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.
</p><p>

The functions in this section use the visual information masks and the
<span class="structname">XVisualInfo</span>
structure,
which is defined in
<code class="filename">&lt;X11/Xutil.h&gt;</code>
<a id="idp53324836" class="indexterm"></a>
<a id="idp53325636" class="indexterm"></a>
<a id="idp53326444" class="indexterm"></a>
and contains:

</p><pre class="literallayout">

/* Visual information mask bits */


#define   VisualNoMask                 0x0
#define   VisualIDMask                 0x1
#define   VisualScreenMask             0x2
#define   VisualDepthMask              0x4
#define   VisualClassMask              0x8
#define   VisualRedMaskMask            0x10
#define   VisualGreenMaskMask          0x20
#define   VisualBlueMaskMask           0x40
#define   VisualColormapSizeMask       0x80
#define   VisualBitsPerRGBMask         0x100
#define   VisualAllMask                0x1FF

</pre><pre class="literallayout">


/* Values */

typedef struct {
     Visual *visual;
     VisualID visualid;
     int screen;
     unsigned int depth;
     int class;
     unsigned long red_mask;
     unsigned long green_mask;
     unsigned long blue_mask;
     int colormap_size;
     int bits_per_rgb;
} XVisualInfo;
</pre><p>


To obtain a list of visual information structures that match a specified
template, use
<a class="xref" href="#XGetVisualInfo"><code class="function">XGetVisualInfo</code></a>.
</p><a id="idp53330428" class="indexterm"></a><div class="funcsynopsis"><a id="XGetVisualInfo"></a><p><code class="funcdef">XVisualInfo *<strong class="fsfunc">XGetVisualInfo</strong>(</code>Display<var class="pdparam"> *display</var>, long<var class="pdparam"> vinfo_mask</var>, XVisualInfo<var class="pdparam"> *vinfo_template</var>, int<var class="pdparam"> *nitems_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>vinfo_mask</em></span>
    </span></p></td><td><p>
Specifies the visual mask value.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>vinfo_template</em></span>
    </span></p></td><td><p>
Specifies the visual attributes that are to be used in matching the visual
structures.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nitems_return</em></span>
    </span></p></td><td><p>
Returns the number of matching visual structures.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetVisualInfo"><code class="function">XGetVisualInfo</code></a>
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,
<a class="xref" href="#XGetVisualInfo"><code class="function">XGetVisualInfo</code></a>
returns a NULL.
To free the data returned by this function, use
<a class="xref" href="#XFree"></a>.
</p><p>


To obtain the visual information that matches the specified depth and
class of the screen, use
<a class="xref" href="#XMatchVisualInfo"><code class="function">XMatchVisualInfo</code></a>.
</p><a id="idp53341300" class="indexterm"></a><div class="funcsynopsis"><a id="XMatchVisualInfo"></a><p><code class="funcdef">Status <strong class="fsfunc">XMatchVisualInfo</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen</var>, int<var class="pdparam"> depth</var>, int<var class="pdparam"> class</var>, XVisualInfo<var class="pdparam"> *vinfo_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the screen.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>depth</em></span>
    </span></p></td><td><p>
Specifies the depth of the screen.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>class</em></span>
    </span></p></td><td><p>
Specifies the class of the screen.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>vinfo_return</em></span>
    </span></p></td><td><p>
Returns the matched visual information.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XMatchVisualInfo"><code class="function">XMatchVisualInfo</code></a>
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,
<a class="xref" href="#XMatchVisualInfo"><code class="function">XMatchVisualInfo</code></a>
returns nonzero and the information on the visual to vinfo_return.
Otherwise, when a visual is not found,
<a class="xref" href="#XMatchVisualInfo"><code class="function">XMatchVisualInfo</code></a>
returns zero.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Manipulating_Images"></a>Manipulating Images</h2></div></div></div><p>

Xlib provides several functions that perform basic operations on images.
All operations on images are defined using an 
<span class="structname">XImage</span>
structure, 
as defined in
<code class="filename">&lt;X11/Xlib.h&gt;</code>.
<a id="idp53354692" class="indexterm"></a>
<a id="idp53355492" class="indexterm"></a>
<a id="idp53356300" class="indexterm"></a>
Because the number of different types of image formats can be very large,
this hides details of image storage properly from applications.
</p><p>

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
<a class="xref" href="#XGetImage"><code class="function">XGetImage</code></a>
and 
<a class="xref" href="#XPutImage"><code class="function">XPutImage</code></a>.
</p><p>

Note that no functions have been defined, as yet, to read and write images 
to and from disk files.
</p><p>

The
<span class="structname">XImage</span>
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, 
<a class="xref" href="#XPutImage"><code class="function">XPutImage</code></a>
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 
<span class="structname">XImage</span>
structure,
see <a class="link" href="#Transferring_Images_between_Client_and_Server" title="Transferring Images between Client and Server">section 8.7</a>.
</p><p>


To allocate an 
<span class="structname">XImage</span>
structure and initialize it with image format values from a display, use
<a class="xref" href="#XCreateImage"><code class="function">XCreateImage</code></a>.
</p><a id="idp53362428" class="indexterm"></a><div class="funcsynopsis"><a id="XCreateImage"></a><p><code class="funcdef">XImage *<strong class="fsfunc">XCreateImage</strong>(</code>Display<var class="pdparam"> *display</var>, Visual<var class="pdparam"> *visual</var>, unsignedint<var class="pdparam"> depth</var>, int<var class="pdparam"> format</var>, int<var class="pdparam"> offset</var>, char<var class="pdparam"> *data</var>, unsignedint<var class="pdparam"> width</var>, unsignedint<var class="pdparam"> height</var>, int<var class="pdparam"> bitmap_pad</var>, int<var class="pdparam"> bytes_per_line</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>visual</em></span>
    </span></p></td><td><p>
Specifies the
<span class="structname">Visual</span>
structure.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>depth</em></span>
    </span></p></td><td><p>
Specifies the depth of the image.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>format</em></span>
    </span></p></td><td><p>
Specifies the format for the image.
You can pass
<span class="symbol">XYBitmap</span>,
<span class="symbol">XYPixmap</span>,
or 
<span class="symbol">ZPixmap</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>offset</em></span>
    </span></p></td><td><p>
Specifies the number of pixels to ignore at the beginning of the scanline.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>data</em></span>
    </span></p></td><td><p>
Specifies the image data.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>
Specifies the width of the image, in pixels.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specifies the height of the image, in pixels.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>bitmap_pad</em></span>
    </span></p></td><td><p>
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.  
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>bytes_per_line</em></span>
    </span></p></td><td><p>
Specifies the number of bytes in the client image between
the start of one scanline and the start of the next.  
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCreateImage"><code class="function">XCreateImage</code></a>
function allocates the memory needed for an
<span class="structname">XImage</span>
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 
<span class="structname">XImage</span>
structure.
The red, green, and blue mask values are defined for Z format images only
and are derived from the 
<span class="structname">Visual</span>
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.
</p><p>

Note that when the image is created using
<a class="xref" href="#XCreateImage"><code class="function">XCreateImage</code></a>,
<a class="xref" href="#XGetImage"><code class="function">XGetImage</code></a>,
or
<a class="xref" href="#XSubImage"><code class="function">XSubImage</code></a>,
the destroy procedure that the 
<a class="xref" href="#XDestroyImage"><code class="function">XDestroyImage</code></a>
function calls frees both the image structure 
and the data pointed to by the image structure.
</p><p>

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
<code class="filename">&lt;X11/Xutil.h&gt;</code>.
<a id="idp53385908" class="indexterm"></a>
<a id="idp53386708" class="indexterm"></a>
<a id="idp53387516" class="indexterm"></a>
</p><p>


To obtain a pixel value in an image, use
<a class="xref" href="#XGetPixel"><code class="function">XGetPixel</code></a>.
</p><a id="idp53389252" class="indexterm"></a><div class="funcsynopsis"><a id="XGetPixel"></a><p><code class="funcdef">unsigned long <strong class="fsfunc">XGetPixel</strong>(</code>XImage<var class="pdparam"> *ximage</var>, int<var class="pdparam"> x</var>, int<var class="pdparam"> y</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ximage</em></span>
    </span></p></td><td><p>
Specifies the image.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetPixel"><code class="function">XGetPixel</code></a>
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.
</p><p>


To set a pixel value in an image, use
<a class="xref" href="#XPutPixel"><code class="function">XPutPixel</code></a>.
</p><a id="idp53397820" class="indexterm"></a><div class="funcsynopsis"><a id="XPutPixel"></a><p><code class="funcdef"><strong class="fsfunc">XPutPixel</strong>(</code>XImage<var class="pdparam"> *ximage</var>, int<var class="pdparam"> x</var>, int<var class="pdparam"> y</var>, unsignedlong<var class="pdparam"> pixel</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ximage</em></span>
    </span></p></td><td><p>
Specifies the image.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>pixel</em></span>
    </span></p></td><td><p>
Specifies the new pixel value.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XPutPixel"><code class="function">XPutPixel</code></a>
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.
</p><p>


To create a subimage, use
<a class="xref" href="#XSubImage"><code class="function">XSubImage</code></a>.
</p><a id="idp53407868" class="indexterm"></a><div class="funcsynopsis"><a id="XSubImage"></a><p><code class="funcdef">XImage *<strong class="fsfunc">XSubImage</strong>(</code>XImage<var class="pdparam"> *ximage</var>, int<var class="pdparam"> x</var>, int<var class="pdparam"> y</var>, unsignedint<var class="pdparam"> subimage_width</var>, unsignedint<var class="pdparam"> subimage_height</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ximage</em></span>
    </span></p></td><td><p>
Specifies the image.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y</em></span>
    </span></p></td><td><p>
Specify the x and y coordinates.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>subimage_width</em></span>
    </span></p></td><td><p>
Specifies the width of the new subimage, in pixels.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>subimage_height</em></span>
    </span></p></td><td><p>
Specifies the height of the new subimage, in pixels.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSubImage"><code class="function">XSubImage</code></a>
function creates a new image that is a subsection of an existing one.
It allocates the memory necessary for the new
<span class="structname">XImage</span>
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.
</p><p>


To increment each pixel in an image by a constant value, use
<a class="xref" href="#XAddPixel"><code class="function">XAddPixel</code></a>.
</p><a id="idp53419892" class="indexterm"></a><div class="funcsynopsis"><a id="XAddPixel"></a><p><code class="funcdef"><strong class="fsfunc">XAddPixel</strong>(</code>XImage<var class="pdparam"> *ximage</var>, long<var class="pdparam"> value</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ximage</em></span>
    </span></p></td><td><p>
Specifies the image.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>value</em></span>
    </span></p></td><td><p>
Specifies the constant value that is to be added.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XAddPixel"><code class="function">XAddPixel</code></a>
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.
</p><p>


To deallocate the memory allocated in a previous call to
<a class="xref" href="#XCreateImage"><code class="function">XCreateImage</code></a>,
use
<a class="xref" href="#XDestroyImage"><code class="function">XDestroyImage</code></a>.
</p><a id="idp53426956" class="indexterm"></a><div class="funcsynopsis"><a id="XDestroyImage"></a><p><code class="funcdef"><strong class="fsfunc">XDestroyImage</strong>(</code>XImage *<var class="pdparam">ximage</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>ximage</em></span>
    </span></p></td><td><p>
Specifies the image.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDestroyImage"><code class="function">XDestroyImage</code></a>
function deallocates the memory associated with the
<span class="structname">XImage</span>
structure.
</p><p>

Note that when the image is created using
<a class="xref" href="#XCreateImage"><code class="function">XCreateImage</code></a>,
<a class="xref" href="#XGetImage"><code class="function">XGetImage</code></a>,
or 
<a class="xref" href="#XSubImage"><code class="function">XSubImage</code></a>,
the destroy procedure that this macro calls
frees both the image structure and the data pointed to by the image structure. 
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Manipulating_Bitmaps"></a>Manipulating Bitmaps</h2></div></div></div><p>

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).
</p><p>

The X version 11 bitmap file format is:
</p><p>


</p><pre class="literallayout">
#define <span class="emphasis"><em>name</em></span>_width <span class="emphasis"><em>width</em></span>
#define <span class="emphasis"><em>name</em></span>_height <span class="emphasis"><em>height</em></span>
#define <span class="emphasis"><em>name</em></span>_x_hot <span class="emphasis"><em>x</em></span>
#define <span class="emphasis"><em>name</em></span>_y_hot <span class="emphasis"><em>y</em></span>
static unsigned char <span class="emphasis"><em>name</em></span>_bits[] = { 0x<span class="emphasis"><em>NN</em></span>,... }
</pre><p>
</p><p>


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.
</p><p>


To read a bitmap from a file and store it in a pixmap, use
<a class="xref" href="#XReadBitmapFile"><code class="function">XReadBitmapFile</code></a>.
</p><a id="idp53440540" class="indexterm"></a><div class="funcsynopsis"><a id="XReadBitmapFile"></a><p><code class="funcdef">int <strong class="fsfunc">XReadBitmapFile</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, char<var class="pdparam"> *filename</var>, unsignedint*width_return,<var class="pdparam"> *height_return</var>, Pixmap<var class="pdparam"> *bitmap_return</var>, int*x_hot_return,<var class="pdparam"> *y_hot_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable that indicates the screen.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>filename</em></span>
    </span></p></td><td><p>
Specifies the file name to use.
The format of the file name is operating-system dependent.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height_return</em></span>
    </span></p></td><td><p>
Return the width and height values of the read in bitmap file.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>bitmap_return</em></span>
    </span></p></td><td><p>
Returns the bitmap that is created.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x_hot_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y_hot_return</em></span>
    </span></p></td><td><p>
Return the hotspot coordinates.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XReadBitmapFile"><code class="function">XReadBitmapFile</code></a>
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, 
<a class="xref" href="#XReadBitmapFile"><code class="function">XReadBitmapFile</code></a>
returns 
<span class="returnvalue">BitmapOpenFailed</span>.
If the file can be opened but does not contain valid bitmap data, 
it returns 
<span class="returnvalue">BitmapFileInvalid</span>.
If insufficient working storage is allocated,
it returns
<span class="returnvalue">BitmapNoMemory</span>.
If the file is readable and valid,
it returns 
<span class="returnvalue">BitmapSuccess</span>.
</p><p>

<a class="xref" href="#XReadBitmapFile"><code class="function">XReadBitmapFile</code></a>
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 
<a class="xref" href="#XFreePixmap"><code class="function">XFreePixmap</code></a>
when finished.
If <span class="emphasis"><em>name</em></span>_x_hot and <span class="emphasis"><em>name</em></span>_y_hot exist,
<a class="xref" href="#XReadBitmapFile"><code class="function">XReadBitmapFile</code></a>
returns them to x_hot_return and y_hot_return;
otherwise, it returns −1,−1.
</p><p>

<a class="xref" href="#XReadBitmapFile"><code class="function">XReadBitmapFile</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadDrawable</span>,
and
<span class="errorname">BadGC</span>
errors.
</p><p>


To read a bitmap from a file and return it as data, use
<a class="xref" href="#XReadBitmapFileData"><code class="function">XReadBitmapFileData</code></a>.
</p><a id="idp53461468" class="indexterm"></a><div class="funcsynopsis"><a id="XReadBitmapFileData"></a><p><code class="funcdef">int <strong class="fsfunc">XReadBitmapFileData</strong>(</code>char<var class="pdparam"> *filename</var>, unsignedint*width_return,<var class="pdparam"> *height_return</var>, unsignedchar<var class="pdparam"> *data_return</var>, int*x_hot_return,<var class="pdparam"> *y_hot_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>filename</em></span>
    </span></p></td><td><p>
Specifies the file name to use.
The format of the file name is operating-system dependent.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height_return</em></span>
    </span></p></td><td><p>
Return the width and height values of the read in bitmap file.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>data_return</em></span>
    </span></p></td><td><p>
Returns the bitmap data.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x_hot_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y_hot_return</em></span>
    </span></p></td><td><p>
Return the hotspot coordinates.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XReadBitmapFileData"><code class="function">XReadBitmapFileData</code></a>
function reads in a file containing a bitmap, in the same manner as
<a class="xref" href="#XReadBitmapFile"><code class="function">XReadBitmapFile</code></a>,
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
<a class="xref" href="#XFree"></a>.
The status and other return values are the same as for
<a class="xref" href="#XReadBitmapFile"><code class="function">XReadBitmapFile</code></a>.
</p><p>


To write out a bitmap from a pixmap to a file, use
<a class="xref" href="#XWriteBitmapFile"><code class="function">XWriteBitmapFile</code></a>.
</p><a id="idp53475364" class="indexterm"></a><div class="funcsynopsis"><a id="XWriteBitmapFile"></a><p><code class="funcdef">int <strong class="fsfunc">XWriteBitmapFile</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> *filename</var>, Pixmap<var class="pdparam"> bitmap</var>, unsignedintwidth,<var class="pdparam"> height</var>, intx_hot,<var class="pdparam"> y_hot</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>filename</em></span>
    </span></p></td><td><p>
Specifies the file name to use.
The format of the file name is operating-system dependent.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>bitmap</em></span>
    </span></p></td><td><p>
Specifies the bitmap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x_hot</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y_hot</em></span>
    </span></p></td><td><p>
Specify where to place the hotspot coordinates (or −1,−1 if none are present)
in the file.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XWriteBitmapFile"><code class="function">XWriteBitmapFile</code></a>
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 
<span class="returnvalue">BitmapOpenFailed</span>.
If insufficient memory is allocated,
<a class="xref" href="#XWriteBitmapFile"><code class="function">XWriteBitmapFile</code></a>
returns
<span class="returnvalue">BitmapNoMemory</span>;
otherwise, on no error,
it returns
<span class="returnvalue">BitmapSuccess</span>.
If x_hot and y_hot are not −1, −1,
<a class="xref" href="#XWriteBitmapFile"><code class="function">XWriteBitmapFile</code></a>
writes them out as the hotspot coordinates for the bitmap.
</p><p>

<a class="xref" href="#XWriteBitmapFile"><code class="function">XWriteBitmapFile</code></a>
can generate
<span class="errorname">BadDrawable</span>
and
<span class="errorname">BadMatch</span>
errors.
</p><p>


To create a pixmap and then store bitmap-format data into it, use
<a class="xref" href="#XCreatePixmapFromBitmapData"><code class="function">XCreatePixmapFromBitmapData</code></a>.
</p><a id="idp53492316" class="indexterm"></a><div class="funcsynopsis"><a id="XCreatePixmapFromBitmapData"></a><p><code class="funcdef">Pixmap <strong class="fsfunc">XCreatePixmapFromBitmapData</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, char<var class="pdparam"> *data</var>, unsignedintwidth,<var class="pdparam"> height</var>, unsignedlongfg,<var class="pdparam"> bg</var>, unsignedint<var class="pdparam"> depth</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable that indicates the screen.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>data</em></span>
    </span></p></td><td><p>
Specifies the data in bitmap format.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>fg</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>bg</em></span>
    </span></p></td><td><p>
Specify the foreground and background pixel values to use.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>depth</em></span>
    </span></p></td><td><p>
Specifies the depth of the pixmap.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCreatePixmapFromBitmapData"><code class="function">XCreatePixmapFromBitmapData</code></a>
function creates a pixmap of the given depth and then does a bitmap-format
<a class="xref" href="#XPutImage"><code class="function">XPutImage</code></a>
of the data into it.
The depth must be supported by the screen of the specified drawable,
or a
<span class="errorname">BadMatch</span>
error results.
</p><p>

<a class="xref" href="#XCreatePixmapFromBitmapData"><code class="function">XCreatePixmapFromBitmapData</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadDrawable</span>,
<span class="errorname">BadGC</span>,
and
<span class="errorname">BadValue</span>
errors.
</p><p>


To include a bitmap written out by 
<a class="xref" href="#XWriteBitmapFile"><code class="function">XWriteBitmapFile</code></a>
<a id="idp53510044" class="indexterm"></a>
in a program directly, as opposed to reading it in every time at run time, use
<a class="xref" href="#XCreateBitmapFromData"><code class="function">XCreateBitmapFromData</code></a>.
</p><a id="idp53510940" class="indexterm"></a><div class="funcsynopsis"><a id="XCreateBitmapFromData"></a><p><code class="funcdef">Pixmap <strong class="fsfunc">XCreateBitmapFromData</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, char<var class="pdparam"> *data</var>, unsignedintwidth,<var class="pdparam"> height</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable that indicates the screen.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>data</em></span>
    </span></p></td><td><p>
Specifies the location of the bitmap data.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height</em></span>
    </span></p></td><td><p>
Specify the width and height.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XCreateBitmapFromData"><code class="function">XCreateBitmapFromData</code></a>
function allows you to include in your C program (using
<code class="code">#include</code>)
a bitmap file that was written out by
<a class="xref" href="#XWriteBitmapFile"><code class="function">XWriteBitmapFile</code></a>
(X version 11 format only) without reading in the bitmap file.
The following example creates a gray bitmap:
</p><p>

</p><pre class="literallayout">
#include "gray.bitmap"

Pixmap bitmap;
bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height);
</pre><p>
</p><p>

If insufficient working storage was allocated,
<a class="xref" href="#XCreateBitmapFromData"><code class="function">XCreateBitmapFromData</code></a>
returns
<span class="symbol">None</span>.
It is your responsibility to free the
bitmap using
<a class="xref" href="#XFreePixmap"><code class="function">XFreePixmap</code></a>
when finished.
</p><p>

<a class="xref" href="#XCreateBitmapFromData"><code class="function">XCreateBitmapFromData</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadGC</span>
errors.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Using_the_Context_Manager"></a>Using the Context Manager</h2></div></div></div><p>

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.
</p><p>

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
<code class="filename">&lt;X11/Xutil.h&gt;</code>.
<a id="idp53528108" class="indexterm"></a>
<a id="idp53528908" class="indexterm"></a>
<a id="idp53529716" class="indexterm"></a>
</p><p>


To save a data value that corresponds to a resource ID and context type, use
<a class="xref" href="#XSaveContext"><code class="function">XSaveContext</code></a>.
</p><a id="idp53531492" class="indexterm"></a><div class="funcsynopsis"><a id="XSaveContext"></a><p><code class="funcdef">int <strong class="fsfunc">XSaveContext</strong>(</code>Display<var class="pdparam"> *display</var>, XID<var class="pdparam"> rid</var>, XContext<var class="pdparam"> context</var>, XPointer<var class="pdparam"> data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>rid</em></span>
    </span></p></td><td><p>
Specifies the resource ID with which the data is associated.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>context</em></span>
    </span></p></td><td><p>
Specifies the context type to which the data belongs.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>data</em></span>
    </span></p></td><td><p>
Specifies the data to be associated with the window and type.
    </p></td></tr></tbody></table></div><p>


If an entry with the specified resource ID and type already exists,
<a class="xref" href="#XSaveContext"><code class="function">XSaveContext</code></a>
overrides it with the specified context.
The
<a class="xref" href="#XSaveContext"><code class="function">XSaveContext</code></a>
function returns a nonzero error code if an error has occurred
and zero otherwise.
Possible errors are
<span class="symbol">XCNOMEM</span>
(out of memory).
</p><p>


To get the data associated with a resource ID and type, use
<a class="xref" href="#XFindContext"><code class="function">XFindContext</code></a>.
</p><a id="idp53542132" class="indexterm"></a><div class="funcsynopsis"><a id="XFindContext"></a><p><code class="funcdef">int <strong class="fsfunc">XFindContext</strong>(</code>Display<var class="pdparam"> *display</var>, XID<var class="pdparam"> rid</var>, XContext<var class="pdparam"> context</var>, XPointer<var class="pdparam"> *data_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>rid</em></span>
    </span></p></td><td><p>
Specifies the resource ID with which the data is associated.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>context</em></span>
    </span></p></td><td><p>
Specifies the context type to which the data belongs.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>data_return</em></span>
    </span></p></td><td><p>
Returns the data.
    </p></td></tr></tbody></table></div><p>


Because it is a return value,
the data is a pointer.
The
<a class="xref" href="#XFindContext"><code class="function">XFindContext</code></a>
function returns a nonzero error code if an error has occurred
and zero otherwise.
Possible errors are
<span class="symbol">XCNOENT</span>
(context-not-found).
</p><p>


To delete an entry for a given resource ID and type, use
<a class="xref" href="#XDeleteContext"><code class="function">XDeleteContext</code></a>.
</p><a id="idp53552252" class="indexterm"></a><div class="funcsynopsis"><a id="XDeleteContext"></a><p><code class="funcdef">int <strong class="fsfunc">XDeleteContext</strong>(</code>Display<var class="pdparam"> *display</var>, XID<var class="pdparam"> rid</var>, XContext<var class="pdparam"> context</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>rid</em></span>
    </span></p></td><td><p>
Specifies the resource ID with which the data is associated.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>context</em></span>
    </span></p></td><td><p>
Specifies the context type to which the data belongs.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDeleteContext"><code class="function">XDeleteContext</code></a>
function deletes the entry for the given resource ID 
and type from the data structure.
This function returns the same error codes that
<a class="xref" href="#XFindContext"><code class="function">XFindContext</code></a>
returns if called with the same arguments.
<a class="xref" href="#XDeleteContext"><code class="function">XDeleteContext</code></a>
does not free the data whose address was saved.
</p><p>


To create a unique context type that may be used in subsequent calls to
<a class="xref" href="#XSaveContext"><code class="function">XSaveContext</code></a>
and
<a class="xref" href="#XFindContext"><code class="function">XFindContext</code></a>,
use
<code class="function">XUniqueContext</code>.
</p><p>XContext XuniqueContext()</p></div></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a id="xlib_functions_and_protocol_requests"></a>Appendix A. Xlib Functions and Protocol Requests</h1></div></div></div><p>
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.
</p><div class="table"><a id="idp40218868"></a><p class="title"><strong>Table A.1. Protocol requests made by each Xlib function</strong></p><div class="table-contents"><table summary="Protocol requests made by each Xlib function" border="1"><colgroup><col align="left" class="col1" /><col align="left" class="col2" /></colgroup><thead><tr><th align="left">Xlib Function</th><th align="left">Protocol Request</th></tr></thead><tbody><tr><td align="left"><a class="xref" href="#XActivateScreenSaver"><code class="function">XActivateScreenSaver</code></a></td><td align="left"><code class="systemitem">ForceScreenSaver</code></td></tr><tr><td align="left"><a class="xref" href="#XAddHost"><code class="function">XAddHost</code></a></td><td align="left"><code class="systemitem">ChangeHosts</code></td></tr><tr><td align="left"><a class="xref" href="#XAddHosts"><code class="function">XAddHosts</code></a></td><td align="left"><code class="systemitem">ChangeHosts</code></td></tr><tr><td align="left"><a class="xref" href="#XAddToSaveSet"><code class="function">XAddToSaveSet</code></a></td><td align="left"><code class="systemitem">ChangeSaveSet</code></td></tr><tr><td align="left"><a class="xref" href="#XAllocColor"><code class="function">XAllocColor</code></a></td><td align="left"><code class="systemitem">AllocColor</code></td></tr><tr><td align="left"><a class="xref" href="#XAllocColorCells"><code class="function">XAllocColorCells</code></a></td><td align="left"><code class="systemitem">AllocColorCells</code></td></tr><tr><td align="left"><a class="xref" href="#XAllocColorPlanes"><code class="function">XAllocColorPlanes</code></a></td><td align="left"><code class="systemitem">AllocColorPlanes</code></td></tr><tr><td align="left"><a class="xref" href="#XAllocNamedColor"><code class="function">XAllocNamedColor</code></a></td><td align="left"><code class="systemitem">AllocNamedColor</code></td></tr><tr><td align="left"><a class="xref" href="#XAllowEvents"><code class="function">XAllowEvents</code></a></td><td align="left"><code class="systemitem">AllowEvents</code></td></tr><tr><td align="left"><a class="xref" href="#XAutoRepeatOff"><code class="function">XAutoRepeatOff</code></a></td><td align="left"><code class="systemitem">ChangeKeyboardControl</code></td></tr><tr><td align="left"><a class="xref" href="#XAutoRepeatOn"><code class="function">XAutoRepeatOn</code></a></td><td align="left"><code class="systemitem">ChangeKeyboardControl</code></td></tr><tr><td align="left"><a class="xref" href="#XBell"><code class="function">XBell</code></a></td><td align="left"><code class="systemitem">Bell</code></td></tr><tr><td align="left"><a class="xref" href="#XChangeActivePointerGrab"><code class="function">XChangeActivePointerGrab</code></a></td><td align="left"><code class="systemitem">ChangeActivePointerGrab</code></td></tr><tr><td align="left"><a class="xref" href="#XChangeGC"><code class="function">XChangeGC</code></a></td><td align="left"><code class="systemitem">ChangeGC</code></td></tr><tr><td align="left"><a class="xref" href="#XChangeKeyboardControl"><code class="function">XChangeKeyboardControl</code></a></td><td align="left"><code class="systemitem">ChangeKeyboardControl</code></td></tr><tr><td align="left"><a class="xref" href="#XChangeKeyboardMapping"><code class="function">XChangeKeyboardMapping</code></a></td><td align="left"><code class="systemitem">ChangeKeyboardMapping</code></td></tr><tr><td align="left"><a class="xref" href="#XChangePointerControl"><code class="function">XChangePointerControl</code></a></td><td align="left"><code class="systemitem">ChangePointerControl</code></td></tr><tr><td align="left"><a class="xref" href="#XChangeProperty"><code class="function">XChangeProperty</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XChangeSaveSet"><code class="function">XChangeSaveSet</code></a></td><td align="left"><code class="systemitem">ChangeSaveSet</code></td></tr><tr><td align="left"><a class="xref" href="#XChangeWindowAttributes"><code class="function">XChangeWindowAttributes</code></a></td><td align="left"><code class="systemitem">ChangeWindowAttributes</code></td></tr><tr><td align="left"><a class="xref" href="#XCirculateSubwindows"><code class="function">XCirculateSubwindows</code></a></td><td align="left"><code class="systemitem">CirculateWindow</code></td></tr><tr><td align="left"><a class="xref" href="#XCirculateSubwindowsDown"><code class="function">XCirculateSubwindowsDown</code></a></td><td align="left"><code class="systemitem">CirculateWindow</code></td></tr><tr><td align="left"><a class="xref" href="#XCirculateSubwindowsUp"><code class="function">XCirculateSubwindowsUp</code></a></td><td align="left"><code class="systemitem">CirculateWindow</code></td></tr><tr><td align="left"><a class="xref" href="#XClearArea"><code class="function">XClearArea</code></a></td><td align="left"><code class="systemitem">ClearArea</code></td></tr><tr><td align="left"><a class="xref" href="#XClearWindow"><code class="function">XClearWindow</code></a></td><td align="left"><code class="systemitem">ClearArea</code></td></tr><tr><td align="left"><a class="xref" href="#XConfigureWindow"><code class="function">XConfigureWindow</code></a></td><td align="left"><code class="systemitem">ConfigureWindow</code></td></tr><tr><td align="left"><a class="xref" href="#XConvertSelection"><code class="function">XConvertSelection</code></a></td><td align="left"><code class="systemitem">ConvertSelection</code></td></tr><tr><td align="left"><a class="xref" href="#XCopyArea"><code class="function">XCopyArea</code></a></td><td align="left"><code class="systemitem">CopyArea</code></td></tr><tr><td align="left"><a class="xref" href="#XCopyColormapAndFree"><code class="function">XCopyColormapAndFree</code></a></td><td align="left"><code class="systemitem">CopyColormapAndFree</code></td></tr><tr><td align="left"><a class="xref" href="#XCopyGC"><code class="function">XCopyGC</code></a></td><td align="left"><code class="systemitem">CopyGC</code></td></tr><tr><td align="left"><a class="xref" href="#XCopyPlane"><code class="function">XCopyPlane</code></a></td><td align="left"><code class="systemitem">CopyPlane</code></td></tr><tr><td rowspan="4" align="left"><a class="xref" href="#XCreateBitmapFromData"><code class="function">XCreateBitmapFromData</code></a></td><td align="left"><code class="systemitem">CreateGC</code></td></tr><tr><td align="left"><code class="systemitem">CreatePixmap</code></td></tr><tr><td align="left"><code class="systemitem">FreeGC</code></td></tr><tr><td align="left"><code class="systemitem">PutImage</code></td></tr><tr><td align="left"><a class="xref" href="#XCreateColormap"><code class="function">XCreateColormap</code></a></td><td align="left"><code class="systemitem">CreateColormap</code></td></tr><tr><td align="left"><a class="xref" href="#XCreateFontCursor"><code class="function">XCreateFontCursor</code></a></td><td align="left"><code class="systemitem">CreateGlyphCursor</code></td></tr><tr><td align="left"><a class="xref" href="#XCreateGC"><code class="function">XCreateGC</code></a></td><td align="left"><code class="systemitem">CreateGC</code></td></tr><tr><td align="left"><a class="xref" href="#XCreateGlyphCursor"><code class="function">XCreateGlyphCursor</code></a></td><td align="left"><code class="systemitem">CreateGlyphCursor</code></td></tr><tr><td align="left"><a class="xref" href="#XCreatePixmap"><code class="function">XCreatePixmap</code></a></td><td align="left"><code class="systemitem">CreatePixmap</code></td></tr><tr><td align="left"><a class="xref" href="#XCreatePixmapCursor"><code class="function">XCreatePixmapCursor</code></a></td><td align="left"><code class="systemitem">CreateCursor</code></td></tr><tr><td rowspan="4" align="left"><code class="function">XCreatePixmapFromData</code></td><td align="left"><code class="systemitem">CreateGC</code></td></tr><tr><td align="left"><code class="systemitem">CreatePixmap</code></td></tr><tr><td align="left"><code class="systemitem">FreeGC</code></td></tr><tr><td align="left"><code class="systemitem">PutImage</code></td></tr><tr><td align="left"><a class="xref" href="#XCreateSimpleWindow"><code class="function">XCreateSimpleWindow</code></a></td><td align="left"><code class="systemitem">CreateWindow</code></td></tr><tr><td align="left"><a class="xref" href="#XCreateWindow"><code class="function">XCreateWindow</code></a></td><td align="left"><code class="systemitem">CreateWindow</code></td></tr><tr><td align="left"><a class="xref" href="#XDefineCursor"><code class="function">XDefineCursor</code></a></td><td align="left"><code class="systemitem">ChangeWindowAttributes</code></td></tr><tr><td align="left"><a class="xref" href="#XDeleteProperty"><code class="function">XDeleteProperty</code></a></td><td align="left"><code class="systemitem">DeleteProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XDestroySubwindows"><code class="function">XDestroySubwindows</code></a></td><td align="left"><code class="systemitem">DestroySubwindows</code></td></tr><tr><td align="left"><a class="xref" href="#XDestroyWindow"><code class="function">XDestroyWindow</code></a></td><td align="left"><code class="systemitem">DestroyWindow</code></td></tr><tr><td align="left"><a class="xref" href="#XDisableAccessControl"><code class="function">XDisableAccessControl</code></a></td><td align="left"><code class="systemitem">SetAccessControl</code></td></tr><tr><td align="left"><a class="xref" href="#XDrawArc"><code class="function">XDrawArc</code></a></td><td align="left"><code class="systemitem">PolyArc</code></td></tr><tr><td align="left"><a class="xref" href="#XDrawArcs"><code class="function">XDrawArcs</code></a></td><td align="left"><code class="systemitem">PolyArc</code></td></tr><tr><td align="left"><a class="xref" href="#XDrawImageString"><code class="function">XDrawImageString</code></a></td><td align="left"><code class="systemitem">ImageText8</code></td></tr><tr><td align="left"><a class="xref" href="#XDrawImageString16"><code class="function">XDrawImageString16</code></a></td><td align="left"><code class="systemitem">ImageText16</code></td></tr><tr><td align="left"><a class="xref" href="#XDrawLine"><code class="function">XDrawLine</code></a></td><td align="left"><code class="systemitem">PolySegment</code></td></tr><tr><td align="left"><a class="xref" href="#XDrawLines"><code class="function">XDrawLines</code></a></td><td align="left"><code class="systemitem">PolyLine</code></td></tr><tr><td align="left"><a class="xref" href="#XDrawPoint"><code class="function">XDrawPoint</code></a></td><td align="left"><code class="systemitem">PolyPoint</code></td></tr><tr><td align="left"><a class="xref" href="#XDrawPoints"><code class="function">XDrawPoints</code></a></td><td align="left"><code class="systemitem">PolyPoint</code></td></tr><tr><td align="left"><a class="xref" href="#XDrawRectangle"><code class="function">XDrawRectangle</code></a></td><td align="left"><code class="systemitem">PolyRectangle</code></td></tr><tr><td align="left"><a class="xref" href="#XDrawRectangles"><code class="function">XDrawRectangles</code></a></td><td align="left"><code class="systemitem">PolyRectangle</code></td></tr><tr><td align="left"><a class="xref" href="#XDrawSegments"><code class="function">XDrawSegments</code></a></td><td align="left"><code class="systemitem">PolySegment</code></td></tr><tr><td align="left"><a class="xref" href="#XDrawString"><code class="function">XDrawString</code></a></td><td align="left"><code class="systemitem">PolyText8</code></td></tr><tr><td align="left"><a class="xref" href="#XDrawString16"><code class="function">XDrawString16</code></a></td><td align="left"><code class="systemitem">PolyText16</code></td></tr><tr><td align="left"><a class="xref" href="#XDrawText"><code class="function">XDrawText</code></a></td><td align="left"><code class="systemitem">PolyText8</code></td></tr><tr><td align="left"><a class="xref" href="#XDrawText16"><code class="function">XDrawText16</code></a></td><td align="left"><code class="systemitem">PolyText16</code></td></tr><tr><td align="left"><a class="xref" href="#XEnableAccessControl"><code class="function">XEnableAccessControl</code></a></td><td align="left"><code class="systemitem">SetAccessControl</code></td></tr><tr><td align="left"><a class="xref" href="#XFetchBytes"><code class="function">XFetchBytes</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XFetchName"><code class="function">XFetchName</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XFillArc"><code class="function">XFillArc</code></a></td><td align="left"><code class="systemitem">PolyFillArc</code></td></tr><tr><td align="left"><a class="xref" href="#XFillArcs"><code class="function">XFillArcs</code></a></td><td align="left"><code class="systemitem">PolyFillArc</code></td></tr><tr><td align="left"><a class="xref" href="#XFillPolygon"><code class="function">XFillPolygon</code></a></td><td align="left"><code class="systemitem">FillPoly</code></td></tr><tr><td align="left"><a class="xref" href="#XFillRectangle"><code class="function">XFillRectangle</code></a></td><td align="left"><code class="systemitem">PolyFillRectangle</code></td></tr><tr><td align="left"><a class="xref" href="#XFillRectangles"><code class="function">XFillRectangles</code></a></td><td align="left"><code class="systemitem">PolyFillRectangle</code></td></tr><tr><td align="left"><a class="xref" href="#XForceScreenSaver"><code class="function">XForceScreenSaver</code></a></td><td align="left"><code class="systemitem">ForceScreenSaver</code></td></tr><tr><td align="left"><a class="xref" href="#XFreeColormap"><code class="function">XFreeColormap</code></a></td><td align="left"><code class="systemitem">FreeColormap</code></td></tr><tr><td align="left"><a class="xref" href="#XFreeColors"><code class="function">XFreeColors</code></a></td><td align="left"><code class="systemitem">FreeColors</code></td></tr><tr><td align="left"><a class="xref" href="#XFreeCursor"><code class="function">XFreeCursor</code></a></td><td align="left"><code class="systemitem">FreeCursor</code></td></tr><tr><td align="left"><a class="xref" href="#XFreeFont"><code class="function">XFreeFont</code></a></td><td align="left"><code class="systemitem">CloseFont</code></td></tr><tr><td align="left"><a class="xref" href="#XFreeGC"><code class="function">XFreeGC</code></a></td><td align="left"><code class="systemitem">FreeGC</code></td></tr><tr><td align="left"><a class="xref" href="#XFreePixmap"><code class="function">XFreePixmap</code></a></td><td align="left"><code class="systemitem">FreePixmap</code></td></tr><tr><td align="left"><a class="xref" href="#XGetAtomName"><code class="function">XGetAtomName</code></a></td><td align="left"><code class="systemitem">GetAtomName</code></td></tr><tr><td align="left"><a class="xref" href="#XGetClassHint"><code class="function">XGetClassHint</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XGetFontPath"><code class="function">XGetFontPath</code></a></td><td align="left"><code class="systemitem">GetFontPath</code></td></tr><tr><td align="left"><a class="xref" href="#XGetGeometry"><code class="function">XGetGeometry</code></a></td><td align="left"><code class="systemitem">GetGeometry</code></td></tr><tr><td align="left"><a class="xref" href="#XGetIconName"><code class="function">XGetIconName</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XGetIconSizes"><code class="function">XGetIconSizes</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XGetImage"><code class="function">XGetImage</code></a></td><td align="left"><code class="systemitem">GetImage</code></td></tr><tr><td align="left"><a class="xref" href="#XGetInputFocus"><code class="function">XGetInputFocus</code></a></td><td align="left"><code class="systemitem">GetInputFocus</code></td></tr><tr><td align="left"><a class="xref" href="#XGetKeyboardControl"><code class="function">XGetKeyboardControl</code></a></td><td align="left"><code class="systemitem">GetKeyboardControl</code></td></tr><tr><td align="left"><a class="xref" href="#XGetKeyboardMapping"><code class="function">XGetKeyboardMapping</code></a></td><td align="left"><code class="systemitem">GetKeyboardMapping</code></td></tr><tr><td align="left"><a class="xref" href="#XGetModifierMapping"><code class="function">XGetModifierMapping</code></a></td><td align="left"><code class="systemitem">GetModifierMapping</code></td></tr><tr><td align="left"><a class="xref" href="#XGetMotionEvents"></a></td><td align="left"><code class="systemitem">GetMotionEvents</code></td></tr><tr><td align="left"><a class="xref" href="#XGetNormalHints"><code class="function">XGetNormalHints</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XGetPointerControl"><code class="function">XGetPointerControl</code></a></td><td align="left"><code class="systemitem">GetPointerControl</code></td></tr><tr><td align="left"><a class="xref" href="#XGetPointerMapping"><code class="function">XGetPointerMapping</code></a></td><td align="left"><code class="systemitem">GetPointerMapping</code></td></tr><tr><td align="left"><a class="xref" href="#XGetRGBColormaps"><code class="function">XGetRGBColormaps</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XGetScreenSaver"><code class="function">XGetScreenSaver</code></a></td><td align="left"><code class="systemitem">GetScreenSaver</code></td></tr><tr><td align="left"><a class="xref" href="#XGetSelectionOwner"><code class="function">XGetSelectionOwner</code></a></td><td align="left"><code class="systemitem">GetSelectionOwner</code></td></tr><tr><td align="left"><a class="xref" href="#XGetSizeHints"><code class="function">XGetSizeHints</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XGetTextProperty"><code class="function">XGetTextProperty</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XGetTransientForHint"><code class="function">XGetTransientForHint</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XGetWMClientMachine"><code class="function">XGetWMClientMachine</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td rowspan="2" align="left"><a class="xref" href="#XGetWMColormapWindows"><code class="function">XGetWMColormapWindows</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td align="left"><code class="systemitem">InternAtom</code></td></tr><tr><td align="left"><a class="xref" href="#XGetWMHints"><code class="function">XGetWMHints</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XGetWMIconName"><code class="function">XGetWMIconName</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XGetWMName"><code class="function">XGetWMName</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XGetWMNormalHints"><code class="function">XGetWMNormalHints</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td rowspan="2" align="left"><a class="xref" href="#XGetWMProtocols"><code class="function">XGetWMProtocols</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td align="left"><code class="systemitem">InternAtom</code></td></tr><tr><td align="left"><a class="xref" href="#XGetWMSizeHints"><code class="function">XGetWMSizeHints</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td rowspan="2" align="left"><a class="xref" href="#XGetWindowAttributes"><code class="function">XGetWindowAttributes</code></a></td><td align="left"><code class="systemitem">GetWindowAttributes</code></td></tr><tr><td align="left"><code class="systemitem">GetGeometry</code></td></tr><tr><td align="left"><a class="xref" href="#XGetWindowProperty"><code class="function">XGetWindowProperty</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XGetZoomHints"><code class="function">XGetZoomHints</code></a></td><td align="left"><code class="systemitem">GetProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XGrabButton"><code class="function">XGrabButton</code></a></td><td align="left"><code class="systemitem">GrabButton</code></td></tr><tr><td align="left"><a class="xref" href="#XGrabKey"><code class="function">XGrabKey</code></a></td><td align="left"><code class="systemitem">GrabKey</code></td></tr><tr><td align="left"><a class="xref" href="#XGrabKeyboard"><code class="function">XGrabKeyboard</code></a></td><td align="left"><code class="systemitem">GrabKeyboard</code></td></tr><tr><td align="left"><a class="xref" href="#XGrabPointer"><code class="function">XGrabPointer</code></a></td><td align="left"><code class="systemitem">GrabPointer</code></td></tr><tr><td align="left"><a class="xref" href="#XGrabServer"><code class="function">XGrabServer</code></a></td><td align="left"><code class="systemitem">GrabServer</code></td></tr><tr><td rowspan="2" align="left"><a class="xref" href="#XIconifyWindow"><code class="function">XIconifyWindow</code></a></td><td align="left"><code class="systemitem">InternAtom</code></td></tr><tr><td align="left"><code class="systemitem">SendEvent</code></td></tr><tr><td align="left"><a class="xref" href="#XInitExtension"><code class="function">XInitExtension</code></a></td><td align="left"><code class="systemitem">QueryExtension</code></td></tr><tr><td align="left"><a class="xref" href="#XInstallColormap"><code class="function">XInstallColormap</code></a></td><td align="left"><code class="systemitem">InstallColormap</code></td></tr><tr><td align="left"><a class="xref" href="#XInternAtom"><code class="function">XInternAtom</code></a></td><td align="left"><code class="systemitem">InternAtom</code></td></tr><tr><td align="left"><a class="xref" href="#XKillClient"><code class="function">XKillClient</code></a></td><td align="left"><code class="systemitem">KillClient</code></td></tr><tr><td align="left"><a class="xref" href="#XListExtensions"><code class="function">XListExtensions</code></a></td><td align="left"><code class="systemitem">ListExtensions</code></td></tr><tr><td align="left"><a class="xref" href="#XListFonts"><code class="function">XListFonts</code></a></td><td align="left"><code class="systemitem">ListFonts</code></td></tr><tr><td align="left"><a class="xref" href="#XListFontsWithInfo"><code class="function">XListFontsWithInfo</code></a></td><td align="left"><code class="systemitem">ListFontsWithInfo</code></td></tr><tr><td align="left"><a class="xref" href="#XListHosts"><code class="function">XListHosts</code></a></td><td align="left"><code class="systemitem">ListHosts</code></td></tr><tr><td align="left"><a class="xref" href="#XListInstalledColormaps"><code class="function">XListInstalledColormaps</code></a></td><td align="left"><code class="systemitem">ListInstalledColormaps</code></td></tr><tr><td align="left"><a class="xref" href="#XListProperties"><code class="function">XListProperties</code></a></td><td align="left"><code class="systemitem">ListProperties</code></td></tr><tr><td align="left"><a class="xref" href="#XLoadFont"><code class="function">XLoadFont</code></a></td><td align="left"><code class="systemitem">OpenFont</code></td></tr><tr><td rowspan="2" align="left"><a class="xref" href="#XLoadQueryFont"><code class="function">XLoadQueryFont</code></a></td><td align="left"><code class="systemitem">OpenFont</code></td></tr><tr><td align="left"><code class="systemitem">QueryFont</code></td></tr><tr><td align="left"><a class="xref" href="#XLookupColor"><code class="function">XLookupColor</code></a></td><td align="left"><code class="systemitem">LookupColor</code></td></tr><tr><td align="left"><a class="xref" href="#XLowerWindow"><code class="function">XLowerWindow</code></a></td><td align="left"><code class="systemitem">ConfigureWindow</code></td></tr><tr><td rowspan="2" align="left"><a class="xref" href="#XMapRaised"><code class="function">XMapRaised</code></a></td><td align="left"><code class="systemitem">ConfigureWindow</code></td></tr><tr><td align="left"><code class="systemitem">MapWindow</code></td></tr><tr><td align="left"><a class="xref" href="#XMapSubwindows"><code class="function">XMapSubwindows</code></a></td><td align="left"><code class="systemitem">MapSubwindows</code></td></tr><tr><td align="left"><a class="xref" href="#XMapWindow"><code class="function">XMapWindow</code></a></td><td align="left"><code class="systemitem">MapWindow</code></td></tr><tr><td align="left"><a class="xref" href="#XMoveResizeWindow"><code class="function">XMoveResizeWindow</code></a></td><td align="left"><code class="systemitem">ConfigureWindow</code></td></tr><tr><td align="left"><a class="xref" href="#XMoveWindow"><code class="function">XMoveWindow</code></a></td><td align="left"><code class="systemitem">ConfigureWindow</code></td></tr><tr><td align="left"><a class="xref" href="#XNoOp"><code class="function">XNoOp</code></a></td><td align="left"><code class="systemitem">NoOperation</code></td></tr><tr><td align="left"><a class="xref" href="#XOpenDisplay"><code class="function">XOpenDisplay</code></a></td><td align="left"><code class="systemitem">CreateGC</code></td></tr><tr><td align="left"><a class="xref" href="#XParseColor"><code class="function">XParseColor</code></a></td><td align="left"><code class="systemitem">LookupColor</code></td></tr><tr><td align="left"><a class="xref" href="#XPutImage"><code class="function">XPutImage</code></a></td><td align="left"><code class="systemitem">PutImage</code></td></tr><tr><td align="left"><a class="xref" href="#XQueryBestCursor"><code class="function">XQueryBestCursor</code></a></td><td align="left"><code class="systemitem">QueryBestSize</code></td></tr><tr><td align="left"><a class="xref" href="#XQueryBestSize"><code class="function">XQueryBestSize</code></a></td><td align="left"><code class="systemitem">QueryBestSize</code></td></tr><tr><td align="left"><a class="xref" href="#XQueryBestStipple"><code class="function">XQueryBestStipple</code></a></td><td align="left"><code class="systemitem">QueryBestSize</code></td></tr><tr><td align="left"><a class="xref" href="#XQueryBestTile"><code class="function">XQueryBestTile</code></a></td><td align="left"><code class="systemitem">QueryBestSize</code></td></tr><tr><td align="left"><a class="xref" href="#XQueryColor"><code class="function">XQueryColor</code></a></td><td align="left"><code class="systemitem">QueryColors</code></td></tr><tr><td align="left"><a class="xref" href="#XQueryColors"><code class="function">XQueryColors</code></a></td><td align="left"><code class="systemitem">QueryColors</code></td></tr><tr><td align="left"><a class="xref" href="#XQueryExtension"><code class="function">XQueryExtension</code></a></td><td align="left"><code class="systemitem">QueryExtension</code></td></tr><tr><td align="left"><a class="xref" href="#XQueryFont"><code class="function">XQueryFont</code></a></td><td align="left"><code class="systemitem">QueryFont</code></td></tr><tr><td align="left"><a class="xref" href="#XQueryKeymap"><code class="function">XQueryKeymap</code></a></td><td align="left"><code class="systemitem">QueryKeymap</code></td></tr><tr><td align="left"><a class="xref" href="#XQueryPointer"><code class="function">XQueryPointer</code></a></td><td align="left"><code class="systemitem">QueryPointer</code></td></tr><tr><td align="left"><a class="xref" href="#XQueryTextExtents"><code class="function">XQueryTextExtents</code></a></td><td align="left"><code class="systemitem">QueryTextExtents</code></td></tr><tr><td align="left"><a class="xref" href="#XQueryTextExtents16"><code class="function">XQueryTextExtents16</code></a></td><td align="left"><code class="systemitem">QueryTextExtents</code></td></tr><tr><td align="left"><a class="xref" href="#XQueryTree"><code class="function">XQueryTree</code></a></td><td align="left"><code class="systemitem">QueryTree</code></td></tr><tr><td align="left"><a class="xref" href="#XRaiseWindow"><code class="function">XRaiseWindow</code></a></td><td align="left"><code class="systemitem">ConfigureWindow</code></td></tr><tr><td rowspan="4" align="left"><a class="xref" href="#XReadBitmapFile"><code class="function">XReadBitmapFile</code></a></td><td align="left"><code class="systemitem">CreateGC</code></td></tr><tr><td align="left"><code class="systemitem">CreatePixmap</code></td></tr><tr><td align="left"><code class="systemitem">FreeGC</code></td></tr><tr><td align="left"><code class="systemitem">PutImage</code></td></tr><tr><td align="left"><a class="xref" href="#XRecolorCursor"><code class="function">XRecolorCursor</code></a></td><td align="left"><code class="systemitem">RecolorCursor</code></td></tr><tr><td rowspan="2" align="left"><a class="xref" href="#XReconfigureWMWindow"><code class="function">XReconfigureWMWindow</code></a></td><td align="left"><code class="systemitem">ConfigureWindow</code></td></tr><tr><td align="left"><code class="systemitem">SendEvent</code></td></tr><tr><td align="left"><a class="xref" href="#XRemoveFromSaveSet"><code class="function">XRemoveFromSaveSet</code></a></td><td align="left"><code class="systemitem">ChangeSaveSet</code></td></tr><tr><td align="left"><a class="xref" href="#XRemoveHost"><code class="function">XRemoveHost</code></a></td><td align="left"><code class="systemitem">ChangeHosts</code></td></tr><tr><td align="left"><a class="xref" href="#XRemoveHosts"><code class="function">XRemoveHosts</code></a></td><td align="left"><code class="systemitem">ChangeHosts</code></td></tr><tr><td align="left"><a class="xref" href="#XReparentWindow"><code class="function">XReparentWindow</code></a></td><td align="left"><code class="systemitem">ReparentWindow</code></td></tr><tr><td align="left"><a class="xref" href="#XResetScreenSaver"><code class="function">XResetScreenSaver</code></a></td><td align="left"><code class="systemitem">ForceScreenSaver</code></td></tr><tr><td align="left"><a class="xref" href="#XResizeWindow"><code class="function">XResizeWindow</code></a></td><td align="left"><code class="systemitem">ConfigureWindow</code></td></tr><tr><td align="left"><a class="xref" href="#XRestackWindows"><code class="function">XRestackWindows</code></a></td><td align="left"><code class="systemitem">ConfigureWindow</code></td></tr><tr><td align="left"><a class="xref" href="#XRotateBuffers"><code class="function">XRotateBuffers</code></a></td><td align="left"><code class="systemitem">RotateProperties</code></td></tr><tr><td align="left"><a class="xref" href="#XRotateWindowProperties"><code class="function">XRotateWindowProperties</code></a></td><td align="left"><code class="systemitem">RotateProperties</code></td></tr><tr><td align="left"><a class="xref" href="#XSelectInput"><code class="function">XSelectInput</code></a></td><td align="left"><code class="systemitem">ChangeWindowAttributes</code></td></tr><tr><td align="left"><a class="xref" href="#XSendEvent"><code class="function">XSendEvent</code></a></td><td align="left"><code class="systemitem">SendEvent</code></td></tr><tr><td align="left"><a class="xref" href="#XSetAccessControl"><code class="function">XSetAccessControl</code></a></td><td align="left"><code class="systemitem">SetAccessControl</code></td></tr><tr><td align="left"><a class="xref" href="#XSetArcMode"><code class="function">XSetArcMode</code></a></td><td align="left"><code class="systemitem">ChangeGC</code></td></tr><tr><td align="left"><a class="xref" href="#XSetBackground"><code class="function">XSetBackground</code></a></td><td align="left"><code class="systemitem">ChangeGC</code></td></tr><tr><td align="left"><a class="xref" href="#XSetClassHint"><code class="function">XSetClassHint</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XSetClipMask"><code class="function">XSetClipMask</code></a></td><td align="left"><code class="systemitem">ChangeGC</code></td></tr><tr><td align="left"><a class="xref" href="#XSetClipOrigin"><code class="function">XSetClipOrigin</code></a></td><td align="left"><code class="systemitem">ChangeGC</code></td></tr><tr><td align="left"><a class="xref" href="#XSetClipRectangles"><code class="function">XSetClipRectangles</code></a></td><td align="left"><code class="systemitem">SetClipRectangles</code></td></tr><tr><td align="left"><a class="xref" href="#XSetCloseDownMode"></a></td><td align="left"><code class="systemitem">SetCloseDownMode</code></td></tr><tr><td align="left"><a class="xref" href="#XSetCommand"><code class="function">XSetCommand</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XSetDashes"><code class="function">XSetDashes</code></a></td><td align="left"><code class="systemitem">SetDashes</code></td></tr><tr><td align="left"><a class="xref" href="#XSetFillRule"><code class="function">XSetFillRule</code></a></td><td align="left"><code class="systemitem">ChangeGC</code></td></tr><tr><td align="left"><a class="xref" href="#XSetFillStyle"><code class="function">XSetFillStyle</code></a></td><td align="left"><code class="systemitem">ChangeGC</code></td></tr><tr><td align="left"><a class="xref" href="#XSetFont"><code class="function">XSetFont</code></a></td><td align="left"><code class="systemitem">ChangeGC</code></td></tr><tr><td align="left"><a class="xref" href="#XSetFontPath"><code class="function">XSetFontPath</code></a></td><td align="left"><code class="systemitem">SetFontPath</code></td></tr><tr><td align="left"><a class="xref" href="#XSetForeground"><code class="function">XSetForeground</code></a></td><td align="left"><code class="systemitem">ChangeGC</code></td></tr><tr><td align="left"><a class="xref" href="#XSetFunction"><code class="function">XSetFunction</code></a></td><td align="left"><code class="systemitem">ChangeGC</code></td></tr><tr><td align="left"><a class="xref" href="#XSetGraphicsExposures"><code class="function">XSetGraphicsExposures</code></a></td><td align="left"><code class="systemitem">ChangeGC</code></td></tr><tr><td align="left"><a class="xref" href="#XSetIconName"><code class="function">XSetIconName</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XSetIconSizes"><code class="function">XSetIconSizes</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XSetInputFocus"><code class="function">XSetInputFocus</code></a></td><td align="left"><code class="systemitem">SetInputFocus</code></td></tr><tr><td align="left"><a class="xref" href="#XSetLineAttributes"><code class="function">XSetLineAttributes</code></a></td><td align="left"><code class="systemitem">ChangeGC</code></td></tr><tr><td align="left"><a class="xref" href="#XSetModifierMapping"><code class="function">XSetModifierMapping</code></a></td><td align="left"><code class="systemitem">SetModifierMapping</code></td></tr><tr><td align="left"><a class="xref" href="#XSetNormalHints"><code class="function">XSetNormalHints</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XSetPlaneMask"><code class="function">XSetPlaneMask</code></a></td><td align="left"><code class="systemitem">ChangeGC</code></td></tr><tr><td align="left"><a class="xref" href="#XSetPointerMapping"><code class="function">XSetPointerMapping</code></a></td><td align="left"><code class="systemitem">SetPointerMapping</code></td></tr><tr><td align="left"><a class="xref" href="#XSetRGBColormaps"><code class="function">XSetRGBColormaps</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XSetScreenSaver"><code class="function">XSetScreenSaver</code></a></td><td align="left"><code class="systemitem">SetScreenSaver</code></td></tr><tr><td align="left"><a class="xref" href="#XSetSelectionOwner"><code class="function">XSetSelectionOwner</code></a></td><td align="left"><code class="systemitem">SetSelectionOwner</code></td></tr><tr><td align="left"><a class="xref" href="#XSetSizeHints"><code class="function">XSetSizeHints</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XSetStandardProperties"><code class="function">XSetStandardProperties</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XSetState"><code class="function">XSetState</code></a></td><td align="left"><code class="systemitem">ChangeGC</code></td></tr><tr><td align="left"><a class="xref" href="#XSetStipple"><code class="function">XSetStipple</code></a></td><td align="left"><code class="systemitem">ChangeGC</code></td></tr><tr><td align="left"><a class="xref" href="#XSetSubwindowMode"><code class="function">XSetSubwindowMode</code></a></td><td align="left"><code class="systemitem">ChangeGC</code></td></tr><tr><td align="left"><a class="xref" href="#XSetTextProperty"><code class="function">XSetTextProperty</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XSetTile"><code class="function">XSetTile</code></a></td><td align="left"><code class="systemitem">ChangeGC</code></td></tr><tr><td align="left"><a class="xref" href="#XSetTransientForHint"><code class="function">XSetTransientForHint</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XSetTSOrigin"><code class="function">XSetTSOrigin</code></a></td><td align="left"><code class="systemitem">ChangeGC</code></td></tr><tr><td align="left"><a class="xref" href="#XSetWMClientMachine"><code class="function">XSetWMClientMachine</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td rowspan="2" align="left"><a class="xref" href="#XSetWMColormapWindows"><code class="function">XSetWMColormapWindows</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><code class="systemitem">InternAtom</code></td></tr><tr><td align="left"><a class="xref" href="#XSetWMHints"><code class="function">XSetWMHints</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XSetWMIconName"><code class="function">XSetWMIconName</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XSetWMName"><code class="function">XSetWMName</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XSetWMNormalHints"><code class="function">XSetWMNormalHints</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XSetWMProperties"><code class="function">XSetWMProperties</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td rowspan="2" align="left"><a class="xref" href="#XSetWMProtocols"><code class="function">XSetWMProtocols</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><code class="systemitem">InternAtom</code></td></tr><tr><td align="left"><a class="xref" href="#XSetWMSizeHints"><code class="function">XSetWMSizeHints</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XSetWindowBackground"><code class="function">XSetWindowBackground</code></a></td><td align="left"><code class="systemitem">ChangeWindowAttributes</code></td></tr><tr><td align="left"><a class="xref" href="#XSetWindowBackgroundPixmap"><code class="function">XSetWindowBackgroundPixmap</code></a></td><td align="left"><code class="systemitem">ChangeWindowAttributes</code></td></tr><tr><td align="left"><a class="xref" href="#XSetWindowBorder"><code class="function">XSetWindowBorder</code></a></td><td align="left"><code class="systemitem">ChangeWindowAttributes</code></td></tr><tr><td align="left"><a class="xref" href="#XSetWindowBorderPixmap"><code class="function">XSetWindowBorderPixmap</code></a></td><td align="left"><code class="systemitem">ChangeWindowAttributes</code></td></tr><tr><td align="left"><a class="xref" href="#XSetWindowBorderWidth"><code class="function">XSetWindowBorderWidth</code></a></td><td align="left"><code class="systemitem">ConfigureWindow</code></td></tr><tr><td align="left"><a class="xref" href="#XSetWindowColormap"><code class="function">XSetWindowColormap</code></a></td><td align="left"><code class="systemitem">ChangeWindowAttributes</code></td></tr><tr><td align="left"><a class="xref" href="#XSetZoomHints"><code class="function">XSetZoomHints</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XStoreBuffer"><code class="function">XStoreBuffer</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XStoreBytes"><code class="function">XStoreBytes</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XStoreColor"><code class="function">XStoreColor</code></a></td><td align="left"><code class="systemitem">StoreColors</code></td></tr><tr><td align="left"><a class="xref" href="#XStoreColors"><code class="function">XStoreColors</code></a></td><td align="left"><code class="systemitem">StoreColors</code></td></tr><tr><td align="left"><a class="xref" href="#XStoreName"><code class="function">XStoreName</code></a></td><td align="left"><code class="systemitem">ChangeProperty</code></td></tr><tr><td align="left"><a class="xref" href="#XStoreNamedColor"><code class="function">XStoreNamedColor</code></a></td><td align="left"><code class="systemitem">StoreNamedColor</code></td></tr><tr><td align="left"><a class="xref" href="#XSync"><code class="function">XSync</code></a></td><td align="left"><code class="systemitem">GetInputFocus</code></td></tr><tr><td align="left"><code class="function">XSynchronize</code></td><td align="left"><code class="systemitem">GetInputFocus</code></td></tr><tr><td align="left"><a class="xref" href="#XTranslateCoordinates"><code class="function">XTranslateCoordinates</code></a></td><td align="left"><code class="systemitem">TranslateCoordinates</code></td></tr><tr><td align="left"><a class="xref" href="#XUndefineCursor"><code class="function">XUndefineCursor</code></a></td><td align="left"><code class="systemitem">ChangeWindowAttributes</code></td></tr><tr><td align="left"><a class="xref" href="#XUngrabButton"><code class="function">XUngrabButton</code></a></td><td align="left"><code class="systemitem">UngrabButton</code></td></tr><tr><td align="left"><a class="xref" href="#XUngrabKey"><code class="function">XUngrabKey</code></a></td><td align="left"><code class="systemitem">UngrabKey</code></td></tr><tr><td align="left"><a class="xref" href="#XUngrabKeyboard"><code class="function">XUngrabKeyboard</code></a></td><td align="left"><code class="systemitem">UngrabKeyboard</code></td></tr><tr><td align="left"><a class="xref" href="#XUngrabPointer"><code class="function">XUngrabPointer</code></a></td><td align="left"><code class="systemitem">UngrabPointer</code></td></tr><tr><td align="left"><a class="xref" href="#XUngrabServer"><code class="function">XUngrabServer</code></a></td><td align="left"><code class="systemitem">UngrabServer</code></td></tr><tr><td align="left"><a class="xref" href="#XUninstallColormap"><code class="function">XUninstallColormap</code></a></td><td align="left"><code class="systemitem">UninstallColormap</code></td></tr><tr><td align="left"><a class="xref" href="#XUnloadFont"><code class="function">XUnloadFont</code></a></td><td align="left"><code class="systemitem">CloseFont</code></td></tr><tr><td align="left"><a class="xref" href="#XUnmapSubwindows"><code class="function">XUnmapSubwindows</code></a></td><td align="left"><code class="systemitem">UnmapSubwindows</code></td></tr><tr><td align="left"><a class="xref" href="#XUnmapWindow"><code class="function">XUnmapWindow</code></a></td><td align="left"><code class="systemitem">UnmapWindow</code></td></tr><tr><td align="left"><a class="xref" href="#XWarpPointer"><code class="function">XWarpPointer</code></a></td><td align="left"><code class="systemitem">WarpPointer</code></td></tr><tr><td rowspan="2" align="left"><a class="xref" href="#XWithdrawWindow"><code class="function">XWithdrawWindow</code></a></td><td align="left"><code class="systemitem">SendEvent</code></td></tr><tr><td align="left"><code class="systemitem">UnmapWindow</code></td></tr></tbody></table></div></div><br class="table-break" /><p>
The following table lists each X protocol request (in alphabetical
order) and the Xlib functions that reference it.
</p><div class="table"><a id="idp53027668"></a><p class="title"><strong>Table A.2. Xlib functions which use each Protocol Request</strong></p><div class="table-contents"><table summary="Xlib functions which use each Protocol Request" border="1"><colgroup><col align="left" class="col1" /><col align="left" class="col2" /></colgroup><thead><tr><th align="left">Protocol Request</th><th align="left">Xlib Function</th></tr></thead><tbody><tr><td align="left"><code class="systemitem">AllocColor</code></td><td align="left"><a class="xref" href="#XAllocColor"><code class="function">XAllocColor</code></a></td></tr><tr><td align="left"><code class="systemitem">AllocColorCells</code></td><td align="left"><a class="xref" href="#XAllocColorCells"><code class="function">XAllocColorCells</code></a></td></tr><tr><td align="left"><code class="systemitem">AllocColorPlanes</code></td><td align="left"><a class="xref" href="#XAllocColorPlanes"><code class="function">XAllocColorPlanes</code></a></td></tr><tr><td align="left"><code class="systemitem">AllocNamedColor</code></td><td align="left"><a class="xref" href="#XAllocNamedColor"><code class="function">XAllocNamedColor</code></a></td></tr><tr><td align="left"><code class="systemitem">AllowEvents</code></td><td align="left"><a class="xref" href="#XAllowEvents"><code class="function">XAllowEvents</code></a></td></tr><tr><td align="left"><code class="systemitem">Bell</code></td><td align="left"><a class="xref" href="#XBell"><code class="function">XBell</code></a></td></tr><tr><td align="left"><code class="systemitem">ChangeActivePointerGrab</code></td><td align="left"><a class="xref" href="#XChangeActivePointerGrab"><code class="function">XChangeActivePointerGrab</code></a></td></tr><tr><td rowspan="18" align="left"><code class="systemitem">ChangeGC</code></td><td align="left"><a class="xref" href="#XChangeGC"><code class="function">XChangeGC</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetArcMode"><code class="function">XSetArcMode</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetBackground"><code class="function">XSetBackground</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetClipMask"><code class="function">XSetClipMask</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetClipOrigin"><code class="function">XSetClipOrigin</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetFillRule"><code class="function">XSetFillRule</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetFillStyle"><code class="function">XSetFillStyle</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetFont"><code class="function">XSetFont</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetForeground"><code class="function">XSetForeground</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetFunction"><code class="function">XSetFunction</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetGraphicsExposures"><code class="function">XSetGraphicsExposures</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetLineAttributes"><code class="function">XSetLineAttributes</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetPlaneMask"><code class="function">XSetPlaneMask</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetState"><code class="function">XSetState</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetStipple"><code class="function">XSetStipple</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetSubwindowMode"><code class="function">XSetSubwindowMode</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetTile"><code class="function">XSetTile</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetTSOrigin"><code class="function">XSetTSOrigin</code></a></td></tr><tr><td rowspan="4" align="left"><code class="systemitem">ChangeHosts</code></td><td align="left"><a class="xref" href="#XAddHost"><code class="function">XAddHost</code></a></td></tr><tr><td align="left"><a class="xref" href="#XAddHosts"><code class="function">XAddHosts</code></a></td></tr><tr><td align="left"><a class="xref" href="#XRemoveHost"><code class="function">XRemoveHost</code></a></td></tr><tr><td align="left"><a class="xref" href="#XRemoveHosts"><code class="function">XRemoveHosts</code></a></td></tr><tr><td rowspan="3" align="left"><code class="systemitem">ChangeKeyboardControl</code></td><td align="left"><a class="xref" href="#XAutoRepeatOff"><code class="function">XAutoRepeatOff</code></a></td></tr><tr><td align="left"><a class="xref" href="#XAutoRepeatOn"><code class="function">XAutoRepeatOn</code></a></td></tr><tr><td align="left"><a class="xref" href="#XChangeKeyboardControl"><code class="function">XChangeKeyboardControl</code></a></td></tr><tr><td align="left"><code class="systemitem">ChangeKeyboardMapping</code></td><td align="left"><a class="xref" href="#XChangeKeyboardMapping"><code class="function">XChangeKeyboardMapping</code></a></td></tr><tr><td align="left"><code class="systemitem">ChangePointerControl</code></td><td align="left"><a class="xref" href="#XChangePointerControl"><code class="function">XChangePointerControl</code></a></td></tr><tr><td rowspan="24" align="left"><code class="systemitem">ChangeProperty</code></td><td align="left"><a class="xref" href="#XChangeProperty"><code class="function">XChangeProperty</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetClassHint"><code class="function">XSetClassHint</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetCommand"><code class="function">XSetCommand</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetIconName"><code class="function">XSetIconName</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetIconSizes"><code class="function">XSetIconSizes</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetNormalHints"><code class="function">XSetNormalHints</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetRGBColormaps"><code class="function">XSetRGBColormaps</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetSizeHints"><code class="function">XSetSizeHints</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetStandardProperties"><code class="function">XSetStandardProperties</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetTextProperty"><code class="function">XSetTextProperty</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetTransientForHint"><code class="function">XSetTransientForHint</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetWMClientMachine"><code class="function">XSetWMClientMachine</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetWMColormapWindows"><code class="function">XSetWMColormapWindows</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetWMHints"><code class="function">XSetWMHints</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetWMIconName"><code class="function">XSetWMIconName</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetWMName"><code class="function">XSetWMName</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetWMNormalHints"><code class="function">XSetWMNormalHints</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetWMProperties"><code class="function">XSetWMProperties</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetWMProtocols"><code class="function">XSetWMProtocols</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetWMSizeHints"><code class="function">XSetWMSizeHints</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetZoomHints"><code class="function">XSetZoomHints</code></a></td></tr><tr><td align="left"><a class="xref" href="#XStoreBuffer"><code class="function">XStoreBuffer</code></a></td></tr><tr><td align="left"><a class="xref" href="#XStoreBytes"><code class="function">XStoreBytes</code></a></td></tr><tr><td align="left"><a class="xref" href="#XStoreName"><code class="function">XStoreName</code></a></td></tr><tr><td rowspan="3" align="left"><code class="systemitem">ChangeSaveSet</code></td><td align="left"><a class="xref" href="#XAddToSaveSet"><code class="function">XAddToSaveSet</code></a></td></tr><tr><td align="left"><a class="xref" href="#XChangeSaveSet"><code class="function">XChangeSaveSet</code></a></td></tr><tr><td align="left"><a class="xref" href="#XRemoveFromSaveSet"><code class="function">XRemoveFromSaveSet</code></a></td></tr><tr><td rowspan="9" align="left"><code class="systemitem">ChangeWindowAttributes</code></td><td align="left"><a class="xref" href="#XChangeWindowAttributes"><code class="function">XChangeWindowAttributes</code></a></td></tr><tr><td align="left"><a class="xref" href="#XDefineCursor"><code class="function">XDefineCursor</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSelectInput"><code class="function">XSelectInput</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetWindowBackground"><code class="function">XSetWindowBackground</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetWindowBackgroundPixmap"><code class="function">XSetWindowBackgroundPixmap</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetWindowBorder"><code class="function">XSetWindowBorder</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetWindowBorderPixmap"><code class="function">XSetWindowBorderPixmap</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetWindowColormap"><code class="function">XSetWindowColormap</code></a></td></tr><tr><td align="left"><a class="xref" href="#XUndefineCursor"><code class="function">XUndefineCursor</code></a></td></tr><tr><td rowspan="3" align="left"><code class="systemitem">CirculateWindow</code></td><td align="left"><a class="xref" href="#XCirculateSubwindowsDown"><code class="function">XCirculateSubwindowsDown</code></a></td></tr><tr><td align="left"><a class="xref" href="#XCirculateSubwindowsUp"><code class="function">XCirculateSubwindowsUp</code></a></td></tr><tr><td align="left"><a class="xref" href="#XCirculateSubwindows"><code class="function">XCirculateSubwindows</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">ClearArea</code></td><td align="left"><a class="xref" href="#XClearArea"><code class="function">XClearArea</code></a></td></tr><tr><td align="left"><a class="xref" href="#XClearWindow"><code class="function">XClearWindow</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">CloseFont</code></td><td align="left"><a class="xref" href="#XFreeFont"><code class="function">XFreeFont</code></a></td></tr><tr><td align="left"><a class="xref" href="#XUnloadFont"><code class="function">XUnloadFont</code></a></td></tr><tr><td rowspan="10" align="left"><code class="systemitem">ConfigureWindow</code></td><td align="left"><a class="xref" href="#XConfigureWindow"><code class="function">XConfigureWindow</code></a></td></tr><tr><td align="left"><a class="xref" href="#XLowerWindow"><code class="function">XLowerWindow</code></a></td></tr><tr><td align="left"><a class="xref" href="#XMapRaised"><code class="function">XMapRaised</code></a></td></tr><tr><td align="left"><a class="xref" href="#XMoveResizeWindow"><code class="function">XMoveResizeWindow</code></a></td></tr><tr><td align="left"><a class="xref" href="#XMoveWindow"><code class="function">XMoveWindow</code></a></td></tr><tr><td align="left"><a class="xref" href="#XRaiseWindow"><code class="function">XRaiseWindow</code></a></td></tr><tr><td align="left"><a class="xref" href="#XReconfigureWMWindow"><code class="function">XReconfigureWMWindow</code></a></td></tr><tr><td align="left"><a class="xref" href="#XResizeWindow"><code class="function">XResizeWindow</code></a></td></tr><tr><td align="left"><a class="xref" href="#XRestackWindows"><code class="function">XRestackWindows</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetWindowBorderWidth"><code class="function">XSetWindowBorderWidth</code></a></td></tr><tr><td align="left"><code class="systemitem">ConvertSelection</code></td><td align="left"><a class="xref" href="#XConvertSelection"><code class="function">XConvertSelection</code></a></td></tr><tr><td align="left"><code class="systemitem">CopyArea</code></td><td align="left"><a class="xref" href="#XCopyArea"><code class="function">XCopyArea</code></a></td></tr><tr><td align="left"><code class="systemitem">CopyColormapAndFree</code></td><td align="left"><a class="xref" href="#XCopyColormapAndFree"><code class="function">XCopyColormapAndFree</code></a></td></tr><tr><td align="left"><code class="systemitem">CopyGC</code></td><td align="left"><a class="xref" href="#XCopyGC"><code class="function">XCopyGC</code></a></td></tr><tr><td align="left"><code class="systemitem">CopyPlane</code></td><td align="left"><a class="xref" href="#XCopyPlane"><code class="function">XCopyPlane</code></a></td></tr><tr><td align="left"><code class="systemitem">CreateColormap</code></td><td align="left"><a class="xref" href="#XCreateColormap"><code class="function">XCreateColormap</code></a></td></tr><tr><td align="left"><code class="systemitem">CreateCursor</code></td><td align="left"><a class="xref" href="#XCreatePixmapCursor"><code class="function">XCreatePixmapCursor</code></a></td></tr><tr><td rowspan="5" align="left"><code class="systemitem">CreateGC</code></td><td align="left"><a class="xref" href="#XCreateGC"><code class="function">XCreateGC</code></a></td></tr><tr><td align="left"><a class="xref" href="#XCreateBitmapFromData"><code class="function">XCreateBitmapFromData</code></a></td></tr><tr><td align="left"><code class="function">XCreatePixmapFromData</code></td></tr><tr><td align="left"><a class="xref" href="#XOpenDisplay"><code class="function">XOpenDisplay</code></a></td></tr><tr><td align="left"><a class="xref" href="#XReadBitmapFile"><code class="function">XReadBitmapFile</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">CreateGlyphCursor</code></td><td align="left"><a class="xref" href="#XCreateFontCursor"><code class="function">XCreateFontCursor</code></a></td></tr><tr><td align="left"><a class="xref" href="#XCreateGlyphCursor"><code class="function">XCreateGlyphCursor</code></a></td></tr><tr><td rowspan="4" align="left"><code class="systemitem">CreatePixmap</code></td><td align="left"><a class="xref" href="#XCreatePixmap"><code class="function">XCreatePixmap</code></a></td></tr><tr><td align="left"><a class="xref" href="#XCreateBitmapFromData"><code class="function">XCreateBitmapFromData</code></a></td></tr><tr><td align="left"><code class="function">XCreatePixmapFromData</code></td></tr><tr><td align="left"><a class="xref" href="#XReadBitmapFile"><code class="function">XReadBitmapFile</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">CreateWindow</code></td><td align="left"><a class="xref" href="#XCreateSimpleWindow"><code class="function">XCreateSimpleWindow</code></a></td></tr><tr><td align="left"><a class="xref" href="#XCreateWindow"><code class="function">XCreateWindow</code></a></td></tr><tr><td align="left"><code class="systemitem">DeleteProperty</code></td><td align="left"><a class="xref" href="#XDeleteProperty"><code class="function">XDeleteProperty</code></a></td></tr><tr><td align="left"><code class="systemitem">DestroySubwindows</code></td><td align="left"><a class="xref" href="#XDestroySubwindows"><code class="function">XDestroySubwindows</code></a></td></tr><tr><td align="left"><code class="systemitem">DestroyWindow</code></td><td align="left"><a class="xref" href="#XDestroyWindow"><code class="function">XDestroyWindow</code></a></td></tr><tr><td align="left"><code class="systemitem">FillPoly</code></td><td align="left"><a class="xref" href="#XFillPolygon"><code class="function">XFillPolygon</code></a></td></tr><tr><td rowspan="3" align="left"><code class="systemitem">ForceScreenSaver</code></td><td align="left"><a class="xref" href="#XActivateScreenSaver"><code class="function">XActivateScreenSaver</code></a></td></tr><tr><td align="left"><a class="xref" href="#XForceScreenSaver"><code class="function">XForceScreenSaver</code></a></td></tr><tr><td align="left"><a class="xref" href="#XResetScreenSaver"><code class="function">XResetScreenSaver</code></a></td></tr><tr><td align="left"><code class="systemitem">FreeColormap</code></td><td align="left"><a class="xref" href="#XFreeColormap"><code class="function">XFreeColormap</code></a></td></tr><tr><td align="left"><code class="systemitem">FreeColors</code></td><td align="left"><a class="xref" href="#XFreeColors"><code class="function">XFreeColors</code></a></td></tr><tr><td align="left"><code class="systemitem">FreeCursor</code></td><td align="left"><a class="xref" href="#XFreeCursor"><code class="function">XFreeCursor</code></a></td></tr><tr><td rowspan="4" align="left"><code class="systemitem">FreeGC</code></td><td align="left"><a class="xref" href="#XFreeGC"><code class="function">XFreeGC</code></a></td></tr><tr><td align="left"><a class="xref" href="#XCreateBitmapFromData"><code class="function">XCreateBitmapFromData</code></a></td></tr><tr><td align="left"><code class="function">XCreatePixmapFromData</code></td></tr><tr><td align="left"><a class="xref" href="#XReadBitmapFile"><code class="function">XReadBitmapFile</code></a></td></tr><tr><td align="left"><code class="systemitem">FreePixmap</code></td><td align="left"><a class="xref" href="#XFreePixmap"><code class="function">XFreePixmap</code></a></td></tr><tr><td align="left"><code class="systemitem">GetAtomName</code></td><td align="left"><a class="xref" href="#XGetAtomName"><code class="function">XGetAtomName</code></a></td></tr><tr><td align="left"><code class="systemitem">GetFontPath</code></td><td align="left"><a class="xref" href="#XGetFontPath"><code class="function">XGetFontPath</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">GetGeometry</code></td><td align="left"><a class="xref" href="#XGetGeometry"><code class="function">XGetGeometry</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetWindowAttributes"><code class="function">XGetWindowAttributes</code></a></td></tr><tr><td align="left"><code class="systemitem">GetImage</code></td><td align="left"><a class="xref" href="#XGetImage"><code class="function">XGetImage</code></a></td></tr><tr><td rowspan="3" align="left"><code class="systemitem">GetInputFocus</code></td><td align="left"><a class="xref" href="#XGetInputFocus"><code class="function">XGetInputFocus</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSync"><code class="function">XSync</code></a></td></tr><tr><td align="left"><code class="function">XSynchronize</code></td></tr><tr><td align="left"><code class="systemitem">GetKeyboardControl</code></td><td align="left"><a class="xref" href="#XGetKeyboardControl"><code class="function">XGetKeyboardControl</code></a></td></tr><tr><td align="left"><code class="systemitem">GetKeyboardMapping</code></td><td align="left"><a class="xref" href="#XGetKeyboardMapping"><code class="function">XGetKeyboardMapping</code></a></td></tr><tr><td align="left"><code class="systemitem">GetModifierMapping</code></td><td align="left"><a class="xref" href="#XGetModifierMapping"><code class="function">XGetModifierMapping</code></a></td></tr><tr><td align="left"><code class="systemitem">GetMotionEvents</code></td><td align="left"><a class="xref" href="#XGetMotionEvents"></a></td></tr><tr><td align="left"><code class="systemitem">GetPointerControl</code></td><td align="left"><a class="xref" href="#XGetPointerControl"><code class="function">XGetPointerControl</code></a></td></tr><tr><td align="left"><code class="systemitem">GetPointerMapping</code></td><td align="left"><a class="xref" href="#XGetPointerMapping"><code class="function">XGetPointerMapping</code></a></td></tr><tr><td rowspan="20" align="left"><code class="systemitem">GetProperty</code></td><td align="left"><a class="xref" href="#XFetchBytes"><code class="function">XFetchBytes</code></a></td></tr><tr><td align="left"><a class="xref" href="#XFetchName"><code class="function">XFetchName</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetClassHint"><code class="function">XGetClassHint</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetIconName"><code class="function">XGetIconName</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetIconSizes"><code class="function">XGetIconSizes</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetNormalHints"><code class="function">XGetNormalHints</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetRGBColormaps"><code class="function">XGetRGBColormaps</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetSizeHints"><code class="function">XGetSizeHints</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetTextProperty"><code class="function">XGetTextProperty</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetTransientForHint"><code class="function">XGetTransientForHint</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetWMClientMachine"><code class="function">XGetWMClientMachine</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetWMColormapWindows"><code class="function">XGetWMColormapWindows</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetWMHints"><code class="function">XGetWMHints</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetWMIconName"><code class="function">XGetWMIconName</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetWMName"><code class="function">XGetWMName</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetWMNormalHints"><code class="function">XGetWMNormalHints</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetWMProtocols"><code class="function">XGetWMProtocols</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetWMSizeHints"><code class="function">XGetWMSizeHints</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetWindowProperty"><code class="function">XGetWindowProperty</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetZoomHints"><code class="function">XGetZoomHints</code></a></td></tr><tr><td align="left"><code class="systemitem">GetSelectionOwner</code></td><td align="left"><a class="xref" href="#XGetSelectionOwner"><code class="function">XGetSelectionOwner</code></a></td></tr><tr><td align="left"><code class="systemitem">GetWindowAttributes</code></td><td align="left"><a class="xref" href="#XGetWindowAttributes"><code class="function">XGetWindowAttributes</code></a></td></tr><tr><td align="left"><code class="systemitem">GrabButton</code></td><td align="left"><a class="xref" href="#XGrabButton"><code class="function">XGrabButton</code></a></td></tr><tr><td align="left"><code class="systemitem">GrabKey</code></td><td align="left"><a class="xref" href="#XGrabKey"><code class="function">XGrabKey</code></a></td></tr><tr><td align="left"><code class="systemitem">GrabKeyboard</code></td><td align="left"><a class="xref" href="#XGrabKeyboard"><code class="function">XGrabKeyboard</code></a></td></tr><tr><td align="left"><code class="systemitem">GrabPointer</code></td><td align="left"><a class="xref" href="#XGrabPointer"><code class="function">XGrabPointer</code></a></td></tr><tr><td align="left"><code class="systemitem">GrabServer</code></td><td align="left"><a class="xref" href="#XGrabServer"><code class="function">XGrabServer</code></a></td></tr><tr><td align="left"><code class="systemitem">ImageText8</code></td><td align="left"><a class="xref" href="#XDrawImageString"><code class="function">XDrawImageString</code></a></td></tr><tr><td align="left"><code class="systemitem">ImageText16</code></td><td align="left"><a class="xref" href="#XDrawImageString16"><code class="function">XDrawImageString16</code></a></td></tr><tr><td align="left"><code class="systemitem">InstallColormap</code></td><td align="left"><a class="xref" href="#XInstallColormap"><code class="function">XInstallColormap</code></a></td></tr><tr><td rowspan="6" align="left"><code class="systemitem">InternAtom</code></td><td align="left"><a class="xref" href="#XGetWMColormapWindows"><code class="function">XGetWMColormapWindows</code></a></td></tr><tr><td align="left"><a class="xref" href="#XGetWMProtocols"><code class="function">XGetWMProtocols</code></a></td></tr><tr><td align="left"><a class="xref" href="#XIconifyWindow"><code class="function">XIconifyWindow</code></a></td></tr><tr><td align="left"><a class="xref" href="#XInternAtom"><code class="function">XInternAtom</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetWMColormapWindows"><code class="function">XSetWMColormapWindows</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetWMProtocols"><code class="function">XSetWMProtocols</code></a></td></tr><tr><td align="left"><code class="systemitem">KillClient</code></td><td align="left"><a class="xref" href="#XKillClient"><code class="function">XKillClient</code></a></td></tr><tr><td align="left"><code class="systemitem">ListExtensions</code></td><td align="left"><a class="xref" href="#XListExtensions"><code class="function">XListExtensions</code></a></td></tr><tr><td align="left"><code class="systemitem">ListFonts</code></td><td align="left"><a class="xref" href="#XListFonts"><code class="function">XListFonts</code></a></td></tr><tr><td align="left"><code class="systemitem">ListFontsWithInfo</code></td><td align="left"><a class="xref" href="#XListFontsWithInfo"><code class="function">XListFontsWithInfo</code></a></td></tr><tr><td align="left"><code class="systemitem">ListHosts</code></td><td align="left"><a class="xref" href="#XListHosts"><code class="function">XListHosts</code></a></td></tr><tr><td align="left"><code class="systemitem">ListInstalledColormaps</code></td><td align="left"><a class="xref" href="#XListInstalledColormaps"><code class="function">XListInstalledColormaps</code></a></td></tr><tr><td align="left"><code class="systemitem">ListProperties</code></td><td align="left"><a class="xref" href="#XListProperties"><code class="function">XListProperties</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">LookupColor</code></td><td align="left"><a class="xref" href="#XLookupColor"><code class="function">XLookupColor</code></a></td></tr><tr><td align="left"><a class="xref" href="#XParseColor"><code class="function">XParseColor</code></a></td></tr><tr><td align="left"><code class="systemitem">MapSubwindows</code></td><td align="left"><a class="xref" href="#XMapSubwindows"><code class="function">XMapSubwindows</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">MapWindow</code></td><td align="left"><a class="xref" href="#XMapRaised"><code class="function">XMapRaised</code></a></td></tr><tr><td align="left"><a class="xref" href="#XMapWindow"><code class="function">XMapWindow</code></a></td></tr><tr><td align="left"><code class="systemitem">NoOperation</code></td><td align="left"><a class="xref" href="#XNoOp"><code class="function">XNoOp</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">OpenFont</code></td><td align="left"><a class="xref" href="#XLoadFont"><code class="function">XLoadFont</code></a></td></tr><tr><td align="left"><a class="xref" href="#XLoadQueryFont"><code class="function">XLoadQueryFont</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">PolyArc</code></td><td align="left"><a class="xref" href="#XDrawArc"><code class="function">XDrawArc</code></a></td></tr><tr><td align="left"><a class="xref" href="#XDrawArcs"><code class="function">XDrawArcs</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">PolyFillArc</code></td><td align="left"><a class="xref" href="#XFillArc"><code class="function">XFillArc</code></a></td></tr><tr><td align="left"><a class="xref" href="#XFillArcs"><code class="function">XFillArcs</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">PolyFillRectangle</code></td><td align="left"><a class="xref" href="#XFillRectangle"><code class="function">XFillRectangle</code></a></td></tr><tr><td align="left"><a class="xref" href="#XFillRectangles"><code class="function">XFillRectangles</code></a></td></tr><tr><td align="left"><code class="systemitem">PolyLine</code></td><td align="left"><a class="xref" href="#XDrawLines"><code class="function">XDrawLines</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">PolyPoint</code></td><td align="left"><a class="xref" href="#XDrawPoint"><code class="function">XDrawPoint</code></a></td></tr><tr><td align="left"><a class="xref" href="#XDrawPoints"><code class="function">XDrawPoints</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">PolyRectangle</code></td><td align="left"><a class="xref" href="#XDrawRectangle"><code class="function">XDrawRectangle</code></a></td></tr><tr><td align="left"><a class="xref" href="#XDrawRectangles"><code class="function">XDrawRectangles</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">PolySegment</code></td><td align="left"><a class="xref" href="#XDrawLine"><code class="function">XDrawLine</code></a></td></tr><tr><td align="left"><a class="xref" href="#XDrawSegments"><code class="function">XDrawSegments</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">PolyText8</code></td><td align="left"><a class="xref" href="#XDrawString"><code class="function">XDrawString</code></a></td></tr><tr><td align="left"><a class="xref" href="#XDrawText"><code class="function">XDrawText</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">PolyText16</code></td><td align="left"><a class="xref" href="#XDrawString16"><code class="function">XDrawString16</code></a></td></tr><tr><td align="left"><a class="xref" href="#XDrawText16"><code class="function">XDrawText16</code></a></td></tr><tr><td rowspan="4" align="left"><code class="systemitem">PutImage</code></td><td align="left"><a class="xref" href="#XPutImage"><code class="function">XPutImage</code></a></td></tr><tr><td align="left"><a class="xref" href="#XCreateBitmapFromData"><code class="function">XCreateBitmapFromData</code></a></td></tr><tr><td align="left"><code class="function">XCreatePixmapFromData</code></td></tr><tr><td align="left"><a class="xref" href="#XReadBitmapFile"><code class="function">XReadBitmapFile</code></a></td></tr><tr><td rowspan="4" align="left"><code class="systemitem">QueryBestSize</code></td><td align="left"><a class="xref" href="#XQueryBestCursor"><code class="function">XQueryBestCursor</code></a></td></tr><tr><td align="left"><a class="xref" href="#XQueryBestSize"><code class="function">XQueryBestSize</code></a></td></tr><tr><td align="left"><a class="xref" href="#XQueryBestStipple"><code class="function">XQueryBestStipple</code></a></td></tr><tr><td align="left"><a class="xref" href="#XQueryBestTile"><code class="function">XQueryBestTile</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">QueryColors</code></td><td align="left"><a class="xref" href="#XQueryColor"><code class="function">XQueryColor</code></a></td></tr><tr><td align="left"><a class="xref" href="#XQueryColors"><code class="function">XQueryColors</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">QueryExtension</code></td><td align="left"><a class="xref" href="#XInitExtension"><code class="function">XInitExtension</code></a></td></tr><tr><td align="left"><a class="xref" href="#XQueryExtension"><code class="function">XQueryExtension</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">QueryFont</code></td><td align="left"><a class="xref" href="#XLoadQueryFont"><code class="function">XLoadQueryFont</code></a></td></tr><tr><td align="left"><a class="xref" href="#XQueryFont"><code class="function">XQueryFont</code></a></td></tr><tr><td align="left"><code class="systemitem">QueryKeymap</code></td><td align="left"><a class="xref" href="#XQueryKeymap"><code class="function">XQueryKeymap</code></a></td></tr><tr><td align="left"><code class="systemitem">QueryPointer</code></td><td align="left"><a class="xref" href="#XQueryPointer"><code class="function">XQueryPointer</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">QueryTextExtents</code></td><td align="left"><a class="xref" href="#XQueryTextExtents"><code class="function">XQueryTextExtents</code></a></td></tr><tr><td align="left"><a class="xref" href="#XQueryTextExtents16"><code class="function">XQueryTextExtents16</code></a></td></tr><tr><td align="left"><code class="systemitem">QueryTree</code></td><td align="left"><a class="xref" href="#XQueryTree"><code class="function">XQueryTree</code></a></td></tr><tr><td align="left"><code class="systemitem">RecolorCursor</code></td><td align="left"><a class="xref" href="#XRecolorCursor"><code class="function">XRecolorCursor</code></a></td></tr><tr><td align="left"><code class="systemitem">ReparentWindow</code></td><td align="left"><a class="xref" href="#XReparentWindow"><code class="function">XReparentWindow</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">RotateProperties</code></td><td align="left"><a class="xref" href="#XRotateBuffers"><code class="function">XRotateBuffers</code></a></td></tr><tr><td align="left"><a class="xref" href="#XRotateWindowProperties"><code class="function">XRotateWindowProperties</code></a></td></tr><tr><td rowspan="4" align="left"><code class="systemitem">SendEvent</code></td><td align="left"><a class="xref" href="#XIconifyWindow"><code class="function">XIconifyWindow</code></a></td></tr><tr><td align="left"><a class="xref" href="#XReconfigureWMWindow"><code class="function">XReconfigureWMWindow</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSendEvent"><code class="function">XSendEvent</code></a></td></tr><tr><td align="left"><a class="xref" href="#XWithdrawWindow"><code class="function">XWithdrawWindow</code></a></td></tr><tr><td rowspan="3" align="left"><code class="systemitem">SetAccessControl</code></td><td align="left"><a class="xref" href="#XDisableAccessControl"><code class="function">XDisableAccessControl</code></a></td></tr><tr><td align="left"><a class="xref" href="#XEnableAccessControl"><code class="function">XEnableAccessControl</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetAccessControl"><code class="function">XSetAccessControl</code></a></td></tr><tr><td align="left"><code class="systemitem">SetClipRectangles</code></td><td align="left"><a class="xref" href="#XSetClipRectangles"><code class="function">XSetClipRectangles</code></a></td></tr><tr><td align="left"><code class="systemitem">SetCloseDownMode</code></td><td align="left"><a class="xref" href="#XSetCloseDownMode"></a></td></tr><tr><td align="left"><code class="systemitem">SetDashes</code></td><td align="left"><a class="xref" href="#XSetDashes"><code class="function">XSetDashes</code></a></td></tr><tr><td align="left"><code class="systemitem">SetFontPath</code></td><td align="left"><a class="xref" href="#XSetFontPath"><code class="function">XSetFontPath</code></a></td></tr><tr><td align="left"><code class="systemitem">SetInputFocus</code></td><td align="left"><a class="xref" href="#XSetInputFocus"><code class="function">XSetInputFocus</code></a></td></tr><tr><td align="left"><code class="systemitem">SetModifierMapping</code></td><td align="left"><a class="xref" href="#XSetModifierMapping"><code class="function">XSetModifierMapping</code></a></td></tr><tr><td align="left"><code class="systemitem">SetPointerMapping</code></td><td align="left"><a class="xref" href="#XSetPointerMapping"><code class="function">XSetPointerMapping</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">SetScreenSaver</code></td><td align="left"><a class="xref" href="#XGetScreenSaver"><code class="function">XGetScreenSaver</code></a></td></tr><tr><td align="left"><a class="xref" href="#XSetScreenSaver"><code class="function">XSetScreenSaver</code></a></td></tr><tr><td align="left"><code class="systemitem">SetSelectionOwner</code></td><td align="left"><a class="xref" href="#XSetSelectionOwner"><code class="function">XSetSelectionOwner</code></a></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">StoreColors</code></td><td align="left"><a class="xref" href="#XStoreColor"><code class="function">XStoreColor</code></a></td></tr><tr><td align="left"><a class="xref" href="#XStoreColors"><code class="function">XStoreColors</code></a></td></tr><tr><td align="left"><code class="systemitem">StoreNamedColor</code></td><td align="left"><a class="xref" href="#XStoreNamedColor"><code class="function">XStoreNamedColor</code></a></td></tr><tr><td align="left"><code class="systemitem">TranslateCoordinates</code></td><td align="left"><a class="xref" href="#XTranslateCoordinates"><code class="function">XTranslateCoordinates</code></a></td></tr><tr><td align="left"><code class="systemitem">UngrabButton</code></td><td align="left"><a class="xref" href="#XUngrabButton"><code class="function">XUngrabButton</code></a></td></tr><tr><td align="left"><code class="systemitem">UngrabKey</code></td><td align="left"><a class="xref" href="#XUngrabKey"><code class="function">XUngrabKey</code></a></td></tr><tr><td align="left"><code class="systemitem">UngrabKeyboard</code></td><td align="left"><a class="xref" href="#XUngrabKeyboard"><code class="function">XUngrabKeyboard</code></a></td></tr><tr><td align="left"><code class="systemitem">UngrabPointer</code></td><td align="left"><a class="xref" href="#XUngrabPointer"><code class="function">XUngrabPointer</code></a></td></tr><tr><td align="left"><code class="systemitem">UngrabServer</code></td><td align="left"><a class="xref" href="#XUngrabServer"><code class="function">XUngrabServer</code></a></td></tr><tr><td align="left"><code class="systemitem">UninstallColormap</code></td><td align="left"><a class="xref" href="#XUninstallColormap"><code class="function">XUninstallColormap</code></a></td></tr><tr><td align="left"><code class="systemitem">UnmapSubwindows</code></td><td align="left"><code class="function">XUnmapSubWindows</code></td></tr><tr><td rowspan="2" align="left"><code class="systemitem">UnmapWindow</code></td><td align="left"><a class="xref" href="#XUnmapWindow"><code class="function">XUnmapWindow</code></a></td></tr><tr><td align="left"><a class="xref" href="#XWithdrawWindow"><code class="function">XWithdrawWindow</code></a></td></tr><tr><td align="left"><code class="systemitem">WarpPointer</code></td><td align="left"><a class="xref" href="#XWarpPointer"><code class="function">XWarpPointer</code></a></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a id="x_font_cursors"></a>Appendix B. X Font Cursors</h1></div></div></div><p>
The following are the available cursors that can be used with
<a class="xref" href="#XCreateFontCursor"><code class="function">XCreateFontCursor</code></a>.
</p><pre class="literallayout">
#define XC_X_cursor 0                     #define XC_ll_angle 76
#define XC_arrow 2                        #define XC_lr_angle 78
#define XC_based_arrow_down 4             #define XC_man 80
#define XC_based_arrow_up 6               #define XC_middlebutton 82
#define XC_boat 8                         #define XC_mouse 84
#define XC_bogosity 10                    #define XC_pencil 86
#define XC_bottom_left_corner 12          #define XC_pirate 88
#define XC_bottom_right_corner 14         #define XC_plus 90
#define XC_bottom_side 16                 #define XC_question_arrow 92
#define XC_bottom_tee 18                  #define XC_right_ptr 94
#define XC_box_spiral 20                  #define XC_right_side 96
#define XC_center_ptr 22                  #define XC_right_tee 98
#define XC_circle 24                      #define XC_rightbutton 100
#define XC_clock 26                       #define XC_rtl_logo 102
#define XC_coffee_mug 28                  #define XC_sailboat 104
#define XC_cross 30                       #define XC_sb_down_arrow 106
#define XC_cross_reverse 32               #define XC_sb_h_double_arrow 108
#define XC_crosshair 34                   #define XC_sb_left_arrow 110
#define XC_diamond_cross 36               #define XC_sb_right_arrow 112
#define XC_dot 38                         #define XC_sb_up_arrow 114
#define XC_dot_box_mask 40                #define XC_sb_v_double_arrow 116
#define XC_double_arrow 42                #define XC_shuttle 118
#define XC_draft_large 44                 #define XC_sizing 120
#define XC_draft_small 46                 #define XC_spider 122
#define XC_draped_box 48                  #define XC_spraycan 124
#define XC_exchange 50                    #define XC_star 126
#define XC_fleur 52                       #define XC_target 128
#define XC_gobbler 54                     #define XC_tcross 130
#define XC_gumby 56                       #define XC_top_left_arrow 132
#define XC_hand1 58                       #define XC_top_left_corner 134
#define XC_hand2 60                       #define XC_top_right_corner 136
#define XC_heart 62                       #define XC_top_side 138
#define XC_icon 64                        #define XC_top_tee 140
#define XC_iron_cross 66                  #define XC_trek 142
#define XC_left_ptr 68                    #define XC_ul_angle 144
#define XC_left_side 70                   #define XC_umbrella 146
#define XC_left_tee 72                    #define XC_ur_angle 148
#define XC_leftbutton 74                  #define XC_watch 150
                                          #define XC_xterm 152
</pre></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a id="extensions"></a>Appendix C. Extensions</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Basic_Protocol_Support_Routines">Basic Protocol Support Routines</a></span></dt><dt><span class="sect1"><a href="#Hooking_into_Xlib">Hooking into Xlib</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Hooks_into_the_Library">Hooks into the Library</a></span></dt><dt><span class="sect2"><a href="#Hooks_onto_Xlib_Data_Structures">Hooks onto Xlib Data Structures</a></span></dt></dl></dd><dt><span class="sect1"><a href="#GC_Caching">GC Caching</a></span></dt><dt><span class="sect1"><a href="#Graphics_Batching">Graphics Batching</a></span></dt><dt><span class="sect1"><a href="#Writing_Extension_Stubs">Writing Extension Stubs</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Requests_Replies_and_Xproto.h">Requests, Replies, and Xproto.h</a></span></dt><dt><span class="sect2"><a href="#Request_Format">Request Format</a></span></dt><dt><span class="sect2"><a href="#Starting_to_Write_a_Stub_Procedure">Starting to Write a Stub Procedure</a></span></dt><dt><span class="sect2"><a href="#Locking_Data_Structures">Locking Data Structures</a></span></dt><dt><span class="sect2"><a href="#Sending_the_Protocol_Request_and_Arguments">Sending the Protocol Request and Arguments</a></span></dt><dt><span class="sect2"><a href="#Variable_Length_Arguments">Variable Length Arguments</a></span></dt><dt><span class="sect2"><a href="#Replies">Replies</a></span></dt><dt><span class="sect2"><a href="#Synchronous_Calling">Synchronous Calling</a></span></dt><dt><span class="sect2"><a href="#Allocating_and_Deallocating_Memory">Allocating and Deallocating Memory</a></span></dt><dt><span class="sect2"><a href="#Portability_Considerations">Portability Considerations</a></span></dt><dt><span class="sect2"><a href="#Deriving_the_Correct_Extension_Opcode">Deriving the Correct Extension Opcode</a></span></dt></dl></dd></dl></div><p>

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.
</p><p>

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.  
</p><p>

This appendix describes techniques for writing extensions to Xlib that will
run at essentially the same performance as the core protocol requests.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
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.
</p></div><p>

The symbols and macros used for writing stubs to Xlib are listed in
<code class="filename">&lt;X11/Xlibint.h&gt;</code>.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Basic_Protocol_Support_Routines"></a>Basic Protocol Support Routines</h2></div></div></div><p>
The basic protocol requests for extensions are 
<a class="xref" href="#XQueryExtension"><code class="function">XQueryExtension</code></a>
and
<a class="xref" href="#XListExtensions"><code class="function">XListExtensions</code></a>.
</p><a id="idp43324092" class="indexterm"></a><div class="funcsynopsis"><a id="XQueryExtension"></a><p><code class="funcdef">Bool <strong class="fsfunc">XQueryExtension</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> *name</var>, int<var class="pdparam"> *major_opcode_return</var>, int<var class="pdparam"> *first_event_return</var>, int<var class="pdparam"> *first_error_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">display</span></p></td><td><p>Specifies the connection to the X server.</p></td></tr><tr><td><p><span class="term">name</span></p></td><td><p>Specifies the extension name.</p></td></tr><tr><td><p><span class="term">major_opcode_return</span></p></td><td><p>Returns the major opcode.</p></td></tr><tr><td><p><span class="term">first_event_return</span></p></td><td><p>Returns the first event code, if any.</p></td></tr><tr><td><p><span class="term">first_error_return</span></p></td><td><p>Returns the first error code, if any.</p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XQueryExtension"><code class="function">XQueryExtension</code></a>
function determines if the named extension is present.  
If the extension is not present,
<a class="xref" href="#XQueryExtension"><code class="function">XQueryExtension</code></a>
returns
<span class="symbol">False</span>;
otherwise, it returns
<span class="symbol">True</span>.
If the extension is present,
<a class="xref" href="#XQueryExtension"><code class="function">XQueryExtension</code></a>
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, 
<a class="xref" href="#XQueryExtension"><code class="function">XQueryExtension</code></a>
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, 
<a class="xref" href="#XQueryExtension"><code class="function">XQueryExtension</code></a>
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.
</p><p>

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.
</p><a id="idp50446212" class="indexterm"></a><div class="funcsynopsis"><a id="XListExtensions"></a><p><code class="funcdef">char **<strong class="fsfunc">XListExtensions</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> *nextensions_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nextensions_return</em></span>
    </span></p></td><td><p>
Returns the number of extensions listed.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XListExtensions"><code class="function">XListExtensions</code></a>
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.
</p><a id="idp49587892" class="indexterm"></a><div class="funcsynopsis"><a id="XFreeExtensionList"></a><p><code class="funcdef"><strong class="fsfunc">XFreeExtensionList</strong>(</code>char<var class="pdparam"> **list</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>list</em></span>
    </span></p></td><td><p>
Specifies the list of extension names.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFreeExtensionList"><code class="function">XFreeExtensionList</code></a>
function frees the memory allocated by 
<a class="xref" href="#XListExtensions"><code class="function">XListExtensions</code></a>.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Hooking_into_Xlib"></a>Hooking into Xlib</h2></div></div></div><p>

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.
</p><p>

In extensions, stubs first should check to see if they have initialized 
themselves on a connection.
If they have not, they then should call 
<a class="xref" href="#XInitExtension"><code class="function">XInitExtension</code></a>
to attempt to initialize themselves on the connection.
</p><p>

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.
</p><p>

The
<span class="structname">XExtCodes</span>
structure returns the information from 
<a class="xref" href="#XInitExtension"><code class="function">XInitExtension</code></a>
and is defined in
<code class="filename">&lt;X11/Xlib.h&gt;</code>:
</p><p>

<a id="idp49591668" class="indexterm"></a>



</p><pre class="synopsis">
typedef struct _XExtCodes {	/* public to extension, cannot be changed */
	int extension;		/* extension number */
	int major_opcode;	/* major op-code assigned by server */
	int first_event;	/* first event number for the extension */
	int first_error;	/* first error number for the extension */
} XExtCodes;
</pre><p>
</p><a id="idp49593652" class="indexterm"></a><div class="funcsynopsis"><a id="XInitExtension"></a><p><code class="funcdef">XExtCodes *<strong class="fsfunc">XInitExtension</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> *name</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>name</em></span>
    </span></p></td><td><p>
Specifies the extension name.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XInitExtension"><code class="function">XInitExtension</code></a>
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,
<a class="xref" href="#XInitExtension"><code class="function">XInitExtension</code></a>
returns NULL.
</p><p>

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.
</p><p>

The extension number in the 
<span class="structname">XExtCodes</span>
structure is
needed in the other calls that follow.  
This extension number is unique only to a single connection.
</p><a id="idp52897844" class="indexterm"></a><div class="funcsynopsis"><a id="XAddExtension"></a><p><code class="funcdef">XExtCodes *<strong class="fsfunc">XAddExtension</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


For local Xlib extensions, the
<a class="xref" href="#XAddExtension"><code class="function">XAddExtension</code></a>
function allocates the
<span class="structname">XExtCodes</span>
structure, bumps the extension number count,
and chains the extension onto the extension list.
(This permits extensions to Xlib without requiring server extensions.)
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Hooks_into_the_Library"></a>Hooks into the Library</h3></div></div></div><p>

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.
</p><p>

All of these functions return the previous procedure defined for this
extension.
</p><a id="idp52904724" class="indexterm"></a><div class="funcsynopsis"><a id="XESetCloseDisplay"></a><p><code class="funcdef">int <strong class="fsfunc">XESetCloseDisplay</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> extension</var>, int<var class="pdparam"> (*proc)()</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>extension</em></span>
    </span></p></td><td><p>
Specifies the extension number.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>proc</em></span>
    </span></p></td><td><p>
Specifies the procedure to call when the display is closed.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XESetCloseDisplay"><code class="function">XESetCloseDisplay</code></a>
function defines a procedure to be called whenever
<code class="function">XCloseDisplay</code>
is called.  
It returns any previously defined procedure, usually NULL.
</p><p>

When 
<code class="function">XCloseDisplay</code>
is called, 
your procedure is called 
with these arguments:
</p><div class="funcsynopsis"><p><code class="funcdef">int <strong class="fsfunc">(*proc)</strong>(</code>Display *<var class="pdparam">display</var>, XExtCodes *<var class="pdparam">codes</var><code>)</code>;</p></div><p>
</p><a id="idp53621652" class="indexterm"></a><div class="funcsynopsis"><a id="XESetCreateGC"></a><p><code class="funcdef">int *<strong class="fsfunc">XESetCreateGC</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> extension</var>, int<var class="pdparam"> (*proc)()</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>extension</em></span>
    </span></p></td><td><p>
Specifies the extension number.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>proc</em></span>
    </span></p></td><td><p>
Specifies the procedure to call when a GC is closed.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XESetCreateGC"><code class="function">XESetCreateGC</code></a>
function defines a procedure to be called whenever
a new GC is created.  
It returns any previously defined procedure, usually NULL.
</p><p>

When a GC is created, 
your procedure is called with these arguments:


</p><div class="funcsynopsis"><p><code class="funcdef">int <strong class="fsfunc">(*proc)</strong>(</code>Display *<var class="pdparam">display</var>, GC <var class="pdparam">gc</var>, XExtCodes *<var class="pdparam">codes</var><code>)</code>;</p></div><p>
</p><a id="idp53633668" class="indexterm"></a><div class="funcsynopsis"><a id="XESetCopyGC"></a><p><code class="funcdef">int *<strong class="fsfunc">XESetCopyGC</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> extension</var>, int<var class="pdparam"> (*proc)()</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>extension</em></span>
    </span></p></td><td><p>
Specifies the extension number.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>proc</em></span>
    </span></p></td><td><p>
Specifies the procedure to call when GC components are copied.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XESetCopyGC"><code class="function">XESetCopyGC</code></a>
function defines a procedure to be called whenever
a GC is copied.  
It returns any previously defined procedure, usually NULL.
</p><p>

When a GC is copied, 
your procedure is called with these arguments:
</p><div class="funcsynopsis"><p><code class="funcdef">int <strong class="fsfunc">(*proc)</strong>(</code>Display *<var class="pdparam">display</var>, GC <var class="pdparam">gc</var>, XExtCodes *<var class="pdparam">codes</var><code>)</code>;</p></div><p>
</p><div class="funcsynopsis"><a id="XESetFreeGC"></a><p><code class="funcdef">int *<strong class="fsfunc">XESetFreeGC</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> extension</var>, int<var class="pdparam"> (*proc)()</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>extension</em></span>
    </span></p></td><td><p>
Specifies the extension number.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>proc</em></span>
    </span></p></td><td><p>
Specifies the procedure to call when a GC is freed.
    </p></td></tr></tbody></table></div><p>
The
<a class="xref" href="#XESetFreeGC"><code class="function">XESetFreeGC</code></a>
function defines a procedure to be called whenever
a GC is freed.  
It returns any previously defined procedure, usually NULL.
</p><p>

When a GC is freed, 
your procedure is called with these arguments:





</p><div class="funcsynopsis"><p><code class="funcdef">int <strong class="fsfunc">(*proc)</strong>(</code>Display *<var class="pdparam">display</var>, GC <var class="pdparam">gc</var>, XExtCodes *<var class="pdparam">codes</var><code>)</code>;</p></div><p>
</p><a id="idp53657052" class="indexterm"></a><div class="funcsynopsis"><a id="XESetCreateFont"></a><p><code class="funcdef">int *<strong class="fsfunc">XESetCreateFont</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> extension</var>, int<var class="pdparam"> (*proc)()</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>extension</em></span>
    </span></p></td><td><p>
Specifies the extension number.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>proc</em></span>
    </span></p></td><td><p>
Specifies the procedure to call when a font is created.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XESetCreateFont"><code class="function">XESetCreateFont</code></a>
function defines a procedure to be called whenever
<a class="xref" href="#XLoadQueryFont"><code class="function">XLoadQueryFont</code></a>
and
<a class="xref" href="#XQueryFont"><code class="function">XQueryFont</code></a>
are called.  
It returns any previously defined procedure, usually NULL.
</p><p>

When 
<a class="xref" href="#XLoadQueryFont"><code class="function">XLoadQueryFont</code></a>
or
<a class="xref" href="#XQueryFont"><code class="function">XQueryFont</code></a>
is called, 
your procedure is called with these arguments:





</p><div class="funcsynopsis"><p><code class="funcdef">int <strong class="fsfunc">(*proc)</strong>(</code>Display *<var class="pdparam">display</var>, XFontStruct *<var class="pdparam">fs</var>, XExtCodes *<var class="pdparam">codes</var><code>)</code>;</p></div><p>
</p><a id="idp53671588" class="indexterm"></a><div class="funcsynopsis"><a id="XESetFreeFont"></a><p><code class="funcdef">int *<strong class="fsfunc">XESetFreeFont</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> extension</var>, int<var class="pdparam"> (*proc)()</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>extension</em></span>
    </span></p></td><td><p>
Specifies the extension number.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>proc</em></span>
    </span></p></td><td><p>
Specifies the procedure to call when a font is freed.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XESetFreeFont"><code class="function">XESetFreeFont</code></a>
function defines a procedure to be called whenever
<a class="xref" href="#XFreeFont"><code class="function">XFreeFont</code></a>
is called.  
It returns any previously defined procedure, usually NULL.
</p><p>

When 
<a class="xref" href="#XFreeFont"><code class="function">XFreeFont</code></a>
is called, your procedure is called with these arguments:





</p><div class="funcsynopsis"><p><code class="funcdef">int <strong class="fsfunc">(*proc)</strong>(</code>Display *<var class="pdparam">display</var>, XFontStruct *<var class="pdparam">fs</var>, XExtCodes *<var class="pdparam">codes</var><code>)</code>;</p></div><p>
</p><p>


The 
<a class="xref" href="#XESetWireToEvent"><code class="function">XESetWireToEvent</code></a>
and
<a class="xref" href="#XESetEventToWire"><code class="function">XESetEventToWire</code></a>
functions allow you to define new events to the library.
An 
<span class="structname">XEvent</span>
structure always has a type code (type
<span class="type">int</span>)
as the first component.
This uniquely identifies what kind of event it is.
The second component is always the serial number (type
<span class="type">unsigned</span>
<span class="type">long</span>)
of the last request processed by the server.
The third component is always a Boolean (type
<span class="type">Bool</span>)
indicating whether the event came from a
<code class="systemitem">SendEvent</code>
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.

There is an implementation limit such that your host event
structure size cannot be bigger than the size of the
<span class="structname">XEvent</span>
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.
</p><a id="idp53742164" class="indexterm"></a><div class="funcsynopsis"><a id="XESetWireToEvent"></a><p><code class="funcdef">int *<strong class="fsfunc">XESetWireToEvent</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> event_number</var>, Status<var class="pdparam"> (*proc)()</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_number</em></span>
    </span></p></td><td><p>
Specifies the event code.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>proc</em></span>
    </span></p></td><td><p>
Specifies the procedure to call when converting an event.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XESetWireToEvent"><code class="function">XESetWireToEvent</code></a>
function defines a procedure to be called when an event
needs to be converted from wire format 
(<span class="structname">xEvent</span>)
to host format 
(<span class="structname">XEvent</span>).
The event number defines which protocol event number to install a
conversion procedure for.
<a class="xref" href="#XESetWireToEvent"><code class="function">XESetWireToEvent</code></a>
returns any previously defined procedure.

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.

When Xlib needs to convert an event from wire format to host
format, your procedure is called with these arguments:





</p><div class="funcsynopsis"><p><code class="funcdef">int <strong class="fsfunc">(*proc)</strong>(</code>Display *<var class="pdparam">display</var>, XEvent *<var class="pdparam">re</var>, xEvent *<var class="pdparam">event</var><code>)</code>;</p></div><p>


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 
<span class="structname">XEvent</span>
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 
<span class="structname">xEvent</span>
structure.
You should copy all other members from the 
<span class="structname">xEvent</span>
structure (wire format) to the
<span class="structname">XEvent</span>
structure (host format).
Your conversion procedure should return 
<span class="symbol">True</span>
if the event should be placed in the queue or
<span class="symbol">False</span>
if it should not be placed in the queue.
</p><p>

To initialize the serial number component of the event, call
<a class="xref" href="#_XSetLastRequestRead"><code class="function">_XSetLastRequestRead</code></a>
with the event and use the return value.
</p><a id="idp53758972" class="indexterm"></a><div class="funcsynopsis"><a id="_XSetLastRequestRead"></a><p><code class="funcdef">unsigned long<strong class="fsfunc">_XSetLastRequestRead</strong>(</code>Display<var class="pdparam"> *display</var>, xGenericReply<var class="pdparam"> *rep</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>rep</em></span>
    </span></p></td><td><p>
Specifies the wire event structure.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#_XSetLastRequestRead"><code class="function">_XSetLastRequestRead</code></a>
function computes and returns a complete serial number from the partial
serial number in the event.

</p><a id="idp53765908" class="indexterm"></a><div class="funcsynopsis"><a id="XESetEventToWire"></a><p><code class="funcdef">Status *<strong class="fsfunc">XESetEventToWire</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> event_number</var>, int<var class="pdparam"> (*proc)()</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_number</em></span>
    </span></p></td><td><p>
Specifies the event code.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>proc</em></span>
    </span></p></td><td><p>
Specifies the procedure to call when converting an event.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XESetEventToWire"><code class="function">XESetEventToWire</code></a>
function defines a procedure to be called when an event
needs to be converted from host format
(<span class="structname">XEvent</span>)
to wire format
(<span class="structname">xEvent</span>)
form.  
The event number defines which protocol event number to install a
conversion procedure for.
<a class="xref" href="#XESetEventToWire"><code class="function">XESetEventToWire</code></a>
returns any previously defined procedure.
It returns zero if the conversion fails or nonzero otherwise.

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.

When Xlib needs to convert an event from host format to wire format, 
your procedure is called with these arguments:





</p><div class="funcsynopsis"><p><code class="funcdef">int <strong class="fsfunc">(*proc)</strong>(</code>Display *<var class="pdparam">display</var>, XEvent *<var class="pdparam">re</var>, xEvent *<var class="pdparam">event</var><code>)</code>;</p></div><p>


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 
<span class="structname">XEvent</span>
structure.
All other members then should be copied from the host format to the 
<span class="structname">xEvent</span>
structure.
</p><a id="idp53780724" class="indexterm"></a><div class="funcsynopsis"><a id="XESetWireToError"></a><p><code class="funcdef">Bool *<strong class="fsfunc">XESetWireToError</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> error_number</var>, Bool<var class="pdparam"> (*proc)()</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>error_number</em></span>
    </span></p></td><td><p>
Specifies the error code.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>proc</em></span>
    </span></p></td><td><p>
Specifies the procedure to call when an error is received.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XESetWireToError"><code class="function">XESetWireToError</code></a>
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.
<a class="xref" href="#XESetWireToError"><code class="function">XESetWireToError</code></a>
returns any previously defined procedure.
</p><p>

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.
</p><p>

When Xlib needs to convert an error from wire format to host format,
the procedure is called with these arguments:





</p><div class="funcsynopsis"><p><code class="funcdef">int <strong class="fsfunc">(*proc)</strong>(</code>Display *<var class="pdparam">display</var>, XErrorEvent *<var class="pdparam">he</var>, xError *<var class="pdparam">we</var><code>)</code>;</p></div><p>


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
<span class="structname">XEvent</span>
structure and so can be cast to a type larger than an
<span class="structname">XErrorEvent</span>
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
<span class="symbol">False</span>;
otherwise, it should return
<span class="symbol">True</span>.
</p><a id="idp53796020" class="indexterm"></a><div class="funcsynopsis"><a id="XESetError"></a><p><code class="funcdef">int *<strong class="fsfunc">XESetError</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> extension</var>, int<var class="pdparam"> (*proc)()</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>extension</em></span>
    </span></p></td><td><p>
Specifies the extension number.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>proc</em></span>
    </span></p></td><td><p>
Specifies the procedure to call when an error is received.
    </p></td></tr></tbody></table></div><p>


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).
</p><p>

When Xlib detects a protocol error in 
<a class="xref" href="#_XReply"><code class="function">_XReply</code></a>,
it calls your procedure with these arguments:





</p><div class="funcsynopsis"><p><code class="funcdef">int <strong class="fsfunc">(*proc)</strong>(</code>Display *<var class="pdparam">display</var>, xError *<var class="pdparam">err</var>, XExtCodes *<var class="pdparam">codes</var>, int *<var class="pdparam">ret_code</var><code>)</code>;</p></div><p>


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 
<a class="xref" href="#_XReply"><code class="function">_XReply</code></a>
returned to.
</p><p>

If your procedure returns a zero value, 
the error is not suppressed, and 
the client's error handler is called.
(For further information,
see <a class="link" href="#Using_the_Default_Error_Handlers" title="Using the Default Error Handlers">section 11.8.2</a>.)
If your procedure returns nonzero, 
the error is suppressed, and 
<a class="xref" href="#_XReply"><code class="function">_XReply</code></a>
returns the value of ret_code.
</p><a id="idp53811420" class="indexterm"></a><div class="funcsynopsis"><a id="XESetErrorString"></a><p><code class="funcdef">char *<strong class="fsfunc">XESetErrorString</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> extension</var>, char<var class="pdparam"> *(*proc)()</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>extension</em></span>
    </span></p></td><td><p>
Specifies the extension number.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>proc</em></span>
    </span></p></td><td><p>
Specifies the procedure to call to obtain an error string.
    </p></td></tr></tbody></table></div><p>


The 
<a class="xref" href="#XGetErrorText"><code class="function">XGetErrorText</code></a>
function returns a string to the user for an error.
<a class="xref" href="#XESetErrorString"><code class="function">XESetErrorString</code></a>
allows you to define a procedure to be called that
should return a pointer to the error message.
The following is an example.
</p><p>





</p><div class="funcsynopsis"><p><code class="funcdef">int <strong class="fsfunc">(*proc)</strong>(</code>Display *<var class="pdparam">display</var>, int <var class="pdparam">code</var>, XExtCodes *<var class="pdparam">codes</var>, char *<var class="pdparam">buffer</var>, int <var class="pdparam">nbytes</var><code>)</code>;</p></div><p>


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.
</p><a id="idp53825676" class="indexterm"></a><div class="funcsynopsis"><a id="XESetPrintErrorValues"></a><p><code class="funcdef">void *<strong class="fsfunc">XESetPrintErrorValues</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> extension</var>, void<var class="pdparam"> (*proc)()</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>extension</em></span>
    </span></p></td><td><p>
Specifies the extension number.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>proc</em></span>
    </span></p></td><td><p>
Specifies the procedure to call when an error is printed.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XESetPrintErrorValues"><code class="function">XESetPrintErrorValues</code></a>
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.
</p><p>

When Xlib needs to print an error,
the procedure is called with these arguments:





</p><div class="funcsynopsis"><p><code class="funcdef">void <strong class="fsfunc">(*proc)</strong>(</code>Display *<var class="pdparam">display</var>, XErrorEvent *<var class="pdparam">ev</var>, void *<var class="pdparam">fp</var><code>)</code>;</p></div><p>


The structure pointed at by ev is guaranteed to be as large as an
<span class="structname">XEvent</span>
structure and so can be cast to a type larger than an
<span class="structname">XErrorEvent</span>
to obtain additional values set by using
<a class="xref" href="#XESetWireToError"><code class="function">XESetWireToError</code></a>.
The underlying type of the fp argument is system dependent;
on a <acronym class="acronym">POSIX</acronym>-compliant system, fp should be cast to type FILE*.
</p><a id="idp53839876" class="indexterm"></a><div class="funcsynopsis"><a id="XESetFlushGC"></a><p><code class="funcdef">int *<strong class="fsfunc">XESetFlushGC</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> extension</var>, int<var class="pdparam"> *(*proc)()</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>extension</em></span>
    </span></p></td><td><p>
Specifies the extension number.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>proc</em></span>
    </span></p></td><td><p>
Specifies the procedure to call when a GC is flushed.
    </p></td></tr></tbody></table></div><p>


The procedure set by the
<a class="xref" href="#XESetFlushGC"><code class="function">XESetFlushGC</code></a>
function has the same interface as the procedure set by the
<a class="xref" href="#XESetCopyGC"><code class="function">XESetCopyGC</code></a>
function, but is called when a GC cache needs to be updated in the server.
</p><a id="idp53848892" class="indexterm"></a><div class="funcsynopsis"><p><code class="funcdef">int *<strong class="fsfunc">XESetCopyGC</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> extension</var>, int<var class="pdparam"> *(*proc)()</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>extension</em></span>
    </span></p></td><td><p>
Specifies the extension number.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>proc</em></span>
    </span></p></td><td><p>
Specifies the procedure to call when a buffer is flushed.
    </p></td></tr></tbody></table></div><p>


The
<code class="function">XESetBeforeFlush</code>
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:





</p><div class="funcsynopsis"><p><code class="funcdef">void <strong class="fsfunc">(*proc)</strong>(</code>Display *<var class="pdparam">display</var>, XExtCodes *<var class="pdparam">codes</var>, char *<var class="pdparam">data</var>, long <var class="pdparam">len</var><code>)</code>;</p></div><p>


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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Hooks_onto_Xlib_Data_Structures"></a>Hooks onto Xlib Data Structures</h3></div></div></div><p>

Various Xlib data structures have provisions for extension procedures
to chain extension supplied data onto a list.
These structures are
<span class="structname">GC</span>,
<span class="structname">Visual</span>,
<span class="type">Screen</span>,
<span class="structname">ScreenFormat</span>,
<span class="type">Display</span>,
and 
<span class="structname">XFontStruct</span>.
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.
</p><p>

The following structure is used in the functions in this section
and is defined in 
<code class="filename">&lt;X11/Xlib.h&gt;</code>
</p><p>

<a id="idp53865716" class="indexterm"></a>



</p><pre class="synopsis">
typedef struct _XExtData {
	int number;	/* number returned by XInitExtension */
	struct _XExtData *next;	/* next item on list of data for structure */
	int (*free_private)();	/* if defined,  called to free private */
	XPointer private_data;	/* data private to this extension. */
} XExtData;
</pre><p>
</p><p>


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. 
</p><p>




</p><pre class="synopsis">
union {	Display *display;
	GC gc;
	Visual *visual;
	Screen *screen;
	ScreenFormat *pixmap_format;
	XFontStruct *font } XEDataObject;
</pre><p>
</p><a id="idp53869844" class="indexterm"></a><div class="funcsynopsis"><a id="XEHeadOfExtensionList"></a><p><code class="funcdef">XExtData **<strong class="fsfunc">XEHeadOfExtensionList</strong>(</code>XEDataObject<var class="pdparam"> object</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>object</em></span>
    </span></p></td><td><p>
Specifies the object.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XEHeadOfExtensionList"><code class="function">XEHeadOfExtensionList</code></a>
function returns a pointer to the list of extension structures attached
to the specified object.
In concert with 
<a class="xref" href="#XAddToExtensionList"><code class="function">XAddToExtensionList</code></a>,
<a class="xref" href="#XEHeadOfExtensionList"><code class="function">XEHeadOfExtensionList</code></a>
allows an extension to attach arbitrary data to any of the structures
of types contained in
<span class="structname">XEDataObject</span>.
</p><a id="idp53875980" class="indexterm"></a><div class="funcsynopsis"><a id="XAddToExtensionList"></a><p><code class="funcdef"><strong class="fsfunc">XAddToExtensionList</strong>(</code>XExtData<var class="pdparam"> **structure</var>, XExtData<var class="pdparam"> *ext_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>structure</em></span>
    </span></p></td><td><p>
Specifies the extension list.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>ext_data</em></span>
    </span></p></td><td><p>
Specifies the extension data structure to add.
    </p></td></tr></tbody></table></div><p>


The structure argument is a pointer to one of the data structures
enumerated above.
You must initialize ext_data-&gt;number with the extension number
before calling this function.
</p><a id="idp53882324" class="indexterm"></a><div class="funcsynopsis"><a id="XFindOnExtensionList"></a><p><code class="funcdef">XExtData *<strong class="fsfunc">XFindOnExtensionList</strong>(</code>struct_XExtData<var class="pdparam"> **structure</var>, int<var class="pdparam"> number</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>structure</em></span>
    </span></p></td><td><p>
Specifies the extension list.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>number</em></span>
    </span></p></td><td><p>
Specifies the extension number from
<a class="xref" href="#XInitExtension"><code class="function">XInitExtension</code></a>.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XFindOnExtensionList"><code class="function">XFindOnExtensionList</code></a>
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.
</p><p>

The 
<a class="xref" href="#XAllocID"><code class="function">XAllocID</code></a>
macro, which allocates and returns a resource ID, is defined in 
<code class="filename">&lt;X11/Xlib.h&gt;</code>.
</p><a id="idp53890940" class="indexterm"></a><div class="funcsynopsis"><a id="XAllocID"></a><p><code class="funcdef"><strong class="fsfunc">XAllocID</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div><p>


This macro is a call through the 
<span class="type">Display</span>
structure to an internal resource ID allocator.
It returns a resource ID that you can use when creating new resources.
</p><p>

The 
<a class="xref" href="#XAllocIDs"><code class="function">XAllocIDs</code></a>
macro allocates and returns an array of resource ID.
</p><a id="idp53896452" class="indexterm"></a><div class="funcsynopsis"><a id="XAllocIDs"></a><p><code class="funcdef"><strong class="fsfunc">XAllocIDs</strong>(</code>Display<var class="pdparam"> *display</var>, XID<var class="pdparam"> *ids_return</var>, int<var class="pdparam"> count</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>ids_return</em></span>
    </span></p></td><td><p>
Returns the resource IDs.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>rep</em></span>
    </span></p></td><td><p>
Specifies the number of resource IDs requested.
    </p></td></tr></tbody></table></div><p>


This macro is a call through the 
<span class="type">Display</span>
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
<a class="xref" href="#XAllocIDs"><code class="function">XAllocIDs</code></a>
when requesting multiple resource IDs.  This call might generate
protocol requests.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="GC_Caching"></a>GC Caching</h2></div></div></div><p>

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.
</p><p>

The 
<a class="xref" href="#FlushGC"><code class="function">FlushGC</code></a>
macro checks the dirty bits in the library's GC structure and calls
<a class="xref" href="#_XFlushGCCache"><code class="function">_XFlushGCCache</code></a>
if any elements have changed.
The
<a class="xref" href="#FlushGC"><code class="function">FlushGC</code></a>
macro is defined as follows:
</p><a id="idp53908308" class="indexterm"></a><div class="funcsynopsis"><a id="FlushGC"></a><p><code class="funcdef"><strong class="fsfunc">FlushGC</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
    </p></td></tr></tbody></table></div><p>


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
<a class="xref" href="#_XFlushGCCache"><code class="function">_XFlushGCCache</code></a>
procedure 
to force the cache to be flushed.
The
<a class="xref" href="#_XFlushGCCache"><code class="function">_XFlushGCCache</code></a>
procedure
is defined as follows:
</p><a id="idp53915652" class="indexterm"></a><div class="funcsynopsis"><a id="_XFlushGCCache"></a><p><code class="funcdef"><strong class="fsfunc">_XFlushGCCache</strong>(</code>Display<var class="pdparam"> *display</var>, GC<var class="pdparam"> gc</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
    </p></td></tr></tbody></table></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Graphics_Batching"></a>Graphics Batching</h2></div></div></div><p>

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 
<span class="structname">xReq</span>,
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 
<a class="xref" href="#XDrawPoint"><code class="function">XDrawPoint</code></a>
stub.
(Writing extension stubs is discussed in the next section.)
</p><pre class="programlisting">
#include &lt;X11/Xlibint.h&gt;

/* 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-&gt;last_req;
    /* if same as previous request, with same drawable, batch requests */
    if (
          (req-&gt;reqType == X_PolyPoint)
       &amp;&amp; (req-&gt;drawable == d)
       &amp;&amp; (req-&gt;gc == gc-&gt;gid)
       &amp;&amp; (req-&gt;coordMode == CoordModeOrigin)
       &amp;&amp; ((dpy-&gt;bufptr + sizeof (xPoint)) &lt;= dpy-&gt;bufmax)
       &amp;&amp; (((char *)dpy-&gt;bufptr - (char *)req) &lt; size) ) {
         point = (xPoint *) dpy-&gt;bufptr;
         req-&gt;length += sizeof (xPoint) &gt;&gt; 2;
         dpy-&gt;bufptr += sizeof (xPoint);
         }

    else {
        GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */
        req-&gt;drawable = d;
        req-&gt;gc = gc-&gt;gid;
        req-&gt;coordMode = CoordModeOrigin;
        point = (xPoint *) (req + 1);
        }
    point-&gt;x = x;
    point-&gt;y = y;
    }
    UnlockDisplay(dpy);
    SyncHandle();
}
</pre><p>


To keep clients from generating very long requests that may monopolize the 
server,
there is a symbol defined in
<code class="filename">&lt;X11/Xlibint.h&gt;</code>
of EPERBATCH on the number of requests batched.
Most of the performance benefit occurs in the first few merged requests.
Note that 
<a class="xref" href="#FlushGC"><code class="function">FlushGC</code></a>
is called <span class="emphasis"><em>before</em></span> picking up the value of last_req,
because it may modify this field.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Writing_Extension_Stubs"></a>Writing Extension Stubs</h2></div></div></div><p>

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-&gt;max_request_size contains the maximum length as
defined by the server implementation.
For further information,
see <span class="olink"><em class="citetitle">X Window System Protocol</em></span>.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Requests_Replies_and_Xproto.h"></a>Requests, Replies, and Xproto.h</h3></div></div></div><p>

The 
<code class="filename">&lt;X11/Xproto.h&gt;</code>
file contains three sets of definitions that
are of interest to the stub implementor:  
request names, request structures, and reply structures.
</p><p>

You need to generate a file equivalent to 
<code class="filename">&lt;X11/Xproto.h&gt;</code>
for your extension and need to include it in your stub procedure.
Each stub procedure also must include 
<code class="filename">&lt;X11/Xlibint.h&gt;</code>.
</p><p>

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 
<code class="filename">&lt;X11/Xlibint.h&gt;</code>,
takes advantage of this naming scheme.
</p><p>

For each X request, 
there is a definition in 
<code class="filename">&lt;X11/Xproto.h&gt;</code>
that looks similar to this:
</p><p>


</p><pre class="programlisting">
#define X_DoSomething   42
</pre><p>
In your extension header file, 
this will be a minor opcode, 
instead of a major opcode.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Request_Format"></a>Request Format</h3></div></div></div><p>

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 
<span class="errorname">BadLength</span>
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).
</p><p>

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.
</p><p>

To help but not cure portability problems to certain machines, the
<span class="symbol">B16</span>
and
<span class="symbol">B32</span>
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.
</p><p>

Most protocol requests have a corresponding structure typedef in
<code class="filename">&lt;X11/Xproto.h&gt;</code>,
which looks like:
</p><p>

<a id="idp53940516" class="indexterm"></a>



</p><pre class="synopsis">
typedef struct _DoSomethingReq {
	CARD8 reqType;		/* X_DoSomething */
	CARD8 someDatum;	/* used differently in different requests */
	CARD16 length B16;	/* total # of bytes in request, divided by 4 */
	...
	/* request-specific data */
	...
} xDoSomethingReq;
</pre><p>
</p><p>


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
<span class="structname">xResourceReq</span>
structure in
<code class="filename">&lt;X11/Xproto.h&gt;</code>.
This structure is used for any request whose single argument is a 
<span class="type">Window</span>,
<span class="type">Pixmap</span>,
<span class="type">Drawable</span>,
<span class="type">GContext</span>,
<span class="type">Font</span>,
<span class="type">Cursor</span>,
<span class="type">Colormap</span>,
<span class="type">Atom</span>,
or
<span class="type">VisualID</span>.
</p><p>

<a id="idp53945972" class="indexterm"></a>



</p><pre class="synopsis">
typedef struct _ResourceReq {
	CARD8 reqType;	/* the request type, e.g. X_DoSomething */
	BYTE pad;	/* not used */
	CARD16 length B16;	/* 2 (= total # of bytes in request, divided by 4) */
	CARD32 id B32;	/* the Window, Drawable, Font, GContext, etc. */
} xResourceReq;
</pre><p>
</p><p>


If convenient,
you can do something similar in your extension header file. 
</p><p>

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.
</p><p>

A few protocol requests take no arguments at all. 
Instead, they use the
<span class="structname">xReq</span>
structure in
<code class="filename">&lt;X11/Xproto.h&gt;</code>,
which contains only a reqType and a length (and a pad byte).
</p><p>

If the protocol request requires a reply, 
then
<code class="filename">&lt;X11/Xproto.h&gt;</code>
also contains a reply structure typedef:
</p><p>

<a id="idp53951580" class="indexterm"></a>



</p><pre class="synopsis">
typedef struct _DoSomethingReply {
	BYTE type;	/* always X_Reply */
	BYTE someDatum;	/* used differently in different requests */
	CARD16 sequenceNumber B16;	/* # of requests sent so far */
	CARD32 length B32;	/* # of additional bytes, divided by 4 */
	...
	/* request-specific data */
	...
} xDoSomethingReply;
</pre><p>
</p><p>


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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The reply structure is followed by variable-length data,
such as a list or string.
    </p></li><li class="listitem"><p>
The reply structure is longer than 32 bytes.
    </p></li></ul></div><p>

Only 
<code class="systemitem">GetWindowAttributesl</code>,
<code class="systemitem">QueryFont</code>,
<code class="systemitem">QueryKeymap</code>,
and
<code class="systemitem">GetKeyboardControl</code>
have reply structures longer than 32 bytes in the core protocol.
</p><p>

A few protocol requests return replies that contain no data.  
<code class="filename">&lt;X11/Xproto.h&gt;</code>
does not define reply structures for these.
Instead, they use the 
<span class="structname">xGenericReply</span>
structure, which contains only a type, length,
and sequence number (and sufficient padding to make it 32 bytes long).
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Starting_to_Write_a_Stub_Procedure"></a>Starting to Write a Stub Procedure</h3></div></div></div><p>

An Xlib stub procedure should start like this:
</p><p>


</p><pre class="programlisting">
#include "&lt;X11/Xlibint.h&gt;

XDoSomething (arguments, ... )
/* argument declarations */
{

register XDoSomethingReq *req;
...
</pre><p>
If the protocol request has a reply, 
then the variable declarations should include the reply structure for the request.
The following is an example:
</p><p>


</p><pre class="programlisting">
xDoSomethingReply rep;
</pre><p>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Locking_Data_Structures"></a>Locking Data Structures</h3></div></div></div><p>

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.
<a id="idp54474708" class="indexterm"></a>

</p><div class="funcsynopsis"><a id="LockDisplay"></a><p><code class="funcdef"><strong class="fsfunc">LockDisplay</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><p>

</p><a id="idp54476852" class="indexterm"></a><div class="funcsynopsis"><a id="UnlockDisplay"></a><p><code class="funcdef"><strong class="fsfunc">UnlockDisplay</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
    </p></td></tr></tbody></table></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Sending_the_Protocol_Request_and_Arguments"></a>Sending the Protocol Request and Arguments</h3></div></div></div><p>

After the variable declarations, 
a stub procedure should call one of four macros defined in 
<code class="filename">&lt;X11/Xlibint.h&gt;</code>:
<code class="function">GetReq</code>,
<code class="function">GetReqExtra</code>,
<code class="function">GetResReq</code>,
or 
<code class="function">GetEmptyReq</code>.
All of these macros take, as their first argument,
the name of the protocol request as declared in 
<code class="filename">&lt;X11/Xproto.h&gt;</code>
except with X_ removed.   
Each one declares a 
<span class="type">Display</span>
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.
</p><p>

If the protocol request has no arguments (for instance, X_GrabServer),
then use 
<code class="function">GetEmptyReq</code>.
</p><p>


</p><pre class="programlisting">
GetEmptyReq (DoSomething, req);
</pre><p>
If the protocol request has a single 32-bit argument (such as a
<span class="type">Pixmap</span>,
<span class="type">Window</span>,
<span class="type">Drawable</span>,
<span class="type">Atom</span>,
and so on),
then use 
<code class="function">GetResReq</code>.
The second argument to the macro is the 32-bit object.  
<span class="symbol">X_MapWindow</span>
is a good example.
</p><p>


</p><pre class="programlisting">
GetResReq (DoSomething, rid, req);
</pre><p>
The rid argument is the 
<span class="type">Pixmap</span>,
<span class="type">Window</span>,
or other resource ID.
</p><p>

If the protocol request takes any other argument list, 
then call 
<code class="function">GetReq</code>.
After the 
<code class="function">GetReq</code>,
you need to set all the other fields in the request structure,
usually from arguments to the stub procedure.
</p><p>


</p><pre class="programlisting">
GetReq (DoSomething, req);
/* fill in arguments here */
req-&gt;arg1 = arg1;
req-&gt;arg2 = arg2;
...
</pre><p>
A few stub procedures (such as 
<a class="xref" href="#XCreateGC"><code class="function">XCreateGC</code></a>
and 
<a class="xref" href="#XCreatePixmap"><code class="function">XCreatePixmap</code></a>)
return a resource ID to the caller but pass a resource ID as an argument
to the protocol request.   
Such procedures use the macro 
<a class="xref" href="#XAllocID"><code class="function">XAllocID</code></a>
to allocate a resource ID from the range of IDs 
that were assigned to this client when it opened the connection.
</p><p>


</p><pre class="programlisting">
rid = req-&gt;rid = XAllocID();
...
return (rid);
</pre><p>
Finally, some stub procedures transmit a fixed amount of variable-length
data after the request.  
Typically, these procedures (such as
<a class="xref" href="#XMoveWindow"><code class="function">XMoveWindow</code></a>
and 
<a class="xref" href="#XSetBackground"><code class="function">XSetBackground</code></a>)
are special cases of more general functions like 
<a class="xref" href="#XMoveResizeWindow"><code class="function">XMoveResizeWindow</code></a>
and 
<a class="xref" href="#XChangeGC"><code class="function">XChangeGC</code></a>.
These procedures use 
<code class="function">GetReqExtra</code>,
which is the same as 
<code class="function">GetReq</code>
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. Note that it is possible
for req to be set to NULL as a defensive measure if the requested length
exceeds the Xlib's buffer size (normally 16K).
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Variable_Length_Arguments"></a>Variable Length Arguments</h3></div></div></div><p>

Some protocol requests take additional variable-length data that
follow the 
<span class="type">xDoSomethingReq</span>
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.
</p><p>

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:
</p><p>


</p><pre class="programlisting">
req-&gt;length += (nbytes+3)&gt;&gt;2;
</pre><p>
To transmit variable-length data, use the 
<a class="xref" href="#Data"><code class="function">Data</code></a>
macros.
If the data fits into the output buffer, 
then this macro copies it to the buffer.  
If it does not fit, however,
the 
<a class="xref" href="#Data"><code class="function">Data</code></a>
macro calls 
<code class="function">_XSend</code>,
which transmits first the contents of the buffer and then your data.
The 
<a class="xref" href="#Data"><code class="function">Data</code></a>
macros take three arguments:  
the display, a pointer to the beginning of the data, 
and the number of bytes to be sent.

</p><div class="funcsynopsis"><a id="Data"></a><p><code class="funcdef"><strong class="fsfunc">Data</strong>(</code><var class="pdparam"> display</var>, (char<var class="pdparam"> *</var><code>)</code>;</p></div><p>

</p><p>


<a class="xref" href="#Data"><code class="function">Data</code></a>,
<code class="function">Data16</code>,
and
<code class="function">Data32</code>
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.
</p><p>

If the protocol request requires a reply, 
then call the procedure 
<code class="function">_XSend</code>
instead of the 
<a class="xref" href="#Data"><code class="function">Data</code></a>
macro.  
<code class="function">_XSend</code>
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 
<a class="xref" href="#_XReply"><code class="function">_XReply</code></a>),
it is faster.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Replies"></a>Replies</h3></div></div></div><p>

If the protocol request has a reply, 
then call 
<a class="xref" href="#_XReply"><code class="function">_XReply</code></a>
after you have finished dealing with 
all the fixed-length and variable-length arguments.  
<a class="xref" href="#_XReply"><code class="function">_XReply</code></a>
flushes the output buffer and waits for an 
<span class="structname">xReply</span>
packet to arrive.  
If any events arrive in the meantime,
<a class="xref" href="#_XReply"><code class="function">_XReply</code></a>
places them in the queue for later use.
</p><a id="idp54507604" class="indexterm"></a><div class="funcsynopsis"><a id="_XReply"></a><p><code class="funcdef">Status <strong class="fsfunc">_XReply</strong>(</code>Display<var class="pdparam"> *display</var>, xReply<var class="pdparam"> *rep</var>, int<var class="pdparam"> extra</var>, Bool<var class="pdparam"> discard</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>rep</em></span>
    </span></p></td><td><p>
Specifies the reply structure.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>extra</em></span>
    </span></p></td><td><p>
Specifies the number of 32-bit words expected after the replay.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>discard</em></span>
    </span></p></td><td><p>
Specifies if any data beyond that specified in the extra argument
should be discarded.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#_XReply"><code class="function">_XReply</code></a>
function waits for a reply packet and copies its contents into the
specified rep.  
<a class="xref" href="#_XReply"><code class="function">_XReply</code></a>
handles error and event packets that occur before the reply is received.
<a class="xref" href="#_XReply"><code class="function">_XReply</code></a>
takes four arguments:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
A 
<span class="type">Display</span>
* structure
    </p></li><li class="listitem"><p>
A pointer to a reply structure (which must be cast to an 
<span class="structname">xReply</span>
*)
    </p></li><li class="listitem"><p>
The number of additional 32-bit words (beyond 
<code class="function">sizeof( xReply</code>)
= 32 bytes)
in the reply structure
    </p></li><li class="listitem"><p>
A Boolean that indicates whether
<a class="xref" href="#_XReply"><code class="function">_XReply</code></a>
is to discard any additional bytes
beyond those it was told to read
    </p></li></ul></div><p>

Because most reply structures are 32 bytes long, 
the third argument is usually 0.  
The only core protocol exceptions are the replies to 
<code class="systemitem">GetWindowAttributesl</code>,
<code class="systemitem">QueryFont</code>,
<code class="systemitem">QueryKeymap</code>,
and 
<code class="systemitem">GetKeyboardControl</code>,
which have longer replies.
</p><p>

The last argument should be 
<span class="symbol">False</span>
if the reply structure is followed
by additional variable-length data (such as a list or string).  
It should be 
<span class="symbol">True</span>
if there is not any variable-length data.

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 
<code class="systemitem">GetWindowAttributesl</code>
might use a
larger, but compatible, 
<span class="structname">xGetWindowAttributesReply</span>
that contains additional attribute data at the end.

<a class="xref" href="#_XReply"><code class="function">_XReply</code></a>
returns 
<span class="symbol">True</span>
if it received a reply successfully or 
<span class="symbol">False</span>
if it received any sort of error. 
</p><p>

For a request with a reply that is not followed by variable-length
data, you write something like:
</p><p>


</p><pre class="programlisting">
_XReply(display, (xReply *)&amp;rep, 0, True);
*ret1 = rep.ret1;
*ret2 = rep.ret2;
*ret3 = rep.ret3;
...
UnlockDisplay(dpy);
SyncHandle();
return (rep.ret4);
}
</pre><p>
If there is variable-length data after the reply, 
change the 
<span class="symbol">True</span>
to 
<span class="symbol">False</span>,
and use the appropriate
<a class="xref" href="#_XRead"><code class="function">_XRead</code></a>
function to read the variable-length data.
</p><div class="funcsynopsis"><a id="_XRead"></a><p><code class="funcdef"><strong class="fsfunc">_XRead</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> *data_return</var>, long<var class="pdparam"> nbytes</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>data_return</em></span>
    </span></p></td><td><p>
Specifies the buffer.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nbytes</em></span>
    </span></p></td><td><p>
Specifies the number of bytes required.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#_XRead"><code class="function">_XRead</code></a>
function reads the specified number of bytes into data_return.
</p><div class="funcsynopsis"><a id="_XRead16"></a><p><code class="funcdef"><strong class="fsfunc">_XRead16</strong>(</code>Display<var class="pdparam"> *display</var>, short<var class="pdparam"> *data_return</var>, long<var class="pdparam"> nbytes</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>data_return</em></span>
    </span></p></td><td><p>
Specifies the buffer.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nbytes</em></span>
    </span></p></td><td><p>
Specifies the number of bytes required.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#_XRead16"><code class="function">_XRead16</code></a>
function reads the specified number of bytes,
unpacking them as 16-bit quantities,
into the specified array as shorts.
</p><div class="funcsynopsis"><a id="_XRead32"></a><p><code class="funcdef"><strong class="fsfunc">_XRead32</strong>(</code>Display<var class="pdparam"> *display</var>, long<var class="pdparam"> *data_return</var>, long<var class="pdparam"> nbytes</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>data_return</em></span>
    </span></p></td><td><p>
Specifies the buffer.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nbytes</em></span>
    </span></p></td><td><p>
Specifies the number of bytes required.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#_XRead32"><code class="function">_XRead32</code></a>
function reads the specified number of bytes,
unpacking them as 32-bit quantities,
into the specified array as longs.
</p><div class="funcsynopsis"><a id="_XRead16Pad"></a><p><code class="funcdef"><strong class="fsfunc">_XRead16Pad</strong>(</code>Display<var class="pdparam"> *display</var>, short<var class="pdparam"> *data_return</var>, long<var class="pdparam"> nbytes</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>data_return</em></span>
    </span></p></td><td><p>
Specifies the buffer.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nbytes</em></span>
    </span></p></td><td><p>
Specifies the number of bytes required.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#_XRead16Pad"><code class="function">_XRead16Pad</code></a>
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,
<a class="xref" href="#_XRead16Pad"><code class="function">_XRead16Pad</code></a>
reads and discards up to two additional pad bytes.
</p><div class="funcsynopsis"><a id="_XReadPad"></a><p><code class="funcdef"><strong class="fsfunc">_XReadPad</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> *data_return</var>, long<var class="pdparam"> nbytes</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>data_return</em></span>
    </span></p></td><td><p>
Specifies the buffer.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nbytes</em></span>
    </span></p></td><td><p>
Specifies the number of bytes required.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#_XReadPad"><code class="function">_XReadPad</code></a>
function reads the specified number of bytes into data_return.
If the number of bytes is not a multiple of four,
<a class="xref" href="#_XReadPad"><code class="function">_XReadPad</code></a>
reads and discards up to three additional pad bytes.
</p><p>

Each protocol request is a little different. 
For further information,
see the Xlib sources for examples.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Synchronous_Calling"></a>Synchronous Calling</h3></div></div></div><p>

Each procedure should have a call, just before returning to the user, 
to a macro called
<code class="systemitem">SyncHandle</code>.
If synchronous mode is enabled (see 
<code class="function">XSynchronize</code>),
the request is sent immediately.
The library, however, waits until any error the procedure could generate
at the server has been handled.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Allocating_and_Deallocating_Memory"></a>Allocating and Deallocating Memory</h3></div></div></div><p>

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:
</p><p>

These should be used in place of any calls you would make to the normal
C library functions.
</p><p>

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:
</p><a id="idp54568116" class="indexterm"></a><div class="funcsynopsis"><a id="_XAllocScratch"></a><p><code class="funcdef">char *<strong class="fsfunc">_XAllocScratch</strong>(</code>Display<var class="pdparam"> *display</var>, unsignedlong<var class="pdparam"> nbytes</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nbytes</em></span>
    </span></p></td><td><p>
Specifies the number of bytes required.
    </p></td></tr></tbody></table></div><p>


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
<code class="function">GetReq</code>
or
<a class="xref" href="#Data"><code class="function">Data</code></a>
families of macros,
after any use of
<a class="xref" href="#_XReply"><code class="function">_XReply</code></a>,
or after any use of the
<code class="function">_XSend</code>
or
<a class="xref" href="#_XRead"><code class="function">_XRead</code></a>
families of functions.
</p><p>


The following function returns a scratch buffer for use across
critical sections:
</p><a id="idp54576068" class="indexterm"></a><div class="funcsynopsis"><a id="_XAllocTemp"></a><p><code class="funcdef">char *<strong class="fsfunc">_XAllocTemp</strong>(</code>Display<var class="pdparam"> *display</var>, unsignedlong<var class="pdparam"> nbytes</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nbytes</em></span>
    </span></p></td><td><p>
Specifies the number of bytes required.
    </p></td></tr></tbody></table></div><p>


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:
</p><a id="idp54581636" class="indexterm"></a><div class="funcsynopsis"><a id="_XFreeTemp"></a><p><code class="funcdef">void <strong class="fsfunc">_XFreeTemp</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> *buf</var>, unsignedlong<var class="pdparam"> nbytes</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>buf</em></span>
    </span></p></td><td><p>
Specifies the buffer to return.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>nbytes</em></span>
    </span></p></td><td><p>
Specifies the size of the buffer.
    </p></td></tr></tbody></table></div><p>


You must pass back the same pointer and size that were returned by
<a class="xref" href="#_XAllocTemp"><code class="function">_XAllocTemp</code></a>.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Portability_Considerations"></a>Portability Considerations</h3></div></div></div><p>

Many machine architectures, 
including many of the more recent <acronym class="acronym">RISC</acronym> 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 <span class="emphasis"><em>must</em></span> 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 <span class="emphasis"><em>must</em></span> 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.
</p><p>

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
<span class="type">CARD16</span>
in the protocol, be sure to declare it as
<span class="type">unsigned</span>
<span class="type">int</span>
and not as
<span class="type">int</span>.
(This, of course, does not apply to Booleans or enumerations.)
</p><p>

Similarly, 
if any integer argument or return value is declared
<span class="type">CARD32</span>
in the protocol, 
declare it as an
<span class="type">unsigned</span>
<span class="type">long</span>
and not as
<span class="type">int</span>
or
<span class="type">long</span>.
This also goes for any internal variables that may
take on values larger than the maximum 16-bit
<span class="type">unsigned</span>
<span class="type">int</span>.
</p><p>

The library currently assumes that a
<span class="type">char</span>
is 8 bits, a
<span class="type">short</span>
is 16 bits, an
<span class="type">int</span>
is 16 or 32 bits, and a
<span class="type">long</span>
is 32 bits.  
The 
<code class="function">PackData</code>
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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Deriving_the_Correct_Extension_Opcode"></a>Deriving the Correct Extension Opcode</h3></div></div></div><p>

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.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Declare an array of pointers, _NFILE long (this is normally found
in 
<code class="filename">&lt;stdio.h&gt;</code>
and is the number of file descriptors supported on the system)
of type 
<span class="structname">XExtCodes</span>.
Make sure these are all initialized to NULL.
    </p></li><li class="listitem"><p>
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.
    </p></li><li class="listitem"><p>
Once in your initialization procedure, call 
<a class="xref" href="#XInitExtension"><code class="function">XInitExtension</code></a>;
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
<span class="structname">XExtCodes</span>
structure for this extension, which is what would normally
be found in your array of pointers.
    </p></li><li class="listitem"><p>
After returning from your initialization procedure, 
the stub can now continue normally, because it has its major opcode safely 
in its hand in the 
<span class="structname">XExtCodes</span>
structure.

    </p></li></ul></div></div></div></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a id="compatibility_functions"></a>Appendix D. Compatibility Functions</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#X_Version_11_Compatibility_Functions">X Version 11 Compatibility Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Setting_Standard_Properties">Setting Standard Properties</a></span></dt><dt><span class="sect2"><a href="#Setting_and_Getting_Window_Sizing_Hints">Setting and Getting Window Sizing Hints</a></span></dt><dt><span class="sect2"><a href="#Getting_and_Setting_an_XStandardColormap_Structure">Getting and Setting an XStandardColormap Structure</a></span></dt><dt><span class="sect2"><a href="#Parsing_Window_Geometry">Parsing Window Geometry</a></span></dt><dt><span class="sect2"><a href="#Getting_the_X_Environment_Defaults">Getting the X Environment Defaults</a></span></dt></dl></dd><dt><span class="sect1"><a href="#X_Version_10_Compatibility_Functions">X Version 10 Compatibility Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Drawing_and_Filling_Polygons_and_Curves">Drawing and Filling Polygons and Curves</a></span></dt><dt><span class="sect2"><a href="#Associating_User_Data_with_a_Value">Associating User Data with a Value</a></span></dt></dl></dd></dl></div><p>
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.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X_Version_11_Compatibility_Functions"></a>X Version 11 Compatibility Functions</h2></div></div></div><p>
You can use the X Version 11 compatibility functions to:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Set standard properties 
    </p></li><li class="listitem"><p>
Set and get window sizing hints 
    </p></li><li class="listitem"><p>
Set and get an
<span class="structname">XStandardColormap</span>
structure 
    </p></li><li class="listitem"><p>
Parse window geometry
    </p></li><li class="listitem"><p>
Get X environment defaults
    </p></li></ul></div><p>
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_Standard_Properties"></a>Setting Standard Properties</h3></div></div></div><p>
To specify a minimum set of properties describing the simplest application,
use
<a class="xref" href="#XSetStandardProperties"><code class="function">XSetStandardProperties</code></a>.
This function has been superseded by
<a class="xref" href="#XSetWMProperties"><code class="function">XSetWMProperties</code></a>
and sets all or portions of the 
<span class="property">WM_NAME</span>, <span class="property">WM_ICON_NAME</span>, <span class="property">WM_HINTS</span>, <span class="property">WM_COMMAND</span>, 
and <span class="property">WM_NORMAL_HINTS</span> properties.
</p><a id="idp42978164" class="indexterm"></a><div class="funcsynopsis"><a id="XSetStandardProperties"></a><p><code class="funcdef"><strong class="fsfunc">XSetStandardProperties</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, char<var class="pdparam"> *window_name</var>, char<var class="pdparam"> *icon_name</var>, Pixmap<var class="pdparam"> icon_pixmap</var>, char<var class="pdparam"> **argv</var>, int<var class="pdparam"> argc</var>, XSizeHints<var class="pdparam"> *hints</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>window_name</em></span>
    </span></p></td><td><p>
Specifies the window name,
which should be a null-terminated string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>icon_name</em></span>
    </span></p></td><td><p>
Specifies the icon name,
which should be a null-terminated string.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>icon_pixmap</em></span>
    </span></p></td><td><p>
Specifies the bitmap that is to be used for the icon or
<span class="symbol">None</span>.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>argv</em></span>
    </span></p></td><td><p>
Specifies the application's argument list.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>argc</em></span>
    </span></p></td><td><p>
Specifies the number of arguments.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hints</em></span>
    </span></p></td><td><p>
Specifies a pointer to the size hints for the window in its normal state.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetStandardProperties"><code class="function">XSetStandardProperties</code></a>
function provides a means by which simple applications set the
most essential properties with a single call.
<a class="xref" href="#XSetStandardProperties"><code class="function">XSetStandardProperties</code></a>
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
<a class="xref" href="#XSetStandardProperties"><code class="function">XSetStandardProperties</code></a>.
(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.
</p><p>

<a class="xref" href="#XSetStandardProperties"><code class="function">XSetStandardProperties</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadWindow</span>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Setting_and_Getting_Window_Sizing_Hints"></a>Setting and Getting Window Sizing Hints</h3></div></div></div><p>
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
<span class="structname">XSizeHints</span>
structure, as defined in the
<code class="filename">&lt;X11/Xutil.h&gt;</code>
<a id="idp50155516" class="indexterm"></a>
<a id="idp49279580" class="indexterm"></a>
<a id="idp49280492" class="indexterm"></a>
header file and use the <span class="property">WM_NORMAL_HINTS</span> property.
</p><p>


To set the size hints for a given window in its normal state, use
<a class="xref" href="#XSetNormalHints"><code class="function">XSetNormalHints</code></a>.
This function has been superseded by
<a class="xref" href="#XSetWMNormalHints"><code class="function">XSetWMNormalHints</code></a>.
</p><a id="idp49283284" class="indexterm"></a><div class="funcsynopsis"><a id="XSetNormalHints"></a><p><code class="funcdef"><strong class="fsfunc">XSetNormalHints</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XSizeHints<var class="pdparam"> *hints</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hints</em></span>
    </span></p></td><td><p>
Specifies a pointer to the size hints for the window in its normal state.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetNormalHints"><code class="function">XSetNormalHints</code></a>
function sets the size hints structure for the specified window.
Applications use
<a class="xref" href="#XSetNormalHints"><code class="function">XSetNormalHints</code></a>
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
<a class="xref" href="#XSetNormalHints"><code class="function">XSetNormalHints</code></a>
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.
</p><p>

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
<a class="xref" href="#XSetNormalHints"><code class="function">XSetNormalHints</code></a>
is meaningless, unless the flags member is set to indicate which members of
the structure have been assigned values.
</p><p>

<a class="xref" href="#XSetNormalHints"><code class="function">XSetNormalHints</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To return the size hints for a window in its normal state, use
<a class="xref" href="#XGetNormalHints"><code class="function">XGetNormalHints</code></a>.
This function has been superseded by
<a class="xref" href="#XGetWMNormalHints"><code class="function">XGetWMNormalHints</code></a>.
</p><a id="idp50386636" class="indexterm"></a><div class="funcsynopsis"><a id="XGetNormalHints"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetNormalHints</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XSizeHints<var class="pdparam"> *hints_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hints_return</em></span>
    </span></p></td><td><p>
Returns the size hints for the window in its normal state.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetNormalHints"><code class="function">XGetNormalHints</code></a>
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.
</p><p>

<a class="xref" href="#XGetNormalHints"><code class="function">XGetNormalHints</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p><p>


The next two functions set and read the <span class="property">WM_ZOOM_HINTS</span> property.
</p><p>

To set the zoom hints for a window, use
<a class="xref" href="#XSetZoomHints"><code class="function">XSetZoomHints</code></a>.
This function is no longer supported by the
<em class="citetitle">Inter-Client Communication Conventions Manual</em>.
</p><a id="idp50363884" class="indexterm"></a><div class="funcsynopsis"><a id="XSetZoomHints"></a><p><code class="funcdef"><strong class="fsfunc">XSetZoomHints</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XSizeHints<var class="pdparam"> *zhints</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>zhints</em></span>
    </span></p></td><td><p>
Specifies a pointer to the zoom hints.
    </p></td></tr></tbody></table></div><p>


Many window managers think of windows in one of three states:
iconic, normal, or zoomed.
The
<a class="xref" href="#XSetZoomHints"><code class="function">XSetZoomHints</code></a>
function provides the window manager with information for the window in the
zoomed state.
</p><p>

<a class="xref" href="#XSetZoomHints"><code class="function">XSetZoomHints</code></a>
can generate
<span class="errorname">BadAlloc</span>
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To read the zoom hints for a window, use
<a class="xref" href="#XGetZoomHints"><code class="function">XGetZoomHints</code></a>.
This function is no longer supported by the
<em class="citetitle">Inter-Client Communication Conventions Manual</em>.
</p><a id="idp50077572" class="indexterm"></a><div class="funcsynopsis"><a id="XGetZoomHints"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetZoomHints</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XSizeHints<var class="pdparam"> *zhints_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>zhints_return</em></span>
    </span></p></td><td><p>
Returns the zoom hints.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetZoomHints"><code class="function">XGetZoomHints</code></a>
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.
</p><p>

<a class="xref" href="#XGetZoomHints"><code class="function">XGetZoomHints</code></a>
can generate a
<span class="errorname">BadWindow</span>
error.
</p><p>


To set the value of any property of type <span class="property">WM_SIZE_HINTS</span>, use
<a class="xref" href="#XSetSizeHints"><code class="function">XSetSizeHints</code></a>.
This function has been superseded by
<a class="xref" href="#XSetWMSizeHints"><code class="function">XSetWMSizeHints</code></a>.
</p><a id="idp49274108" class="indexterm"></a><div class="funcsynopsis"><a id="XSetSizeHints"></a><p><code class="funcdef"><strong class="fsfunc">XSetSizeHints</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XSizeHints<var class="pdparam"> *hints</var>, Atom<var class="pdparam"> property</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hints</em></span>
    </span></p></td><td><p>
Specifies a pointer to the size hints.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>property</em></span>
    </span></p></td><td><p>
Specifies the property name.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetSizeHints"><code class="function">XSetSizeHints</code></a>
function sets the
<span class="structname">XSizeHints</span>
structure for the named property and the specified window.
This is used by
<a class="xref" href="#XSetNormalHints"><code class="function">XSetNormalHints</code></a>
and
<a class="xref" href="#XSetZoomHints"><code class="function">XSetZoomHints</code></a>
and can be used to set the value of any property of type <span class="property">WM_SIZE_HINTS</span>.
Thus, it may be useful if other properties of that type get defined.
</p><p>

<a class="xref" href="#XSetSizeHints"><code class="function">XSetSizeHints</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadAtom</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To read the value of any property of type <span class="property">WM_SIZE_HINTS</span>, use
<a class="xref" href="#XGetSizeHints"><code class="function">XGetSizeHints</code></a>.
This function has been superseded by
<a class="xref" href="#XGetWMSizeHints"><code class="function">XGetWMSizeHints</code></a>.
</p><a id="idp52724228" class="indexterm"></a><div class="funcsynopsis"><a id="XGetSizeHints"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetSizeHints</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XSizeHints<var class="pdparam"> *hints_return</var>, Atom<var class="pdparam"> property</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>hints_return</em></span>
    </span></p></td><td><p>
Returns the size hints.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>property</em></span>
    </span></p></td><td><p>
Specifies the property name.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetSizeHints"><code class="function">XGetSizeHints</code></a>
function returns the
<span class="structname">XSizeHints</span>
structure for the named property and the specified window.
This is used by
<a class="xref" href="#XGetNormalHints"><code class="function">XGetNormalHints</code></a>
and
<a class="xref" href="#XGetZoomHints"><code class="function">XGetZoomHints</code></a>.
It also can be used to retrieve the value of any property of type
<span class="property">WM_SIZE_HINTS</span>.
Thus, it may be useful if other properties of that type get defined.
<a class="xref" href="#XGetSizeHints"><code class="function">XGetSizeHints</code></a>
returns a nonzero status if a size hint was defined
or zero otherwise.
</p><p>

<a class="xref" href="#XGetSizeHints"><code class="function">XGetSizeHints</code></a>
can generate
<span class="errorname">BadAtom</span>
and 
<span class="errorname">BadWindow</span>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Getting_and_Setting_an_XStandardColormap_Structure"></a>Getting and Setting an XStandardColormap Structure</h3></div></div></div><p>
To get the 
<span class="structname">XStandardColormap</span>
structure associated with one of the described atoms, use
<a class="xref" href="#XGetStandardColormap"><code class="function">XGetStandardColormap</code></a>.
This function has been superseded by
<a class="xref" href="#XGetRGBColormaps"><code class="function">XGetRGBColormaps</code></a>.
</p><a id="idp52733756" class="indexterm"></a><div class="funcsynopsis"><a id="XGetStandardColormap"></a><p><code class="funcdef">Status <strong class="fsfunc">XGetStandardColormap</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XStandardColormap<var class="pdparam"> *colormap_return</var>, Atom<var class="pdparam"> property</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap_return</em></span>
    </span></p></td><td><p>
Returns the colormap associated with the specified atom.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>property</em></span>
    </span></p></td><td><p>
Specifies the property name.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetStandardColormap"><code class="function">XGetStandardColormap</code></a>
function returns the colormap definition associated with the atom supplied
as the property argument.
<a class="xref" href="#XGetStandardColormap"><code class="function">XGetStandardColormap</code></a>
returns a nonzero status if successful and zero otherwise.
For example,
to fetch the standard
<span class="symbol">GrayScale</span>
colormap for a display,
you use
<a class="xref" href="#XGetStandardColormap"><code class="function">XGetStandardColormap</code></a>
with the following syntax:
</p><pre class="programlisting">
XGetStandardColormap(dpy, DefaultRootWindow(dpy), &amp;cmap, XA_RGB_GRAY_MAP);
</pre><p>
See <a class="link" href="#Standard_Colormaps" title="Standard Colormaps">section 14.3</a> for the
semantics of standard colormaps.
</p><p>

<a class="xref" href="#XGetStandardColormap"><code class="function">XGetStandardColormap</code></a>
can generate
<span class="errorname">BadAtom</span>
and
<span class="errorname">BadWindow</span>
errors.
</p><p>


To set a standard colormap, use
<a class="xref" href="#XSetStandardColormap"><code class="function">XSetStandardColormap</code></a>.
This function has been superseded by
<a class="xref" href="#XSetRGBColormaps"><code class="function">XSetRGBColormaps</code></a>.
</p><a id="idp50393532" class="indexterm"></a><div class="funcsynopsis"><a id="XSetStandardColormap"></a><p><code class="funcdef"><strong class="fsfunc">XSetStandardColormap</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> w</var>, XStandardColormap<var class="pdparam"> *colormap</var>, Atom<var class="pdparam"> property</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>w</em></span>
    </span></p></td><td><p>
Specifies the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>colormap</em></span>
    </span></p></td><td><p>
Specifies the colormap.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>property</em></span>
    </span></p></td><td><p>
Specifies the property name.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XSetStandardColormap"><code class="function">XSetStandardColormap</code></a>
function usually is only used by window or session managers.
</p><p>

<a class="xref" href="#XSetStandardColormap"><code class="function">XSetStandardColormap</code></a>
can generate
<span class="errorname">BadAlloc</span>,
<span class="errorname">BadAtom</span>,
<span class="errorname">BadDrawable</span>,
and
<span class="errorname">BadWindow</span>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Parsing_Window_Geometry"></a>Parsing Window Geometry</h3></div></div></div><p>
To parse window geometry given a user-specified position 
and a default position, use
<a class="xref" href="#XGeometry"><code class="function">XGeometry</code></a>.
This function has been superseded by
<a class="xref" href="#XWMGeometry"><code class="function">XWMGeometry</code></a>.
</p><a id="idp50416148" class="indexterm"></a><a id="idp50416700" class="indexterm"></a><div class="funcsynopsis"><a id="XGeometry"></a><p><code class="funcdef">int <strong class="fsfunc">XGeometry</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> screen</var>, char*position,<var class="pdparam"> *default_position</var>, unsignedint<var class="pdparam"> bwidth</var>, unsignedintfwidth,<var class="pdparam"> fheight</var>, intxadder,<var class="pdparam"> yadder</var>, int*x_return,<var class="pdparam"> *y_return</var>, int*width_return,<var class="pdparam"> *height_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>screen</em></span>
    </span></p></td><td><p>
Specifies the screen.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>position</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>default_position</em></span>
    </span></p></td><td><p>
Specify the geometry specifications.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>bwidth</em></span>
    </span></p></td><td><p>
Specifies the border width.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>fheight</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>fwidth</em></span>
    </span></p></td><td><p>
Specify the font height and width in pixels (increment size).
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>xadder</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>yadder</em></span>
    </span></p></td><td><p>
Specify additional interior padding needed in the window.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>y_return</em></span>
    </span></p></td><td><p>
Return the x and y offsets.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>width_return</em></span>
    </span></p></td><td><p>


      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>height_return</em></span>
    </span></p></td><td><p>
Return the width and height determined.
    </p></td></tr></tbody></table></div><p>


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
<a class="xref" href="#XGeometry"><code class="function">XGeometry</code></a>
function returns the position the window should be placed given a position and
a default position.
<a class="xref" href="#XGeometry"><code class="function">XGeometry</code></a>
determines the placement of
a window using a geometry specification as specified by
<a class="xref" href="#XParseGeometry"><code class="function">XParseGeometry</code></a>
and the additional information about the window.
Given a fully qualified default geometry specification and
an incomplete geometry specification, 
<a class="xref" href="#XParseGeometry"><code class="function">XParseGeometry</code></a>
returns a bitmask value as defined above in the 
<a class="xref" href="#XParseGeometry"><code class="function">XParseGeometry</code></a>
call,
by using the position argument.
</p><p>

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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Getting_the_X_Environment_Defaults"></a>Getting the X Environment Defaults</h3></div></div></div><p>
The
<a class="xref" href="#XGetDefault"><code class="function">XGetDefault</code></a>
function provides a primitive interface to the resource manager facilities 
discussed in <a class="link" href="#Resource_Manager_Functions" title="Chapter 15. Resource Manager Functions">chapter 15</a>.
It is only useful in very simple applications.
</p><a id="idp53708348" class="indexterm"></a><div class="funcsynopsis"><a id="XGetDefault"></a><p><code class="funcdef">char *<strong class="fsfunc">XGetDefault</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> *program</var>, char<var class="pdparam"> *option</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>program</em></span>
    </span></p></td><td><p>
Specifies the program name for the Xlib defaults (usually argv[0] 
of the main program).
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>option</em></span>
    </span></p></td><td><p>
Specifies the option name.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XGetDefault"><code class="function">XGetDefault</code></a>
function returns the value of the resource <span class="emphasis"><em>prog</em></span>.<span class="emphasis"><em>option</em></span>,
where <span class="emphasis"><em>prog</em></span> is the program argument with the directory prefix removed
and <span class="emphasis"><em>option</em></span> must be a single component.
Note that multilevel resources cannot be used with
<a class="xref" href="#XGetDefault"><code class="function">XGetDefault</code></a>.
The class "Program.Name" is always used for the resource lookup.
If the specified option name does not exist for this program,
<a class="xref" href="#XGetDefault"><code class="function">XGetDefault</code></a>
returns NULL.
The strings returned by
<a class="xref" href="#XGetDefault"><code class="function">XGetDefault</code></a>
are owned by Xlib and should not be modified or freed by the client.
</p><p>

If a database has been set with 
<a class="xref" href="#XrmSetDatabase"><code class="function">XrmSetDatabase</code></a>,
that database is used for the lookup.
Otherwise, a database is created
and is set in the display (as if by calling 
<a class="xref" href="#XrmSetDatabase"><code class="function">XrmSetDatabase</code></a>).
The database is created in the current locale.
To create a database,
<a class="xref" href="#XGetDefault"><code class="function">XGetDefault</code></a>
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 <acronym class="acronym">POSIX</acronym>-conformant system,
this file is
<code class="function">"$HOME/.Xdefaults"</code>.
<a id="idp53722372" class="indexterm"></a>
After loading these defaults,
<a class="xref" href="#XGetDefault"><code class="function">XGetDefault</code></a>
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,
<a class="xref" href="#XGetDefault"><code class="function">XGetDefault</code></a>
looks for
"<code class="filename">$HOME/.Xdefaults-<em class="replaceable"><code>name</code></em></code>" ,
where <em class="replaceable"><code>name</code></em> specifies the name of the machine on which the application
is running.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="X_Version_10_Compatibility_Functions"></a>X Version 10 Compatibility Functions</h2></div></div></div><p>
You can use the X Version 10 compatibility functions to:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Draw and fill polygons and curves
    </p></li><li class="listitem"><p>
Associate user data with a value
    </p></li></ul></div><p>
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Drawing_and_Filling_Polygons_and_Curves"></a>Drawing and Filling Polygons and Curves</h3></div></div></div><p>

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 
<a class="xref" href="#XDrawLines"><code class="function">XDrawLines</code></a>
<a id="idp53728940" class="indexterm"></a>
or
<a class="xref" href="#XDrawSegments"><code class="function">XDrawSegments</code></a>
<a id="idp53729796" class="indexterm"></a>
is much faster.
</p><p>

The functions discussed here provide all the functionality of the 
X Version 10 functions 
<a class="xref" href="#XDraw"><code class="function">XDraw</code></a>,
<a id="idp53731132" class="indexterm"></a>
<a class="xref" href="#XDrawFilled"><code class="function">XDrawFilled</code></a>,
<a id="idp53732132" class="indexterm"></a>
<code class="function">XDrawPatterned</code>,
<a id="idp53733076" class="indexterm"></a>
<code class="function">XDrawDashed</code>,
<a id="idp53734020" class="indexterm"></a>
and
<code class="function">XDrawTiled</code>.
<a id="idp53734956" class="indexterm"></a>
They are as compatible as possible given X Version 11's new line-drawing 
functions.  
One thing to note, however, is that
<code class="function">VertexDrawLastPoint</code>
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).  
<code class="function">XAppendVertex</code>
and 
<code class="function">XClearVertexFlag</code>
from X Version 10 also are not supported.
</p><p>

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 
<a class="xref" href="#XDrawLines"><code class="function">XDrawLines</code></a>).
The functions discussed here fail (return zero) only if they run out of memory
or are passed a 
<span class="structname">Vertex</span>
list that has a 
<span class="structname">Vertex</span>
with 
<span class="symbol">VertexStartClosed</span>
set that is not followed by a 
<span class="structname">Vertex</span>
with 
<span class="symbol">VertexEndClosed</span>
set.
</p><p>


To achieve the effects of the X Version 10
<a class="xref" href="#XDraw"><code class="function">XDraw</code></a>,
<a id="idp50288236" class="indexterm"></a>
<code class="function">XDrawDashed</code>,
<a id="idp50289172" class="indexterm"></a>
and 
<code class="function">XDrawPatterned</code>,
<a id="idp50290116" class="indexterm"></a>
use
<a class="xref" href="#XDraw"><code class="function">XDraw</code></a>.
</p><p>
#include &lt;X11/X10.h&gt;
</p><div class="funcsynopsis"><a id="XDraw"></a><p><code class="funcdef">Status <strong class="fsfunc">XDraw</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, Vertex<var class="pdparam"> *vlist</var>, int<var class="pdparam"> vcount</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>vlist</em></span>
    </span></p></td><td><p>
Specifies a pointer to the list of vertices that indicate what to draw.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>vcount</em></span>
    </span></p></td><td><p>
Specifies how many vertices are in vlist.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDraw"><code class="function">XDraw</code></a>
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.
</p><p>

Each Vertex, as defined in
<code class="filename">&lt;X11/X10.h&gt;</code>,
<a id="idp50303612" class="indexterm"></a>
<a id="idp50304508" class="indexterm"></a>
<a id="idp50305412" class="indexterm"></a>
is a structure with the following members:
<a id="idp50306356" class="indexterm"></a>
</p><pre class="synopsis">
typedef struct _Vertex {
	short x,y;
	unsigned short flags;
} Vertex;
</pre><p>
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 
<span class="symbol">VertexRelative</span>
is zero) or the previous vertex (if 
<span class="symbol">VertexRelative</span>
is one).
</p><p>

The flags, as defined in 
<code class="filename">&lt;X11/X10.h&gt;</code>,
<a id="idp50308700" class="indexterm"></a>
<a id="idp50309596" class="indexterm"></a>
<a id="idp50310500" class="indexterm"></a>
are as follows:
<a id="idp50311412" class="indexterm"></a>
<a id="idp50311844" class="indexterm"></a>
<a id="idp50312276" class="indexterm"></a>
<a id="idp50312708" class="indexterm"></a>
<a id="idp50313140" class="indexterm"></a>


</p><pre class="synopsis">
VertexRelative     0x0001     /* else absolute */
VertexDontDraw     0x0002     /* else draw */
VertexCurved       0x0004     /* else straight */
VertexStartClosed  0x0008     /* else not */
VertexEndClosed    0x0010     /* else not */
</pre><p>

</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If 
<span class="symbol">VertexRelative</span>
is not set,  
the coordinates are absolute (that is, relative to the drawable's origin).  
The first vertex must be an absolute vertex.
    </p></li><li class="listitem"><p>
If
<span class="symbol">VertexDontDraw</span>
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.
    </p></li><li class="listitem"><p>
If 
<span class="symbol">VertexCurved</span>
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 
<span class="symbol">VertexCurved</span>
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).
    </p></li><li class="listitem"><p>
It is permissible for 
<span class="symbol">VertexDontDraw</span>
bits and 
<span class="symbol">VertexCurved</span>
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.
    </p></li><li class="listitem"><p>
If 
<span class="symbol">VertexStartClosed</span>
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
<span class="symbol">VertexEndClosed</span>
bit of one.
The points in between form a cycle to determine predecessor 
and successor vertices for the spline algorithm.
    </p></li></ul></div><p>
</p><p>

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.
</p><p>


To achieve the effects of the X Version 10
<code class="function">XDrawTiled</code>
<a id="idp50321420" class="indexterm"></a>
and 
<a class="xref" href="#XDrawFilled"><code class="function">XDrawFilled</code></a>,
<a id="idp50322420" class="indexterm"></a>
use
<a class="xref" href="#XDrawFilled"><code class="function">XDrawFilled</code></a>.
</p><p>#include &lt;X11/X10.h&gt;</p><div class="funcsynopsis"><a id="XDrawFilled"></a><p><code class="funcdef">Status <strong class="fsfunc">XDrawFilled</strong>(</code>Display<var class="pdparam"> *display</var>, Drawable<var class="pdparam"> d</var>, GC<var class="pdparam"> gc</var>, Vertex<var class="pdparam"> *vlist</var>, int<var class="pdparam"> vcount</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>d</em></span>
    </span></p></td><td><p>
Specifies the drawable. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>gc</em></span>
    </span></p></td><td><p>
Specifies the GC.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>vlist</em></span>
    </span></p></td><td><p>
Specifies a pointer to the list of vertices that indicate what to draw.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>vcount</em></span>
    </span></p></td><td><p>
Specifies how many vertices are in vlist.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDrawFilled"><code class="function">XDrawFilled</code></a>
function draws arbitrary polygons or curves and then fills them.
</p><p>

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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Associating_User_Data_with_a_Value"></a>Associating User Data with a Value</h3></div></div></div><p>

These functions have been superseded by the context management functions
(see <a class="link" href="#Using_the_Context_Manager" title="Using the Context Manager">section 16.10</a>).
It is often necessary to associate arbitrary information with resource IDs.
Xlib provides the 
<code class="function">XAssocTable</code>
functions that you can use to make such an association.
<a id="idp50337660" class="indexterm"></a>
<a id="idp50338084" class="indexterm"></a>
<a id="idp50338652" class="indexterm"></a>
Application programs often need to be able to easily refer to
their own data structures when an event arrives.
The 
<code class="function">XAssocTable</code>
system provides users of the X library with a method
for associating their own data structures with X resources
(<span class="type">Pixmap</span>s,
<span class="type">Font</span>s,
<span class="type">Window</span>s,
and so on).
</p><p>

An 
<code class="function">XAssocTable</code>
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.
</p><p>

There are a few  guidelines  that  should be observed when using an
<code class="function">XAssocTable</code> :
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
All  XIDs  are  relative  to  the  specified display.
    </p></li><li class="listitem"><p>
Because  of  the  hashing  scheme  used  by  the  association mechanism,
the following rules for determining the size of a
<code class="function">XAssocTable</code>
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.
    </p></li></ul></div><p>


To return a pointer to a new
<code class="function">XAssocTable</code>,
use 
<a class="xref" href="#XCreateAssocTable"><code class="function">XCreateAssocTable</code></a>.
<a id="idp50345428" class="indexterm"></a>

</p><div class="funcsynopsis"><a id="XCreateAssocTable"></a><p><code class="funcdef">XAssocTable *<strong class="fsfunc">XCreateAssocTable</strong>(</code>int<var class="pdparam"> size</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>size</em></span>
    </span></p></td><td><p>
Specifies the number of buckets in the hash system of
<code class="function">XAssocTable</code>.
    </p></td></tr></tbody></table></div><p>


The size argument specifies the number of buckets in the 
hash system of
<code class="function">XAssocTable</code>.
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
<code class="function">XAssocTable</code>
occurs, 
a NULL pointer is returned. 
</p><p>


To create an entry in a given 
<code class="function">XAssocTable</code>,
use 
<a class="xref" href="#XMakeAssoc"><code class="function">XMakeAssoc</code></a>.
<a id="idp50352628" class="indexterm"></a>

</p><div class="funcsynopsis"><a id="XMakeAssoc"></a><p><code class="funcdef"><strong class="fsfunc">XMakeAssoc</strong>(</code>Display<var class="pdparam"> *display</var>, XAssocTable<var class="pdparam"> *table</var>, XID<var class="pdparam"> x_id</var>, char<var class="pdparam"> *data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>table</em></span>
    </span></p></td><td><p>
Specifies the assoc table. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x_id</em></span>
    </span></p></td><td><p>
Specifies the X resource ID.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>data</em></span>
    </span></p></td><td><p>
Specifies the data to be associated with the X resource ID.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XMakeAssoc"><code class="function">XMakeAssoc</code></a>
function inserts data into an 
<code class="function">XAssocTable</code>
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.
</p><p>


To obtain data from a given 
<code class="function">XAssocTable</code>,
use 
<a class="xref" href="#XLookUpAssoc"><code class="function">XLookUpAssoc</code></a>.
</p><a id="idp54348540" class="indexterm"></a><div class="funcsynopsis"><a id="XLookUpAssoc"></a><p><code class="funcdef">char *<strong class="fsfunc">XLookUpAssoc</strong>(</code>Display<var class="pdparam"> *display</var>, XAssocTable<var class="pdparam"> *table</var>, XID<var class="pdparam"> x_id</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>table</em></span>
    </span></p></td><td><p>
Specifies the assoc table. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x_id</em></span>
    </span></p></td><td><p>
Specifies the X resource ID.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XLookUpAssoc"><code class="function">XLookUpAssoc</code></a>
function retrieves the data stored in an 
<code class="function">XAssocTable</code>
by its XID.  
If  an appropriately  matching XID can be found in the table,
<a class="xref" href="#XLookUpAssoc"><code class="function">XLookUpAssoc</code></a>
returns the data associated with it.
If the x_id cannot be found in the table,
it returns NULL.
</p><p>


To delete an entry from a given 
<code class="function">XAssocTable</code>,
use 
<a class="xref" href="#XDeleteAssoc"><code class="function">XDeleteAssoc</code></a>.
</p><a id="idp54359212" class="indexterm"></a><div class="funcsynopsis"><a id="XDeleteAssoc"></a><p><code class="funcdef"><strong class="fsfunc">XDeleteAssoc</strong>(</code>Display<var class="pdparam"> *display</var>, XAssocTable<var class="pdparam"> *table</var>, XID<var class="pdparam"> x_id</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>table</em></span>
    </span></p></td><td><p>
Specifies the assoc table. 
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>x_id</em></span>
    </span></p></td><td><p>
Specifies the X resource ID.
    </p></td></tr></tbody></table></div><p>


The
<a class="xref" href="#XDeleteAssoc"><code class="function">XDeleteAssoc</code></a>
function deletes an association in an 
<code class="function">XAssocTable</code>
keyed on its XID.
Redundant deletes (and deletes of nonexistent XIDs) are ignored.
Deleting associations in no way impairs the performance of an
<code class="function">XAssocTable</code>.
</p><p>


To free the memory associated with a given 
<code class="function">XAssocTable</code>,
use 
<a class="xref" href="#XDestroyAssocTable"><code class="function">XDestroyAssocTable</code></a>.
</p><a id="idp54369764" class="indexterm"></a><div class="funcsynopsis"><a id="XDestroyAssocTable"></a><p><code class="funcdef"><strong class="fsfunc">XDestroyAssocTable</strong>(</code>XAssocTable<var class="pdparam"> *table</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>table</em></span>
    </span></p></td><td><p>
Specifies the assoc table. 
    </p></td></tr></tbody></table></div></div></div></div><div class="glossary"><div class="titlepage"><div><div><h1 class="title"><a id="glossary"></a>Glossary</h1></div></div></div><dl><dt><a id="glossary:Access_control_list"></a><span class="glossterm">Access control list</span></dt><a id="idp36928468" class="indexterm"></a><dd class="glossdef"><p>
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. 
    </p></dd><dt><a id="glossary:Active_grab"></a><span class="glossterm">Active grab</span></dt><a id="idp42002788" class="indexterm"></a><dd class="glossdef"><p>
A grab is active when the pointer or keyboard is actually owned by the 
single grabbing client.
    </p></dd><dt><a id="glossary:Ancestors"></a><span class="glossterm">Ancestors</span></dt><a id="idp38711260" class="indexterm"></a><dd class="glossdef"><p>
If W is an inferior of A, then A is an ancestor of W.
    </p></dd><dt><a id="glossary:Atom"></a><span class="glossterm">Atom</span></dt><a id="idp40429156" class="indexterm"></a><dd class="glossdef"><p>
An atom is a unique ID corresponding to a string name.
Atoms are used to identify properties, types, and selections.
    </p></dd><dt><a id="glossary:Background"></a><span class="glossterm">Background</span></dt><a id="idp41782148" class="indexterm"></a><dd class="glossdef"><p>
An
<span class="symbol">InputOutput</span>
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.
    </p></dd><dt><a id="glossary:Backing_store"></a><span class="glossterm">Backing store</span></dt><a id="idp40497196" class="indexterm"></a><dd class="glossdef"><p>
When a server maintains the contents of a window, 
the pixels saved off-screen are known as a backing store.
    </p></dd><dt><a id="glossary:Base_font_name"></a><span class="glossterm">Base font name</span></dt><a id="idp42347780" class="indexterm"></a><dd class="glossdef"><p>
A font name used to select a family of fonts whose members may be encoded 
in various charsets.
The
<em class="structfield"><code>CharSetRegistry</code></em>
and 
<em class="structfield"><code>CharSetEncoding</code></em>
fields of an <acronym class="acronym">XLFD</acronym> name identify the charset of the font.
A base font name may be a full <acronym class="acronym">XLFD</acronym> name, with all fourteen '-' delimiters, 
or an abbreviated <acronym class="acronym">XLFD</acronym> name containing only the first 12 fields of an <acronym class="acronym">XLFD</acronym> name,
up to but not including 
<em class="structfield"><code>CharSetRegistry</code></em>,
with or without the thirteenth '-', or a non-<acronym class="acronym">XLFD</acronym> name.
Any <acronym class="acronym">XLFD</acronym> fields may contain wild cards.
</p><p>
When creating an 
<span class="type">XFontSet</span>,
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.
    </p></dd><dt><a id="glossary:Bit_gravity"></a><span class="glossterm">Bit gravity</span></dt><a id="idp50088972" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Bit_plane"></a><span class="glossterm">Bit plane</span></dt><a id="idp50090940" class="indexterm"></a><dd class="glossdef"><p>
When a pixmap or window is thought of as a stack of bitmaps,
each bitmap is called a bit plane or plane.
    </p></dd><dt><a id="glossary:Bitmap"></a><span class="glossterm">Bitmap</span></dt><a id="idp50092676" class="indexterm"></a><dd class="glossdef"><p>
A bitmap is a <a class="glossterm" href="#glossary:Pixmap"><em class="glossterm">pixmap</em></a> of depth one.
    </p></dd><dt><a id="glossary:Border"></a><span class="glossterm">Border</span></dt><a id="idp47563892" class="indexterm"></a><dd class="glossdef"><p>
An
<span class="symbol">InputOutput</span>
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.
    </p></dd><dt><a id="glossary:Button_grabbing"></a><span class="glossterm">Button grabbing</span></dt><a id="idp47565788" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Byte_order"></a><span class="glossterm">Byte order</span></dt><a id="idp47567580" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Character"></a><span class="glossterm">Character</span></dt><a id="idp48702588" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Character_glyph"></a><span class="glossterm">Character glyph</span></dt><a id="idp48704260" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Character_set"></a><span class="glossterm">Character set</span></dt><a id="idp48705948" class="indexterm"></a><dd class="glossdef"><p>
A collection of characters.
    </p></dd><dt><a id="glossary:Charset"></a><span class="glossterm">Charset</span></dt><a id="idp48707452" class="indexterm"></a><dd class="glossdef"><p>
An encoding with a uniform, state-independent mapping from characters 
to codepoints.
A coded character set.
</p><p>
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.
</p><p>
Note that a single font charset is sometimes used as the encoding of a locale,
for example, ISO8859-1.
    </p></dd><dt><a id="glossary:Children"></a><span class="glossterm">Children</span></dt><a id="idp54375908" class="indexterm"></a><dd class="glossdef"><p>
The children of a window are its first-level subwindows.
    </p></dd><dt><a id="glossary:Class"></a><span class="glossterm">Class</span></dt><a id="idp54377452" class="indexterm"></a><dd class="glossdef"><p>
Windows can be of different classes or types.
See the entries for
<a class="glossterm" href="#glossary:InputOnly_window"><em class="glossterm">InputOnly</em></a>
and
<a class="glossterm" href="#glossary:InputOutput_window"><em class="glossterm">InputOutput</em></a>
windows for further information about valid window types.
    </p></dd><dt><a id="glossary:Client"></a><span class="glossterm">Client</span></dt><a id="idp54379740" class="indexterm"></a><dd class="glossdef"><p>
An application program connects to the window system server by some
interprocess communication (<acronym class="acronym">IPC</acronym>) path, such as a <acronym class="acronym">TCP</acronym> 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 <acronym class="acronym">IPC</acronym> 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.
    </p></dd><dt><a id="glossary:Clipping_region"></a><span class="glossterm">Clipping region</span></dt><a id="idp54382260" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Coded_character"></a><span class="glossterm">Coded character</span></dt><a id="idp54383916" class="indexterm"></a><dd class="glossdef"><p>
A character bound to a codepoint.
    </p></dd><dt><a id="glossary:Coded_character_set"></a><span class="glossterm">Coded character set</span></dt><a id="idp54385356" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Codepoint"></a><span class="glossterm">Codepoint</span></dt><a id="idp54387140" class="indexterm"></a><dd class="glossdef"><p>
The coded representation of a single character in a coded character set.
    </p></dd><dt><a id="glossary:Colormap"></a><span class="glossterm">Colormap</span></dt><a id="idp54388700" class="indexterm"></a><dd class="glossdef"><p>
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 <acronym class="acronym">RGB</acronym> 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.
    </p></dd><dt><a id="glossary:Connection"></a><span class="glossterm">Connection</span></dt><a id="idp54390796" class="indexterm"></a><dd class="glossdef"><p>
The <acronym class="acronym">IPC</acronym> 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.
    </p></dd><dt><a id="glossary:Containment"></a><span class="glossterm">Containment</span></dt><a id="idp54392652" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Coordinate_system"></a><span class="glossterm">Coordinate system</span></dt><a id="idp54394428" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Cursor"></a><span class="glossterm">Cursor</span></dt><a id="idp54396236" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Depth"></a><span class="glossterm">Depth</span></dt><a id="idp54397964" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Device"></a><span class="glossterm">Device</span></dt><a id="idp54399636" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:DirectColor"></a><span class="glossterm">DirectColor</span></dt><a id="idp54401332" class="indexterm"></a><dd class="glossdef"><p>
<span class="symbol">DirectColor</span>
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 <acronym class="acronym">RGB</acronym> (red, green, and blue) values in the colormap entry can be 
changed dynamically.
    </p></dd><dt><a id="glossary:Display"></a><span class="glossterm">Display</span></dt><a id="idp54403676" class="indexterm"></a><a id="idp54404100" class="indexterm"></a><dd class="glossdef"><p>
A server, together with its screens and input devices, is called a display.
The Xlib
<span class="type">Display</span>
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.
    </p></dd><dt><a id="glossary:Drawable"></a><span class="glossterm">Drawable</span></dt><a id="idp54406212" class="indexterm"></a><dd class="glossdef"><p>
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 
<span class="symbol">InputOnly</span>
window cannot be used as a source or destination in a
graphics operation.
    </p></dd><dt><a id="glossary:Encoding"></a><span class="glossterm">Encoding</span></dt><a id="idp54408156" class="indexterm"></a><dd class="glossdef"><p>
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.
</p><p>
In X, encodings are identified by a string
which appears as: the
<em class="structfield"><code>CharSetRegistry</code></em>
and
<em class="structfield"><code>CharSetEncoding</code></em>
components of an <acronym class="acronym">XLFD</acronym>
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.
    </p></dd><dt><a id="glossary:Escapement"></a><span class="glossterm">Escapement</span></dt><a id="idp54411340" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Event"></a><span class="glossterm">Event</span></dt><a id="idp54413028" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Event_mask"></a><span class="glossterm">Event mask</span></dt><a id="idp54421348" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Event_propagation"></a><span class="glossterm">Event propagation</span></dt><a id="idp54423060" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Event_source"></a><span class="glossterm">Event source</span></dt><a id="idp54424844" class="indexterm"></a><dd class="glossdef"><p>
The deepest viewable window that the pointer is in is called
the source of a device-related event.
    </p></dd><dt><a id="glossary:Event_synchronization"></a><span class="glossterm">Event synchronization</span></dt><a id="idp54426508" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Exposure_event"></a><span class="glossterm">Exposure event</span></dt><a id="idp54428404" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Extension"></a><span class="glossterm">Extension</span></dt><a id="idp54430044" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Font"></a><span class="glossterm">Font</span></dt><a id="idp54431692" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Font_glyph"></a><span class="glossterm">Font glyph</span></dt><a id="idp54433468" class="indexterm"></a><dd class="glossdef"><p>
The abstract graphical symbol for an index into a font.
    </p></dd><dt><a id="glossary:Frozen_events"></a><span class="glossterm">Frozen events</span></dt><a id="idp54434948" class="indexterm"></a><dd class="glossdef"><p>
Clients can freeze event processing during keyboard and pointer grabs.
    </p></dd><dt><a id="glossary:GC"></a><span class="glossterm">GC</span></dt><a id="idp54436500" class="indexterm"></a><dd class="glossdef"><p>
GC is an abbreviation for graphics context.
See <a class="glossterm" href="#glossary:Graphics_context"><em class="glossterm">Graphics context</em></a>.
    </p></dd><dt><a id="glossary:Glyph"></a><span class="glossterm">Glyph</span></dt><a id="idp54438404" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Glyph_image"></a><span class="glossterm">Glyph image</span></dt><a id="idp54440020" class="indexterm"></a><dd class="glossdef"><p>
An image of a glyph, as obtained from a glyph representation displayed 
on a presentation surface.
(ISO/IEC/DIS 9541-1)
    </p></dd><dt><a id="glossary:Grab"></a><span class="glossterm">Grab</span></dt><a id="idp54441628" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Graphics_context"></a><span class="glossterm">Graphics context</span></dt><a id="idp54443356" class="indexterm"></a><dd class="glossdef"><p>
Various information for graphics output is stored in a graphics
context (<acronym class="acronym">GC</acronym>), 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. 
    </p></dd><dt><a id="glossary:Gravity"></a><span class="glossterm">Gravity</span></dt><a id="idp54445364" class="indexterm"></a><dd class="glossdef"><p>
The contents of windows and windows themselves have a gravity,
which determines how the contents move when a window is resized.
See <a class="glossterm" href="#glossary:Bit_gravity"><em class="glossterm">Bit gravity</em></a> and
<a class="glossterm" href="#glossary:Window_gravity"><em class="glossterm">Window gravity</em></a>.
    </p></dd><dt><a id="glossary:GrayScale"></a><span class="glossterm">GrayScale</span></dt><a id="idp54447676" class="indexterm"></a><dd class="glossdef"><p>
<span class="symbol">GrayScale</span>
can be viewed as a degenerate case of 
<a class="glossterm" href="#glossary:PseudoColor"><em class="glossterm"><span class="symbol">PseudoColor</span></em></a>,
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.
    </p></dd><dt><a id="glossary:Host_Portable_Character_Encoding"></a><span class="glossterm">Host Portable Character Encoding</span></dt><a id="idp54449876" class="indexterm"></a><dd class="glossdef"><p>
The encoding of the <a class="glossterm" href="#glossary:X_Portable_Character_Set"><em class="glossterm">X Portable Character Set</em></a> 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></dd><dt><a id="glossary:Hotspot"></a><span class="glossterm">Hotspot</span></dt><a id="idp54451964" class="indexterm"></a><dd class="glossdef"><p>
A cursor has an associated hotspot, which defines the point in the
cursor corresponding to the coordinates reported for the pointer.
    </p></dd><dt><a id="glossary:Identifier"></a><span class="glossterm">Identifier</span></dt><a id="idp54453580" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Inferiors"></a><span class="glossterm">Inferiors</span></dt><a id="idp54455236" class="indexterm"></a><dd class="glossdef"><p>
The inferiors of a window are all of the subwindows nested below it:
the children, the children's children, and so on.
    </p></dd><dt><a id="glossary:Input_focus"></a><span class="glossterm">Input focus</span></dt><a id="idp54456796" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Input_manager"></a><span class="glossterm">Input manager</span></dt><a id="idp54458860" class="indexterm"></a><dd class="glossdef"><p>
Control over keyboard input is typically provided by an input manager 
client, which usually is part of a window manager.
    </p></dd><dt><a id="glossary:InputOnly_window"></a><span class="glossterm">InputOnly window</span></dt><a id="idp54460572" class="indexterm"></a><dd class="glossdef"><p>
An
<span class="symbol">InputOnly</span>
window is a window that cannot be used for graphics requests.  
<span class="symbol">InputOnly</span>
windows are invisible and are used to control such things as cursors,
input event generation, and grabbing.
<span class="symbol">InputOnly</span>
windows cannot have 
<span class="symbol">InputOutput</span>
windows as inferiors.
    </p></dd><dt><a id="glossary:InputOutput_window"></a><span class="glossterm">InputOutput window</span></dt><a id="idp54463188" class="indexterm"></a><dd class="glossdef"><p>
An
<span class="symbol">InputOutput</span>
window is the normal kind of window that is used for both input and output.
<span class="symbol">InputOutput</span>
windows can have both 
<span class="symbol">InputOutput</span>
and 
<span class="symbol">InputOnly</span>
windows as inferiors.
    </p></dd><dt><a id="glossary:Internationalization"></a><span class="glossterm">Internationalization</span></dt><a id="idp54465692" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:ISO2022"></a><span class="glossterm">ISO2022</span></dt><a id="idp54467436" class="indexterm"></a><dd class="glossdef"><p>
ISO standard for code extension techniques for 7-bit and 8-bit coded 
character sets.
    </p></dd><dt><a id="glossary:Key_grabbing"></a><span class="glossterm">Key grabbing</span></dt><a id="idp54075716" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Keyboard_grabbing"></a><span class="glossterm">Keyboard grabbing</span></dt><a id="idp54077444" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Keysym"></a><span class="glossterm">Keysym</span></dt><a id="idp54079260" class="indexterm"></a><dd class="glossdef"><p>
An encoding of a symbol on a keycap on a keyboard.
    </p></dd><dt><a id="glossary:Latin-1"></a><span class="glossterm">Latin-1</span></dt><a id="idp54080796" class="indexterm"></a><dd class="glossdef"><p>
The coded character set defined by the ISO8859-1 standard.
    </p></dd><dt><a id="glossary:Latin_Portable_Character_Encoding"></a><span class="glossterm">Latin Portable Character Encoding</span></dt><a id="idp54082276" class="indexterm"></a><dd class="glossdef"><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></dd><dt><a id="glossary:Locale"></a><span class="glossterm">Locale</span></dt><a id="idp54084004" class="indexterm"></a><dd class="glossdef"><p>
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
<code class="function">setlocale</code>
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:
    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Encoding and processing of input method text
      </p></li><li class="listitem"><p>
Encoding of resource files and values
      </p></li><li class="listitem"><p>
Encoding and imaging of text strings
      </p></li><li class="listitem"><p>
Encoding and decoding for inter-client text communication
      </p></li></ul></div></dd><dt><a id="glossary:Locale_name"></a><span class="glossterm">Locale name</span></dt><a id="idp54087956" class="indexterm"></a><dd class="glossdef"><p>
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
<code class="function">setlocale</code>
function.
    </p></dd><dt><a id="glossary:Localization"></a><span class="glossterm">Localization</span></dt><a id="idp54089900" class="indexterm"></a><dd class="glossdef"><p>
The process of establishing information within a computer system specific 
to the operation of particular native languages, local customs 
and coded character sets.
(XPG3)
    </p></dd><dt><a id="glossary:Mapped"></a><span class="glossterm">Mapped</span></dt><a id="idp54091588" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Modifier_keys"></a><span class="glossterm">Modifier keys</span></dt><a id="idp54093156" class="indexterm"></a><dd class="glossdef"><p>
Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple, CapsLock,
ShiftLock, and similar keys are called modifier keys.
    </p></dd><dt><a id="glossary:Monochrome"></a><span class="glossterm">Monochrome</span></dt><a id="idp54094796" class="indexterm"></a><dd class="glossdef"><p>
Monochrome is a special case of 
<a class="glossterm" href="#glossary:StaticGray"><em class="glossterm"><span class="symbol">StaticGray</span></em></a>
in which there are only two colormap entries.
    </p></dd><dt><a id="glossary:Multibyte"></a><span class="glossterm">Multibyte</span></dt><a id="idp54096740" class="indexterm"></a><dd class="glossdef"><p>
A character whose codepoint is stored in more than one byte;
any encoding which can contain multibyte characters;
text in a multibyte encoding.
The ``<span class="type">char *</span>'' null-terminated string datatype in ANSI C.
Note that references in this document to multibyte strings
imply only that the strings <span class="emphasis"><em>may</em></span> contain multibyte characters.
    </p></dd><dt><a id="glossary:Obscure"></a><span class="glossterm">Obscure</span></dt><a id="idp54099068" class="indexterm"></a><dd class="glossdef"><p>
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 
<span class="symbol">InputOutput</span>
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.
    </p></dd><dt><a id="glossary:Occlude"></a><span class="glossterm">Occlude</span></dt><a id="idp54101228" class="indexterm"></a><dd class="glossdef"><p>
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
<span class="symbol">InputOnly</span>
windows never obscure other windows but can occlude other windows.
    </p></dd><dt><a id="glossary:Padding"></a><span class="glossterm">Padding</span></dt><a id="idp54103388" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Parent_window"></a><span class="glossterm">Parent window</span></dt><a id="idp54104996" class="indexterm"></a><dd class="glossdef"><p>
If C is a child of P, then P is the parent of C.
    </p></dd><dt><a id="glossary:Passive_grab"></a><span class="glossterm">Passive grab</span></dt><a id="idp54106636" class="indexterm"></a><dd class="glossdef"><p>
Grabbing a key or button is a passive grab.  
The grab activates when the key or button is actually pressed.
    </p></dd><dt><a id="glossary:Pixel_value"></a><span class="glossterm">Pixel value</span></dt><a id="idp54108188" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Pixmap"></a><span class="glossterm">Pixmap</span></dt><a id="idp54109932" class="indexterm"></a><dd class="glossdef"><p>
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 2<sup>N</sup>-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.
    </p></dd><dt><a id="glossary:Plane"></a><span class="glossterm">Plane</span></dt><a id="idp54111980" class="indexterm"></a><dd class="glossdef"><p>
When a pixmap or window is thought of as a stack of bitmaps, each
bitmap is called a plane or bit plane.
    </p></dd><dt><a id="glossary:Plane_mask"></a><span class="glossterm">Plane mask</span></dt><a id="idp54113572" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Pointer"></a><span class="glossterm">Pointer</span></dt><a id="idp54115420" class="indexterm"></a><dd class="glossdef"><p>
The pointer is the pointing device currently attached to the cursor
and tracked on the screens.
    </p></dd><dt><a id="glossary:Pointer_grabbing"></a><span class="glossterm">Pointer grabbing</span></dt><a id="idp54116940" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Pointing_device"></a><span class="glossterm">Pointing device</span></dt><a id="idp54118708" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:POSIX"></a><span class="glossterm"><acronym class="acronym">POSIX</acronym></span></dt><a id="idp54120516" class="indexterm"></a><dd class="glossdef"><p>
Portable Operating System Interface, ISO/IEC 9945-1 (IEEE Std 1003.1).
    </p></dd><dt><a id="glossary:POSIX_Portable_Filename_Character_Set"></a><span class="glossterm"><acronym class="acronym">POSIX</acronym> Portable Filename Character Set</span></dt><a id="idp54122388" class="indexterm"></a><dd class="glossdef"><p>
The set of 65 characters which can be used in naming files on a <acronym class="acronym">POSIX</acronym>-compliant
host that are correctly processed in all locales.
The set is:
</p><p>

a..z A..Z 0..9 ._-

    </p></dd><dt><a id="glossary:Property"></a><span class="glossterm">Property</span></dt><a id="idp54124820" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Property_list"></a><span class="glossterm">Property list</span></dt><a id="idp54126612" class="indexterm"></a><dd class="glossdef"><p>
The property list of a window is the list of properties that have
been defined for the window.
    </p></dd><dt><a id="glossary:PseudoColor"></a><span class="glossterm">PseudoColor</span></dt><a id="idp54128156" class="indexterm"></a><dd class="glossdef"><p>
<span class="symbol">PseudoColor</span>
is a class of colormap in which a pixel value indexes the colormap entry to
produce an independent <acronym class="acronym">RGB</acronym> value;
that is, the colormap is viewed as an array of triples (<acronym class="acronym">RGB</acronym> values).
The <acronym class="acronym">RGB</acronym> values can be changed dynamically.
    </p></dd><dt><a id="glossary:Rectangle"></a><span class="glossterm">Rectangle</span></dt><a id="idp54130708" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Redirecting_control"></a><span class="glossterm">Redirecting control</span></dt><a id="idp54132412" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Reply"></a><span class="glossterm">Reply</span></dt><a id="idp54134196" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Request"></a><span class="glossterm">Request</span></dt><a id="idp54135940" class="indexterm"></a><dd class="glossdef"><p>
A command to the server is called a request.
It is a single block of data sent over a connection.
    </p></dd><dt><a id="glossary:Resource"></a><span class="glossterm">Resource</span></dt><a id="idp54137524" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:RGB_values"></a><span class="glossterm"><acronym class="acronym">RGB</acronym> values</span></dt><a id="idp54139444" class="indexterm"></a><dd class="glossdef"><p>
<acronym class="acronym">RGB</acronym> 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.
    </p></dd><dt><a id="glossary:Root"></a><span class="glossterm">Root</span></dt><a id="idp54141572" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Root_window"></a><span class="glossterm">Root window</span></dt><a id="idp54143220" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Save_set"></a><span class="glossterm">Save set</span></dt><a id="idp54145020" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Scanline"></a><span class="glossterm">Scanline</span></dt><a id="idp54146836" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Scanline_order"></a><span class="glossterm">Scanline order</span></dt><a id="idp54148436" class="indexterm"></a><dd class="glossdef"><p>
An image represented in scanline order contains scanlines ordered by
increasing the y coordinate.
    </p></dd><dt><a id="glossary:Screen"></a><span class="glossterm">Screen</span></dt><a id="idp54150188" class="indexterm"></a><a id="idp54150612" class="indexterm"></a><a id="idp54151180" class="indexterm"></a><dd class="glossdef"><p>
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 
<span class="type">Screen</span>
structure contains the information about that screen
and is linked to the 
<span class="type">Display</span>
structure.
    </p></dd><dt><a id="glossary:Selection"></a><span class="glossterm">Selection</span></dt><a id="idp54153564" class="indexterm"></a><dd class="glossdef"><p>
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.
</p><p>
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.
    </p></dd><dt><a id="glossary:Server"></a><span class="glossterm">Server</span></dt><a id="idp54156356" class="indexterm"></a><dd class="glossdef"><p>
The server, which is also referred to as the X server, 
provides the basic windowing mechanism.  
It handles <acronym class="acronym">IPC</acronym> connections from clients, 
multiplexes graphics requests onto the screens, 
and demultiplexes input back to the appropriate clients.
    </p></dd><dt><a id="glossary:Server_grabbing"></a><span class="glossterm">Server grabbing</span></dt><a id="idp54158236" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Shift_sequence"></a><span class="glossterm">Shift sequence</span></dt><a id="idp54160116" class="indexterm"></a><dd class="glossdef"><p>
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).
    </p></dd><dt><a id="glossary:Sibling"></a><span class="glossterm">Sibling</span></dt><a id="idp54161836" class="indexterm"></a><dd class="glossdef"><p>
Children of the same parent window are known as sibling windows.
    </p></dd><dt><a id="glossary:Stacking_order"></a><span class="glossterm">Stacking order</span></dt><a id="idp54163324" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:State-dependent_encoding"></a><span class="glossterm">State-dependent encoding</span></dt><a id="idp54164972" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:State-independent_encoding"></a><span class="glossterm">State-independent encoding</span></dt><a id="idp54166708" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:StaticColor"></a><span class="glossterm">StaticColor</span></dt><a id="idp54168308" class="indexterm"></a><dd class="glossdef"><p>
<span class="symbol">StaticColor</span>
can be viewed as a degenerate case of 
<a class="glossterm" href="#glossary:PseudoColor"><em class="glossterm"><span class="symbol">PseudoColor</span></em></a>
in which the <acronym class="acronym">RGB</acronym> values are predefined and read-only.
    </p></dd><dt><a id="glossary:StaticGray"></a><span class="glossterm">StaticGray</span></dt><a id="idp54170652" class="indexterm"></a><dd class="glossdef"><p>
<span class="symbol">StaticGray</span>
can be viewed as a degenerate case of 
<a class="glossterm" href="#glossary:GrayScale"><em class="glossterm"><span class="symbol">GrayScale</span></em></a>
in which the gray values are predefined and read-only.
The values are typically linear or near-linear increasing ramps.
    </p></dd><dt><a id="glossary:Status"></a><span class="glossterm">Status</span></dt><a id="idp54172900" class="indexterm"></a><dd class="glossdef"><p>
Many Xlib functions return a success status.
If the function does not succeed,
however, its arguments are not disturbed.
    </p></dd><dt><a id="glossary:Stipple"></a><span class="glossterm">Stipple</span></dt><a id="idp54174508" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:STRING_encoding"></a><span class="glossterm">STRING encoding</span></dt><dd class="glossdef"><p>
<a class="glossterm" href="#glossary:Latin-1"><em class="glossterm">Latin-1</em></a>, plus tab and newline.
    </p></dd><dt><a id="glossary:String_Equivalence"></a><span class="glossterm">String Equivalence</span></dt><a id="idp54177452" class="indexterm"></a><dd class="glossdef"><p>
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'').
    </p></dd><dt><a id="glossary:Tile"></a><span class="glossterm">Tile</span></dt><a id="idp54179652" class="indexterm"></a><dd class="glossdef"><p>
A pixmap can be replicated in two dimensions to tile a region.  
The pixmap itself is also known as a tile.
    </p></dd><dt><a id="glossary:Timestamp"></a><span class="glossterm">Timestamp</span></dt><a id="idp54181244" class="indexterm"></a><dd class="glossdef"><p>
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 
<span class="symbol">CurrentTime</span>,
is never generated by the server. 
This value is reserved for use in requests to represent the current server time.
    </p></dd><dt><a id="glossary:TrueColor"></a><span class="glossterm">TrueColor</span></dt><a id="idp54183524" class="indexterm"></a><dd class="glossdef"><p>
<span class="symbol">TrueColor</span>
can be viewed as a degenerate case of 
<a class="glossterm" href="#glossary:DirectColor"><em class="glossterm"><span class="symbol">DirectColor</span></em></a>
in which the subfields in the pixel value directly encode the corresponding <acronym class="acronym">RGB</acronym>
values.
That is, the colormap has predefined read-only <acronym class="acronym">RGB</acronym> values.
The values are typically linear or near-linear increasing ramps.
    </p></dd><dt><a id="glossary:Type"></a><span class="glossterm">Type</span></dt><a id="idp54186268" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Viewable"></a><span class="glossterm">Viewable</span></dt><a id="idp54188028" class="indexterm"></a><dd class="glossdef"><p>
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. 
    </p></dd><dt><a id="glossary:Visible"></a><span class="glossterm">Visible</span></dt><a id="idp54189804" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Whitespace"></a><span class="glossterm">Whitespace</span></dt><a id="idp54191460" class="indexterm"></a><dd class="glossdef"><p>
Any spacing character.
On implementations that conform to the ANSI C library,
whitespace is any character for which
<code class="function">isspace</code>
returns true.
    </p></dd><dt><a id="glossary:Window_gravity"></a><span class="glossterm">Window gravity</span></dt><a id="idp54193364" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Window_manager"></a><span class="glossterm">Window manager</span></dt><a id="idp54195156" class="indexterm"></a><dd class="glossdef"><p>
Manipulation of windows on the screen and much of the user interface
(policy) is typically provided by a window manager client.
    </p></dd><dt><a id="glossary:X_Portable_Character_Set"></a><span class="glossterm">X Portable Character Set</span></dt><a id="idp54196852" class="indexterm"></a><dd class="glossdef"><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><div class="literallayout"><p><br />
a..z A..Z 0..9<br />
!"#$%&amp;'()*+,-./:;&lt;=&gt;?@[\\]^_`{|}~<br />
&lt;space&gt;, &lt;tab&gt;, and &lt;newline&gt;<br />
      </p></div><p>
    </p><p>
This is the left/lower half (also called the G0 set)
of the graphic character set of ISO8859-1 plus &lt;space&gt;, &lt;tab&gt;, and &lt;newline&gt;.
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 <a class="glossterm" href="#glossary:Host_Portable_Character_Encoding"><em class="glossterm">Host Portable Character Encoding</em></a>.
    </p></dd><dt><a id="glossary:XLFD"></a><span class="glossterm"><acronym class="acronym">XLFD</acronym></span></dt><a id="idp54199988" class="indexterm"></a><dd class="glossdef"><p>
The <span class="olink"><em class="citetitle">X Logical Font Description Conventions</em></span>
that define a standard syntax for structured font names.
    </p></dd><dt><a id="glossary:XY_format"></a><span class="glossterm">XY format</span></dt><a id="idp54202140" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd><dt><a id="glossary:Z_format"></a><span class="glossterm">Z format</span></dt><a id="idp54203828" class="indexterm"></a><dd class="glossdef"><p>
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.
    </p></dd></dl></div><div class="index"><div class="titlepage"><div><div><h1 class="title"><a id="idp37026124"></a>Index</h1></div></div></div><div class="index"><div class="indexdiv"><h3>Symbols</h3><dl><dt>_XAllocScratch, <a class="indexterm" href="#idp54568116">Allocating and Deallocating Memory</a></dt><dt>_XAllocTemp, <a class="indexterm" href="#idp54576068">Allocating and Deallocating Memory</a></dt><dt>_Xdebug, <a class="indexterm" href="#idp48422468">Enabling or Disabling Synchronization</a></dt><dt>_XFlushGCCache, <a class="indexterm" href="#idp53915652">GC Caching</a></dt><dt>_XFreeTemp, <a class="indexterm" href="#idp54581636">Allocating and Deallocating Memory</a></dt><dt>_XReply, <a class="indexterm" href="#idp54507604">Replies</a></dt><dt>_XSetLastRequestRead, <a class="indexterm" href="#idp53758972">Hooks into the Library</a></dt></dl></div><div class="indexdiv"><h3>A</h3><dl><dt>Access control list, <a class="indexterm" href="#idp45682524">Controlling Host Access</a>, <a class="indexterm" href="#idp36928468">Glossary</a></dt><dt>Active grab, <a class="indexterm" href="#idp40286180">Pointer Grabbing</a>, <a class="indexterm" href="#idp42002788">Glossary</a></dt><dt>Allocation</dt><dd><dl><dt>colormap, <a class="indexterm" href="#idp46262140">Allocating and Freeing Color Cells</a></dt><dt>read-only colormap cells, <a class="indexterm" href="#idp46250764">Allocating and Freeing Color Cells</a>, <a class="indexterm" href="#idp46266132">Allocating and Freeing Color Cells</a>, <a class="indexterm" href="#idp46282740">Allocating and Freeing Color Cells</a>, <a class="indexterm" href="#idp46298036">Allocating and Freeing Color Cells</a></dt><dt>read/write colormap cells, <a class="indexterm" href="#idp46319988">Allocating and Freeing Color Cells</a></dt><dt>read/write colormap planes, <a class="indexterm" href="#idp46343868">Allocating and Freeing Color Cells</a></dt></dl></dd><dt>AllPlanes, <a class="indexterm" href="#idp41679452">Display Macros</a></dt><dt>Ancestors, <a class="indexterm" href="#idp38711260">Glossary</a></dt><dt>Arcs</dt><dd><dl><dt>drawing, <a class="indexterm" href="#idp47762100">Drawing Single and Multiple Arcs</a></dt><dt>filling, <a class="indexterm" href="#idp47865116">Filling Single and Multiple Arcs</a></dt></dl></dd><dt>Areas</dt><dd><dl><dt>clearing, <a class="indexterm" href="#idp43384652">Clearing Areas</a></dt><dt>copying, <a class="indexterm" href="#idp46197692">Copying Areas</a></dt></dl></dd><dt>Atom, <a class="indexterm" href="#idp44534756">Properties and Atoms</a>, <a class="indexterm" href="#idp44536812">Properties and Atoms</a>, <a class="indexterm" href="#idp40429156">Glossary</a></dt><dd><dl><dt>getting name, <a class="indexterm" href="#idp44152548">Properties and Atoms</a>, <a class="indexterm" href="#idp44162612">Properties and Atoms</a></dt><dt>interning, <a class="indexterm" href="#idp44123612">Properties and Atoms</a>, <a class="indexterm" href="#idp44136372">Properties and Atoms</a></dt><dt>predefined, <a class="indexterm" href="#idp44533092">Properties and Atoms</a></dt></dl></dd><dt>Authentication, <a class="indexterm" href="#idp45682956">Controlling Host Access</a></dt></dl></div><div class="indexdiv"><h3>B</h3><dl><dt>Background, <a class="indexterm" href="#idp41782148">Glossary</a></dt><dt>Backing store, <a class="indexterm" href="#idp40497196">Glossary</a></dt><dt>BadAccess, <a class="indexterm" href="#idp48458164">Using the Default Error Handlers</a></dt><dt>BadAlloc, <a class="indexterm" href="#idp48458588">Using the Default Error Handlers</a></dt><dt>BadAtom, <a class="indexterm" href="#idp48459012">Using the Default Error Handlers</a></dt><dt>BadColor, <a class="indexterm" href="#idp48459436">Using the Default Error Handlers</a></dt><dt>BadCursor, <a class="indexterm" href="#idp48459860">Using the Default Error Handlers</a></dt><dt>BadDrawable, <a class="indexterm" href="#idp48460284">Using the Default Error Handlers</a></dt><dt>BadFont, <a class="indexterm" href="#idp48460708">Using the Default Error Handlers</a></dt><dt>BadGC, <a class="indexterm" href="#idp48461132">Using the Default Error Handlers</a></dt><dt>BadIDChoice, <a class="indexterm" href="#idp48461556">Using the Default Error Handlers</a></dt><dt>BadImplementation, <a class="indexterm" href="#idp48536348">Using the Default Error Handlers</a></dt><dt>BadLength, <a class="indexterm" href="#idp48536780">Using the Default Error Handlers</a></dt><dt>BadMatch, <a class="indexterm" href="#idp48537204">Using the Default Error Handlers</a></dt><dt>BadName, <a class="indexterm" href="#idp48537628">Using the Default Error Handlers</a></dt><dt>BadPixmap, <a class="indexterm" href="#idp48538052">Using the Default Error Handlers</a></dt><dt>BadRequest, <a class="indexterm" href="#idp48538476">Using the Default Error Handlers</a></dt><dt>BadValue, <a class="indexterm" href="#idp48538900">Using the Default Error Handlers</a></dt><dt>BadWindow, <a class="indexterm" href="#idp48539324">Using the Default Error Handlers</a></dt><dt>Base font name, <a class="indexterm" href="#idp42347780">Glossary</a></dt><dt>Bit</dt><dd><dl><dt>gravity, <a class="indexterm" href="#idp50088972">Glossary</a></dt><dt>plane, <a class="indexterm" href="#idp50090940">Glossary</a></dt></dl></dd><dt>Bitmap, <a class="indexterm" href="#idp42120620">Overview of the X Window System</a>, <a class="indexterm" href="#idp50092676">Glossary</a></dt><dt>BitmapBitOrder, <a class="indexterm" href="#idp43694332">Image Format Functions and Macros</a></dt><dt>BitmapPad, <a class="indexterm" href="#idp43700036">Image Format Functions and Macros</a></dt><dt>BitmapUnit, <a class="indexterm" href="#idp43689092">Image Format Functions and Macros</a></dt><dt>BlackPixel, <a class="indexterm" href="#idp42519484">Display Macros</a></dt><dt>BlackPixelOfScreen, <a class="indexterm" href="#idp43735220">Screen Information Macros</a></dt><dt>Bool, <a class="indexterm" href="#idp41853100">Generic Values and Types</a></dt><dt>Border, <a class="indexterm" href="#idp47563892">Glossary</a></dt><dt>Button</dt><dd><dl><dt>grabbing, <a class="indexterm" href="#idp49154908">Pointer Grabbing</a>, <a class="indexterm" href="#idp47565788">Glossary</a></dt><dt>ungrabbing, <a class="indexterm" href="#idp49189636">Pointer Grabbing</a></dt></dl></dd><dt>ButtonPress, <a class="indexterm" href="#idp47334572">Keyboard and Pointer Events</a></dt><dt>ButtonRelease, <a class="indexterm" href="#idp47334996">Keyboard and Pointer Events</a></dt><dt>Byte</dt><dd><dl><dt>order, <a class="indexterm" href="#idp47567580">Glossary</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>C</h3><dl><dt>CallbackPrototype, <a class="indexterm" href="#idp52242636">Input Method Callback Semantics</a></dt><dt>CCC, <a class="indexterm" href="#idp45090356">Color Conversion Contexts and Gamut Mapping</a></dt><dd><dl><dt>creation, <a class="indexterm" href="#idp46666300">Creating and Freeing a Color Conversion Context</a></dt><dt>default, <a class="indexterm" href="#idp45098380">Color Conversion Contexts and Gamut Mapping</a>, <a class="indexterm" href="#idp46553372">Color Conversion Context Functions</a>, <a class="indexterm" href="#idp46579892">Obtaining the Default Color Conversion Context</a>, <a class="indexterm" href="#idp46583196">Obtaining the Default Color Conversion Context</a></dt><dt>freeing, <a class="indexterm" href="#idp46687044">Creating and Freeing a Color Conversion Context</a></dt><dt>of colormap, <a class="indexterm" href="#idp45097092">Color Conversion Contexts and Gamut Mapping</a>, <a class="indexterm" href="#idp46549932">Color Conversion Context Functions</a>, <a class="indexterm" href="#idp46557940">Getting and Setting the Color Conversion Context of a Colormap</a>, <a class="indexterm" href="#idp46568132">Getting and Setting the Color Conversion Context of a Colormap</a></dt></dl></dd><dt>CellsOfScreen, <a class="indexterm" href="#idp43745876">Screen Information Macros</a></dt><dt>Changing</dt><dd><dl><dt>pointer grab, <a class="indexterm" href="#idp49139740">Pointer Grabbing</a></dt></dl></dd><dt>Character, <a class="indexterm" href="#idp48702588">Glossary</a></dt><dt>Character glyph, <a class="indexterm" href="#idp48704260">Glossary</a></dt><dt>Character set, <a class="indexterm" href="#idp48705948">Glossary</a></dt><dt>Charset, <a class="indexterm" href="#idp48707452">Glossary</a></dt><dt>Child window, <a class="indexterm" href="#idp38653676">Overview of the X Window System</a></dt><dt>Child Window, <a class="indexterm" href="#idp42684300">Obtaining Window Information</a></dt><dt>Children, <a class="indexterm" href="#idp54375908">Glossary</a></dt><dt>Chroma, <a class="indexterm" href="#idp46982404">TekHVC Queries</a>, <a class="indexterm" href="#idp47008196">TekHVC Queries</a>, <a class="indexterm" href="#idp47020540">TekHVC Queries</a></dt><dd><dl><dt>maximum, <a class="indexterm" href="#idp46982828">TekHVC Queries</a>, <a class="indexterm" href="#idp47009044">TekHVC Queries</a>, <a class="indexterm" href="#idp47021388">TekHVC Queries</a></dt></dl></dd><dt>CIE metric lightness, <a class="indexterm" href="#idp46860980">CIELab Queries</a>, <a class="indexterm" href="#idp46877652">CIELab Queries</a>, <a class="indexterm" href="#idp46892940">CIELab Queries</a>, <a class="indexterm" href="#idp46906252">CIELab Queries</a>, <a class="indexterm" href="#idp46921804">CIELuv Queries</a>, <a class="indexterm" href="#idp46938892">CIELuv Queries</a>, <a class="indexterm" href="#idp46954156">CIELuv Queries</a>, <a class="indexterm" href="#idp46967468">CIELuv Queries</a></dt><dd><dl><dt>maximum, <a class="indexterm" href="#idp46878228">CIELab Queries</a>, <a class="indexterm" href="#idp46894092">CIELab Queries</a>, <a class="indexterm" href="#idp46939468">CIELuv Queries</a>, <a class="indexterm" href="#idp46955308">CIELuv Queries</a></dt><dt>minimum, <a class="indexterm" href="#idp46906828">CIELab Queries</a>, <a class="indexterm" href="#idp46968044">CIELuv Queries</a></dt></dl></dd><dt>CirculateNotify, <a class="indexterm" href="#idp48922524">CirculateNotify Events</a></dt><dt>CirculateRequest, <a class="indexterm" href="#idp49028188">CirculateRequest Events</a></dt><dt>Class, <a class="indexterm" href="#idp54377452">Glossary</a></dt><dt>Clearing</dt><dd><dl><dt>areas, <a class="indexterm" href="#idp40873052">Clearing Areas</a></dt><dt>windows, <a class="indexterm" href="#idp46184980">Clearing Areas</a></dt></dl></dd><dt>Client, <a class="indexterm" href="#idp54379740">Glossary</a></dt><dt>Client White Point, <a class="indexterm" href="#idp45093948">Color Conversion Contexts and Gamut Mapping</a></dt><dd><dl><dt>of Color Conversion Context, <a class="indexterm" href="#idp46628996">Modifying Attributes of a Color Conversion Context</a></dt></dl></dd><dt>ClientMessage, <a class="indexterm" href="#idp49083164">ClientMessage Events</a></dt><dt>ClientWhitePointOfCCC, <a class="indexterm" href="#idp46619860">Color Conversion Context Macros</a></dt><dt>Clipping region, <a class="indexterm" href="#idp54382260">Glossary</a></dt><dt>Coded character, <a class="indexterm" href="#idp54383916">Glossary</a></dt><dt>Coded character set, <a class="indexterm" href="#idp54385356">Glossary</a></dt><dt>Codepoint, <a class="indexterm" href="#idp54387140">Glossary</a></dt><dt>Color, <a class="indexterm" href="#idp43561092">Color Structures</a></dt><dd><dl><dt>allocation, <a class="indexterm" href="#idp46251772">Allocating and Freeing Color Cells</a>, <a class="indexterm" href="#idp46261636">Allocating and Freeing Color Cells</a>, <a class="indexterm" href="#idp46267140">Allocating and Freeing Color Cells</a>, <a class="indexterm" href="#idp46284252">Allocating and Freeing Color Cells</a>, <a class="indexterm" href="#idp46299548">Allocating and Freeing Color Cells</a>, <a class="indexterm" href="#idp46320572">Allocating and Freeing Color Cells</a>, <a class="indexterm" href="#idp46344452">Allocating and Freeing Color Cells</a></dt><dt>conversion, <a class="indexterm" href="#idp46694844">Converting between Color Spaces</a></dt><dt>deallocation, <a class="indexterm" href="#idp46375580">Allocating and Freeing Color Cells</a></dt><dt>naming, <a class="indexterm" href="#idp45151156">Mapping Color Names to Values</a>, <a class="indexterm" href="#idp46218772">Mapping Color Names to Values</a>, <a class="indexterm" href="#idp46231268">Mapping Color Names to Values</a>, <a class="indexterm" href="#idp46283748">Allocating and Freeing Color Cells</a>, <a class="indexterm" href="#idp46299044">Allocating and Freeing Color Cells</a>, <a class="indexterm" href="#idp46469492">Modifying and Querying Colormap Cells</a></dt><dt>querying, <a class="indexterm" href="#idp46489420">Modifying and Querying Colormap Cells</a>, <a class="indexterm" href="#idp46502308">Modifying and Querying Colormap Cells</a>, <a class="indexterm" href="#idp46517116">Modifying and Querying Colormap Cells</a>, <a class="indexterm" href="#idp46531588">Modifying and Querying Colormap Cells</a></dt><dt>storing, <a class="indexterm" href="#idp46398332">Modifying and Querying Colormap Cells</a>, <a class="indexterm" href="#idp46412740">Modifying and Querying Colormap Cells</a>, <a class="indexterm" href="#idp46429204">Modifying and Querying Colormap Cells</a>, <a class="indexterm" href="#idp46446724">Modifying and Querying Colormap Cells</a>, <a class="indexterm" href="#idp46468924">Modifying and Querying Colormap Cells</a></dt></dl></dd><dt>Color Characterization Data, <a class="indexterm" href="#idp47179972">Creating Additional Function Sets</a></dt><dt>Color conversion, <a class="indexterm" href="#idp46694412">Converting between Color Spaces</a></dt><dt>Color Conversion Context, <a class="indexterm" href="#idp45089948">Color Conversion Contexts and Gamut Mapping</a></dt><dd><dl><dt>creation, <a class="indexterm" href="#idp45096436">Color Conversion Contexts and Gamut Mapping</a>, <a class="indexterm" href="#idp46549252">Color Conversion Context Functions</a>, <a class="indexterm" href="#idp46665716">Creating and Freeing a Color Conversion Context</a></dt><dt>default, <a class="indexterm" href="#idp45098948">Color Conversion Contexts and Gamut Mapping</a>, <a class="indexterm" href="#idp46553940">Color Conversion Context Functions</a>, <a class="indexterm" href="#idp46580460">Obtaining the Default Color Conversion Context</a>, <a class="indexterm" href="#idp46582612">Obtaining the Default Color Conversion Context</a></dt><dt>freeing, <a class="indexterm" href="#idp46686460">Creating and Freeing a Color Conversion Context</a></dt><dt>of colormap, <a class="indexterm" href="#idp45097660">Color Conversion Contexts and Gamut Mapping</a>, <a class="indexterm" href="#idp46550500">Color Conversion Context Functions</a>, <a class="indexterm" href="#idp46558508">Getting and Setting the Color Conversion Context of a Colormap</a>, <a class="indexterm" href="#idp46568700">Getting and Setting the Color Conversion Context of a Colormap</a></dt></dl></dd><dt>Color map, <a class="indexterm" href="#idp43530196">Color Management Functions</a>, <a class="indexterm" href="#idp46261260">Allocating and Freeing Color Cells</a></dt><dt>Colormap, <a class="indexterm" href="#idp54388700">Glossary</a></dt><dd><dl><dt>CCC of, <a class="indexterm" href="#idp46557372">Getting and Setting the Color Conversion Context of a Colormap</a>, <a class="indexterm" href="#idp46567564">Getting and Setting the Color Conversion Context of a Colormap</a></dt></dl></dd><dt>ColormapNotify, <a class="indexterm" href="#idp49067340">Colormap State Change Events</a></dt><dt>Colormaps</dt><dd><dl><dt>standard, <a class="indexterm" href="#idp52666548">Standard Colormap Properties and Atoms</a></dt></dl></dd><dt>ConfigureNotify, <a class="indexterm" href="#idp48931996">ConfigureNotify Events</a></dt><dt>ConfigureRequest, <a class="indexterm" href="#idp49037764">ConfigureRequest Events</a></dt><dt>Connection, <a class="indexterm" href="#idp54390796">Glossary</a></dt><dt>ConnectionNumber, <a class="indexterm" href="#idp42533780">Display Macros</a></dt><dt>Containment, <a class="indexterm" href="#idp54392652">Glossary</a></dt><dt>Coordinate system, <a class="indexterm" href="#idp54394428">Glossary</a></dt><dt>Copying</dt><dd><dl><dt>areas, <a class="indexterm" href="#idp46198260">Copying Areas</a></dt><dt>planes, <a class="indexterm" href="#idp45296172">Copying Areas</a></dt></dl></dd><dt>CreateNotify, <a class="indexterm" href="#idp48948316">CreateNotify Events</a></dt><dt>CurrentTime, <a class="indexterm" href="#idp47704476">Event Processing Overview</a>, <a class="indexterm" href="#idp40421172">Pointer Grabbing</a></dt><dt>Cursor, <a class="indexterm" href="#idp54396236">Glossary</a></dt><dd><dl><dt>Initial State, <a class="indexterm" href="#idp44607340">Creating Windows</a></dt><dt>limitations, <a class="indexterm" href="#idp44582492">Creating, Recoloring, and Freeing Cursors</a></dt></dl></dd><dt>Cut Buffers, <a class="indexterm" href="#idp53278044">Using Cut Buffers</a></dt></dl></div><div class="indexdiv"><h3>D</h3><dl><dt>Debugging</dt><dd><dl><dt>error event, <a class="indexterm" href="#idp48451636">Using the Default Error Handlers</a></dt><dt>error handlers, <a class="indexterm" href="#idp48441516">Using the Default Error Handlers</a></dt><dt>error message strings, <a class="indexterm" href="#idp48543852">Using the Default Error Handlers</a></dt><dt>error numbers, <a class="indexterm" href="#idp48456684">Using the Default Error Handlers</a></dt><dt>synchronous mode, <a class="indexterm" href="#idp48431868">Enabling or Disabling Synchronization</a></dt></dl></dd><dt>Default Protection, <a class="indexterm" href="#idp45684292">Controlling Host Access</a></dt><dt>DefaultColormap, <a class="indexterm" href="#idp42542332">Display Macros</a></dt><dt>DefaultColormapOfScreen, <a class="indexterm" href="#idp43751236">Screen Information Macros</a></dt><dt>DefaultDepth, <a class="indexterm" href="#idp42550692">Display Macros</a></dt><dt>DefaultDepthOfScreen, <a class="indexterm" href="#idp43756556">Screen Information Macros</a></dt><dt>DefaultGC, <a class="indexterm" href="#idp42570716">Display Macros</a></dt><dt>DefaultGCOfScreen, <a class="indexterm" href="#idp43761812">Screen Information Macros</a></dt><dt>DefaultRootWindow, <a class="indexterm" href="#idp42577132">Display Macros</a></dt><dt>DefaultScreen, <a class="indexterm" href="#idp42597364">Display Macros</a></dt><dt>DefaultScreenOfDisplay, <a class="indexterm" href="#idp42583100">Display Macros</a></dt><dt>DefaultVisual, <a class="indexterm" href="#idp42606188">Display Macros</a></dt><dt>DefaultVisualOfScreen, <a class="indexterm" href="#idp43767276">Screen Information Macros</a></dt><dt>Depth, <a class="indexterm" href="#idp54397964">Glossary</a></dt><dt>Destination, <a class="indexterm" href="#idp44367116">Manipulating Graphics Context/State</a></dt><dt>DestroyCallback, <a class="indexterm" href="#idp51863124">Destroy Callback</a>, <a class="indexterm" href="#idp52262932">Destroy Callback</a></dt><dt>DestroyNotify, <a class="indexterm" href="#idp48956276">DestroyNotify Events</a></dt><dt>Device, <a class="indexterm" href="#idp54399636">Glossary</a></dt><dt>Device Color Characterization, <a class="indexterm" href="#idp47150380">Function Sets</a></dt><dt>Device profile, <a class="indexterm" href="#idp45089476">Color Conversion Contexts and Gamut Mapping</a>, <a class="indexterm" href="#idp47179540">Creating Additional Function Sets</a></dt><dt>DirectColor, <a class="indexterm" href="#idp54401332">Glossary</a></dt><dt>Display, <a class="indexterm" href="#idp43545964">Opening the Display</a>, <a class="indexterm" href="#idp54403676">Glossary</a></dt><dd><dl><dt>data structure, <a class="indexterm" href="#idp41670220">Obtaining Information about the Display, Image Formats, or Screens</a></dt><dt>structure, <a class="indexterm" href="#idp54404100">Glossary</a>, <a class="indexterm" href="#idp54151180">Glossary</a></dt></dl></dd><dt>Display Functions, <a class="indexterm" href="#idp44366260">Manipulating Graphics Context/State</a></dt><dt>DisplayCells, <a class="indexterm" href="#idp42614876">Display Macros</a></dt><dt>DisplayHeight, <a class="indexterm" href="#idp43707156">Image Format Functions and Macros</a></dt><dt>DisplayHeightMM, <a class="indexterm" href="#idp43714260">Image Format Functions and Macros</a></dt><dt>DisplayOfCCC, <a class="indexterm" href="#idp46592708">Color Conversion Context Macros</a></dt><dt>DisplayOfScreen, <a class="indexterm" href="#idp43785484">Screen Information Macros</a></dt><dt>DisplayPlanes, <a class="indexterm" href="#idp42623148">Display Macros</a></dt><dt>DisplayString, <a class="indexterm" href="#idp42629268">Display Macros</a></dt><dt>DisplayWidth, <a class="indexterm" href="#idp43721356">Image Format Functions and Macros</a></dt><dt>DisplayWidthMM, <a class="indexterm" href="#idp43728436">Image Format Functions and Macros</a></dt><dt>DoesBackingStore, <a class="indexterm" href="#idp43772988">Screen Information Macros</a></dt><dt>DoesSaveUnders, <a class="indexterm" href="#idp43779292">Screen Information Macros</a></dt><dt>Drawable, <a class="indexterm" href="#idp38659076">Overview of the X Window System</a>, <a class="indexterm" href="#idp54406212">Glossary</a></dt><dt>Drawing</dt><dd><dl><dt>arcs, <a class="indexterm" href="#idp47761220">Drawing Single and Multiple Arcs</a></dt><dt>image text, <a class="indexterm" href="#idp48209788">Drawing Image Text Characters</a></dt><dt>lines, <a class="indexterm" href="#idp45374012">Drawing Single and Multiple Lines</a></dt><dt>points, <a class="indexterm" href="#idp45338732">Drawing Single and Multiple Points</a></dt><dt>polygons, <a class="indexterm" href="#idp45375996">Drawing Single and Multiple Lines</a></dt><dt>rectangles, <a class="indexterm" href="#idp47729476">Drawing Single and Multiple Rectangles</a></dt><dt>strings, <a class="indexterm" href="#idp48174468">Drawing Text Characters</a></dt><dt>text items, <a class="indexterm" href="#idp48139580">Drawing Complex Text</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>E</h3><dl><dt>Encoding, <a class="indexterm" href="#idp54408156">Glossary</a></dt><dt>EnterNotify, <a class="indexterm" href="#idp48752372">Window Entry/Exit Events</a></dt><dt>Environment</dt><dd><dl><dt>DISPLAY, <a class="indexterm" href="#idp42947844">Opening the Display</a></dt></dl></dd><dt>Error</dt><dd><dl><dt>codes, <a class="indexterm" href="#idp48457260">Using the Default Error Handlers</a></dt><dt>handlers, <a class="indexterm" href="#idp48442092">Using the Default Error Handlers</a></dt><dt>handling, <a class="indexterm" href="#idp42294868">Errors</a></dt></dl></dd><dt>Escapement, <a class="indexterm" href="#idp54411340">Glossary</a></dt><dt>Event, <a class="indexterm" href="#idp39767620">Overview of the X Window System</a>, <a class="indexterm" href="#idp44384676">Event Types</a>, <a class="indexterm" href="#idp54413028">Glossary</a></dt><dd><dl><dt>categories, <a class="indexterm" href="#idp40881636">Event Types</a></dt><dt>Exposure, <a class="indexterm" href="#idp54428404">Glossary</a></dt><dt>mask, <a class="indexterm" href="#idp54421348">Glossary</a></dt><dt>propagation, <a class="indexterm" href="#idp47246004">Selecting Events</a>, <a class="indexterm" href="#idp54423060">Glossary</a></dt><dt>source, <a class="indexterm" href="#idp54424844">Glossary</a></dt><dt>synchronization, <a class="indexterm" href="#idp54426508">Glossary</a></dt><dt>types, <a class="indexterm" href="#idp44383964">Event Types</a></dt></dl></dd><dt>Event mask, <a class="indexterm" href="#idp45615940">Event Masks</a></dt><dt>EventMaskOfScreen, <a class="indexterm" href="#idp43796020">Screen Information Macros</a></dt><dt>Events</dt><dd><dl><dt>ButtonPress, <a class="indexterm" href="#idp47328308">Keyboard and Pointer Events</a></dt><dt>ButtonRelease, <a class="indexterm" href="#idp47328876">Keyboard and Pointer Events</a></dt><dt>CirculateNotify, <a class="indexterm" href="#idp48922020">CirculateNotify Events</a></dt><dt>CirculateRequest, <a class="indexterm" href="#idp49027684">CirculateRequest Events</a></dt><dt>ClientMessage, <a class="indexterm" href="#idp49082660">ClientMessage Events</a></dt><dt>ColormapNotify, <a class="indexterm" href="#idp49066836">Colormap State Change Events</a></dt><dt>ConfigureNotify, <a class="indexterm" href="#idp48931492">ConfigureNotify Events</a></dt><dt>ConfigureRequest, <a class="indexterm" href="#idp49037260">ConfigureRequest Events</a></dt><dt>CreateNotify, <a class="indexterm" href="#idp48947812">CreateNotify Events</a></dt><dt>DestroyNotify, <a class="indexterm" href="#idp48955772">DestroyNotify Events</a></dt><dt>EnterNotify, <a class="indexterm" href="#idp48750892">Window Entry/Exit Events</a></dt><dt>Expose, <a class="indexterm" href="#idp48885532">Expose Events</a></dt><dt>FocusIn, <a class="indexterm" href="#idp48805900">Input Focus Events</a></dt><dt>FocusOut, <a class="indexterm" href="#idp48806404">Input Focus Events</a></dt><dt>GraphicsExpose, <a class="indexterm" href="#idp48895612">GraphicsExpose and NoExpose Events</a></dt><dt>GravityNotify, <a class="indexterm" href="#idp48964756">GravityNotify Events</a></dt><dt>KeymapNotify, <a class="indexterm" href="#idp48876700">Key Map State Notification Events</a></dt><dt>KeyPress, <a class="indexterm" href="#idp47329452">Keyboard and Pointer Events</a></dt><dt>KeyRelease, <a class="indexterm" href="#idp47330020">Keyboard and Pointer Events</a></dt><dt>LeaveNotify, <a class="indexterm" href="#idp48751396">Window Entry/Exit Events</a></dt><dt>MapNotify, <a class="indexterm" href="#idp48973484">MapNotify Events</a></dt><dt>MappingNotify, <a class="indexterm" href="#idp48982924">MappingNotify Events</a></dt><dt>MapRequest, <a class="indexterm" href="#idp49050028">MapRequest Events</a></dt><dt>MotionNotify, <a class="indexterm" href="#idp47330588">Keyboard and Pointer Events</a></dt><dt>NoExpose, <a class="indexterm" href="#idp48896116">GraphicsExpose and NoExpose Events</a></dt><dt>PropertyNotify, <a class="indexterm" href="#idp49088868">PropertyNotify Events</a></dt><dt>ReparentNotify, <a class="indexterm" href="#idp48993588">ReparentNotify Events</a></dt><dt>ResizeRequest, <a class="indexterm" href="#idp49059244">ResizeRequest Events</a></dt><dt>SelectionClear, <a class="indexterm" href="#idp49099052">SelectionClear Events</a></dt><dt>SelectionNotify, <a class="indexterm" href="#idp49113980">SelectionNotify Events</a></dt><dt>SelectionRequest, <a class="indexterm" href="#idp49105268">SelectionRequest Events</a></dt><dt>UnmapNotify, <a class="indexterm" href="#idp49002036">UnmapNotify Events</a></dt><dt>VisibilityNotify, <a class="indexterm" href="#idp49010036">VisibilityNotify Events</a></dt></dl></dd><dt>Expose, <a class="indexterm" href="#idp48886036">Expose Events</a></dt><dt>Extension, <a class="indexterm" href="#idp54430044">Glossary</a></dt></dl></div><div class="indexdiv"><h3>F</h3><dl><dt>False, <a class="indexterm" href="#idp41853948">Generic Values and Types</a></dt><dt>Files</dt><dd><dl><dt>$HOME/.Xdefaults, <a class="indexterm" href="#idp53722372">Getting the X Environment Defaults</a></dt><dt>/etc/X?.hosts, <a class="indexterm" href="#idp45686684">Controlling Host Access</a></dt><dt>&lt;X11/cursorfont.h&gt;, <a class="indexterm" href="#idp41819484">Standard Header Files</a></dt><dt>&lt;X11/keysym.h&gt;, <a class="indexterm" href="#idp41831332">Standard Header Files</a>, <a class="indexterm" href="#idp49929204">Manipulating the Keyboard Encoding</a></dt><dt>&lt;X11/keysymdef.h&gt;, <a class="indexterm" href="#idp41823468">Standard Header Files</a>, <a class="indexterm" href="#idp49926100">Manipulating the Keyboard Encoding</a>, <a class="indexterm" href="#idp50174180">Using Keyboard Utility Functions</a></dt><dt>&lt;X11/X.h&gt;, <a class="indexterm" href="#idp39765068">Overview of the X Window System</a>, <a class="indexterm" href="#idp42305012">Standard Header Files</a>, <a class="indexterm" href="#idp44369636">Manipulating Graphics Context/State</a>, <a class="indexterm" href="#idp41428348">Event Types</a>, <a class="indexterm" href="#idp45617964">Event Masks</a></dt><dt>&lt;X11/X10.h&gt;, <a class="indexterm" href="#idp41849772">Standard Header Files</a>, <a class="indexterm" href="#idp50304508">Drawing and Filling Polygons and Curves</a>, <a class="indexterm" href="#idp50309596">Drawing and Filling Polygons and Curves</a></dt><dt>&lt;X11/Xatom.h&gt;, <a class="indexterm" href="#idp41815908">Standard Header Files</a>, <a class="indexterm" href="#idp44539140">Properties and Atoms</a>, <a class="indexterm" href="#idp47986908">Loading and Freeing Fonts</a>, <a class="indexterm" href="#idp52668532">Standard Colormap Properties and Atoms</a></dt><dt>&lt;X11/Xcms.h&gt;, <a class="indexterm" href="#idp41801772">Standard Header Files</a>, <a class="indexterm" href="#idp40504404">Color Management Functions</a></dt><dt>&lt;X11/Xlib.h&gt;, <a class="indexterm" href="#idp42300708">Standard Header Files</a>, <a class="indexterm" href="#idp43548420">Opening the Display</a>, <a class="indexterm" href="#idp40507596">Color Management Functions</a>, <a class="indexterm" href="#idp45417252">Event Structures</a>, <a class="indexterm" href="#idp53355492">Manipulating Images</a></dt><dt>&lt;X11/Xlibint.h&gt;, <a class="indexterm" href="#idp41836956">Standard Header Files</a></dt><dt>&lt;X11/Xproto.h&gt;, <a class="indexterm" href="#idp41841436">Standard Header Files</a>, <a class="indexterm" href="#idp48909876">GraphicsExpose and NoExpose Events</a></dt><dt>&lt;X11/Xprotostr.h&gt;, <a class="indexterm" href="#idp41845652">Standard Header Files</a></dt><dt>&lt;X11/Xresource.h&gt;, <a class="indexterm" href="#idp41811260">Standard Header Files</a>, <a class="indexterm" href="#idp49691204">Resource Manager Functions</a></dt><dt>&lt;X11/Xutil.h&gt;, <a class="indexterm" href="#idp41806332">Standard Header Files</a>, <a class="indexterm" href="#idp50641596">Setting and Reading the WM_HINTS Property</a>, <a class="indexterm" href="#idp50681388">Setting and Reading the WM_NORMAL_HINTS Property</a>, <a class="indexterm" href="#idp50763252">Setting and Reading the WM_CLASS Property</a>, <a class="indexterm" href="#idp50890460">Setting and Reading the WM_ICON_SIZE Property</a>, <a class="indexterm" href="#idp50276412">Parsing the Window Geometry</a>, <a class="indexterm" href="#idp53156388">Manipulating Regions</a>, <a class="indexterm" href="#idp53325636">Determining the Appropriate Visual Type</a>, <a class="indexterm" href="#idp53386708">Manipulating Images</a>, <a class="indexterm" href="#idp53528908">Using the Context Manager</a>, <a class="indexterm" href="#idp49279580">Setting and Getting Window Sizing Hints</a></dt></dl></dd><dt>Filling</dt><dd><dl><dt>arcs, <a class="indexterm" href="#idp47865620">Filling Single and Multiple Arcs</a></dt><dt>polygon, <a class="indexterm" href="#idp47840852">Filling a Single Polygon</a></dt><dt>rectangles, <a class="indexterm" href="#idp47806308">Filling Single and Multiple Rectangles</a></dt></dl></dd><dt>FlushGC, <a class="indexterm" href="#idp53908308">GC Caching</a></dt><dt>FocusIn, <a class="indexterm" href="#idp48807380">Input Focus Events</a></dt><dt>FocusOut, <a class="indexterm" href="#idp48807756">Input Focus Events</a></dt><dt>Font, <a class="indexterm" href="#idp47898956">Font Metrics</a>, <a class="indexterm" href="#idp54431692">Glossary</a></dt><dt>Font glyph, <a class="indexterm" href="#idp54433468">Glossary</a></dt><dt>Fonts</dt><dd><dl><dt>freeing font information, <a class="indexterm" href="#idp47938804">Loading and Freeing Fonts</a></dt><dt>getting information, <a class="indexterm" href="#idp47937796">Loading and Freeing Fonts</a></dt><dt>unloading, <a class="indexterm" href="#idp47938300">Loading and Freeing Fonts</a></dt></dl></dd><dt>Freeing</dt><dd><dl><dt>colors, <a class="indexterm" href="#idp46374140">Allocating and Freeing Color Cells</a></dt><dt>resources, <a class="indexterm" href="#idp42674340">Window Attributes</a>, <a class="indexterm" href="#idp44898356">Changing Window Attributes</a>, <a class="indexterm" href="#idp44922156">Changing Window Attributes</a></dt></dl></dd><dt>Frozen events, <a class="indexterm" href="#idp54434948">Glossary</a></dt><dt>Function set, <a class="indexterm" href="#idp47147956">Function Sets</a></dt><dd><dl><dt>LINEAR_RGB, <a class="indexterm" href="#idp47148388">Function Sets</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>G</h3><dl><dt>Gamut compression, <a class="indexterm" href="#idp45094380">Color Conversion Contexts and Gamut Mapping</a></dt><dd><dl><dt>client data, <a class="indexterm" href="#idp46640604">Modifying Attributes of a Color Conversion Context</a></dt><dt>procedure, <a class="indexterm" href="#idp46640028">Modifying Attributes of a Color Conversion Context</a></dt><dt>setting in Color Conversion Context, <a class="indexterm" href="#idp46639428">Modifying Attributes of a Color Conversion Context</a></dt></dl></dd><dt>Gamut handling, <a class="indexterm" href="#idp45094812">Color Conversion Contexts and Gamut Mapping</a></dt><dt>Gamut querying, <a class="indexterm" href="#idp46799012">Gamut Querying Functions</a></dt><dt>GC, <a class="indexterm" href="#idp54436500">Glossary</a></dt><dt>GeometryCallback, <a class="indexterm" href="#idp52253172">Geometry Callback</a></dt><dt>Glyph, <a class="indexterm" href="#idp54438404">Glossary</a></dt><dt>Glyph image, <a class="indexterm" href="#idp54440020">Glossary</a></dt><dt>Grab, <a class="indexterm" href="#idp54441628">Glossary</a></dt><dt>Grabbing</dt><dd><dl><dt>buttons, <a class="indexterm" href="#idp49154340">Pointer Grabbing</a></dt><dt>keyboard, <a class="indexterm" href="#idp49208612">Keyboard Grabbing</a></dt><dt>keys, <a class="indexterm" href="#idp49695956">Keyboard Grabbing</a></dt><dt>pointer, <a class="indexterm" href="#idp43502308">Pointer Grabbing</a></dt><dt>server, <a class="indexterm" href="#idp45722828">Grabbing the Server</a></dt></dl></dd><dt>Graphics context, <a class="indexterm" href="#idp54443356">Glossary</a></dt><dd><dl><dt>initializing, <a class="indexterm" href="#idp45234020">Manipulating Graphics Context/State</a></dt></dl></dd><dt>GraphicsExpose, <a class="indexterm" href="#idp48896620">GraphicsExpose and NoExpose Events</a></dt><dt>Gravity, <a class="indexterm" href="#idp54445364">Glossary</a></dt><dt>GravityNotify, <a class="indexterm" href="#idp48965260">GravityNotify Events</a></dt><dt>GrayScale, <a class="indexterm" href="#idp54447676">Glossary</a></dt></dl></div><div class="indexdiv"><h3>H</h3><dl><dt>Hash Lookup, <a class="indexterm" href="#idp50337660">Associating User Data with a Value</a></dt><dt>Headers, <a class="indexterm" href="#idp42298148">Standard Header Files</a></dt><dd><dl><dt>&lt;X11/cursorfont.h&gt;, <a class="indexterm" href="#idp41820060">Standard Header Files</a></dt><dt>&lt;X11/keysym.h&gt;, <a class="indexterm" href="#idp41831908">Standard Header Files</a>, <a class="indexterm" href="#idp49930012">Manipulating the Keyboard Encoding</a></dt><dt>&lt;X11/keysymdef.h&gt;, <a class="indexterm" href="#idp41824044">Standard Header Files</a>, <a class="indexterm" href="#idp49926908">Manipulating the Keyboard Encoding</a>, <a class="indexterm" href="#idp50175092">Using Keyboard Utility Functions</a></dt><dt>&lt;X11/X.h&gt;, <a class="indexterm" href="#idp39765972">Overview of the X Window System</a>, <a class="indexterm" href="#idp42305580">Standard Header Files</a>, <a class="indexterm" href="#idp44370540">Manipulating Graphics Context/State</a>, <a class="indexterm" href="#idp41279884">Event Types</a>, <a class="indexterm" href="#idp45618868">Event Masks</a></dt><dt>&lt;X11/X10.h&gt;, <a class="indexterm" href="#idp41850340">Standard Header Files</a>, <a class="indexterm" href="#idp50305412">Drawing and Filling Polygons and Curves</a>, <a class="indexterm" href="#idp50310500">Drawing and Filling Polygons and Curves</a></dt><dt>&lt;X11/Xatom.h&gt;, <a class="indexterm" href="#idp41816484">Standard Header Files</a>, <a class="indexterm" href="#idp44540052">Properties and Atoms</a>, <a class="indexterm" href="#idp47987716">Loading and Freeing Fonts</a>, <a class="indexterm" href="#idp52669340">Standard Colormap Properties and Atoms</a></dt><dt>&lt;X11/Xcms.h&gt;, <a class="indexterm" href="#idp41802324">Standard Header Files</a>, <a class="indexterm" href="#idp40505292">Color Management Functions</a></dt><dt>&lt;X11/Xlib.h&gt;, <a class="indexterm" href="#idp42301284">Standard Header Files</a>, <a class="indexterm" href="#idp43549332">Opening the Display</a>, <a class="indexterm" href="#idp40508508">Color Management Functions</a>, <a class="indexterm" href="#idp45418164">Event Structures</a>, <a class="indexterm" href="#idp53356300">Manipulating Images</a></dt><dt>&lt;X11/Xlibint.h&gt;, <a class="indexterm" href="#idp41837532">Standard Header Files</a></dt><dt>&lt;X11/Xproto.h&gt;, <a class="indexterm" href="#idp41842012">Standard Header Files</a>, <a class="indexterm" href="#idp48910684">GraphicsExpose and NoExpose Events</a></dt><dt>&lt;X11/Xprotostr.h&gt;, <a class="indexterm" href="#idp41846228">Standard Header Files</a></dt><dt>&lt;X11/Xresource.h&gt;, <a class="indexterm" href="#idp41811836">Standard Header Files</a>, <a class="indexterm" href="#idp49692116">Resource Manager Functions</a></dt><dt>&lt;X11/Xutil.h&gt;, <a class="indexterm" href="#idp41806908">Standard Header Files</a>, <a class="indexterm" href="#idp50642508">Setting and Reading the WM_HINTS Property</a>, <a class="indexterm" href="#idp50682300">Setting and Reading the WM_NORMAL_HINTS Property</a>, <a class="indexterm" href="#idp50764164">Setting and Reading the WM_CLASS Property</a>, <a class="indexterm" href="#idp50891372">Setting and Reading the WM_ICON_SIZE Property</a>, <a class="indexterm" href="#idp50277324">Parsing the Window Geometry</a>, <a class="indexterm" href="#idp53157196">Manipulating Regions</a>, <a class="indexterm" href="#idp53326444">Determining the Appropriate Visual Type</a>, <a class="indexterm" href="#idp53387516">Manipulating Images</a>, <a class="indexterm" href="#idp53529716">Using the Context Manager</a>, <a class="indexterm" href="#idp49280492">Setting and Getting Window Sizing Hints</a></dt></dl></dd><dt>HeightMMOfScreen, <a class="indexterm" href="#idp43817508">Screen Information Macros</a></dt><dt>HeightOfScreen, <a class="indexterm" href="#idp43806780">Screen Information Macros</a></dt><dt>Host Portable Character Encoding, <a class="indexterm" href="#idp54449876">Glossary</a></dt><dt>Hotspot, <a class="indexterm" href="#idp54451964">Glossary</a></dt></dl></div><div class="indexdiv"><h3>I</h3><dl><dt>Identifier, <a class="indexterm" href="#idp54453580">Glossary</a></dt><dt>Image text</dt><dd><dl><dt>drawing, <a class="indexterm" href="#idp48209220">Drawing Image Text Characters</a></dt></dl></dd><dt>ImageByteOrder, <a class="indexterm" href="#idp43683404">Image Format Functions and Macros</a></dt><dt>IMInstantiateCallback, <a class="indexterm" href="#idp51778836">Input Method Functions</a></dt><dt>Inferiors, <a class="indexterm" href="#idp54455236">Glossary</a></dt><dt>Input</dt><dd><dl><dt>focus, <a class="indexterm" href="#idp54456796">Glossary</a></dt><dt>manager, <a class="indexterm" href="#idp54458860">Glossary</a></dt></dl></dd><dt>Input Control, <a class="indexterm" href="#idp43051284">Event Types</a></dt><dt>Internationalization, <a class="indexterm" href="#idp54465692">Glossary</a></dt><dt>IsCursorKey, <a class="indexterm" href="#idp50187812">KeySym Classification Macros</a></dt><dt>IsFunctionKey, <a class="indexterm" href="#idp50191740">KeySym Classification Macros</a></dt><dt>IsKeypadKey, <a class="indexterm" href="#idp50195732">KeySym Classification Macros</a></dt><dt>IsMiscFunctionKey, <a class="indexterm" href="#idp50203556">KeySym Classification Macros</a></dt><dt>IsModifierKey, <a class="indexterm" href="#idp50207396">KeySym Classification Macros</a></dt><dt>ISO2022, <a class="indexterm" href="#idp54467436">Glossary</a></dt><dt>IsPFKey, <a class="indexterm" href="#idp50210740">KeySym Classification Macros</a></dt><dt>IsPrivateKeypadKey, <a class="indexterm" href="#idp50199556">KeySym Classification Macros</a></dt></dl></div><div class="indexdiv"><h3>K</h3><dl><dt>Key</dt><dd><dl><dt>grabbing, <a class="indexterm" href="#idp49695452">Keyboard Grabbing</a>, <a class="indexterm" href="#idp54075716">Glossary</a></dt><dt>ungrabbing, <a class="indexterm" href="#idp49720052">Keyboard Grabbing</a></dt></dl></dd><dt>Keyboard</dt><dd><dl><dt>bell volume, <a class="indexterm" href="#idp49818908">Manipulating the Keyboard and Pointer Settings</a></dt><dt>bit vector, <a class="indexterm" href="#idp49819916">Manipulating the Keyboard and Pointer Settings</a></dt><dt>grabbing, <a class="indexterm" href="#idp49208044">Keyboard Grabbing</a>, <a class="indexterm" href="#idp54077444">Glossary</a></dt><dt>keyclick volume, <a class="indexterm" href="#idp49819412">Manipulating the Keyboard and Pointer Settings</a></dt><dt>ungrabbing, <a class="indexterm" href="#idp49234156">Keyboard Grabbing</a></dt></dl></dd><dt>KeymapNotify, <a class="indexterm" href="#idp48877204">Key Map State Notification Events</a></dt><dt>KeyPress, <a class="indexterm" href="#idp47333132">Keyboard and Pointer Events</a></dt><dt>KeyRelease, <a class="indexterm" href="#idp47333556">Keyboard and Pointer Events</a></dt><dt>Keysym, <a class="indexterm" href="#idp54079260">Glossary</a></dt></dl></div><div class="indexdiv"><h3>L</h3><dl><dt>LastKnownRequestProcessed, <a class="indexterm" href="#idp43620196">Display Macros</a></dt><dt>Latin Portable Character Encoding, <a class="indexterm" href="#idp54082276">Glossary</a></dt><dt>Latin-1, <a class="indexterm" href="#idp54080796">Glossary</a></dt><dt>LeaveNotify, <a class="indexterm" href="#idp48752748">Window Entry/Exit Events</a></dt><dt>Lines</dt><dd><dl><dt>drawing, <a class="indexterm" href="#idp45373444">Drawing Single and Multiple Lines</a></dt></dl></dd><dt>Locale, <a class="indexterm" href="#idp54084004">Glossary</a></dt><dt>Locale name, <a class="indexterm" href="#idp54087956">Glossary</a></dt><dt>Localization, <a class="indexterm" href="#idp54089900">Glossary</a></dt><dt>LockDisplay, <a class="indexterm" href="#idp54474708">Locking Data Structures</a></dt></dl></div><div class="indexdiv"><h3>M</h3><dl><dt>MapNotify, <a class="indexterm" href="#idp48973988">MapNotify Events</a></dt><dt>Mapped window, <a class="indexterm" href="#idp54091588">Glossary</a></dt><dt>MappingNotify, <a class="indexterm" href="#idp48983428">MappingNotify Events</a></dt><dt>MapRequest, <a class="indexterm" href="#idp49050532">MapRequest Events</a></dt><dt>MaxCmapsOfScreen, <a class="indexterm" href="#idp43822876">Screen Information Macros</a></dt><dt>Menus, <a class="indexterm" href="#idp45720164">Grabbing the Server</a></dt><dt>MinCmapsOfScreen, <a class="indexterm" href="#idp43828628">Screen Information Macros</a></dt><dt>Modifier keys, <a class="indexterm" href="#idp54093156">Glossary</a></dt><dt>Monochrome, <a class="indexterm" href="#idp54094796">Glossary</a></dt><dt>MotionNotify, <a class="indexterm" href="#idp47336324">Keyboard and Pointer Events</a></dt><dt>Mouse</dt><dd><dl><dt>programming, <a class="indexterm" href="#idp49820420">Manipulating the Keyboard and Pointer Settings</a></dt></dl></dd><dt>Multibyte, <a class="indexterm" href="#idp54096740">Glossary</a></dt></dl></div><div class="indexdiv"><h3>N</h3><dl><dt>NextRequest, <a class="indexterm" href="#idp43625516">Display Macros</a></dt><dt>NoExpose, <a class="indexterm" href="#idp48898716">GraphicsExpose and NoExpose Events</a></dt><dt>None, <a class="indexterm" href="#idp41855460">Generic Values and Types</a></dt></dl></div><div class="indexdiv"><h3>O</h3><dl><dt>Obscure, <a class="indexterm" href="#idp54099068">Glossary</a></dt><dt>Occlude, <a class="indexterm" href="#idp54101228">Glossary</a></dt><dt>Output Control, <a class="indexterm" href="#idp41292388">Event Types</a></dt></dl></div><div class="indexdiv"><h3>P</h3><dl><dt>Padding, <a class="indexterm" href="#idp54103388">Glossary</a></dt><dt>Parent Window, <a class="indexterm" href="#idp38654028">Overview of the X Window System</a>, <a class="indexterm" href="#idp40502284">Obtaining Window Information</a></dt><dt>Passive grab, <a class="indexterm" href="#idp40767036">Pointer Grabbing</a>, <a class="indexterm" href="#idp54106636">Glossary</a></dt><dt>Pixel value, <a class="indexterm" href="#idp45163556">Manipulating Graphics Context/State</a>, <a class="indexterm" href="#idp54108188">Glossary</a></dt><dt>Pixmap, <a class="indexterm" href="#idp38658652">Overview of the X Window System</a>, <a class="indexterm" href="#idp54109932">Glossary</a></dt><dt>Plane, <a class="indexterm" href="#idp54111980">Glossary</a></dt><dd><dl><dt>copying, <a class="indexterm" href="#idp45295604">Copying Areas</a></dt><dt>mask, <a class="indexterm" href="#idp45164100">Manipulating Graphics Context/State</a>, <a class="indexterm" href="#idp54113572">Glossary</a></dt></dl></dd><dt>PlanesOfScreen, <a class="indexterm" href="#idp43834380">Screen Information Macros</a></dt><dt>Pointer, <a class="indexterm" href="#idp54115420">Glossary</a></dt><dd><dl><dt>grabbing, <a class="indexterm" href="#idp43502876">Pointer Grabbing</a>, <a class="indexterm" href="#idp49139172">Pointer Grabbing</a>, <a class="indexterm" href="#idp54116940">Glossary</a></dt><dt>ungrabbing, <a class="indexterm" href="#idp49128292">Pointer Grabbing</a></dt></dl></dd><dt>Pointing device, <a class="indexterm" href="#idp54118708">Glossary</a></dt><dt>Points</dt><dd><dl><dt>drawing, <a class="indexterm" href="#idp45338164">Drawing Single and Multiple Points</a></dt></dl></dd><dt>Polygons</dt><dd><dl><dt>drawing, <a class="indexterm" href="#idp45375428">Drawing Single and Multiple Lines</a></dt><dt>filling, <a class="indexterm" href="#idp47840348">Filling a Single Polygon</a></dt></dl></dd><dt>POSIX, <a class="indexterm" href="#idp54120516">Glossary</a></dt><dt>POSIX Portable Filename Character Set, <a class="indexterm" href="#idp54122388">Glossary</a></dt><dt>POSIX System Call</dt><dd><dl><dt>fork, <a class="indexterm" href="#idp42630956">Display Macros</a></dt></dl></dd><dt>PreeditCaretCallback, <a class="indexterm" href="#idp52360180">Preedit Caret Callback</a></dt><dt>PreeditDoneCallback, <a class="indexterm" href="#idp52303300">Preedit State Callbacks</a></dt><dt>PreeditDrawCallback, <a class="indexterm" href="#idp52316348">Preedit Draw Callback</a></dt><dt>PreeditStartCallback, <a class="indexterm" href="#idp52294356">Preedit State Callbacks</a></dt><dt>PreeditStateNotifyCallback, <a class="indexterm" href="#idp52206124">Preedit State Notify Callback</a></dt><dt>Property, <a class="indexterm" href="#idp54124820">Glossary</a></dt><dd><dl><dt>appending, <a class="indexterm" href="#idp44232156">Obtaining and Changing Window Properties</a></dt><dt>changing, <a class="indexterm" href="#idp44231588">Obtaining and Changing Window Properties</a></dt><dt>deleting, <a class="indexterm" href="#idp44984708">Obtaining and Changing Window Properties</a></dt><dt>format, <a class="indexterm" href="#idp44233860">Obtaining and Changing Window Properties</a></dt><dt>getting, <a class="indexterm" href="#idp44180516">Obtaining and Changing Window Properties</a></dt><dt>listing, <a class="indexterm" href="#idp44219820">Obtaining and Changing Window Properties</a></dt><dt>prepending, <a class="indexterm" href="#idp44232724">Obtaining and Changing Window Properties</a></dt><dt>replacing, <a class="indexterm" href="#idp44233292">Obtaining and Changing Window Properties</a></dt><dt>type, <a class="indexterm" href="#idp44234428">Obtaining and Changing Window Properties</a></dt></dl></dd><dt>Property list, <a class="indexterm" href="#idp54126612">Glossary</a></dt><dt>PropertyNotify, <a class="indexterm" href="#idp49089372">PropertyNotify Events</a></dt><dt>Protocol</dt><dd><dl><dt>DECnet, <a class="indexterm" href="#idp43542476">Opening the Display</a></dt><dt>TCP, <a class="indexterm" href="#idp43541844">Opening the Display</a></dt></dl></dd><dt>ProtocolRevision, <a class="indexterm" href="#idp43636028">Display Macros</a></dt><dt>ProtocolVersion, <a class="indexterm" href="#idp43630796">Display Macros</a></dt><dt>PseudoColor, <a class="indexterm" href="#idp54128156">Glossary</a></dt><dt>Psychometric Chroma, <a class="indexterm" href="#idp46861556">CIELab Queries</a>, <a class="indexterm" href="#idp46892508">CIELab Queries</a>, <a class="indexterm" href="#idp46922380">CIELuv Queries</a>, <a class="indexterm" href="#idp46953724">CIELuv Queries</a></dt><dd><dl><dt>maximum, <a class="indexterm" href="#idp46861988">CIELab Queries</a>, <a class="indexterm" href="#idp46893516">CIELab Queries</a>, <a class="indexterm" href="#idp46922812">CIELuv Queries</a>, <a class="indexterm" href="#idp46954732">CIELuv Queries</a></dt></dl></dd><dt>Psychometric Hue Angle, <a class="indexterm" href="#idp46860540">CIELab Queries</a>, <a class="indexterm" href="#idp46877212">CIELab Queries</a>, <a class="indexterm" href="#idp46892068">CIELab Queries</a>, <a class="indexterm" href="#idp46905812">CIELab Queries</a>, <a class="indexterm" href="#idp46921364">CIELuv Queries</a>, <a class="indexterm" href="#idp46938452">CIELuv Queries</a>, <a class="indexterm" href="#idp46953284">CIELuv Queries</a>, <a class="indexterm" href="#idp46967028">CIELuv Queries</a></dt></dl></div><div class="indexdiv"><h3>Q</h3><dl><dt>QLength, <a class="indexterm" href="#idp43641220">Display Macros</a></dt></dl></div><div class="indexdiv"><h3>R</h3><dl><dt>Read-only colormap cells, <a class="indexterm" href="#idp46247692">Allocating and Freeing Color Cells</a></dt><dd><dl><dt>allocating, <a class="indexterm" href="#idp46251268">Allocating and Freeing Color Cells</a>, <a class="indexterm" href="#idp46266636">Allocating and Freeing Color Cells</a>, <a class="indexterm" href="#idp46283244">Allocating and Freeing Color Cells</a>, <a class="indexterm" href="#idp46298540">Allocating and Freeing Color Cells</a></dt></dl></dd><dt>read-only colormap cells, <a class="indexterm" href="#idp46262644">Allocating and Freeing Color Cells</a></dt><dt>Read/write colormap cells, <a class="indexterm" href="#idp46248260">Allocating and Freeing Color Cells</a></dt><dd><dl><dt>allocating, <a class="indexterm" href="#idp46319404">Allocating and Freeing Color Cells</a></dt></dl></dd><dt>Read/write colormap planes</dt><dd><dl><dt>allocating, <a class="indexterm" href="#idp46343284">Allocating and Freeing Color Cells</a></dt></dl></dd><dt>Rectangle, <a class="indexterm" href="#idp54130708">Glossary</a></dt><dd><dl><dt>filling, <a class="indexterm" href="#idp47807188">Filling Single and Multiple Rectangles</a></dt></dl></dd><dt>Rectangles</dt><dd><dl><dt>drawing, <a class="indexterm" href="#idp47728972">Drawing Single and Multiple Rectangles</a></dt></dl></dd><dt>Redirecting control, <a class="indexterm" href="#idp54132412">Glossary</a></dt><dt>ReparentNotify, <a class="indexterm" href="#idp48994092">ReparentNotify Events</a></dt><dt>Reply, <a class="indexterm" href="#idp54134196">Glossary</a></dt><dt>Request, <a class="indexterm" href="#idp54135940">Glossary</a></dt><dt>ResizeRequest, <a class="indexterm" href="#idp49059748">ResizeRequest Events</a></dt><dt>Resource, <a class="indexterm" href="#idp54137524">Glossary</a></dt><dt>Resource IDs, <a class="indexterm" href="#idp42124140">Overview of the X Window System</a>, <a class="indexterm" href="#idp43861764">Closing the Display</a>, <a class="indexterm" href="#idp50338652">Associating User Data with a Value</a></dt><dd><dl><dt>Colormap, <a class="indexterm" href="#idp42126276">Overview of the X Window System</a></dt><dt>Cursor, <a class="indexterm" href="#idp42126852">Overview of the X Window System</a></dt><dt>Font, <a class="indexterm" href="#idp42125124">Overview of the X Window System</a></dt><dt>freeing, <a class="indexterm" href="#idp42673764">Window Attributes</a>, <a class="indexterm" href="#idp44897852">Changing Window Attributes</a>, <a class="indexterm" href="#idp44921652">Changing Window Attributes</a></dt><dt>GContext, <a class="indexterm" href="#idp42127428">Overview of the X Window System</a></dt><dt>Pixmap, <a class="indexterm" href="#idp42125700">Overview of the X Window System</a></dt><dt>Window, <a class="indexterm" href="#idp42124548">Overview of the X Window System</a></dt></dl></dd><dt>RGB values, <a class="indexterm" href="#idp54139444">Glossary</a></dt><dt>Root, <a class="indexterm" href="#idp54141572">Glossary</a></dt><dt>RootWindow, <a class="indexterm" href="#idp43649276">Display Macros</a></dt><dt>RootWindowOfScreen, <a class="indexterm" href="#idp43839724">Screen Information Macros</a></dt></dl></div><div class="indexdiv"><h3>S</h3><dl><dt>Save set, <a class="indexterm" href="#idp54145020">Glossary</a></dt><dt>Save Unders, <a class="indexterm" href="#idp44020156">Save Under Flag</a></dt><dt>Scanline, <a class="indexterm" href="#idp54146836">Glossary</a></dt><dd><dl><dt>order, <a class="indexterm" href="#idp54148436">Glossary</a></dt></dl></dd><dt>Screen, <a class="indexterm" href="#idp41228916">Overview of the X Window System</a>, <a class="indexterm" href="#idp41181020">Opening the Display</a>, <a class="indexterm" href="#idp54150188">Glossary</a></dt><dd><dl><dt>structure, <a class="indexterm" href="#idp54150612">Glossary</a></dt></dl></dd><dt>Screen White Point, <a class="indexterm" href="#idp46802756">Gamut Querying Functions</a></dt><dt>ScreenCount, <a class="indexterm" href="#idp43655052">Display Macros</a></dt><dt>ScreenNumberOfCCC, <a class="indexterm" href="#idp46606268">Color Conversion Context Macros</a></dt><dt>ScreenOfDisplay, <a class="indexterm" href="#idp42591308">Display Macros</a></dt><dt>ScreenWhitePointOfCCC, <a class="indexterm" href="#idp46613028">Color Conversion Context Macros</a></dt><dt>Selection, <a class="indexterm" href="#idp44995076">Selections</a>, <a class="indexterm" href="#idp54153564">Glossary</a></dt><dd><dl><dt>converting, <a class="indexterm" href="#idp45023036">Selections</a></dt><dt>getting the owner, <a class="indexterm" href="#idp45014412">Selections</a></dt><dt>setting the owner, <a class="indexterm" href="#idp44999116">Selections</a></dt></dl></dd><dt>SelectionClear, <a class="indexterm" href="#idp49099556">SelectionClear Events</a></dt><dt>SelectionNotify, <a class="indexterm" href="#idp49114484">SelectionNotify Events</a></dt><dt>SelectionRequest, <a class="indexterm" href="#idp49105772">SelectionRequest Events</a></dt><dt>Serial Number, <a class="indexterm" href="#idp48454620">Using the Default Error Handlers</a></dt><dt>Server, <a class="indexterm" href="#idp54156356">Glossary</a></dt><dd><dl><dt>grabbing, <a class="indexterm" href="#idp45722260">Grabbing the Server</a>, <a class="indexterm" href="#idp54158236">Glossary</a></dt></dl></dd><dt>ServerVendor, <a class="indexterm" href="#idp43660228">Display Macros</a></dt><dt>Shift sequence, <a class="indexterm" href="#idp54160116">Glossary</a></dt><dt>Sibling, <a class="indexterm" href="#idp54161836">Glossary</a></dt><dt>Source, <a class="indexterm" href="#idp44366692">Manipulating Graphics Context/State</a></dt><dt>Stacking order, <a class="indexterm" href="#idp38654988">Overview of the X Window System</a>, <a class="indexterm" href="#idp54163324">Glossary</a></dt><dt>Standard Colormaps, <a class="indexterm" href="#idp52666172">Standard Colormap Properties and Atoms</a></dt><dt>State-dependent encoding, <a class="indexterm" href="#idp54164972">Glossary</a></dt><dt>State-independent encoding, <a class="indexterm" href="#idp54166708">Glossary</a></dt><dt>StaticColor, <a class="indexterm" href="#idp54168308">Glossary</a></dt><dt>StaticGray, <a class="indexterm" href="#idp54170652">Glossary</a></dt><dt>Status, <a class="indexterm" href="#idp42294316">Errors</a>, <a class="indexterm" href="#idp54172900">Glossary</a></dt><dt>StatusDoneCallback, <a class="indexterm" href="#idp52407100">Status Callbacks</a></dt><dt>StatusDrawCallback, <a class="indexterm" href="#idp52416316">Status Callbacks</a></dt><dt>StatusStartCallback, <a class="indexterm" href="#idp52398052">Status Callbacks</a></dt><dt>Stipple, <a class="indexterm" href="#idp54174508">Glossary</a></dt><dt>String Equivalence, <a class="indexterm" href="#idp54177452">Glossary</a></dt><dt>StringConversionCallback, <a class="indexterm" href="#idp52273076">String Conversion Callback</a></dt><dt>Strings</dt><dd><dl><dt>drawing, <a class="indexterm" href="#idp48173964">Drawing Text Characters</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>T</h3><dl><dt>Text</dt><dd><dl><dt>drawing, <a class="indexterm" href="#idp48139076">Drawing Complex Text</a></dt></dl></dd><dt>Tile, <a class="indexterm" href="#idp38659500">Overview of the X Window System</a>, <a class="indexterm" href="#idp54179652">Glossary</a></dt><dd><dl><dt>mode, <a class="indexterm" href="#idp42675052">Window Attributes</a></dt><dt>pixmaps, <a class="indexterm" href="#idp42673156">Window Attributes</a></dt></dl></dd><dt>Time, <a class="indexterm" href="#idp43365292">Pointer Grabbing</a></dt><dt>Timestamp, <a class="indexterm" href="#idp54181244">Glossary</a></dt><dt>True, <a class="indexterm" href="#idp41853524">Generic Values and Types</a></dt><dt>TrueColor, <a class="indexterm" href="#idp54183524">Glossary</a></dt><dt>Type, <a class="indexterm" href="#idp54186268">Glossary</a></dt></dl></div><div class="indexdiv"><h3>U</h3><dl><dt>Ungrabbing</dt><dd><dl><dt>buttons, <a class="indexterm" href="#idp49189068">Pointer Grabbing</a></dt><dt>keyboard, <a class="indexterm" href="#idp49234724">Keyboard Grabbing</a></dt><dt>keys, <a class="indexterm" href="#idp49720556">Keyboard Grabbing</a></dt><dt>pointer, <a class="indexterm" href="#idp49127724">Pointer Grabbing</a></dt></dl></dd><dt>UnlockDisplay, <a class="indexterm" href="#idp54476852">Locking Data Structures</a></dt><dt>UnmapNotify, <a class="indexterm" href="#idp49002540">UnmapNotify Events</a></dt><dt>UnmapNotify Event, <a class="indexterm" href="#idp44696316">Unmapping Windows</a>, <a class="indexterm" href="#idp44706052">Unmapping Windows</a></dt></dl></div><div class="indexdiv"><h3>V</h3><dl><dt>Value, <a class="indexterm" href="#idp46995292">TekHVC Queries</a>, <a class="indexterm" href="#idp47008620">TekHVC Queries</a>, <a class="indexterm" href="#idp47020964">TekHVC Queries</a>, <a class="indexterm" href="#idp47034524">TekHVC Queries</a></dt><dd><dl><dt>maximum, <a class="indexterm" href="#idp46995716">TekHVC Queries</a>, <a class="indexterm" href="#idp47009612">TekHVC Queries</a>, <a class="indexterm" href="#idp47021956">TekHVC Queries</a></dt><dt>minimum, <a class="indexterm" href="#idp47034948">TekHVC Queries</a></dt></dl></dd><dt>VendorRelease, <a class="indexterm" href="#idp43665692">Display Macros</a></dt><dt>Vertex, <a class="indexterm" href="#idp50306356">Drawing and Filling Polygons and Curves</a></dt><dt>VertexCurved, <a class="indexterm" href="#idp50312276">Drawing and Filling Polygons and Curves</a></dt><dt>VertexDontDraw, <a class="indexterm" href="#idp50311844">Drawing and Filling Polygons and Curves</a></dt><dt>VertexEndClosed, <a class="indexterm" href="#idp50313140">Drawing and Filling Polygons and Curves</a></dt><dt>VertexRelative, <a class="indexterm" href="#idp50311412">Drawing and Filling Polygons and Curves</a></dt><dt>VertexStartClosed, <a class="indexterm" href="#idp50312708">Drawing and Filling Polygons and Curves</a></dt><dt>Viewable, <a class="indexterm" href="#idp54188028">Glossary</a></dt><dt>VisibilityNotify, <a class="indexterm" href="#idp49010540">VisibilityNotify Events</a></dt><dt>Visible, <a class="indexterm" href="#idp54189804">Glossary</a></dt><dt>Visual, <a class="indexterm" href="#idp43020308">Visual Types</a></dt><dt>Visual Classes</dt><dd><dl><dt>GrayScale, <a class="indexterm" href="#idp43019108">Visual Types</a></dt><dt>PseudoColor, <a class="indexterm" href="#idp42895284">Visual Types</a></dt><dt>StaticColor, <a class="indexterm" href="#idp41234268">Visual Types</a>, <a class="indexterm" href="#idp40794932">Visual Types</a></dt><dt>StaticGray, <a class="indexterm" href="#idp42641572">Visual Types</a></dt><dt>TrueColor, <a class="indexterm" href="#idp40415276">Visual Types</a></dt></dl></dd><dt>Visual Type, <a class="indexterm" href="#idp41430948">Visual Types</a></dt><dt>VisualOfCCC, <a class="indexterm" href="#idp46599556">Color Conversion Context Macros</a></dt></dl></div><div class="indexdiv"><h3>W</h3><dl><dt>White point, <a class="indexterm" href="#idp45091420">Color Conversion Contexts and Gamut Mapping</a></dt><dt>White point adjustment, <a class="indexterm" href="#idp45095244">Color Conversion Contexts and Gamut Mapping</a></dt><dd><dl><dt>client data, <a class="indexterm" href="#idp46652716">Modifying Attributes of a Color Conversion Context</a></dt><dt>procedure, <a class="indexterm" href="#idp46652132">Modifying Attributes of a Color Conversion Context</a></dt><dt>setting in Color Conversion Context, <a class="indexterm" href="#idp46651524">Modifying Attributes of a Color Conversion Context</a></dt></dl></dd><dt>WhitePixel, <a class="indexterm" href="#idp42527724">Display Macros</a></dt><dt>WhitePixelOfScreen, <a class="indexterm" href="#idp43740548">Screen Information Macros</a></dt><dt>Whitespace, <a class="indexterm" href="#idp54191460">Glossary</a></dt><dt>WidthMMOfScreen, <a class="indexterm" href="#idp43812140">Screen Information Macros</a></dt><dt>WidthOfScreen, <a class="indexterm" href="#idp43801420">Screen Information Macros</a></dt><dt>Window, <a class="indexterm" href="#idp38656044">Overview of the X Window System</a>, <a class="indexterm" href="#idp40341028">Window Attributes</a></dt><dd><dl><dt>attributes, <a class="indexterm" href="#idp40341452">Window Attributes</a></dt><dt>background, <a class="indexterm" href="#idp44890180">Changing Window Attributes</a></dt><dt>clearing, <a class="indexterm" href="#idp46184412">Clearing Areas</a></dt><dt>defining the cursor, <a class="indexterm" href="#idp44934548">Changing Window Attributes</a></dt><dt>determining location, <a class="indexterm" href="#idp50256484">Parsing the Window Geometry</a>, <a class="indexterm" href="#idp50416148">Parsing Window Geometry</a></dt><dt>gravity, <a class="indexterm" href="#idp54193364">Glossary</a></dt><dt>icon name, <a class="indexterm" href="#idp50616508">Setting and Reading the WM_ICON_NAME Property</a></dt><dt>IDs, <a class="indexterm" href="#idp50338084">Associating User Data with a Value</a></dt><dt>InputOnly, <a class="indexterm" href="#idp44053140">Creating Windows</a>, <a class="indexterm" href="#idp54460572">Glossary</a></dt><dt>InputOutput, <a class="indexterm" href="#idp54463188">Glossary</a></dt><dt>manager, <a class="indexterm" href="#idp54195156">Glossary</a></dt><dt>managers, <a class="indexterm" href="#idp45720588">Grabbing the Server</a></dt><dt>mapping, <a class="indexterm" href="#idp42676508">Window Attributes</a></dt><dt>name, <a class="indexterm" href="#idp51021076">Setting and Reading the WM_NAME Property</a></dt><dt>parent, <a class="indexterm" href="#idp54104996">Glossary</a></dt><dt>root, <a class="indexterm" href="#idp54143220">Glossary</a></dt><dt>RootWindow, <a class="indexterm" href="#idp43648772">Display Macros</a></dt><dt>undefining the cursor, <a class="indexterm" href="#idp44944708">Changing Window Attributes</a></dt><dt>XRootWindow, <a class="indexterm" href="#idp43649652">Display Macros</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>X</h3><dl><dt>X Portable Character Set, <a class="indexterm" href="#idp54196852">Glossary</a></dt><dt>X10 compatibility</dt><dd><dl><dt>XDraw, <a class="indexterm" href="#idp53731132">Drawing and Filling Polygons and Curves</a>, <a class="indexterm" href="#idp50288236">Drawing and Filling Polygons and Curves</a></dt><dt>XDrawDashed, <a class="indexterm" href="#idp53734020">Drawing and Filling Polygons and Curves</a>, <a class="indexterm" href="#idp50289172">Drawing and Filling Polygons and Curves</a></dt><dt>XDrawFilled, <a class="indexterm" href="#idp53732132">Drawing and Filling Polygons and Curves</a>, <a class="indexterm" href="#idp50322420">Drawing and Filling Polygons and Curves</a></dt><dt>XDrawPatterned, <a class="indexterm" href="#idp53733076">Drawing and Filling Polygons and Curves</a>, <a class="indexterm" href="#idp50290116">Drawing and Filling Polygons and Curves</a></dt><dt>XDrawTiled, <a class="indexterm" href="#idp53734956">Drawing and Filling Polygons and Curves</a>, <a class="indexterm" href="#idp50321420">Drawing and Filling Polygons and Curves</a></dt></dl></dd><dt>X11/cursorfont.h, <a class="indexterm" href="#idp41818580">Standard Header Files</a></dt><dt>X11/keysym.h, <a class="indexterm" href="#idp41830428">Standard Header Files</a>, <a class="indexterm" href="#idp49928404">Manipulating the Keyboard Encoding</a></dt><dt>X11/keysymdef.h, <a class="indexterm" href="#idp41822564">Standard Header Files</a>, <a class="indexterm" href="#idp49925300">Manipulating the Keyboard Encoding</a>, <a class="indexterm" href="#idp50173276">Using Keyboard Utility Functions</a></dt><dt>X11/X.h, <a class="indexterm" href="#idp39764172">Overview of the X Window System</a>, <a class="indexterm" href="#idp42304116">Standard Header Files</a>, <a class="indexterm" href="#idp44368740">Manipulating Graphics Context/State</a>, <a class="indexterm" href="#idp40394044">Event Types</a>, <a class="indexterm" href="#idp45617068">Event Masks</a></dt><dt>X11/X10.h, <a class="indexterm" href="#idp41848876">Standard Header Files</a>, <a class="indexterm" href="#idp50303612">Drawing and Filling Polygons and Curves</a>, <a class="indexterm" href="#idp50308700">Drawing and Filling Polygons and Curves</a></dt><dt>X11/Xatom.h, <a class="indexterm" href="#idp41815012">Standard Header Files</a>, <a class="indexterm" href="#idp44538244">Properties and Atoms</a>, <a class="indexterm" href="#idp47986108">Loading and Freeing Fonts</a>, <a class="indexterm" href="#idp52667732">Standard Colormap Properties and Atoms</a></dt><dt>X11/Xcms.h, <a class="indexterm" href="#idp42308284">Standard Header Files</a>, <a class="indexterm" href="#idp40503564">Color Management Functions</a></dt><dt>X11/Xlib.h, <a class="indexterm" href="#idp42299812">Standard Header Files</a>, <a class="indexterm" href="#idp43547524">Opening the Display</a>, <a class="indexterm" href="#idp40506700">Color Management Functions</a>, <a class="indexterm" href="#idp45416356">Event Structures</a>, <a class="indexterm" href="#idp53354692">Manipulating Images</a></dt><dt>X11/Xlibint.h, <a class="indexterm" href="#idp41836052">Standard Header Files</a></dt><dt>X11/Xproto.h, <a class="indexterm" href="#idp41840532">Standard Header Files</a>, <a class="indexterm" href="#idp48909076">GraphicsExpose and NoExpose Events</a></dt><dt>X11/Xprotostr.h, <a class="indexterm" href="#idp41844748">Standard Header Files</a></dt><dt>X11/Xresource.h, <a class="indexterm" href="#idp41810356">Standard Header Files</a>, <a class="indexterm" href="#idp49690356">Resource Manager Functions</a></dt><dt>X11/Xutil.h, <a class="indexterm" href="#idp41805436">Standard Header Files</a>, <a class="indexterm" href="#idp50640700">Setting and Reading the WM_HINTS Property</a>, <a class="indexterm" href="#idp50680492">Setting and Reading the WM_NORMAL_HINTS Property</a>, <a class="indexterm" href="#idp50762356">Setting and Reading the WM_CLASS Property</a>, <a class="indexterm" href="#idp50889564">Setting and Reading the WM_ICON_SIZE Property</a>, <a class="indexterm" href="#idp50275516">Parsing the Window Geometry</a>, <a class="indexterm" href="#idp53155588">Manipulating Regions</a>, <a class="indexterm" href="#idp53324836">Determining the Appropriate Visual Type</a>, <a class="indexterm" href="#idp53385908">Manipulating Images</a>, <a class="indexterm" href="#idp53528108">Using the Context Manager</a>, <a class="indexterm" href="#idp50155516">Setting and Getting Window Sizing Hints</a></dt><dt>XActivateScreenSaver, <a class="indexterm" href="#idp45779492">Controlling the Screen Saver</a></dt><dt>XAddExtension, <a class="indexterm" href="#idp52897844">Hooking into Xlib</a></dt><dt>XAddHost, <a class="indexterm" href="#idp45702724">Adding, Getting, or Removing Hosts</a></dt><dt>XAddHosts, <a class="indexterm" href="#idp45711932">Adding, Getting, or Removing Hosts</a></dt><dt>XAddPixel, <a class="indexterm" href="#idp53419892">Manipulating Images</a></dt><dt>XAddToExtensionList, <a class="indexterm" href="#idp53875980">Hooks onto Xlib Data Structures</a></dt><dt>XAddToSaveSet, <a class="indexterm" href="#idp43484604">Controlling the Lifetime of a Window</a></dt><dt>XAllocClassHint, <a class="indexterm" href="#idp50766236">Setting and Reading the WM_CLASS Property</a></dt><dt>XAllocColor, <a class="indexterm" href="#idp46252276">Allocating and Freeing Color Cells</a>, <a class="indexterm" href="#idp46388100">Allocating and Freeing Color Cells</a></dt><dt>XAllocColorCells, <a class="indexterm" href="#idp46321140">Allocating and Freeing Color Cells</a>, <a class="indexterm" href="#idp46388956">Allocating and Freeing Color Cells</a></dt><dt>XAllocColorPlanes, <a class="indexterm" href="#idp46345020">Allocating and Freeing Color Cells</a>, <a class="indexterm" href="#idp46389388">Allocating and Freeing Color Cells</a></dt><dt>XAllocID, <a class="indexterm" href="#idp53890940">Hooks onto Xlib Data Structures</a></dt><dt>XAllocIDs, <a class="indexterm" href="#idp53896452">Hooks onto Xlib Data Structures</a></dt><dt>XAllocNamedColor, <a class="indexterm" href="#idp46284756">Allocating and Freeing Color Cells</a>, <a class="indexterm" href="#idp46388524">Allocating and Freeing Color Cells</a></dt><dt>XAllowEvents, <a class="indexterm" href="#idp49734332">Resuming Event Processing</a></dt><dt>XAllPlanes, <a class="indexterm" href="#idp41679876">Display Macros</a></dt><dt>XAnyEvent, <a class="indexterm" href="#idp45419516">Event Structures</a></dt><dt>XArc, <a class="indexterm" href="#idp45334508">Drawing Points, Lines, Rectangles, and Arcs</a></dt><dt>XAutoRepeatOff, <a class="indexterm" href="#idp49856428">Manipulating the Keyboard and Pointer Settings</a></dt><dt>XAutoRepeatOn, <a class="indexterm" href="#idp49851436">Manipulating the Keyboard and Pointer Settings</a></dt><dt>XBaseFontNameListOfFontSet, <a class="indexterm" href="#idp51344748">Creating and Freeing a Font Set</a></dt><dt>XBell, <a class="indexterm" href="#idp49861420">Manipulating the Keyboard and Pointer Settings</a></dt><dt>XBitmapBitOrder, <a class="indexterm" href="#idp43694708">Image Format Functions and Macros</a></dt><dt>XBitmapPad, <a class="indexterm" href="#idp43700412">Image Format Functions and Macros</a></dt><dt>XBitmapUnit, <a class="indexterm" href="#idp43689468">Image Format Functions and Macros</a></dt><dt>XBlackPixel, <a class="indexterm" href="#idp42519908">Display Macros</a></dt><dt>XBlackPixelOfScreen, <a class="indexterm" href="#idp43735596">Screen Information Macros</a></dt><dt>XCellsOfScreen, <a class="indexterm" href="#idp43746252">Screen Information Macros</a></dt><dt>XChangeActivePointerGrab, <a class="indexterm" href="#idp49140316">Pointer Grabbing</a></dt><dt>XChangeGC, <a class="indexterm" href="#idp45261652">Manipulating Graphics Context/State</a></dt><dt>XChangeKeyboardControl, <a class="indexterm" href="#idp49831028">Manipulating the Keyboard and Pointer Settings</a></dt><dt>XChangeKeyboardMapping, <a class="indexterm" href="#idp49973364">Manipulating the Keyboard Encoding</a></dt><dt>XChangePointerControl, <a class="indexterm" href="#idp49899684">Manipulating the Keyboard and Pointer Settings</a></dt><dt>XChangeProperty, <a class="indexterm" href="#idp44234996">Obtaining and Changing Window Properties</a></dt><dt>XChangeSaveSet, <a class="indexterm" href="#idp45753604">Controlling the Lifetime of a Window</a></dt><dt>XChangeWindowAttributes, <a class="indexterm" href="#idp44860988">Changing Window Attributes</a></dt><dt>XChar2b, <a class="indexterm" href="#idp47909012">Font Metrics</a></dt><dt>XCharStruct, <a class="indexterm" href="#idp47905684">Font Metrics</a></dt><dt>XCheckIfEvent, <a class="indexterm" href="#idp47459756">Selecting Events Using a Predicate Procedure</a></dt><dt>XCheckMaskEvent, <a class="indexterm" href="#idp47424900">Selecting Events Using a Window or Event Mask</a></dt><dt>XCheckTypedEvent, <a class="indexterm" href="#idp47436252">Selecting Events Using a Window or Event Mask</a></dt><dt>XCheckTypedWindowEvent, <a class="indexterm" href="#idp47447628">Selecting Events Using a Window or Event Mask</a></dt><dt>XCheckWindowEvent, <a class="indexterm" href="#idp47399148">Selecting Events Using a Window or Event Mask</a>, <a class="indexterm" href="#idp47400324">Selecting Events Using a Window or Event Mask</a></dt><dt>XCirculateEvent, <a class="indexterm" href="#idp48926196">CirculateNotify Events</a></dt><dt>XCirculateRequestEvent, <a class="indexterm" href="#idp49032828">CirculateRequest Events</a></dt><dt>XCirculateSubwindows, <a class="indexterm" href="#idp44819340">Changing Window Stacking Order</a></dt><dt>XCirculateSubwindowsDown, <a class="indexterm" href="#idp44839516">Changing Window Stacking Order</a></dt><dt>XCirculateSubwindowsUp, <a class="indexterm" href="#idp44831308">Changing Window Stacking Order</a></dt><dt>XClassHint, <a class="indexterm" href="#idp50770588">Setting and Reading the WM_CLASS Property</a></dt><dt>XClearArea, <a class="indexterm" href="#idp43072036">Clearing Areas</a></dt><dt>XClearWindow, <a class="indexterm" href="#idp46185548">Clearing Areas</a></dt><dt>XClientMessageEvent, <a class="indexterm" href="#idp49084852">ClientMessage Events</a></dt><dt>XClipBox, <a class="indexterm" href="#idp53201364">Computing with Regions</a></dt><dt>XCloseDisplay, <a class="indexterm" href="#idp43854364">Closing the Display</a>, <a class="indexterm" href="#idp43862140">Closing the Display</a></dt><dt>XCloseIM, <a class="indexterm" href="#idp51728532">Input Method Functions</a></dt><dt>XCloseOM, <a class="indexterm" href="#idp49378460">Output Method Functions</a></dt><dt>XcmsAddColorSpace, <a class="indexterm" href="#idp47060148">Adding Device-Independent Color Spaces</a></dt><dt>XcmsAddFunctionSet, <a class="indexterm" href="#idp47154060">Adding Function Sets</a></dt><dt>XcmsAllocColor, <a class="indexterm" href="#idp46267644">Allocating and Freeing Color Cells</a></dt><dt>XcmsAllocNamedColor, <a class="indexterm" href="#idp46300052">Allocating and Freeing Color Cells</a></dt><dt>XcmsCCCOfColormap, <a class="indexterm" href="#idp46556940">Getting and Setting the Color Conversion Context of a Colormap</a></dt><dt>XcmsCIELab, <a class="indexterm" href="#idp42188548">Color Structures</a></dt><dt>XcmsCIELabQueryMaxC, <a class="indexterm" href="#idp46864436">CIELab Queries</a></dt><dt>XcmsCIELabQueryMaxL, <a class="indexterm" href="#idp46878948">CIELab Queries</a></dt><dt>XcmsCIELabQueryMaxLC, <a class="indexterm" href="#idp46894812">CIELab Queries</a></dt><dt>XcmsCIELabQueryMinL, <a class="indexterm" href="#idp46907548">CIELab Queries</a></dt><dt>XcmsCIELuv, <a class="indexterm" href="#idp45041404">Color Structures</a></dt><dt>XcmsCIELuvQueryMaxC, <a class="indexterm" href="#idp46925644">CIELuv Queries</a></dt><dt>XcmsCIELuvQueryMaxL, <a class="indexterm" href="#idp46940188">CIELuv Queries</a></dt><dt>XcmsCIELuvQueryMaxLC, <a class="indexterm" href="#idp46956028">CIELuv Queries</a></dt><dt>XcmsCIELuvQueryMinL, <a class="indexterm" href="#idp46968764">CIELuv Queries</a></dt><dt>XcmsCIEuvY, <a class="indexterm" href="#idp42184964">Color Structures</a></dt><dt>XcmsCIExyY, <a class="indexterm" href="#idp42186764">Color Structures</a></dt><dt>XcmsCIEXYZ, <a class="indexterm" href="#idp42183220">Color Structures</a></dt><dt>XcmsClientWhitePointOfCCC, <a class="indexterm" href="#idp46620300">Color Conversion Context Macros</a></dt><dt>XcmsColor, <a class="indexterm" href="#idp43564044">Color Structures</a></dt><dt>XcmsCompressionProc, <a class="indexterm" href="#idp46716348">Prototype Gamut Compression Procedure</a></dt><dt>XcmsConvertColors, <a class="indexterm" href="#idp46695412">Converting between Color Spaces</a></dt><dt>XcmsCreateCCC, <a class="indexterm" href="#idp46665284">Creating and Freeing a Color Conversion Context</a></dt><dt>XcmsDefaultCCC, <a class="indexterm" href="#idp46582180">Obtaining the Default Color Conversion Context</a></dt><dt>XcmsDisplayOfCCC, <a class="indexterm" href="#idp46593140">Color Conversion Context Macros</a></dt><dt>XcmsFormatOfPrefix, <a class="indexterm" href="#idp47070844">Querying Color Space Format and Prefix</a></dt><dt>XcmsFreeCCC, <a class="indexterm" href="#idp46686036">Creating and Freeing a Color Conversion Context</a></dt><dt>XcmsLookupColor, <a class="indexterm" href="#idp46231772">Mapping Color Names to Values</a></dt><dt>XcmsPad, <a class="indexterm" href="#idp45044964">Color Structures</a></dt><dt>XcmsParseStringProc, <a class="indexterm" href="#idp47096148">Parse String Callback</a></dt><dt>XcmsPrefixOfFormat, <a class="indexterm" href="#idp47077748">Querying Color Space Format and Prefix</a></dt><dt>XcmsQueryBlack, <a class="indexterm" href="#idp46809204">Red, Green, and Blue Queries</a></dt><dt>XcmsQueryBlue, <a class="indexterm" href="#idp46819204">Red, Green, and Blue Queries</a></dt><dt>XcmsQueryColor, <a class="indexterm" href="#idp46517684">Modifying and Querying Colormap Cells</a></dt><dt>XcmsQueryColors, <a class="indexterm" href="#idp46532156">Modifying and Querying Colormap Cells</a></dt><dt>XcmsQueryGreen, <a class="indexterm" href="#idp46829260">Red, Green, and Blue Queries</a></dt><dt>XcmsQueryRed, <a class="indexterm" href="#idp46839308">Red, Green, and Blue Queries</a></dt><dt>XcmsQueryWhite, <a class="indexterm" href="#idp46849316">Red, Green, and Blue Queries</a></dt><dt>XcmsRGB, <a class="indexterm" href="#idp42179580">Color Structures</a></dt><dt>XcmsRGBi, <a class="indexterm" href="#idp42181428">Color Structures</a></dt><dt>XcmsScreenInitProc, <a class="indexterm" href="#idp47170588">Creating Additional Function Sets</a></dt><dt>XcmsScreenNumberOfCCC, <a class="indexterm" href="#idp46606700">Color Conversion Context Macros</a></dt><dt>XcmsScreenWhitePointOfCCC, <a class="indexterm" href="#idp46613468">Color Conversion Context Macros</a></dt><dt>XcmsSetCCCOfColormap, <a class="indexterm" href="#idp46567124">Getting and Setting the Color Conversion Context of a Colormap</a></dt><dt>XcmsSetCompressionProc, <a class="indexterm" href="#idp46638988">Modifying Attributes of a Color Conversion Context</a></dt><dt>XcmsSetWhiteAdjustProc, <a class="indexterm" href="#idp46651084">Modifying Attributes of a Color Conversion Context</a></dt><dt>XcmsSetWhitePoint, <a class="indexterm" href="#idp46628564">Modifying Attributes of a Color Conversion Context</a></dt><dt>XcmsStoreColor, <a class="indexterm" href="#idp46429772">Modifying and Querying Colormap Cells</a></dt><dt>XcmsStoreColors, <a class="indexterm" href="#idp46447292">Modifying and Querying Colormap Cells</a></dt><dt>XcmsTekHVC, <a class="indexterm" href="#idp45043172">Color Structures</a></dt><dt>XcmsTekHVCQueryMaxC, <a class="indexterm" href="#idp46983396">TekHVC Queries</a></dt><dt>XcmsTekHVCQueryMaxV, <a class="indexterm" href="#idp46996284">TekHVC Queries</a></dt><dt>XcmsTekHVCQueryMaxVC, <a class="indexterm" href="#idp47010180">TekHVC Queries</a></dt><dt>XcmsTekHVCQueryMaxVSamples, <a class="indexterm" href="#idp47022524">TekHVC Queries</a></dt><dt>XcmsTekHVCQueryMinV, <a class="indexterm" href="#idp47035516">TekHVC Queries</a></dt><dt>XcmsVisualOfCCC, <a class="indexterm" href="#idp46599980">Color Conversion Context Macros</a></dt><dt>XcmsWhiteAdjustProc, <a class="indexterm" href="#idp46757860">Prototype White Point Adjustment Procedure</a></dt><dt>XColor, <a class="indexterm" href="#idp43558660">Color Structures</a></dt><dt>XColormapEvent, <a class="indexterm" href="#idp49072660">Colormap State Change Events</a></dt><dt>XConfigureEvent, <a class="indexterm" href="#idp48941156">ConfigureNotify Events</a></dt><dt>XConfigureRequestEvent, <a class="indexterm" href="#idp49045300">ConfigureRequest Events</a></dt><dt>XConfigureWindow, <a class="indexterm" href="#idp44735940">Configuring Windows</a></dt><dt>XConnectionNumber, <a class="indexterm" href="#idp42534212">Display Macros</a></dt><dt>XContextDependentDrawing, <a class="indexterm" href="#idp51391036">Obtaining Font Set Metrics</a></dt><dt>XContextualDrawing, <a class="indexterm" href="#idp51384516">Obtaining Font Set Metrics</a></dt><dt>XConvertCase, <a class="indexterm" href="#idp49256428">Using Keyboard Utility Functions</a></dt><dt>XConvertSelection, <a class="indexterm" href="#idp45023540">Selections</a></dt><dt>XCopyArea, <a class="indexterm" href="#idp46198828">Copying Areas</a></dt><dt>XCopyColormapAndFree, <a class="indexterm" href="#idp45125892">Creating, Copying, and Destroying Colormaps</a></dt><dt>XCopyGC, <a class="indexterm" href="#idp45248564">Manipulating Graphics Context/State</a></dt><dt>XCopyPlane, <a class="indexterm" href="#idp45296740">Copying Areas</a></dt><dt>XCreateAssocTable, <a class="indexterm" href="#idp50345428">Associating User Data with a Value</a></dt><dt>XCreateBitmapFromData, <a class="indexterm" href="#idp53510940">Manipulating Bitmaps</a></dt><dt>XCreateColormap, <a class="indexterm" href="#idp45105060">Creating, Copying, and Destroying Colormaps</a></dt><dt>XCreateFontCursor, <a class="indexterm" href="#idp43516460">Creating, Recoloring, and Freeing Cursors</a></dt><dt>XCreateFontSet, <a class="indexterm" href="#idp51286740">Creating and Freeing a Font Set</a></dt><dt>XCreateGC, <a class="indexterm" href="#idp45234604">Manipulating Graphics Context/State</a></dt><dt>XCreateGlyphCursor, <a class="indexterm" href="#idp41908796">Creating, Recoloring, and Freeing Cursors</a></dt><dt>XCreateIC, <a class="indexterm" href="#idp51896892">Input Context Functions</a></dt><dt>XCreateImage, <a class="indexterm" href="#idp53362428">Manipulating Images</a></dt><dt>XCreateOC, <a class="indexterm" href="#idp51174172">Output Context Functions</a></dt><dt>XCreatePixmap, <a class="indexterm" href="#idp43456268">Creating and Freeing Pixmaps</a></dt><dt>XCreatePixmapCursor, <a class="indexterm" href="#idp42819972">Creating, Recoloring, and Freeing Cursors</a></dt><dt>XCreatePixmapFromBitmapData, <a class="indexterm" href="#idp53492316">Manipulating Bitmaps</a></dt><dt>XCreateSimpleWindow, <a class="indexterm" href="#idp44611524">Creating Windows</a></dt><dt>XCreateWindow, <a class="indexterm" href="#idp44056084">Creating Windows</a></dt><dt>XCreateWindowEvent, <a class="indexterm" href="#idp48951292">CreateNotify Events</a></dt><dt>XCrossingEvent, <a class="indexterm" href="#idp48759756">Window Entry/Exit Events</a></dt><dt>XDefaultColormap, <a class="indexterm" href="#idp42542764">Display Macros</a></dt><dt>XDefaultColormapOfScreen, <a class="indexterm" href="#idp43751612">Screen Information Macros</a></dt><dt>XDefaultDepth, <a class="indexterm" href="#idp42551124">Display Macros</a></dt><dt>XDefaultDepthOfScreen, <a class="indexterm" href="#idp43756932">Screen Information Macros</a></dt><dt>XDefaultGC, <a class="indexterm" href="#idp42571140">Display Macros</a></dt><dt>XDefaultGCOfScreen, <a class="indexterm" href="#idp43762188">Screen Information Macros</a></dt><dt>XDefaultRootWindow, <a class="indexterm" href="#idp42577564">Display Macros</a></dt><dt>XDefaultScreen, <a class="indexterm" href="#idp42597796">Display Macros</a></dt><dt>XDefaultScreenOfDisplay, <a class="indexterm" href="#idp42583508">Display Macros</a></dt><dt>XDefaultVisual, <a class="indexterm" href="#idp42606620">Display Macros</a></dt><dt>XDefaultVisualOfScreen, <a class="indexterm" href="#idp43767652">Screen Information Macros</a></dt><dt>XDefineCursor, <a class="indexterm" href="#idp44607844">Creating Windows</a>, <a class="indexterm" href="#idp44935052">Changing Window Attributes</a></dt><dt>XDeleteAssoc, <a class="indexterm" href="#idp54359212">Associating User Data with a Value</a></dt><dt>XDeleteContext, <a class="indexterm" href="#idp53552252">Using the Context Manager</a></dt><dt>XDeleteModifiermapEntry, <a class="indexterm" href="#idp50009180">Manipulating the Keyboard Encoding</a></dt><dt>XDeleteProperty, <a class="indexterm" href="#idp44985212">Obtaining and Changing Window Properties</a></dt><dt>XDestroyAssocTable, <a class="indexterm" href="#idp54369764">Associating User Data with a Value</a></dt><dt>XDestroyIC, <a class="indexterm" href="#idp51909756">Input Context Functions</a></dt><dt>XDestroyImage, <a class="indexterm" href="#idp53426956">Manipulating Images</a></dt><dt>XDestroyOC, <a class="indexterm" href="#idp51184436">Output Context Functions</a></dt><dt>XDestroyRegion, <a class="indexterm" href="#idp53180356">Creating, Copying, or Destroying Regions</a></dt><dt>XDestroySubwindows, <a class="indexterm" href="#idp44642484">Destroying Windows</a></dt><dt>XDestroyWindow, <a class="indexterm" href="#idp44633596">Destroying Windows</a></dt><dt>XDestroyWindowEvent, <a class="indexterm" href="#idp48960484">DestroyNotify Events</a></dt><dt>XDirectionalDependentDrawing, <a class="indexterm" href="#idp51377940">Obtaining Font Set Metrics</a></dt><dt>XDisableAccessControl, <a class="indexterm" href="#idp45602068">Changing, Enabling, or Disabling Access Control</a></dt><dt>XDisplayCells, <a class="indexterm" href="#idp42615308">Display Macros</a></dt><dt>XDisplayHeight, <a class="indexterm" href="#idp43707532">Image Format Functions and Macros</a></dt><dt>XDisplayHeightMM, <a class="indexterm" href="#idp43714636">Image Format Functions and Macros</a></dt><dt>XDisplayKeycodes, <a class="indexterm" href="#idp49948764">Manipulating the Keyboard Encoding</a></dt><dt>XDisplayMotionBufferSize, <a class="indexterm" href="#idp48395692">Getting Pointer Motion History</a></dt><dt>XDisplayName, <a class="indexterm" href="#idp48574620">Using the Default Error Handlers</a></dt><dt>XDisplayOfIM, <a class="indexterm" href="#idp51751332">Input Method Functions</a></dt><dt>XDisplayOfOM, <a class="indexterm" href="#idp49398884">Output Method Functions</a></dt><dt>XDisplayOfScreen, <a class="indexterm" href="#idp43785860">Screen Information Macros</a></dt><dt>XDisplayPlanes, <a class="indexterm" href="#idp42623580">Display Macros</a></dt><dt>XDisplayString, <a class="indexterm" href="#idp42629700">Display Macros</a></dt><dt>XDisplayWidth, <a class="indexterm" href="#idp43721732">Image Format Functions and Macros</a></dt><dt>XDisplayWidthMM, <a class="indexterm" href="#idp43728812">Image Format Functions and Macros</a></dt><dt>XDoesBackingStore, <a class="indexterm" href="#idp43773364">Screen Information Macros</a></dt><dt>XDoesSaveUnders, <a class="indexterm" href="#idp43779668">Screen Information Macros</a></dt><dt>xDoSomethingReply, <a class="indexterm" href="#idp53951580">Request Format</a></dt><dt>xDoSomethingReq, <a class="indexterm" href="#idp53940516">Request Format</a></dt><dt>XDrawArc, <a class="indexterm" href="#idp47761724">Drawing Single and Multiple Arcs</a>, <a class="indexterm" href="#idp47763916">Drawing Single and Multiple Arcs</a></dt><dt>XDrawArcs, <a class="indexterm" href="#idp47762604">Drawing Single and Multiple Arcs</a>, <a class="indexterm" href="#idp47780084">Drawing Single and Multiple Arcs</a></dt><dt>XDrawImageString, <a class="indexterm" href="#idp48210556">Drawing Image Text Characters</a>, <a class="indexterm" href="#idp48212532">Drawing Image Text Characters</a></dt><dt>XDrawImageString16, <a class="indexterm" href="#idp48210988">Drawing Image Text Characters</a>, <a class="indexterm" href="#idp48228252">Drawing Image Text Characters</a></dt><dt>XDrawLine, <a class="indexterm" href="#idp45374580">Drawing Single and Multiple Lines</a>, <a class="indexterm" href="#idp45377940">Drawing Single and Multiple Lines</a></dt><dt>XDrawLines, <a class="indexterm" href="#idp45375004">Drawing Single and Multiple Lines</a>, <a class="indexterm" href="#idp45392980">Drawing Single and Multiple Lines</a>, <a class="indexterm" href="#idp53728940">Drawing and Filling Polygons and Curves</a></dt><dt>XDrawPoint, <a class="indexterm" href="#idp45339724">Drawing Single and Multiple Points</a>, <a class="indexterm" href="#idp45341076">Drawing Single and Multiple Points</a></dt><dt>XDrawPoints, <a class="indexterm" href="#idp45339300">Drawing Single and Multiple Points</a>, <a class="indexterm" href="#idp45352964">Drawing Single and Multiple Points</a></dt><dt>XDrawRectangle, <a class="indexterm" href="#idp47729980">Drawing Single and Multiple Rectangles</a>, <a class="indexterm" href="#idp47731564">Drawing Single and Multiple Rectangles</a></dt><dt>XDrawRectangles, <a class="indexterm" href="#idp47730356">Drawing Single and Multiple Rectangles</a>, <a class="indexterm" href="#idp47744852">Drawing Single and Multiple Rectangles</a></dt><dt>XDrawSegments, <a class="indexterm" href="#idp45376564">Drawing Single and Multiple Lines</a>, <a class="indexterm" href="#idp45407308">Drawing Single and Multiple Lines</a>, <a class="indexterm" href="#idp53729796">Drawing and Filling Polygons and Curves</a></dt><dt>XDrawString, <a class="indexterm" href="#idp48175460">Drawing Text Characters</a></dt><dt>XDrawString16, <a class="indexterm" href="#idp48189436">Drawing Text Characters</a></dt><dt>XDrawText, <a class="indexterm" href="#idp48140892">Drawing Complex Text</a></dt><dt>XDrawText16, <a class="indexterm" href="#idp48154420">Drawing Complex Text</a></dt><dt>XEHeadOfExtensionList, <a class="indexterm" href="#idp53869844">Hooks onto Xlib Data Structures</a></dt><dt>XEmptyRegion, <a class="indexterm" href="#idp53245140">Determining if Regions Are Empty or Equal</a></dt><dt>XEnableAccessControl, <a class="indexterm" href="#idp45595356">Changing, Enabling, or Disabling Access Control</a></dt><dt>XEnterWindowEvent, <a class="indexterm" href="#idp48760132">Window Entry/Exit Events</a></dt><dt>XEqualRegion, <a class="indexterm" href="#idp53250332">Determining if Regions Are Empty or Equal</a></dt><dt>XErrorEvent, <a class="indexterm" href="#idp48452588">Using the Default Error Handlers</a></dt><dt>XESetBeforeFlush, <a class="indexterm" href="#idp53848892">Hooks into the Library</a></dt><dt>XESetCloseDisplay, <a class="indexterm" href="#idp52904724">Hooks into the Library</a></dt><dt>XESetCopyGC, <a class="indexterm" href="#idp53633668">Hooks into the Library</a></dt><dt>XESetCreateFont, <a class="indexterm" href="#idp53657052">Hooks into the Library</a></dt><dt>XESetCreateGC, <a class="indexterm" href="#idp53621652">Hooks into the Library</a></dt><dt>XESetError, <a class="indexterm" href="#idp53796020">Hooks into the Library</a></dt><dt>XESetErrorString, <a class="indexterm" href="#idp53811420">Hooks into the Library</a></dt><dt>XESetEventToWire, <a class="indexterm" href="#idp53765908">Hooks into the Library</a></dt><dt>XESetFlushGC, <a class="indexterm" href="#idp53839876">Hooks into the Library</a></dt><dt>XESetFreeFont, <a class="indexterm" href="#idp53671588">Hooks into the Library</a></dt><dt>XESetPrintErrorValues, <a class="indexterm" href="#idp53825676">Hooks into the Library</a></dt><dt>XESetWireToError, <a class="indexterm" href="#idp53780724">Hooks into the Library</a></dt><dt>XESetWireToEvent, <a class="indexterm" href="#idp53742164">Hooks into the Library</a></dt><dt>XEvent, <a class="indexterm" href="#idp45609652">Event Structures</a></dt><dt>XEventMaskOfScreen, <a class="indexterm" href="#idp43796396">Screen Information Macros</a></dt><dt>XEventsQueued, <a class="indexterm" href="#idp47527700">Event Queue Management</a></dt><dt>XExposeEvent, <a class="indexterm" href="#idp48890572">Expose Events</a></dt><dt>XExtCodes, <a class="indexterm" href="#idp49591668">Hooking into Xlib</a></dt><dt>XExtData, <a class="indexterm" href="#idp53865716">Hooks onto Xlib Data Structures</a></dt><dt>XExtendedMaxRequestSize, <a class="indexterm" href="#idp42637260">Display Macros</a></dt><dt>XExtentsOfFontSet, <a class="indexterm" href="#idp51405972">Obtaining Font Set Metrics</a></dt><dt>XFetchBuffer, <a class="indexterm" href="#idp53307452">Using Cut Buffers</a></dt><dt>XFetchBytes, <a class="indexterm" href="#idp53300172">Using Cut Buffers</a></dt><dt>XFetchName, <a class="indexterm" href="#idp50578860">Setting and Reading the WM_NAME Property</a></dt><dt>XFillArc, <a class="indexterm" href="#idp47864740">Filling Single and Multiple Arcs</a>, <a class="indexterm" href="#idp47866612">Filling Single and Multiple Arcs</a></dt><dt>XFillArcs, <a class="indexterm" href="#idp47882780">Filling Single and Multiple Arcs</a></dt><dt>XFillPolygon, <a class="indexterm" href="#idp47841420">Filling a Single Polygon</a></dt><dt>XFillRectangle, <a class="indexterm" href="#idp47806812">Filling Single and Multiple Rectangles</a>, <a class="indexterm" href="#idp47809020">Filling Single and Multiple Rectangles</a></dt><dt>XFillRectangles, <a class="indexterm" href="#idp47807692">Filling Single and Multiple Rectangles</a>, <a class="indexterm" href="#idp47822356">Filling Single and Multiple Rectangles</a></dt><dt>XFilterEvent, <a class="indexterm" href="#idp52436100">Event Filtering</a></dt><dt>XFindContext, <a class="indexterm" href="#idp53542132">Using the Context Manager</a></dt><dt>XFindOnExtensionList, <a class="indexterm" href="#idp53882324">Hooks onto Xlib Data Structures</a></dt><dt>XFlush, <a class="indexterm" href="#idp47613420">Handling the Output Buffer</a></dt><dt>XFlushGC, <a class="indexterm" href="#idp45859012">Manipulating Graphics Context/State</a></dt><dt>XFocusChangeEvent, <a class="indexterm" href="#idp48810460">Input Focus Events</a></dt><dt>XFocusInEvent, <a class="indexterm" href="#idp48810836">Input Focus Events</a></dt><dt>XFocusOutEvent, <a class="indexterm" href="#idp48811212">Input Focus Events</a></dt><dt>XFontProp, <a class="indexterm" href="#idp47907540">Font Metrics</a></dt><dt>XFontSetExtents, <a class="indexterm" href="#idp51397900">Obtaining Font Set Metrics</a></dt><dt>XFontsOfFontSet, <a class="indexterm" href="#idp51329772">Creating and Freeing a Font Set</a></dt><dt>XFontStruct, <a class="indexterm" href="#idp47910532">Font Metrics</a></dt><dt>XForceScreenSaver, <a class="indexterm" href="#idp45530276">Controlling the Screen Saver</a></dt><dt>XFree, <a class="indexterm" href="#idp43848604">Freeing Client-Created Data</a></dt><dt>XFreeColormap, <a class="indexterm" href="#idp45137860">Creating, Copying, and Destroying Colormaps</a></dt><dt>XFreeColors, <a class="indexterm" href="#idp46375156">Allocating and Freeing Color Cells</a></dt><dt>XFreeCursor, <a class="indexterm" href="#idp44401564">Creating, Recoloring, and Freeing Cursors</a></dt><dt>XFreeExtensionList, <a class="indexterm" href="#idp49587892">Basic Protocol Support Routines</a></dt><dt>XFreeFont, <a class="indexterm" href="#idp47969508">Loading and Freeing Fonts</a></dt><dt>XFreeFontInfo, <a class="indexterm" href="#idp48031060">Obtaining and Freeing Font Names and Information</a></dt><dt>XFreeFontNames, <a class="indexterm" href="#idp48010956">Obtaining and Freeing Font Names and Information</a></dt><dt>XFreeFontPath, <a class="indexterm" href="#idp44266124">Setting and Retrieving the Font Search Path</a></dt><dt>XFreeFontSet, <a class="indexterm" href="#idp51363556">Creating and Freeing a Font Set</a></dt><dt>XFreeGC, <a class="indexterm" href="#idp45844660">Manipulating Graphics Context/State</a></dt><dt>XFreeModifiermap, <a class="indexterm" href="#idp50017932">Manipulating the Keyboard Encoding</a></dt><dt>XFreePixmap, <a class="indexterm" href="#idp41419412">Creating and Freeing Pixmaps</a></dt><dt>XFreeStringList, <a class="indexterm" href="#idp50954068">Converting String Lists</a></dt><dt>XGContextFromGC, <a class="indexterm" href="#idp45853460">Manipulating Graphics Context/State</a></dt><dt>XGeometry, <a class="indexterm" href="#idp50416700">Parsing Window Geometry</a></dt><dt>XGetAtomName, <a class="indexterm" href="#idp44153124">Properties and Atoms</a></dt><dt>XGetAtomNames, <a class="indexterm" href="#idp44163188">Properties and Atoms</a></dt><dt>XGetClassHint, <a class="indexterm" href="#idp50786820">Setting and Reading the WM_CLASS Property</a></dt><dt>XGetCommand, <a class="indexterm" href="#idp52611828">Setting and Reading the WM_COMMAND Property</a></dt><dt>XGetDefault, <a class="indexterm" href="#idp53708348">Getting the X Environment Defaults</a></dt><dt>XGetErrorDatabaseText, <a class="indexterm" href="#idp48555516">Using the Default Error Handlers</a></dt><dt>XGetErrorText, <a class="indexterm" href="#idp48543420">Using the Default Error Handlers</a></dt><dt>XGetFontPath, <a class="indexterm" href="#idp44257324">Setting and Retrieving the Font Search Path</a></dt><dt>XGetFontProperty, <a class="indexterm" href="#idp47977380">Loading and Freeing Fonts</a></dt><dt>XGetGCValues, <a class="indexterm" href="#idp45276788">Manipulating Graphics Context/State</a></dt><dt>XGetGeometry, <a class="indexterm" href="#idp42813700">Obtaining Window Information</a></dt><dt>XGetIconName, <a class="indexterm" href="#idp50627060">Setting and Reading the WM_ICON_NAME Property</a></dt><dt>XGetIconSizes, <a class="indexterm" href="#idp52515156">Setting and Reading the WM_ICON_SIZE Property</a></dt><dt>XGetICValues, <a class="indexterm" href="#idp51962508">Input Context Functions</a></dt><dt>XGetImage, <a class="indexterm" href="#idp48296212">Transferring Images between Client and Server</a></dt><dt>XGetIMValues, <a class="indexterm" href="#idp51741948">Input Method Functions</a></dt><dt>XGetInputFocus, <a class="indexterm" href="#idp49808772">Controlling Input Focus</a></dt><dt>XGetKeyboardControl, <a class="indexterm" href="#idp49840668">Manipulating the Keyboard and Pointer Settings</a>, <a class="indexterm" href="#idp49847068">Manipulating the Keyboard and Pointer Settings</a></dt><dt>XGetKeyboardMapping, <a class="indexterm" href="#idp49956756">Manipulating the Keyboard Encoding</a></dt><dt>XGetModifierMapping, <a class="indexterm" href="#idp50036852">Manipulating the Keyboard Encoding</a></dt><dt>XGetMotionEvents, <a class="indexterm" href="#idp48401820">Getting Pointer Motion History</a></dt><dt>XGetNormalHints, <a class="indexterm" href="#idp50386636">Setting and Getting Window Sizing Hints</a></dt><dt>XGetOCValues, <a class="indexterm" href="#idp51206412">Output Context Functions</a></dt><dt>XGetOMValues, <a class="indexterm" href="#idp49391972">Output Method Functions</a></dt><dt>XGetPixel, <a class="indexterm" href="#idp53389252">Manipulating Images</a></dt><dt>XGetPointerControl, <a class="indexterm" href="#idp49913796">Manipulating the Keyboard and Pointer Settings</a></dt><dt>XGetPointerMapping, <a class="indexterm" href="#idp49890756">Manipulating the Keyboard and Pointer Settings</a></dt><dt>XGetRGBColormaps, <a class="indexterm" href="#idp52703900">Setting and Obtaining Standard Colormaps</a></dt><dt>XGetScreenSaver, <a class="indexterm" href="#idp45789340">Controlling the Screen Saver</a></dt><dt>XGetSelectionOwner, <a class="indexterm" href="#idp45014916">Selections</a></dt><dt>XGetSizeHints, <a class="indexterm" href="#idp52724228">Setting and Getting Window Sizing Hints</a></dt><dt>XGetStandardColormap, <a class="indexterm" href="#idp52733756">Getting and Setting an XStandardColormap Structure</a></dt><dt>XGetSubImage, <a class="indexterm" href="#idp48321980">Transferring Images between Client and Server</a></dt><dt>XGetTextProperty, <a class="indexterm" href="#idp50980436">Setting and Reading Text Properties</a></dt><dt>XGetTransientForHint, <a class="indexterm" href="#idp50812428">Setting and Reading the WM_TRANSIENT_FOR Property</a></dt><dt>XGetVisualInfo, <a class="indexterm" href="#idp53330428">Determining the Appropriate Visual Type</a></dt><dt>XGetWindowAttributes, <a class="indexterm" href="#idp40672940">Obtaining Window Information</a></dt><dt>XGetWindowProperty, <a class="indexterm" href="#idp44181324">Obtaining and Changing Window Properties</a></dt><dt>XGetWMClientMachine, <a class="indexterm" href="#idp52634924">Setting and Reading the WM_CLIENT_MACHINE Property</a></dt><dt>XGetWMColormapWindows, <a class="indexterm" href="#idp50873100">Setting and Reading the WM_COLORMAP_WINDOWS Property</a></dt><dt>XGetWMHints, <a class="indexterm" href="#idp50668876">Setting and Reading the WM_HINTS Property</a></dt><dt>XGetWMIconName, <a class="indexterm" href="#idp50604308">Setting and Reading the WM_ICON_NAME Property</a></dt><dt>XGetWMName, <a class="indexterm" href="#idp51009124">Setting and Reading the WM_NAME Property</a></dt><dt>XGetWMNormalHints, <a class="indexterm" href="#idp50707268">Setting and Reading the WM_NORMAL_HINTS Property</a></dt><dt>XGetWMProtocols, <a class="indexterm" href="#idp50841220">Setting and Reading the WM_PROTOCOLS Property</a></dt><dt>XGetWMSizeHints, <a class="indexterm" href="#idp50740372">Setting and Reading the WM_NORMAL_HINTS Property</a></dt><dt>XGetZoomHints, <a class="indexterm" href="#idp50077572">Setting and Getting Window Sizing Hints</a></dt><dt>XGrabButton, <a class="indexterm" href="#idp49155476">Pointer Grabbing</a></dt><dt>XGrabKey, <a class="indexterm" href="#idp49696460">Keyboard Grabbing</a></dt><dt>XGrabKeyboard, <a class="indexterm" href="#idp49209180">Keyboard Grabbing</a></dt><dt>XGrabPointer, <a class="indexterm" href="#idp43503444">Pointer Grabbing</a></dt><dt>XGrabServer, <a class="indexterm" href="#idp45723396">Grabbing the Server</a></dt><dt>XGraphicsExposeEvent, <a class="indexterm" href="#idp48902572">GraphicsExpose and NoExpose Events</a></dt><dt>XGravityEvent, <a class="indexterm" href="#idp48969012">GravityNotify Events</a></dt><dt>XHeightMMOfScreen, <a class="indexterm" href="#idp43817884">Screen Information Macros</a></dt><dt>XHeightOfScreen, <a class="indexterm" href="#idp43807156">Screen Information Macros</a></dt><dt>XHostAddress, <a class="indexterm" href="#idp45691924">Adding, Getting, or Removing Hosts</a></dt><dt>XIconifyWindow, <a class="indexterm" href="#idp48686692">Manipulating Top-Level Windows</a></dt><dt>XIconSize, <a class="indexterm" href="#idp50888604">Setting and Reading the WM_ICON_SIZE Property</a>, <a class="indexterm" href="#idp50897180">Setting and Reading the WM_ICON_SIZE Property</a></dt><dt>XID, <a class="indexterm" href="#idp41856596">Generic Values and Types</a></dt><dt>XIfEvent, <a class="indexterm" href="#idp47215316">Selecting Events Using a Predicate Procedure</a></dt><dt>XIMAbsolutePosition, <a class="indexterm" href="#idp52394756">Preedit Caret Callback</a></dt><dt>XImage, <a class="indexterm" href="#idp48257492">Transferring Images between Client and Server</a></dt><dt>XImageByteOrder, <a class="indexterm" href="#idp43683780">Image Format Functions and Macros</a></dt><dt>XIMBackwardChar, <a class="indexterm" href="#idp52378868">Preedit Caret Callback</a></dt><dt>XIMBackwardWord, <a class="indexterm" href="#idp52379732">Preedit Caret Callback</a></dt><dt>XIMCallback, <a class="indexterm" href="#idp52235676">Preedit and Status Callbacks</a></dt><dt>XIMCaretDirection, <a class="indexterm" href="#idp52375716">Preedit Caret Callback</a></dt><dt>XIMCaretDown, <a class="indexterm" href="#idp52380588">Preedit Caret Callback</a></dt><dt>XIMCaretStyle, <a class="indexterm" href="#idp52372860">Preedit Caret Callback</a></dt><dt>XIMCaretUp, <a class="indexterm" href="#idp52380164">Preedit Caret Callback</a></dt><dt>XIMDontChange, <a class="indexterm" href="#idp52395188">Preedit Caret Callback</a></dt><dt>XIMForwardChar, <a class="indexterm" href="#idp52378436">Preedit Caret Callback</a></dt><dt>XIMForwardWord, <a class="indexterm" href="#idp52379300">Preedit Caret Callback</a></dt><dt>XIMHighlight, <a class="indexterm" href="#idp52349884">Preedit Draw Callback</a></dt><dt>XIMInitialState, <a class="indexterm" href="#idp52122148">Reset State</a></dt><dt>XIMLineEnd, <a class="indexterm" href="#idp52394332">Preedit Caret Callback</a></dt><dt>XIMLineStart, <a class="indexterm" href="#idp52393900">Preedit Caret Callback</a></dt><dt>XIMNextLine, <a class="indexterm" href="#idp52393044">Preedit Caret Callback</a></dt><dt>XIMOfIC, <a class="indexterm" href="#idp51942420">Input Context Functions</a></dt><dt>XIMPreeditArea, <a class="indexterm" href="#idp51827748">Query Input Style</a>, <a class="indexterm" href="#idp51835404">Query Input Style</a></dt><dt>XIMPreeditCallbacks, <a class="indexterm" href="#idp51828180">Query Input Style</a>, <a class="indexterm" href="#idp51836268">Query Input Style</a></dt><dt>XIMPreeditCaretCallbackStruct, <a class="indexterm" href="#idp52369580">Preedit Caret Callback</a></dt><dt>XIMPreeditDisable, <a class="indexterm" href="#idp52196820">Preedit State</a></dt><dt>XIMPreeditDrawCallbackStruct, <a class="indexterm" href="#idp52325964">Preedit Draw Callback</a></dt><dt>XIMPreeditEnable, <a class="indexterm" href="#idp52196388">Preedit State</a></dt><dt>XIMPreeditNone, <a class="indexterm" href="#idp51829476">Query Input Style</a>, <a class="indexterm" href="#idp51837132">Query Input Style</a></dt><dt>XIMPreeditNothing, <a class="indexterm" href="#idp51829044">Query Input Style</a>, <a class="indexterm" href="#idp51836700">Query Input Style</a></dt><dt>XIMPreeditPosition, <a class="indexterm" href="#idp51828612">Query Input Style</a>, <a class="indexterm" href="#idp51835836">Query Input Style</a></dt><dt>XIMPreeditStateNotifyCallbackStruct, <a class="indexterm" href="#idp52214924">Preedit State Notify Callback</a></dt><dt>XIMPreeditUnknown, <a class="indexterm" href="#idp52195956">Preedit State</a></dt><dt>XIMPreviousLine, <a class="indexterm" href="#idp52393468">Preedit Caret Callback</a></dt><dt>XIMPrimary, <a class="indexterm" href="#idp52350316">Preedit Draw Callback</a></dt><dt>XIMProc, <a class="indexterm" href="#idp52235252">Preedit and Status Callbacks</a></dt><dt>XIMReverse, <a class="indexterm" href="#idp52349028">Preedit Draw Callback</a></dt><dt>XIMSecondary, <a class="indexterm" href="#idp52350740">Preedit Draw Callback</a></dt><dt>XIMStatusArea, <a class="indexterm" href="#idp51829908">Query Input Style</a>, <a class="indexterm" href="#idp51847268">Query Input Style</a></dt><dt>XIMStatusCallbacks, <a class="indexterm" href="#idp51830340">Query Input Style</a>, <a class="indexterm" href="#idp51847700">Query Input Style</a></dt><dt>XIMStatusDataType, <a class="indexterm" href="#idp52425420">Status Callbacks</a></dt><dt>XIMStatusDrawCallbackStruct, <a class="indexterm" href="#idp52425852">Status Callbacks</a></dt><dt>XIMStatusNone, <a class="indexterm" href="#idp51831204">Query Input Style</a>, <a class="indexterm" href="#idp51848564">Query Input Style</a></dt><dt>XIMStatusNothing, <a class="indexterm" href="#idp51830772">Query Input Style</a>, <a class="indexterm" href="#idp51848132">Query Input Style</a></dt><dt>XIMStringConversionCallbackStruct, <a class="indexterm" href="#idp52284356">String Conversion Callback</a></dt><dt>XIMStyle, <a class="indexterm" href="#idp51827324">Query Input Style</a></dt><dt>XIMStyles, <a class="indexterm" href="#idp51831636">Query Input Style</a></dt><dt>XIMTertiary, <a class="indexterm" href="#idp52351172">Preedit Draw Callback</a></dt><dt>XIMText, <a class="indexterm" href="#idp52336756">Preedit Draw Callback</a></dt><dt>XIMUnderline, <a class="indexterm" href="#idp52349452">Preedit Draw Callback</a></dt><dt>XIMVisibleToBackward, <a class="indexterm" href="#idp52352028">Preedit Draw Callback</a></dt><dt>XIMVisibleToCenter, <a class="indexterm" href="#idp52352468">Preedit Draw Callback</a></dt><dt>XIMVisibleToForward, <a class="indexterm" href="#idp52351596">Preedit Draw Callback</a></dt><dt>XInitExtension, <a class="indexterm" href="#idp49593652">Hooking into Xlib</a></dt><dt>XInitImage, <a class="indexterm" href="#idp48261452">Transferring Images between Client and Server</a></dt><dt>XInitThreads, <a class="indexterm" href="#idp43892412">Using Xlib with Threads</a></dt><dt>XINPreserveState, <a class="indexterm" href="#idp52122580">Reset State</a></dt><dt>XInsertModifiermapEntry, <a class="indexterm" href="#idp50000364">Manipulating the Keyboard Encoding</a></dt><dt>XInstallColormap, <a class="indexterm" href="#idp44286804">Managing Installed Colormaps</a></dt><dt>XInternalConnectionNumbers, <a class="indexterm" href="#idp43940276">Using Internal Connections</a></dt><dt>XInternAtom, <a class="indexterm" href="#idp44124180">Properties and Atoms</a></dt><dt>XInternAtoms, <a class="indexterm" href="#idp44136940">Properties and Atoms</a></dt><dt>XIntersectRegion, <a class="indexterm" href="#idp53207932">Computing with Regions</a></dt><dt>XKeyboardState, <a class="indexterm" href="#idp49847444">Manipulating the Keyboard and Pointer Settings</a></dt><dt>XKeycodeToKeysym, <a class="indexterm" href="#idp45628220">Using Keyboard Utility Functions</a></dt><dt>XKeymapEvent, <a class="indexterm" href="#idp48879756">Key Map State Notification Events</a></dt><dt>XKeysymToKeycode, <a class="indexterm" href="#idp50459388">Using Keyboard Utility Functions</a></dt><dt>XKeysymToString, <a class="indexterm" href="#idp50178556">Using Keyboard Utility Functions</a></dt><dt>XKillClient, <a class="indexterm" href="#idp45736260">Killing Clients</a></dt><dt>XLastKnownRequestProcessed, <a class="indexterm" href="#idp43620572">Display Macros</a></dt><dt>XLeaveWindowEvent, <a class="indexterm" href="#idp48760508">Window Entry/Exit Events</a></dt><dt>XLFD, <a class="indexterm" href="#idp54199988">Glossary</a></dt><dt>XlibSpecificationRelease, <a class="indexterm" href="#idp42302364">Standard Header Files</a></dt><dt>XListDepths, <a class="indexterm" href="#idp42552676">Display Macros</a></dt><dt>XListExtensions, <a class="indexterm" href="#idp50446212">Basic Protocol Support Routines</a></dt><dt>XListFonts, <a class="indexterm" href="#idp47999164">Obtaining and Freeing Font Names and Information</a></dt><dt>XListFontsWithInfo, <a class="indexterm" href="#idp48016740">Obtaining and Freeing Font Names and Information</a></dt><dt>XListHosts, <a class="indexterm" href="#idp45644380">Adding, Getting, or Removing Hosts</a></dt><dt>XListInstalledColormaps, <a class="indexterm" href="#idp44101348">Managing Installed Colormaps</a></dt><dt>XListPixmapFormats, <a class="indexterm" href="#idp43671476">Image Format Functions and Macros</a></dt><dt>XListProperties, <a class="indexterm" href="#idp44220388">Obtaining and Changing Window Properties</a></dt><dt>XLoadFont, <a class="indexterm" href="#idp47940468">Loading and Freeing Fonts</a></dt><dt>XLoadQueryFont, <a class="indexterm" href="#idp47959980">Loading and Freeing Fonts</a></dt><dt>XLocaleOfFontSet, <a class="indexterm" href="#idp51354932">Creating and Freeing a Font Set</a></dt><dt>XLocaleOfIM, <a class="indexterm" href="#idp51757340">Input Method Functions</a></dt><dt>XLocaleOfOM, <a class="indexterm" href="#idp49404828">Output Method Functions</a></dt><dt>XLockDisplay, <a class="indexterm" href="#idp43895892">Using Xlib with Threads</a></dt><dt>XLookUpAssoc, <a class="indexterm" href="#idp54348540">Associating User Data with a Value</a></dt><dt>XLookupColor, <a class="indexterm" href="#idp45151724">Mapping Color Names to Values</a></dt><dt>XLookupKeysym, <a class="indexterm" href="#idp51150324">Using Keyboard Utility Functions</a></dt><dt>XLookupString, <a class="indexterm" href="#idp50215236">Using Latin-1 Keyboard Event Functions</a></dt><dt>XLowerWindow, <a class="indexterm" href="#idp44810188">Changing Window Stacking Order</a></dt><dt>XMakeAssoc, <a class="indexterm" href="#idp50352628">Associating User Data with a Value</a></dt><dt>XMapEvent, <a class="indexterm" href="#idp48978060">MapNotify Events</a></dt><dt>XMappingEvent, <a class="indexterm" href="#idp48987484">MappingNotify Events</a></dt><dt>XMapRaised, <a class="indexterm" href="#idp44672596">Mapping Windows</a></dt><dt>XMapRequestEvent, <a class="indexterm" href="#idp49055908">MapRequest Events</a></dt><dt>XMapSubwindows, <a class="indexterm" href="#idp44680948">Mapping Windows</a>, <a class="indexterm" href="#idp44686500">Mapping Windows</a></dt><dt>XMapWindow, <a class="indexterm" href="#idp42677636">Window Attributes</a>, <a class="indexterm" href="#idp44658988">Mapping Windows</a>, <a class="indexterm" href="#idp44668348">Mapping Windows</a></dt><dt>XMaskEvent, <a class="indexterm" href="#idp47413476">Selecting Events Using a Window or Event Mask</a></dt><dt>XMatchVisualInfo, <a class="indexterm" href="#idp53341300">Determining the Appropriate Visual Type</a></dt><dt>XMaxCmapsOfScreen, <a class="indexterm" href="#idp43823252">Screen Information Macros</a></dt><dt>XMaxRequestSize, <a class="indexterm" href="#idp43612572">Display Macros</a></dt><dt>XmbDrawImageString, <a class="indexterm" href="#idp51554452">Drawing Text Using Font Sets</a></dt><dt>XmbDrawString, <a class="indexterm" href="#idp51527644">Drawing Text Using Font Sets</a></dt><dt>XmbDrawText, <a class="indexterm" href="#idp51500564">Drawing Text Using Font Sets</a></dt><dt>XmbLookupString, <a class="indexterm" href="#idp52448940">Getting Keyboard Input</a></dt><dt>XmbResetIC, <a class="indexterm" href="#idp51929828">Input Context Functions</a></dt><dt>XmbSetWMProperties, <a class="indexterm" href="#idp52530940">Using Window Manager Convenience Functions</a></dt><dt>XmbTextEscapement, <a class="indexterm" href="#idp51414140">Obtaining Font Set Metrics</a></dt><dt>XmbTextExtents, <a class="indexterm" href="#idp51430020">Obtaining Font Set Metrics</a></dt><dt>XmbTextItem, <a class="indexterm" href="#idp51495308">Drawing Text Using Font Sets</a></dt><dt>XmbTextListToTextProperty, <a class="indexterm" href="#idp50537524">Converting String Lists</a></dt><dt>XmbTextPerCharExtents, <a class="indexterm" href="#idp51454988">Obtaining Font Set Metrics</a></dt><dt>XmbTextPropertyToTextList, <a class="indexterm" href="#idp50562516">Converting String Lists</a></dt><dt>XMinCmapsOfScreen, <a class="indexterm" href="#idp43829004">Screen Information Macros</a></dt><dt>XModifierKeymap, <a class="indexterm" href="#idp49992468">Manipulating the Keyboard Encoding</a></dt><dt>XMoveResizeWindow, <a class="indexterm" href="#idp44774732">Configuring Windows</a></dt><dt>XMoveWindow, <a class="indexterm" href="#idp44749516">Configuring Windows</a></dt><dt>XNArea, <a class="indexterm" href="#idp52156348">Area</a></dt><dt>XNAreaNeeded, <a class="indexterm" href="#idp52163348">Area Needed</a></dt><dt>XNBackground, <a class="indexterm" href="#idp52179364">Foreground and Background</a></dt><dt>XNClientWindow, <a class="indexterm" href="#idp52078356">Client Window</a></dt><dt>XNColormap, <a class="indexterm" href="#idp52173468">Colormap</a></dt><dt>XNCursor, <a class="indexterm" href="#idp52191300">Cursor</a></dt><dt>XNewModifiermap, <a class="indexterm" href="#idp49994924">Manipulating the Keyboard Encoding</a></dt><dt>XNextEvent, <a class="indexterm" href="#idp47549940">Handling the Output Buffer</a>, <a class="indexterm" href="#idp45452628">Returning the Next Event</a></dt><dt>XNextRequest, <a class="indexterm" href="#idp43625892">Display Macros</a></dt><dt>XNFilterEvents, <a class="indexterm" href="#idp52097660">Filter Events</a></dt><dt>XNFocusWindow, <a class="indexterm" href="#idp52083356">Focus Window</a></dt><dt>XNFontSet, <a class="indexterm" href="#idp52185732">Font Set</a></dt><dt>XNForeground, <a class="indexterm" href="#idp52178932">Foreground and Background</a></dt><dt>XNGeometryCallback, <a class="indexterm" href="#idp52093772">Geometry Callback</a></dt><dt>XNoExposeEvent, <a class="indexterm" href="#idp48904740">GraphicsExpose and NoExpose Events</a></dt><dt>XNoOp, <a class="indexterm" href="#idp43842692">Generating a NoOperation Protocol Request</a></dt><dt>XNPreeditAttributes, <a class="indexterm" href="#idp52152476">Preedit and Status Attributes</a></dt><dt>XNPreeditCaretCallback, <a class="indexterm" href="#idp52221764">Preedit and Status Callbacks</a></dt><dt>XNPreeditDoneCallback, <a class="indexterm" href="#idp52220884">Preedit and Status Callbacks</a></dt><dt>XNPreeditDrawCallback, <a class="indexterm" href="#idp52221324">Preedit and Status Callbacks</a></dt><dt>XNPreeditStartCallback, <a class="indexterm" href="#idp52220444">Preedit and Status Callbacks</a></dt><dt>XNResourceClass, <a class="indexterm" href="#idp52090316">Resource Name and Class</a></dt><dt>XNResourceName, <a class="indexterm" href="#idp52089884">Resource Name and Class</a></dt><dt>XNSpotLocation, <a class="indexterm" href="#idp52168220">Spot Location</a></dt><dt>XNStatusAttributes, <a class="indexterm" href="#idp52152908">Preedit and Status Attributes</a></dt><dt>XNStatusDoneCallback, <a class="indexterm" href="#idp52228980">Preedit and Status Callbacks</a></dt><dt>XNStatusDrawCallback, <a class="indexterm" href="#idp52229420">Preedit and Status Callbacks</a></dt><dt>XNStatusStartCallback, <a class="indexterm" href="#idp52228540">Preedit and Status Callbacks</a></dt><dt>XNStdColormap, <a class="indexterm" href="#idp52175084">Colormap</a></dt><dt>XOffsetRegion, <a class="indexterm" href="#idp53185660">Moving or Shrinking Regions</a></dt><dt>XOMCharSetList, <a class="indexterm" href="#idp49426836">Required Char Set</a></dt><dt>XOMOfOC, <a class="indexterm" href="#idp51189524">Output Context Functions</a></dt><dt>XOpenDisplay, <a class="indexterm" href="#idp42015420">Opening the Display</a></dt><dt>XOpenIM, <a class="indexterm" href="#idp51711140">Input Method Functions</a></dt><dt>XOpenOM, <a class="indexterm" href="#idp49361788">Output Method Functions</a></dt><dt>XParseColor, <a class="indexterm" href="#idp46219276">Mapping Color Names to Values</a></dt><dt>XParseGeometry, <a class="indexterm" href="#idp50257036">Parsing the Window Geometry</a></dt><dt>XPeekEvent, <a class="indexterm" href="#idp45460940">Returning the Next Event</a></dt><dt>XPeekIfEvent, <a class="indexterm" href="#idp47472596">Selecting Events Using a Predicate Procedure</a></dt><dt>XPending, <a class="indexterm" href="#idp47549516">Handling the Output Buffer</a>, <a class="indexterm" href="#idp45441508">Event Queue Management</a></dt><dt>Xpermalloc, <a class="indexterm" href="#idp50251044">Allocating Permanent Storage</a></dt><dt>XPlanesOfScreen, <a class="indexterm" href="#idp43834756">Screen Information Macros</a></dt><dt>XPoint, <a class="indexterm" href="#idp45330484">Drawing Points, Lines, Rectangles, and Arcs</a></dt><dt>XPointer, <a class="indexterm" href="#idp41857676">Generic Values and Types</a></dt><dt>XPointInRegion, <a class="indexterm" href="#idp53257884">Locating a Point or a Rectangle in a Region</a></dt><dt>XPolygonRegion, <a class="indexterm" href="#idp53163044">Creating, Copying, or Destroying Regions</a></dt><dt>XProcessInternalConnection, <a class="indexterm" href="#idp43932564">Using Internal Connections</a></dt><dt>XPropertyEvent, <a class="indexterm" href="#idp49091492">PropertyNotify Events</a></dt><dt>XProtocolRevision, <a class="indexterm" href="#idp43636404">Display Macros</a></dt><dt>XProtocolVersion, <a class="indexterm" href="#idp43631172">Display Macros</a></dt><dt>XPutBackEvent, <a class="indexterm" href="#idp48359516">Putting an Event Back into the Queue</a></dt><dt>XPutImage, <a class="indexterm" href="#idp48269572">Transferring Images between Client and Server</a></dt><dt>XPutPixel, <a class="indexterm" href="#idp53397820">Manipulating Images</a></dt><dt>XQLength, <a class="indexterm" href="#idp43641596">Display Macros</a></dt><dt>XQueryBestCursor, <a class="indexterm" href="#idp42654220">Creating, Recoloring, and Freeing Cursors</a>, <a class="indexterm" href="#idp40447348">Creating, Recoloring, and Freeing Cursors</a></dt><dt>XQueryBestSize, <a class="indexterm" href="#idp45987676">Setting the Fill Tile and Stipple</a></dt><dt>XQueryBestStipple, <a class="indexterm" href="#idp46025308">Setting the Fill Tile and Stipple</a></dt><dt>XQueryBestTile, <a class="indexterm" href="#idp46008844">Setting the Fill Tile and Stipple</a></dt><dt>XQueryColor, <a class="indexterm" href="#idp46489988">Modifying and Querying Colormap Cells</a></dt><dt>XQueryColors, <a class="indexterm" href="#idp46502876">Modifying and Querying Colormap Cells</a></dt><dt>XQueryExtension, <a class="indexterm" href="#idp43324092">Basic Protocol Support Routines</a></dt><dt>XQueryFont, <a class="indexterm" href="#idp47950436">Loading and Freeing Fonts</a></dt><dt>XQueryKeymap, <a class="indexterm" href="#idp49871804">Manipulating the Keyboard and Pointer Settings</a></dt><dt>XQueryPointer, <a class="indexterm" href="#idp44507084">Translating Screen Coordinates</a></dt><dt>XQueryTextExtents, <a class="indexterm" href="#idp48091772">Querying Character String Sizes</a></dt><dt>XQueryTextExtents16, <a class="indexterm" href="#idp48107452">Querying Character String Sizes</a></dt><dt>XQueryTree, <a class="indexterm" href="#idp41664652">Obtaining Window Information</a></dt><dt>XRaiseWindow, <a class="indexterm" href="#idp44801020">Changing Window Stacking Order</a></dt><dt>XReadBitmapFile, <a class="indexterm" href="#idp53440540">Manipulating Bitmaps</a></dt><dt>XReadBitmapFileData, <a class="indexterm" href="#idp53461468">Manipulating Bitmaps</a></dt><dt>XRebindKeysym, <a class="indexterm" href="#idp50234060">Using Latin-1 Keyboard Event Functions</a></dt><dt>XRecolorCursor, <a class="indexterm" href="#idp44585348">Creating, Recoloring, and Freeing Cursors</a></dt><dt>XReconfigureWMWindow, <a class="indexterm" href="#idp50514228">Manipulating Top-Level Windows</a></dt><dt>XRectangle, <a class="indexterm" href="#idp45332476">Drawing Points, Lines, Rectangles, and Arcs</a></dt><dt>XRectInRegion, <a class="indexterm" href="#idp53266052">Locating a Point or a Rectangle in a Region</a></dt><dt>XRefreshKeyboardMapping, <a class="indexterm" href="#idp49249868">Using Keyboard Utility Functions</a></dt><dt>XRegisterIMInstantiateCallback, <a class="indexterm" href="#idp51763332">Input Method Functions</a></dt><dt>XRemoveConnectionWatch, <a class="indexterm" href="#idp43924076">Using Internal Connections</a></dt><dt>XRemoveFromSaveSet, <a class="indexterm" href="#idp43493884">Controlling the Lifetime of a Window</a></dt><dt>XRemoveHost, <a class="indexterm" href="#idp45655028">Adding, Getting, or Removing Hosts</a></dt><dt>XRemoveHosts, <a class="indexterm" href="#idp45664404">Adding, Getting, or Removing Hosts</a></dt><dt>XReparentEvent, <a class="indexterm" href="#idp48997028">ReparentNotify Events</a></dt><dt>XReparentWindow, <a class="indexterm" href="#idp40980852">Changing the Parent of a Window</a></dt><dt>XResetScreenSaver, <a class="indexterm" href="#idp45784340">Controlling the Screen Saver</a></dt><dt>XResizeRequestEvent, <a class="indexterm" href="#idp49063180">ResizeRequest Events</a></dt><dt>XResizeWindow, <a class="indexterm" href="#idp44761996">Configuring Windows</a></dt><dt>XResourceManagerString, <a class="indexterm" href="#idp48662044">Creating and Storing Databases</a></dt><dt>xResourceReq, <a class="indexterm" href="#idp53945972">Request Format</a></dt><dt>XRestackWindows, <a class="indexterm" href="#idp44847676">Changing Window Stacking Order</a></dt><dt>XrmCombineDatabase, <a class="indexterm" href="#idp49567860">Merging Resource Databases</a></dt><dt>XrmCombineFileDatabase, <a class="indexterm" href="#idp48641756">Merging Resource Databases</a></dt><dt>XrmDatabase, <a class="indexterm" href="#idp49670068">Creating and Storing Databases</a></dt><dt>XrmDestroyDatabase, <a class="indexterm" href="#idp48685812">Creating and Storing Databases</a></dt><dt>XrmEnumerateDatabase, <a class="indexterm" href="#idp49464332">Enumerating Database Entries</a></dt><dt>XrmGetDatabase, <a class="indexterm" href="#idp51097588">Creating and Storing Databases</a></dt><dt>XrmGetFileDatabase, <a class="indexterm" href="#idp49620524">Creating and Storing Databases</a></dt><dt>XrmGetResource, <a class="indexterm" href="#idp49496076">Looking Up Resources</a></dt><dt>XrmGetStringDatabase, <a class="indexterm" href="#idp48672116">Creating and Storing Databases</a></dt><dt>XrmInitialize, <a class="indexterm" href="#idp49617044">Creating and Storing Databases</a></dt><dt>XrmLocaleOfDatabase, <a class="indexterm" href="#idp48679580">Creating and Storing Databases</a></dt><dt>XrmMergeDatabases, <a class="indexterm" href="#idp49578196">Merging Resource Databases</a></dt><dt>XrmOptionDescRec, <a class="indexterm" href="#idp51042948">Parsing Command Line Options</a></dt><dt>XrmOptionKind, <a class="indexterm" href="#idp51038652">Parsing Command Line Options</a></dt><dt>XrmParseCommand, <a class="indexterm" href="#idp51046036">Parsing Command Line Options</a></dt><dt>XrmPermStringToQuark, <a class="indexterm" href="#idp48597780">Quarks</a></dt><dt>XrmPutFileDatabase, <a class="indexterm" href="#idp48653444">Creating and Storing Databases</a></dt><dt>XrmPutLineResource, <a class="indexterm" href="#idp49454404">Storing into a Resource Database</a></dt><dt>XrmPutResource, <a class="indexterm" href="#idp50476204">Storing into a Resource Database</a></dt><dt>XrmPutStringResource, <a class="indexterm" href="#idp50502268">Storing into a Resource Database</a></dt><dt>XrmQGetResource, <a class="indexterm" href="#idp49507308">Looking Up Resources</a></dt><dt>XrmQGetSearchList, <a class="indexterm" href="#idp51112380">Looking Up Resources</a></dt><dt>XrmQGetSearchResource, <a class="indexterm" href="#idp51129996">Looking Up Resources</a></dt><dt>XrmQPutResource, <a class="indexterm" href="#idp50488876">Storing into a Resource Database</a></dt><dt>XrmQPutStringResource, <a class="indexterm" href="#idp49441508">Storing into a Resource Database</a></dt><dt>XrmQuarkToString, <a class="indexterm" href="#idp49549932">Quarks</a></dt><dt>XrmSetDatabase, <a class="indexterm" href="#idp51089620">Creating and Storing Databases</a></dt><dt>XrmStringToBindingQuarkList, <a class="indexterm" href="#idp49485332">Quarks</a></dt><dt>XrmStringToQuark, <a class="indexterm" href="#idp48597348">Quarks</a></dt><dt>XrmStringToQuarkList, <a class="indexterm" href="#idp49557188">Quarks</a></dt><dt>XrmUniqueQuark, <a class="indexterm" href="#idp48492716">Quarks</a></dt><dt>XrmValue, <a class="indexterm" href="#idp49614372">Creating and Storing Databases</a></dt><dt>XRootWindow, <a class="indexterm" href="#idp43650156">Display Macros</a></dt><dt>XRootWindowOfScreen, <a class="indexterm" href="#idp43840100">Screen Information Macros</a></dt><dt>XRotateBuffers, <a class="indexterm" href="#idp53315740">Using Cut Buffers</a></dt><dt>XRotateWindowProperties, <a class="indexterm" href="#idp44970388">Obtaining and Changing Window Properties</a></dt><dt>XSaveContext, <a class="indexterm" href="#idp53531492">Using the Context Manager</a></dt><dt>XScreenCount, <a class="indexterm" href="#idp43655428">Display Macros</a></dt><dt>XScreenNumberOfScreen, <a class="indexterm" href="#idp43786868">Screen Information Macros</a></dt><dt>XScreenOfDisplay, <a class="indexterm" href="#idp42591740">Display Macros</a></dt><dt>XScreenResourceString, <a class="indexterm" href="#idp49677964">Creating and Storing Databases</a></dt><dt>XSegment, <a class="indexterm" href="#idp45328484">Drawing Points, Lines, Rectangles, and Arcs</a></dt><dt>XSelectInput, <a class="indexterm" href="#idp43016108">Selecting Events</a></dt><dt>XSelectionClearEvent, <a class="indexterm" href="#idp49101356">SelectionClear Events</a></dt><dt>XSelectionEvent, <a class="indexterm" href="#idp49118132">SelectionNotify Events</a></dt><dt>XSelectionRequestEvent, <a class="indexterm" href="#idp49107548">SelectionRequest Events</a></dt><dt>XSendEvent, <a class="indexterm" href="#idp48368548">Sending Events to Other Applications</a>, <a class="indexterm" href="#idp48369884">Sending Events to Other Applications</a></dt><dt>XServerInterpretedAddress, <a class="indexterm" href="#idp45699148">Adding, Getting, or Removing Hosts</a></dt><dt>XServerVendor, <a class="indexterm" href="#idp43660604">Display Macros</a></dt><dt>XSetAccessControl, <a class="indexterm" href="#idp45586108">Changing, Enabling, or Disabling Access Control</a></dt><dt>XSetAfterFunction, <a class="indexterm" href="#idp48424532">Enabling or Disabling Synchronization</a></dt><dt>XSetArcMode, <a class="indexterm" href="#idp46136476">Setting the Arc Mode, Subwindow Mode, and Graphics Exposure</a></dt><dt>XSetBackground, <a class="indexterm" href="#idp45897364">Setting the Foreground, Background, Function, or Plane Mask</a></dt><dt>XSetClassHint, <a class="indexterm" href="#idp50775460">Setting and Reading the WM_CLASS Property</a></dt><dt>XSetClipMask, <a class="indexterm" href="#idp46099772">Setting the Clip Region</a></dt><dt>XSetClipOrigin, <a class="indexterm" href="#idp46087804">Setting the Clip Region</a></dt><dt>XSetClipRectangles, <a class="indexterm" href="#idp46110884">Setting the Clip Region</a></dt><dt>XSetCloseDownMode, <a class="indexterm" href="#idp43864324">Closing the Display</a></dt><dt>XSetCommand, <a class="indexterm" href="#idp52600588">Setting and Reading the WM_COMMAND Property</a></dt><dt>XSetDashes, <a class="indexterm" href="#idp45946140">Setting the Line Attributes and Dashes</a></dt><dt>XSetErrorHandler, <a class="indexterm" href="#idp48444220">Using the Default Error Handlers</a></dt><dt>XSetFillRule, <a class="indexterm" href="#idp45975276">Setting the Fill Style and Fill Rule</a></dt><dt>XSetFillStyle, <a class="indexterm" href="#idp45964300">Setting the Fill Style and Fill Rule</a></dt><dt>XSetFont, <a class="indexterm" href="#idp46076348">Setting the Current Font</a></dt><dt>XSetFontPath, <a class="indexterm" href="#idp44245996">Setting and Retrieving the Font Search Path</a></dt><dt>XSetForeground, <a class="indexterm" href="#idp45887524">Setting the Foreground, Background, Function, or Plane Mask</a></dt><dt>XSetFunction, <a class="indexterm" href="#idp45907212">Setting the Foreground, Background, Function, or Plane Mask</a></dt><dt>XSetGraphicsExposures, <a class="indexterm" href="#idp46157420">Setting the Arc Mode, Subwindow Mode, and Graphics Exposure</a></dt><dt>XSetICFocus, <a class="indexterm" href="#idp51916180">Input Context Functions</a></dt><dt>XSetIconName, <a class="indexterm" href="#idp50617076">Setting and Reading the WM_ICON_NAME Property</a></dt><dt>XSetIconSizes, <a class="indexterm" href="#idp50900668">Setting and Reading the WM_ICON_SIZE Property</a></dt><dt>XSetICValues, <a class="indexterm" href="#idp51950660">Input Context Functions</a></dt><dt>XSetIMValues, <a class="indexterm" href="#idp51734468">Input Method Functions</a></dt><dt>XSetInputFocus, <a class="indexterm" href="#idp49788876">Controlling Input Focus</a></dt><dt>XSetIOErrorHandler, <a class="indexterm" href="#idp48582004">Using the Default Error Handlers</a></dt><dt>XSetLineAttributes, <a class="indexterm" href="#idp45928284">Setting the Line Attributes and Dashes</a></dt><dt>XSetLocaleModifiers, <a class="indexterm" href="#idp48617276">X Locale Management</a></dt><dt>XSetModifierMapping, <a class="indexterm" href="#idp50023268">Manipulating the Keyboard Encoding</a></dt><dt>XSetNormalHints, <a class="indexterm" href="#idp49283284">Setting and Getting Window Sizing Hints</a></dt><dt>XSetOCValues, <a class="indexterm" href="#idp51196420">Output Context Functions</a></dt><dt>XSetOMValues, <a class="indexterm" href="#idp49384284">Output Method Functions</a></dt><dt>XSetPlaneMask, <a class="indexterm" href="#idp45917260">Setting the Foreground, Background, Function, or Plane Mask</a></dt><dt>XSetPointerMapping, <a class="indexterm" href="#idp49879212">Manipulating the Keyboard and Pointer Settings</a></dt><dt>XSetRegion, <a class="indexterm" href="#idp53172084">Creating, Copying, or Destroying Regions</a></dt><dt>XSetRGBColormaps, <a class="indexterm" href="#idp52682004">Setting and Obtaining Standard Colormaps</a></dt><dt>XSetScreenSaver, <a class="indexterm" href="#idp45511884">Controlling the Screen Saver</a></dt><dt>XSetSelectionOwner, <a class="indexterm" href="#idp44999620">Selections</a></dt><dt>XSetSizeHints, <a class="indexterm" href="#idp49274108">Setting and Getting Window Sizing Hints</a></dt><dt>XSetStandardColormap, <a class="indexterm" href="#idp50393532">Getting and Setting an XStandardColormap Structure</a></dt><dt>XSetStandardProperties, <a class="indexterm" href="#idp42978164">Setting Standard Properties</a></dt><dt>XSetState, <a class="indexterm" href="#idp45872436">Setting the Foreground, Background, Function, or Plane Mask</a></dt><dt>XSetStipple, <a class="indexterm" href="#idp46052612">Setting the Fill Tile and Stipple</a></dt><dt>XSetSubwindowMode, <a class="indexterm" href="#idp46146916">Setting the Arc Mode, Subwindow Mode, and Graphics Exposure</a></dt><dt>XSetTextProperty, <a class="indexterm" href="#idp50966244">Setting and Reading Text Properties</a></dt><dt>XSetTile, <a class="indexterm" href="#idp46041724">Setting the Fill Tile and Stipple</a></dt><dt>XSetTransientForHint, <a class="indexterm" href="#idp50800788">Setting and Reading the WM_TRANSIENT_FOR Property</a></dt><dt>XSetTSOrigin, <a class="indexterm" href="#idp46063516">Setting the Fill Tile and Stipple</a></dt><dt>XSetWindowAttributes, <a class="indexterm" href="#idp42682220">Window Attributes</a></dt><dt>XSetWindowBackground, <a class="indexterm" href="#idp44879620">Changing Window Attributes</a></dt><dt>XSetWindowBackgroundPixmap, <a class="indexterm" href="#idp44890684">Changing Window Attributes</a></dt><dt>XSetWindowBorder, <a class="indexterm" href="#idp44903740">Changing Window Attributes</a></dt><dt>XSetWindowBorderPixmap, <a class="indexterm" href="#idp44913428">Changing Window Attributes</a></dt><dt>XSetWindowBorderWidth, <a class="indexterm" href="#idp44790148">Configuring Windows</a></dt><dt>XSetWindowColormap, <a class="indexterm" href="#idp44924860">Changing Window Attributes</a></dt><dt>XSetWMClientMachine, <a class="indexterm" href="#idp52625644">Setting and Reading the WM_CLIENT_MACHINE Property</a></dt><dt>XSetWMColormapWindows, <a class="indexterm" href="#idp50858108">Setting and Reading the WM_COLORMAP_WINDOWS Property</a></dt><dt>XSetWMHints, <a class="indexterm" href="#idp50657580">Setting and Reading the WM_HINTS Property</a></dt><dt>XSetWMIconName, <a class="indexterm" href="#idp50593484">Setting and Reading the WM_ICON_NAME Property</a></dt><dt>XSetWMName, <a class="indexterm" href="#idp50998324">Setting and Reading the WM_NAME Property</a></dt><dt>XSetWMNormalHints, <a class="indexterm" href="#idp50694468">Setting and Reading the WM_NORMAL_HINTS Property</a></dt><dt>XSetWMProperties, <a class="indexterm" href="#idp52564972">Using Window Manager Convenience Functions</a></dt><dt>XSetWMProtocols, <a class="indexterm" href="#idp50826044">Setting and Reading the WM_PROTOCOLS Property</a></dt><dt>XSetWMSizeHints, <a class="indexterm" href="#idp50725548">Setting and Reading the WM_NORMAL_HINTS Property</a></dt><dt>XSetZoomHints, <a class="indexterm" href="#idp50363884">Setting and Getting Window Sizing Hints</a></dt><dt>XShrinkRegion, <a class="indexterm" href="#idp53192852">Moving or Shrinking Regions</a></dt><dt>XStoreBuffer, <a class="indexterm" href="#idp53289780">Using Cut Buffers</a></dt><dt>XStoreBytes, <a class="indexterm" href="#idp53280588">Using Cut Buffers</a></dt><dt>XStoreColor, <a class="indexterm" href="#idp46398900">Modifying and Querying Colormap Cells</a></dt><dt>XStoreColors, <a class="indexterm" href="#idp46413308">Modifying and Querying Colormap Cells</a></dt><dt>XStoreName, <a class="indexterm" href="#idp51021644">Setting and Reading the WM_NAME Property</a></dt><dt>XStoreNamedColor, <a class="indexterm" href="#idp46470060">Modifying and Querying Colormap Cells</a></dt><dt>XStringListToTextProperty, <a class="indexterm" href="#idp50931084">Converting String Lists</a></dt><dt>XStringToKeysym, <a class="indexterm" href="#idp50168404">Using Keyboard Utility Functions</a></dt><dt>XSubImage, <a class="indexterm" href="#idp53407868">Manipulating Images</a></dt><dt>XSubtractRegion, <a class="indexterm" href="#idp53229524">Computing with Regions</a></dt><dt>XSync, <a class="indexterm" href="#idp42122748">Overview of the X Window System</a>, <a class="indexterm" href="#idp42292172">Overview of the X Window System</a>, <a class="indexterm" href="#idp47551996">Handling the Output Buffer</a></dt><dt>XSynchronize, <a class="indexterm" href="#idp48432444">Enabling or Disabling Synchronization</a></dt><dt>XTextExtents, <a class="indexterm" href="#idp48058884">Computing Logical Extents</a></dt><dt>XTextExtents16, <a class="indexterm" href="#idp48072884">Computing Logical Extents</a></dt><dt>XTextItem, <a class="indexterm" href="#idp48132284">Drawing Text</a></dt><dt>XTextItem16, <a class="indexterm" href="#idp48134044">Drawing Text</a></dt><dt>XTextProperty, <a class="indexterm" href="#idp50531260">Converting String Lists</a></dt><dt>XTextPropertyToStringList, <a class="indexterm" href="#idp50942796">Converting String Lists</a></dt><dt>XTextWidth, <a class="indexterm" href="#idp48040796">Computing Character String Sizes</a>, <a class="indexterm" href="#idp48042700">Computing Character String Sizes</a></dt><dt>XTextWidth16, <a class="indexterm" href="#idp48041172">Computing Character String Sizes</a>, <a class="indexterm" href="#idp48050220">Computing Character String Sizes</a></dt><dt>XTimeCoord, <a class="indexterm" href="#idp48415436">Getting Pointer Motion History</a></dt><dt>XTranslateCoordinates, <a class="indexterm" href="#idp44487028">Translating Screen Coordinates</a></dt><dt>XUndefineCursor, <a class="indexterm" href="#idp44945212">Changing Window Attributes</a></dt><dt>XUngrabButton, <a class="indexterm" href="#idp49190204">Pointer Grabbing</a></dt><dt>XUngrabKey, <a class="indexterm" href="#idp49721060">Keyboard Grabbing</a></dt><dt>XUngrabKeyboard, <a class="indexterm" href="#idp49235292">Keyboard Grabbing</a></dt><dt>XUngrabPointer, <a class="indexterm" href="#idp49128860">Pointer Grabbing</a></dt><dt>XUngrabServer, <a class="indexterm" href="#idp45729300">Grabbing the Server</a></dt><dt>XUninstallColormap, <a class="indexterm" href="#idp44090900">Managing Installed Colormaps</a></dt><dt>XUnionRectWithRegion, <a class="indexterm" href="#idp53221452">Computing with Regions</a></dt><dt>XUnionRegion, <a class="indexterm" href="#idp53214660">Computing with Regions</a></dt><dt>XUnloadFont, <a class="indexterm" href="#idp47989996">Loading and Freeing Fonts</a></dt><dt>XUnlockDisplay, <a class="indexterm" href="#idp43902164">Using Xlib with Threads</a></dt><dt>XUnmapEvent, <a class="indexterm" href="#idp49005092">UnmapNotify Events</a></dt><dt>XUnmapSubwindows, <a class="indexterm" href="#idp44699892">Unmapping Windows</a></dt><dt>XUnmapWindow, <a class="indexterm" href="#idp44690484">Unmapping Windows</a>, <a class="indexterm" href="#idp44696692">Unmapping Windows</a></dt><dt>XUnregisterIMInstantiateCallback, <a class="indexterm" href="#idp51787556">Input Method Functions</a></dt><dt>XUnsetICFocus, <a class="indexterm" href="#idp51922180">Input Context Functions</a></dt><dt>XVaCreateNestedList, <a class="indexterm" href="#idp49339844">Variable Argument Lists</a></dt><dt>XVendorRelease, <a class="indexterm" href="#idp43666068">Display Macros</a></dt><dt>XVisibilityEvent, <a class="indexterm" href="#idp49016468">VisibilityNotify Events</a></dt><dt>XVisualIDFromVisual, <a class="indexterm" href="#idp42263196">Visual Types</a></dt><dt>XWarpPointer, <a class="indexterm" href="#idp49766508">Moving the Pointer</a></dt><dt>XwcDrawImageString, <a class="indexterm" href="#idp51554884">Drawing Text Using Font Sets</a></dt><dt>XwcDrawString, <a class="indexterm" href="#idp51528076">Drawing Text Using Font Sets</a></dt><dt>XwcDrawText, <a class="indexterm" href="#idp51500988">Drawing Text Using Font Sets</a></dt><dt>XwcFreeStringList, <a class="indexterm" href="#idp50918820">Converting String Lists</a></dt><dt>XwcLookupString, <a class="indexterm" href="#idp52449372">Getting Keyboard Input</a></dt><dt>XwcResetIC, <a class="indexterm" href="#idp51930252">Input Context Functions</a></dt><dt>XwcTextEscapement, <a class="indexterm" href="#idp51414572">Obtaining Font Set Metrics</a></dt><dt>XwcTextExtents, <a class="indexterm" href="#idp51430452">Obtaining Font Set Metrics</a></dt><dt>XwcTextItem, <a class="indexterm" href="#idp51497356">Drawing Text Using Font Sets</a></dt><dt>XwcTextListToTextProperty, <a class="indexterm" href="#idp50537932">Converting String Lists</a></dt><dt>XwcTextPerCharExtents, <a class="indexterm" href="#idp51455428">Obtaining Font Set Metrics</a></dt><dt>XwcTextPropertyToTextList, <a class="indexterm" href="#idp50562924">Converting String Lists</a></dt><dt>XWhitePixel, <a class="indexterm" href="#idp42528148">Display Macros</a></dt><dt>XWhitePixelOfScreen, <a class="indexterm" href="#idp43740924">Screen Information Macros</a></dt><dt>XWidthMMOfScreen, <a class="indexterm" href="#idp43812516">Screen Information Macros</a></dt><dt>XWidthOfScreen, <a class="indexterm" href="#idp43801796">Screen Information Macros</a></dt><dt>XWindowAttributes, <a class="indexterm" href="#idp44417292">Obtaining Window Information</a></dt><dt>XWindowChanges, <a class="indexterm" href="#idp44711340">Configuring Windows</a></dt><dt>XWindowEvent, <a class="indexterm" href="#idp47550364">Handling the Output Buffer</a>, <a class="indexterm" href="#idp47386556">Selecting Events Using a Window or Event Mask</a></dt><dt>XWithdrawWindow, <a class="indexterm" href="#idp48699316">Manipulating Top-Level Windows</a></dt><dt>XWMGeometry, <a class="indexterm" href="#idp50280276">Parsing the Window Geometry</a></dt><dt>XWriteBitmapFile, <a class="indexterm" href="#idp53475364">Manipulating Bitmaps</a>, <a class="indexterm" href="#idp53510044">Manipulating Bitmaps</a></dt><dt>XXorRegion, <a class="indexterm" href="#idp53237116">Computing with Regions</a></dt><dt>XY format, <a class="indexterm" href="#idp54202140">Glossary</a></dt></dl></div><div class="indexdiv"><h3>Z</h3><dl><dt>Z format, <a class="indexterm" href="#idp54203828">Glossary</a></dt></dl></div></div></div></div></body></html>
libx11-doc 2:1.6.2-1ubuntu2 / usr / share / doc / libx11-dev / libX11 / libX11.html
