diff options
Diffstat (limited to 'libX11/specs/libX11/AppD.xml')
-rw-r--r-- | libX11/specs/libX11/AppD.xml | 3778 |
1 files changed, 1889 insertions, 1889 deletions
diff --git a/libX11/specs/libX11/AppD.xml b/libX11/specs/libX11/AppD.xml index 0d060069e..afe65907d 100644 --- a/libX11/specs/libX11/AppD.xml +++ b/libX11/specs/libX11/AppD.xml @@ -1,1889 +1,1889 @@ -<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
-<appendix id="compatibility_functions">
-<title>Compatibility Functions</title>
-<para>
-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.
-</para>
-<sect1 id="X_Version_11_Compatibility_Functions">
-<title>X Version 11 Compatibility Functions</title>
-<para>
-You can use the X Version 11 compatibility functions to:
-<itemizedlist>
- <listitem>
- <para>
-Set standard properties
- </para>
- </listitem>
- <listitem>
- <para>
-Set and get window sizing hints
- </para>
- </listitem>
- <listitem>
- <para>
-Set and get an
-<structname>XStandardColormap</structname>
-structure
- </para>
- </listitem>
- <listitem>
- <para>
-Parse window geometry
- </para>
- </listitem>
- <listitem>
- <para>
-Get X environment defaults
- </para>
- </listitem>
-</itemizedlist>
-</para>
-<sect2 id="Setting_Standard_Properties">
-<title>Setting Standard Properties</title>
-<para>
-To specify a minimum set of properties describing the simplest application,
-use
-<function>XSetStandardProperties</function>.
-This function has been superseded by
-<function>XSetWMProperties</function>
-and sets all or portions of the
-<property>WM_NAME</property>, <property>WM_ICON_NAME</property>, <property>WM_HINTS</property>, <property>WM_COMMAND</property>,
-and <property>WM_NORMAL_HINTS</property> properties.
-<indexterm significance="preferred"><primary>XSetStandardProperties</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetStandardProperties</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Window<parameter> w</parameter></paramdef>
- <paramdef>char<parameter> *window_name</parameter></paramdef>
- <paramdef>char<parameter> *icon_name</parameter></paramdef>
- <paramdef>Pixmap<parameter> icon_pixmap</parameter></paramdef>
- <paramdef>char<parameter> **argv</parameter></paramdef>
- <paramdef>int<parameter> argc</parameter></paramdef>
- <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>w</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the window.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>window_name</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the window name,
-which should be a null-terminated string.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>icon_name</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the icon name,
-which should be a null-terminated string.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>icon_pixmap</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the bitmap that is to be used for the icon or
-<symbol>None</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>argv</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the application's argument list.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>argc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of arguments.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hints</emphasis>
- </term>
- <listitem>
- <para>
-Specifies a pointer to the size hints for the window in its normal state.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XSetStandardProperties</function>
-function provides a means by which simple applications set the
-most essential properties with a single call.
-<function>XSetStandardProperties</function>
-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
-<function>XSetStandardProperties</function>.
-(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.
-</para>
-<para>
-<!-- .LP -->
-<function>XSetStandardProperties</function>
-can generate
-<errorname>BadAlloc</errorname>
-and
-<errorname>BadWindow</errorname>
-errors.
-</para>
-</sect2>
-<sect2 id="Setting_and_Getting_Window_Sizing_Hints">
-<title>Setting and Getting Window Sizing Hints</title>
-<para>
-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
-<structname>XSizeHints</structname>
-structure, as defined in the
-<filename class="headerfile"><X11/Xutil.h></filename>
-<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
-<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
-<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
-header file and use the <property>WM_NORMAL_HINTS</property> property.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To set the size hints for a given window in its normal state, use
-<function>XSetNormalHints</function>.
-This function has been superseded by
-<function>XSetWMNormalHints</function>.
-<indexterm significance="preferred"><primary>XSetNormalHints</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetNormalHints</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Window<parameter> w</parameter></paramdef>
- <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>w</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the window.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hints</emphasis>
- </term>
- <listitem>
- <para>
-Specifies a pointer to the size hints for the window in its normal state.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XSetNormalHints</function>
-function sets the size hints structure for the specified window.
-Applications use
-<function>XSetNormalHints</function>
-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
-<function>XSetNormalHints</function>
-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.
-</para>
-<para>
-<!-- .LP -->
-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
-<function>XSetNormalHints</function>
-is meaningless, unless the flags member is set to indicate which members of
-the structure have been assigned values.
-</para>
-<para>
-<!-- .LP -->
-<function>XSetNormalHints</function>
-can generate
-<errorname>BadAlloc</errorname>
-and
-<errorname>BadWindow</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To return the size hints for a window in its normal state, use
-<function>XGetNormalHints</function>.
-This function has been superseded by
-<function>XGetWMNormalHints</function>.
-<indexterm significance="preferred"><primary>XGetNormalHints</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>Status <function>XGetNormalHints</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Window<parameter> w</parameter></paramdef>
- <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>w</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the window.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hints_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the size hints for the window in its normal state.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XGetNormalHints</function>
-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.
-</para>
-<para>
-<!-- .LP -->
-<function>XGetNormalHints</function>
-can generate a
-<errorname>BadWindow</errorname>
-error.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-The next two functions set and read the <property>WM_ZOOM_HINTS</property> property.
-</para>
-<para>
-<!-- .LP -->
-To set the zoom hints for a window, use
-<function>XSetZoomHints</function>.
-This function is no longer supported by the
-<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
-<indexterm significance="preferred"><primary>XSetZoomHints</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetZoomHints</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Window<parameter> w</parameter></paramdef>
- <paramdef>XSizeHints<parameter> *zhints</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>w</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the window.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>zhints</emphasis>
- </term>
- <listitem>
- <para>
-Specifies a pointer to the zoom hints.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-Many window managers think of windows in one of three states:
-iconic, normal, or zoomed.
-The
-<function>XSetZoomHints</function>
-function provides the window manager with information for the window in the
-zoomed state.
-</para>
-<para>
-<!-- .LP -->
-<function>XSetZoomHints</function>
-can generate
-<errorname>BadAlloc</errorname>
-and
-<errorname>BadWindow</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To read the zoom hints for a window, use
-<function>XGetZoomHints</function>.
-This function is no longer supported by the
-<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
-<indexterm significance="preferred"><primary>XGetZoomHints</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>Status <function>XGetZoomHints</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Window<parameter> w</parameter></paramdef>
- <paramdef>XSizeHints<parameter> *zhints_return</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>w</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the window.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>zhints_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the zoom hints.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XGetZoomHints</function>
-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.
-</para>
-<para>
-<!-- .LP -->
-<function>XGetZoomHints</function>
-can generate a
-<errorname>BadWindow</errorname>
-error.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To set the value of any property of type <property>WM_SIZE_HINTS</property>, use
-<function>XSetSizeHints</function>.
-This function has been superseded by
-<function>XSetWMSizeHints</function>.
-<indexterm significance="preferred"><primary>XSetSizeHints</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetSizeHints</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Window<parameter> w</parameter></paramdef>
- <paramdef>XSizeHints<parameter> *hints</parameter></paramdef>
- <paramdef>Atom<parameter> property</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>w</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the window.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hints</emphasis>
- </term>
- <listitem>
- <para>
-Specifies a pointer to the size hints.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>property</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the property name.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XSetSizeHints</function>
-function sets the
-<structname>XSizeHints</structname>
-structure for the named property and the specified window.
-This is used by
-<function>XSetNormalHints</function>
-and
-<function>XSetZoomHints</function>
-and can be used to set the value of any property of type <property>WM_SIZE_HINTS</property>.
-Thus, it may be useful if other properties of that type get defined.
-</para>
-<para>
-<!-- .LP -->
-<function>XSetSizeHints</function>
-can generate
-<errorname>BadAlloc</errorname>,
-<errorname>BadAtom</errorname>,
-and
-<errorname>BadWindow</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To read the value of any property of type <property>WM_SIZE_HINTS</property>, use
-<function>XGetSizeHints</function>.
-This function has been superseded by
-<function>XGetWMSizeHints</function>.
-<indexterm significance="preferred"><primary>XGetSizeHints</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>Status <function>XGetSizeHints</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Window<parameter> w</parameter></paramdef>
- <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>
- <paramdef>Atom<parameter> property</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>w</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the window.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hints_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the size hints.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>property</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the property name.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XGetSizeHints</function>
-function returns the
-<structname>XSizeHints</structname>
-structure for the named property and the specified window.
-This is used by
-<function>XGetNormalHints</function>
-and
-<function>XGetZoomHints</function>.
-It also can be used to retrieve the value of any property of type
-<property>WM_SIZE_HINTS</property>.
-Thus, it may be useful if other properties of that type get defined.
-<function>XGetSizeHints</function>
-returns a nonzero status if a size hint was defined
-or zero otherwise.
-</para>
-<para>
-<!-- .LP -->
-<function>XGetSizeHints</function>
-can generate
-<errorname>BadAtom</errorname>
-and
-<errorname>BadWindow</errorname>
-errors.
-</para>
-</sect2>
-<sect2 id="Getting_and_Setting_an_XStandardColormap_Structure">
-<title>Getting and Setting an XStandardColormap Structure</title>
-<para>
-To get the
-<structname>XStandardColormap</structname>
-structure associated with one of the described atoms, use
-<function>XGetStandardColormap</function>.
-This function has been superseded by
-<function>XGetRGBColormaps</function>.
-<indexterm significance="preferred"><primary>XGetStandardColormap</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>Status <function>XGetStandardColormap</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Window<parameter> w</parameter></paramdef>
- <paramdef>XStandardColormap<parameter> *colormap_return</parameter></paramdef>
- <paramdef>Atom<parameter> property</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>w</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the window.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>colormap_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the colormap associated with the specified atom.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>property</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the property name.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XGetStandardColormap</function>
-function returns the colormap definition associated with the atom supplied
-as the property argument.
-<function>XGetStandardColormap</function>
-returns a nonzero status if successful and zero otherwise.
-For example,
-to fetch the standard
-<symbol>GrayScale</symbol>
-colormap for a display,
-you use
-<function>XGetStandardColormap</function>
-with the following syntax:
-<programlisting>
-XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_MAP);
-</programlisting>
-See section 14.3 for the semantics of standard colormaps.
-</para>
-<para>
-<!-- .LP -->
-<function>XGetStandardColormap</function>
-can generate
-<errorname>BadAtom</errorname>
-and
-<errorname>BadWindow</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To set a standard colormap, use
-<function>XSetStandardColormap</function>.
-This function has been superseded by
-<function>XSetRGBColormaps</function>.
-<indexterm significance="preferred"><primary>XSetStandardColormap</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetStandardColormap</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Window<parameter> w</parameter></paramdef>
- <paramdef>XStandardColormap<parameter> *colormap</parameter></paramdef>
- <paramdef>Atom<parameter> property</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>w</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the window.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>colormap</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the colormap.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>property</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the property name.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XSetStandardColormap</function>
-function usually is only used by window or session managers.
-</para>
-<para>
-<!-- .LP -->
-<function>XSetStandardColormap</function>
-can generate
-<errorname>BadAlloc</errorname>,
-<errorname>BadAtom</errorname>,
-<errorname>BadDrawable</errorname>,
-and
-<errorname>BadWindow</errorname>
-errors.
-</para>
-</sect2>
-<sect2 id="Parsing_Window_Geometry">
-<title>Parsing Window Geometry</title>
-<para>
-To parse window geometry given a user-specified position
-and a default position, use
-<function>XGeometry</function>.
-This function has been superseded by
-<function>XWMGeometry</function>.
-<indexterm><primary>Window</primary><secondary>determining location</secondary></indexterm>
-<indexterm significance="preferred"><primary>XGeometry</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>int <function>XGeometry</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>int<parameter> screen</parameter></paramdef>
- <paramdef>char*position,<parameter> *default_position</parameter></paramdef>
- <paramdef>unsignedint<parameter> bwidth</parameter></paramdef>
- <paramdef>unsignedintfwidth,<parameter> fheight</parameter></paramdef>
- <paramdef>intxadder,<parameter> yadder</parameter></paramdef>
- <paramdef>int*x_return,<parameter> *y_return</parameter></paramdef>
- <paramdef>int*width_return,<parameter> *height_return</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>screen</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the screen.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>position</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>default_position</emphasis>
- </term>
- <listitem>
- <para>
-Specify the geometry specifications.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>bwidth</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the border width.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>fheight</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>fwidth</emphasis>
- </term>
- <listitem>
- <para>
-Specify the font height and width in pixels (increment size).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>xadder</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>yadder</emphasis>
- </term>
- <listitem>
- <para>
-Specify additional interior padding needed in the window.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>x_return</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>y_return</emphasis>
- </term>
- <listitem>
- <para>
-Return the x and y offsets.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>width_return</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>height_return</emphasis>
- </term>
- <listitem>
- <para>
-Return the width and height determined.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-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
-<function>XGeometry</function>
-function returns the position the window should be placed given a position and
-a default position.
-<function>XGeometry</function>
-determines the placement of
-a window using a geometry specification as specified by
-<function>XParseGeometry</function>
-and the additional information about the window.
-Given a fully qualified default geometry specification and
-an incomplete geometry specification,
-<function>XParseGeometry</function>
-returns a bitmask value as defined above in the
-<function>XParseGeometry</function>
-call,
-by using the position argument.
-</para>
-<para>
-<!-- .LP -->
-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.
-</para>
-</sect2>
-<sect2 id="Getting_the_X_Environment_Defaults">
-<title>Getting the X Environment Defaults</title>
-<para>
-The
-<function>XGetDefault</function>
-function provides a primitive interface to the resource manager facilities
-discussed in chapter 15. <!-- xref -->
-It is only useful in very simple applications.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-<indexterm significance="preferred"><primary>XGetDefault</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>char *<function>XGetDefault</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>char<parameter> *program</parameter></paramdef>
- <paramdef>char<parameter> *option</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>program</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the program name for the Xlib defaults (usually argv[0]
-of the main program).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>option</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the option name.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XGetDefault</function>
-function returns the value of the resource <emphasis remap='I'>prog</emphasis>.<emphasis remap='I'>option</emphasis>,
-where <emphasis remap='I'>prog</emphasis> is the program argument with the directory prefix removed
-and <emphasis remap='I'>option</emphasis> must be a single component.
-Note that multilevel resources cannot be used with
-<function>XGetDefault</function>.
-The class "Program.Name" is always used for the resource lookup.
-If the specified option name does not exist for this program,
-<function>XGetDefault</function>
-returns NULL.
-The strings returned by
-<function>XGetDefault</function>
-are owned by Xlib and should not be modified or freed by the client.
-</para>
-<para>
-<!-- .LP -->
-If a database has been set with
-<function>XrmSetDatabase</function>,
-that database is used for the lookup.
-Otherwise, a database is created
-and is set in the display (as if by calling
-<function>XrmSetDatabase</function>).
-The database is created in the current locale.
-To create a database,
-<function>XGetDefault</function>
-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>POSIX</acronym>-conformant system,
-this file is
-<function>"$HOME/.Xdefaults"</function>.
-<indexterm><primary>Files</primary><secondary><filename>$HOME/.Xdefaults</filename></secondary></indexterm>
-After loading these defaults,
-<function>XGetDefault</function>
-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,
-<function>XGetDefault</function>
-looks for
-"<filename>$HOME/.Xdefaults-<replaceable>name</replaceable></filename>" ,
-where <replaceable>name</replaceable> specifies the name of the machine on which the application
-is running.
-</para>
-</sect2>
-</sect1>
-<sect1 id="X_Version_10_Compatibility_Functions">
-<title>X Version 10 Compatibility Functions</title>
-<para>
-You can use the X Version 10 compatibility functions to:
-<itemizedlist>
- <listitem>
- <para>
-Draw and fill polygons and curves
- </para>
- </listitem>
- <listitem>
- <para>
-Associate user data with a value
- </para>
- </listitem>
-</itemizedlist>
-</para>
-<sect2 id="Drawing_and_Filling_Polygons_and_Curves">
-<title>Drawing and Filling Polygons and Curves</title>
-<para>
-<!-- .LP -->
-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
-<function>XDrawLines</function>
-<indexterm><primary>XDrawLines</primary></indexterm>
-or
-<function>XDrawSegments</function>
-<indexterm><primary>XDrawSegments</primary></indexterm>
-is much faster.
-</para>
-<para>
-<!-- .LP -->
-The functions discussed here provide all the functionality of the
-X Version 10 functions
-<function>XDraw</function>,
-<indexterm ><primary>X10 compatibility</primary><secondary>XDraw</secondary></indexterm>
-<function>XDrawFilled</function>,
-<indexterm><primary>X10 compatibility</primary><secondary>XDrawFilled</secondary></indexterm>
-<function>XDrawPatterned</function>,
-<indexterm ><primary>X10 compatibility</primary><secondary>XDrawPatterned</secondary></indexterm>
-<function>XDrawDashed</function>,
-<indexterm><primary>X10 compatibility</primary><secondary>XDrawDashed</secondary></indexterm>
-and
-<function>XDrawTiled</function>.
-<indexterm><primary>X10 compatibility</primary><secondary>XDrawTiled</secondary></indexterm>
-They are as compatible as possible given X Version 11's new line-drawing
-functions.
-One thing to note, however, is that
-<function>VertexDrawLastPoint</function>
-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).
-<function>XAppendVertex</function>
-and
-<function>XClearVertexFlag</function>
-from X Version 10 also are not supported.
-</para>
-<para>
-<!-- .LP -->
-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
-<function>XDrawLines</function>).
-The functions discussed here fail (return zero) only if they run out of memory
-or are passed a
-<structname>Vertex</structname>
-list that has a
-<structname>Vertex</structname>
-with
-<symbol>VertexStartClosed</symbol>
-set that is not followed by a
-<structname>Vertex</structname>
-with
-<symbol>VertexEndClosed</symbol>
-set.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To achieve the effects of the X Version 10
-<function>XDraw</function>,
-<indexterm ><primary>X10 compatibility</primary><secondary>XDraw</secondary></indexterm>
-<function>XDrawDashed</function>,
-<indexterm><primary>X10 compatibility</primary><secondary>XDrawDashed</secondary></indexterm>
-and
-<function>XDrawPatterned</function>,
-<indexterm ><primary>X10 compatibility</primary><secondary>XDrawPatterned</secondary></indexterm>
-use
-<function>XDraw</function>.
-</para>
-
-<para>
-#include <X11/X10.h>
-</para>
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>Status <function>XDraw</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>Vertex<parameter> *vlist</parameter></paramdef>
- <paramdef>int<parameter> vcount</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>d</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the drawable.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>vlist</emphasis>
- </term>
- <listitem>
- <para>
-Specifies a pointer to the list of vertices that indicate what to draw.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>vcount</emphasis>
- </term>
- <listitem>
- <para>
-Specifies how many vertices are in vlist.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XDraw</function>
-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.
-</para>
-<para>
-<!-- .LP -->
-Each Vertex, as defined in
-<filename class="headerfile"><X11/X10.h></filename>,
-<indexterm type="file"><primary><filename class="headerfile">X11/X10.h</filename></primary></indexterm>
-<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/X10.h></filename></secondary></indexterm>
-<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/X10.h></filename></secondary></indexterm>
-is a structure with the following members:
-<indexterm significance="preferred"><primary>Vertex</primary></indexterm>
-<synopsis>
-typedef struct _Vertex {
- short x,y;
- unsigned short flags;
-} Vertex;
-</synopsis>
-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
-<symbol>VertexRelative</symbol>
-is zero) or the previous vertex (if
-<symbol>VertexRelative</symbol>
-is one).
-</para>
-<para>
-<!-- .LP -->
-The flags, as defined in
-<filename class="headerfile"><X11/X10.h></filename>,
-<indexterm type="file"><primary><filename class="headerfile">X11/X10.h</filename></primary></indexterm>
-<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/X10.h></filename></secondary></indexterm>
-<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/X10.h></filename></secondary></indexterm>
-are as follows:
-<indexterm significance="preferred"><primary>VertexRelative</primary></indexterm>
-<indexterm significance="preferred"><primary>VertexDontDraw</primary></indexterm>
-<indexterm significance="preferred"><primary>VertexCurved</primary></indexterm>
-<indexterm significance="preferred"><primary>VertexStartClosed</primary></indexterm>
-<indexterm significance="preferred"><primary>VertexEndClosed</primary></indexterm>
-<!-- .sM -->
-
-<synopsis>
-VertexRelative 0x0001 /* else absolute */
-VertexDontDraw 0x0002 /* else draw */
-VertexCurved 0x0004 /* else straight */
-VertexStartClosed 0x0008 /* else not */
-VertexEndClosed 0x0010 /* else not */
-</synopsis>
-
-<itemizedlist>
- <listitem>
- <para>
-If
-<symbol>VertexRelative</symbol>
-is not set,
-the coordinates are absolute (that is, relative to the drawable's origin).
-The first vertex must be an absolute vertex.
- </para>
- </listitem>
- <listitem>
- <para>
-If
-<symbol>VertexDontDraw</symbol>
-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.
- </para>
- </listitem>
- <listitem>
- <para>
-If
-<symbol>VertexCurved</symbol>
-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
-<symbol>VertexCurved</symbol>
-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).
- </para>
- </listitem>
- <listitem>
- <para>
-It is permissible for
-<symbol>VertexDontDraw</symbol>
-bits and
-<symbol>VertexCurved</symbol>
-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.
- </para>
- </listitem>
- <listitem>
- <para>
-If
-<symbol>VertexStartClosed</symbol>
-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
-<symbol>VertexEndClosed</symbol>
-bit of one.
-The points in between form a cycle to determine predecessor
-and successor vertices for the spline algorithm.
- </para>
- </listitem>
-</itemizedlist>
-</para>
-<para>
-<!-- .LP -->
-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.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To achieve the effects of the X Version 10
-<function>XDrawTiled</function>
-<indexterm><primary>X10 compatibility</primary><secondary>XDrawTiled</secondary></indexterm>
-and
-<function>XDrawFilled</function>,
-<indexterm><primary>X10 compatibility</primary><secondary>XDrawFilled</secondary></indexterm>
-use
-<function>XDrawFilled</function>.
-</para>
-
-<para>#include <X11/X10.h></para>
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>Status <function>XDrawFilled</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>Vertex<parameter> *vlist</parameter></paramdef>
- <paramdef>int<parameter> vcount</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>d</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the drawable.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>vlist</emphasis>
- </term>
- <listitem>
- <para>
-Specifies a pointer to the list of vertices that indicate what to draw.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>vcount</emphasis>
- </term>
- <listitem>
- <para>
-Specifies how many vertices are in vlist.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XDrawFilled</function>
-function draws arbitrary polygons or curves and then fills them.
-</para>
-<para>
-<!-- .LP -->
-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.
-</para>
-</sect2>
-<sect2 id="Associating_User_Data_with_a_Value">
-<title>Associating User Data with a Value</title>
-<para>
-<!-- .LP -->
-These functions have been superseded by the context management functions
-(see section 16.10).
-It is often necessary to associate arbitrary information with resource IDs.
-Xlib provides the
-<function>XAssocTable</function>
-functions that you can use to make such an association.
-<indexterm><primary>Hash Lookup</primary></indexterm>
-<indexterm><primary>Window</primary><secondary>IDs</secondary></indexterm>
-<indexterm><primary>Resource IDs</primary></indexterm>
-Application programs often need to be able to easily refer to
-their own data structures when an event arrives.
-The
-<function>XAssocTable</function>
-system provides users of the X library with a method
-for associating their own data structures with X resources
-(<type>Pixmap</type>s,
-<type>Font</type>s,
-<type>Window</type>s,
-and so on).
-</para>
-<para>
-<!-- .LP -->
-An
-<function>XAssocTable</function>
-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.
-</para>
-<para>
-<!-- .LP -->
-There are a few guidelines that should be observed when using an
-<function>XAssocTable</function> :
-</para>
-<itemizedlist>
- <listitem>
- <para>
-All XIDs are relative to the specified display.
- </para>
- </listitem>
- <listitem>
- <para>
-Because of the hashing scheme used by the association mechanism,
-the following rules for determining the size of a
-<function>XAssocTable</function>
-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.
- </para>
- </listitem>
-</itemizedlist>
-
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To return a pointer to a new
-<function>XAssocTable</function>,
-use
-<function>XCreateAssocTable</function>.
-<indexterm significance="preferred"><primary>XCreateAssocTable</primary></indexterm>
-<!-- .sM -->
-</para>
-<funcsynopsis>
-<funcprototype>
- <funcdef>XAssocTable *<function>XCreateAssocTable</function></funcdef>
- <paramdef>int<parameter> size</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>size</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of buckets in the hash system of
-<function>XAssocTable</function>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The size argument specifies the number of buckets in the
-hash system of
-<function>XAssocTable</function>.
-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
-<function>XAssocTable</function>
-occurs,
-a NULL pointer is returned.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To create an entry in a given
-<function>XAssocTable</function>,
-use
-<function>XMakeAssoc</function>.
-<indexterm significance="preferred"><primary>XMakeAssoc</primary></indexterm>
-<!-- .sM -->
-</para>
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XMakeAssoc</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>XAssocTable<parameter> *table</parameter></paramdef>
- <paramdef>XID<parameter> x_id</parameter></paramdef>
- <paramdef>char<parameter> *data</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>table</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the assoc table.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>x_id</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the X resource ID.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>data</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the data to be associated with the X resource ID.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XMakeAssoc</function>
-function inserts data into an
-<function>XAssocTable</function>
-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.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To obtain data from a given
-<function>XAssocTable</function>,
-use
-<function>XLookUpAssoc</function>.
-<indexterm significance="preferred"><primary>XLookUpAssoc</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>char *<function>XLookUpAssoc</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>XAssocTable<parameter> *table</parameter></paramdef>
- <paramdef>XID<parameter> x_id</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>table</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the assoc table.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>x_id</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the X resource ID.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XLookUpAssoc</function>
-function retrieves the data stored in an
-<function>XAssocTable</function>
-by its XID.
-If an appropriately matching XID can be found in the table,
-<function>XLookUpAssoc</function>
-returns the data associated with it.
-If the x_id cannot be found in the table,
-it returns NULL.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To delete an entry from a given
-<function>XAssocTable</function>,
-use
-<function>XDeleteAssoc</function>.
-<indexterm significance="preferred"><primary>XDeleteAssoc</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XDeleteAssoc</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>XAssocTable<parameter> *table</parameter></paramdef>
- <paramdef>XID<parameter> x_id</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>table</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the assoc table.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>x_id</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the X resource ID.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XDeleteAssoc</function>
-function deletes an association in an
-<function>XAssocTable</function>
-keyed on its XID.
-Redundant deletes (and deletes of nonexistent XIDs) are ignored.
-Deleting associations in no way impairs the performance of an
-<function>XAssocTable</function>.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To free the memory associated with a given
-<function>XAssocTable</function>,
-use
-<function>XDestroyAssocTable</function>.
-</para>
-<indexterm significance="preferred"><primary>XDestroyAssocTable</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XDestroyAssocTable</function></funcdef>
- <paramdef>XAssocTable<parameter> *table</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>table</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the assoc table.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect2>
-</sect1>
-</appendix>
+<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> +<appendix id="compatibility_functions"> +<title>Compatibility Functions</title> +<para> +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. +</para> +<sect1 id="X_Version_11_Compatibility_Functions"> +<title>X Version 11 Compatibility Functions</title> +<para> +You can use the X Version 11 compatibility functions to: +<itemizedlist> + <listitem> + <para> +Set standard properties + </para> + </listitem> + <listitem> + <para> +Set and get window sizing hints + </para> + </listitem> + <listitem> + <para> +Set and get an +<structname>XStandardColormap</structname> +structure + </para> + </listitem> + <listitem> + <para> +Parse window geometry + </para> + </listitem> + <listitem> + <para> +Get X environment defaults + </para> + </listitem> +</itemizedlist> +</para> +<sect2 id="Setting_Standard_Properties"> +<title>Setting Standard Properties</title> +<para> +To specify a minimum set of properties describing the simplest application, +use +<function>XSetStandardProperties</function>. +This function has been superseded by +<function>XSetWMProperties</function> +and sets all or portions of the +<property>WM_NAME</property>, <property>WM_ICON_NAME</property>, <property>WM_HINTS</property>, <property>WM_COMMAND</property>, +and <property>WM_NORMAL_HINTS</property> properties. +<indexterm significance="preferred"><primary>XSetStandardProperties</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetstandardproperties'> +<funcprototype> + <funcdef><function>XSetStandardProperties</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> w</parameter></paramdef> + <paramdef>char<parameter> *window_name</parameter></paramdef> + <paramdef>char<parameter> *icon_name</parameter></paramdef> + <paramdef>Pixmap<parameter> icon_pixmap</parameter></paramdef> + <paramdef>char<parameter> **argv</parameter></paramdef> + <paramdef>int<parameter> argc</parameter></paramdef> + <paramdef>XSizeHints<parameter> *hints</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the window. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>window_name</emphasis> + </term> + <listitem> + <para> +Specifies the window name, +which should be a null-terminated string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>icon_name</emphasis> + </term> + <listitem> + <para> +Specifies the icon name, +which should be a null-terminated string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>icon_pixmap</emphasis> + </term> + <listitem> + <para> +Specifies the bitmap that is to be used for the icon or +<symbol>None</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>argv</emphasis> + </term> + <listitem> + <para> +Specifies the application's argument list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>argc</emphasis> + </term> + <listitem> + <para> +Specifies the number of arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hints</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the size hints for the window in its normal state. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XSetStandardProperties</function> +function provides a means by which simple applications set the +most essential properties with a single call. +<function>XSetStandardProperties</function> +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 +<function>XSetStandardProperties</function>. +(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. +</para> +<para> +<!-- .LP --> +<function>XSetStandardProperties</function> +can generate +<errorname>BadAlloc</errorname> +and +<errorname>BadWindow</errorname> +errors. +</para> +</sect2> +<sect2 id="Setting_and_Getting_Window_Sizing_Hints"> +<title>Setting and Getting Window Sizing Hints</title> +<para> +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 +<structname>XSizeHints</structname> +structure, as defined in the +<filename class="headerfile"><X11/Xutil.h></filename> +<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm> +<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm> +<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm> +header file and use the <property>WM_NORMAL_HINTS</property> property. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set the size hints for a given window in its normal state, use +<function>XSetNormalHints</function>. +This function has been superseded by +<function>XSetWMNormalHints</function>. +<indexterm significance="preferred"><primary>XSetNormalHints</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetnormalhints'> +<funcprototype> + <funcdef><function>XSetNormalHints</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> w</parameter></paramdef> + <paramdef>XSizeHints<parameter> *hints</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the window. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hints</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the size hints for the window in its normal state. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XSetNormalHints</function> +function sets the size hints structure for the specified window. +Applications use +<function>XSetNormalHints</function> +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 +<function>XSetNormalHints</function> +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. +</para> +<para> +<!-- .LP --> +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 +<function>XSetNormalHints</function> +is meaningless, unless the flags member is set to indicate which members of +the structure have been assigned values. +</para> +<para> +<!-- .LP --> +<function>XSetNormalHints</function> +can generate +<errorname>BadAlloc</errorname> +and +<errorname>BadWindow</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To return the size hints for a window in its normal state, use +<function>XGetNormalHints</function>. +This function has been superseded by +<function>XGetWMNormalHints</function>. +<indexterm significance="preferred"><primary>XGetNormalHints</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xgetnormalhints'> +<funcprototype> + <funcdef>Status <function>XGetNormalHints</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> w</parameter></paramdef> + <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the window. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hints_return</emphasis> + </term> + <listitem> + <para> +Returns the size hints for the window in its normal state. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XGetNormalHints</function> +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. +</para> +<para> +<!-- .LP --> +<function>XGetNormalHints</function> +can generate a +<errorname>BadWindow</errorname> +error. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +The next two functions set and read the <property>WM_ZOOM_HINTS</property> property. +</para> +<para> +<!-- .LP --> +To set the zoom hints for a window, use +<function>XSetZoomHints</function>. +This function is no longer supported by the +<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>. +<indexterm significance="preferred"><primary>XSetZoomHints</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetzoomhints'> +<funcprototype> + <funcdef><function>XSetZoomHints</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> w</parameter></paramdef> + <paramdef>XSizeHints<parameter> *zhints</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the window. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>zhints</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the zoom hints. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +Many window managers think of windows in one of three states: +iconic, normal, or zoomed. +The +<function>XSetZoomHints</function> +function provides the window manager with information for the window in the +zoomed state. +</para> +<para> +<!-- .LP --> +<function>XSetZoomHints</function> +can generate +<errorname>BadAlloc</errorname> +and +<errorname>BadWindow</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To read the zoom hints for a window, use +<function>XGetZoomHints</function>. +This function is no longer supported by the +<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>. +<indexterm significance="preferred"><primary>XGetZoomHints</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xgetzoomhints'> +<funcprototype> + <funcdef>Status <function>XGetZoomHints</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> w</parameter></paramdef> + <paramdef>XSizeHints<parameter> *zhints_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the window. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>zhints_return</emphasis> + </term> + <listitem> + <para> +Returns the zoom hints. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XGetZoomHints</function> +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. +</para> +<para> +<!-- .LP --> +<function>XGetZoomHints</function> +can generate a +<errorname>BadWindow</errorname> +error. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set the value of any property of type <property>WM_SIZE_HINTS</property>, use +<function>XSetSizeHints</function>. +This function has been superseded by +<function>XSetWMSizeHints</function>. +<indexterm significance="preferred"><primary>XSetSizeHints</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetsizehints'> +<funcprototype> + <funcdef><function>XSetSizeHints</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> w</parameter></paramdef> + <paramdef>XSizeHints<parameter> *hints</parameter></paramdef> + <paramdef>Atom<parameter> property</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the window. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hints</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the size hints. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>property</emphasis> + </term> + <listitem> + <para> +Specifies the property name. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XSetSizeHints</function> +function sets the +<structname>XSizeHints</structname> +structure for the named property and the specified window. +This is used by +<function>XSetNormalHints</function> +and +<function>XSetZoomHints</function> +and can be used to set the value of any property of type <property>WM_SIZE_HINTS</property>. +Thus, it may be useful if other properties of that type get defined. +</para> +<para> +<!-- .LP --> +<function>XSetSizeHints</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadAtom</errorname>, +and +<errorname>BadWindow</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To read the value of any property of type <property>WM_SIZE_HINTS</property>, use +<function>XGetSizeHints</function>. +This function has been superseded by +<function>XGetWMSizeHints</function>. +<indexterm significance="preferred"><primary>XGetSizeHints</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xgetsizehints'> +<funcprototype> + <funcdef>Status <function>XGetSizeHints</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> w</parameter></paramdef> + <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef> + <paramdef>Atom<parameter> property</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the window. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hints_return</emphasis> + </term> + <listitem> + <para> +Returns the size hints. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>property</emphasis> + </term> + <listitem> + <para> +Specifies the property name. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XGetSizeHints</function> +function returns the +<structname>XSizeHints</structname> +structure for the named property and the specified window. +This is used by +<function>XGetNormalHints</function> +and +<function>XGetZoomHints</function>. +It also can be used to retrieve the value of any property of type +<property>WM_SIZE_HINTS</property>. +Thus, it may be useful if other properties of that type get defined. +<function>XGetSizeHints</function> +returns a nonzero status if a size hint was defined +or zero otherwise. +</para> +<para> +<!-- .LP --> +<function>XGetSizeHints</function> +can generate +<errorname>BadAtom</errorname> +and +<errorname>BadWindow</errorname> +errors. +</para> +</sect2> +<sect2 id="Getting_and_Setting_an_XStandardColormap_Structure"> +<title>Getting and Setting an XStandardColormap Structure</title> +<para> +To get the +<structname>XStandardColormap</structname> +structure associated with one of the described atoms, use +<function>XGetStandardColormap</function>. +This function has been superseded by +<function>XGetRGBColormaps</function>. +<indexterm significance="preferred"><primary>XGetStandardColormap</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xgetstandardcolormap'> +<funcprototype> + <funcdef>Status <function>XGetStandardColormap</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> w</parameter></paramdef> + <paramdef>XStandardColormap<parameter> *colormap_return</parameter></paramdef> + <paramdef>Atom<parameter> property</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the window. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>colormap_return</emphasis> + </term> + <listitem> + <para> +Returns the colormap associated with the specified atom. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>property</emphasis> + </term> + <listitem> + <para> +Specifies the property name. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XGetStandardColormap</function> +function returns the colormap definition associated with the atom supplied +as the property argument. +<function>XGetStandardColormap</function> +returns a nonzero status if successful and zero otherwise. +For example, +to fetch the standard +<symbol>GrayScale</symbol> +colormap for a display, +you use +<function>XGetStandardColormap</function> +with the following syntax: +<programlisting> +XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_MAP); +</programlisting> +See section 14.3 for the semantics of standard colormaps. +</para> +<para> +<!-- .LP --> +<function>XGetStandardColormap</function> +can generate +<errorname>BadAtom</errorname> +and +<errorname>BadWindow</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set a standard colormap, use +<function>XSetStandardColormap</function>. +This function has been superseded by +<function>XSetRGBColormaps</function>. +<indexterm significance="preferred"><primary>XSetStandardColormap</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetstandardcolormap'> +<funcprototype> + <funcdef><function>XSetStandardColormap</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> w</parameter></paramdef> + <paramdef>XStandardColormap<parameter> *colormap</parameter></paramdef> + <paramdef>Atom<parameter> property</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the window. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>colormap</emphasis> + </term> + <listitem> + <para> +Specifies the colormap. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>property</emphasis> + </term> + <listitem> + <para> +Specifies the property name. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XSetStandardColormap</function> +function usually is only used by window or session managers. +</para> +<para> +<!-- .LP --> +<function>XSetStandardColormap</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadAtom</errorname>, +<errorname>BadDrawable</errorname>, +and +<errorname>BadWindow</errorname> +errors. +</para> +</sect2> +<sect2 id="Parsing_Window_Geometry"> +<title>Parsing Window Geometry</title> +<para> +To parse window geometry given a user-specified position +and a default position, use +<function>XGeometry</function>. +This function has been superseded by +<function>XWMGeometry</function>. +<indexterm><primary>Window</primary><secondary>determining location</secondary></indexterm> +<indexterm significance="preferred"><primary>XGeometry</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xgeometry'> +<funcprototype> + <funcdef>int <function>XGeometry</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>int<parameter> screen</parameter></paramdef> + <paramdef>char*position,<parameter> *default_position</parameter></paramdef> + <paramdef>unsignedint<parameter> bwidth</parameter></paramdef> + <paramdef>unsignedintfwidth,<parameter> fheight</parameter></paramdef> + <paramdef>intxadder,<parameter> yadder</parameter></paramdef> + <paramdef>int*x_return,<parameter> *y_return</parameter></paramdef> + <paramdef>int*width_return,<parameter> *height_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>screen</emphasis> + </term> + <listitem> + <para> +Specifies the screen. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>position</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>default_position</emphasis> + </term> + <listitem> + <para> +Specify the geometry specifications. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>bwidth</emphasis> + </term> + <listitem> + <para> +Specifies the border width. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>fheight</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>fwidth</emphasis> + </term> + <listitem> + <para> +Specify the font height and width in pixels (increment size). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>xadder</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>yadder</emphasis> + </term> + <listitem> + <para> +Specify additional interior padding needed in the window. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x_return</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y_return</emphasis> + </term> + <listitem> + <para> +Return the x and y offsets. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>width_return</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>height_return</emphasis> + </term> + <listitem> + <para> +Return the width and height determined. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +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 +<function>XGeometry</function> +function returns the position the window should be placed given a position and +a default position. +<function>XGeometry</function> +determines the placement of +a window using a geometry specification as specified by +<function>XParseGeometry</function> +and the additional information about the window. +Given a fully qualified default geometry specification and +an incomplete geometry specification, +<function>XParseGeometry</function> +returns a bitmask value as defined above in the +<function>XParseGeometry</function> +call, +by using the position argument. +</para> +<para> +<!-- .LP --> +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. +</para> +</sect2> +<sect2 id="Getting_the_X_Environment_Defaults"> +<title>Getting the X Environment Defaults</title> +<para> +The +<function>XGetDefault</function> +function provides a primitive interface to the resource manager facilities +discussed in chapter 15. <!-- xref --> +It is only useful in very simple applications. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +<indexterm significance="preferred"><primary>XGetDefault</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xgetdefault'> +<funcprototype> + <funcdef>char *<function>XGetDefault</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>char<parameter> *program</parameter></paramdef> + <paramdef>char<parameter> *option</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>program</emphasis> + </term> + <listitem> + <para> +Specifies the program name for the Xlib defaults (usually argv[0] +of the main program). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>option</emphasis> + </term> + <listitem> + <para> +Specifies the option name. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XGetDefault</function> +function returns the value of the resource <emphasis remap='I'>prog</emphasis>.<emphasis remap='I'>option</emphasis>, +where <emphasis remap='I'>prog</emphasis> is the program argument with the directory prefix removed +and <emphasis remap='I'>option</emphasis> must be a single component. +Note that multilevel resources cannot be used with +<function>XGetDefault</function>. +The class "Program.Name" is always used for the resource lookup. +If the specified option name does not exist for this program, +<function>XGetDefault</function> +returns NULL. +The strings returned by +<function>XGetDefault</function> +are owned by Xlib and should not be modified or freed by the client. +</para> +<para> +<!-- .LP --> +If a database has been set with +<function>XrmSetDatabase</function>, +that database is used for the lookup. +Otherwise, a database is created +and is set in the display (as if by calling +<function>XrmSetDatabase</function>). +The database is created in the current locale. +To create a database, +<function>XGetDefault</function> +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>POSIX</acronym>-conformant system, +this file is +<function>"$HOME/.Xdefaults"</function>. +<indexterm><primary>Files</primary><secondary><filename>$HOME/.Xdefaults</filename></secondary></indexterm> +After loading these defaults, +<function>XGetDefault</function> +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, +<function>XGetDefault</function> +looks for +"<filename>$HOME/.Xdefaults-<replaceable>name</replaceable></filename>" , +where <replaceable>name</replaceable> specifies the name of the machine on which the application +is running. +</para> +</sect2> +</sect1> +<sect1 id="X_Version_10_Compatibility_Functions"> +<title>X Version 10 Compatibility Functions</title> +<para> +You can use the X Version 10 compatibility functions to: +<itemizedlist> + <listitem> + <para> +Draw and fill polygons and curves + </para> + </listitem> + <listitem> + <para> +Associate user data with a value + </para> + </listitem> +</itemizedlist> +</para> +<sect2 id="Drawing_and_Filling_Polygons_and_Curves"> +<title>Drawing and Filling Polygons and Curves</title> +<para> +<!-- .LP --> +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 +<function>XDrawLines</function> +<indexterm><primary>XDrawLines</primary></indexterm> +or +<function>XDrawSegments</function> +<indexterm><primary>XDrawSegments</primary></indexterm> +is much faster. +</para> +<para> +<!-- .LP --> +The functions discussed here provide all the functionality of the +X Version 10 functions +<function>XDraw</function>, +<indexterm ><primary>X10 compatibility</primary><secondary>XDraw</secondary></indexterm> +<function>XDrawFilled</function>, +<indexterm><primary>X10 compatibility</primary><secondary>XDrawFilled</secondary></indexterm> +<function>XDrawPatterned</function>, +<indexterm ><primary>X10 compatibility</primary><secondary>XDrawPatterned</secondary></indexterm> +<function>XDrawDashed</function>, +<indexterm><primary>X10 compatibility</primary><secondary>XDrawDashed</secondary></indexterm> +and +<function>XDrawTiled</function>. +<indexterm><primary>X10 compatibility</primary><secondary>XDrawTiled</secondary></indexterm> +They are as compatible as possible given X Version 11's new line-drawing +functions. +One thing to note, however, is that +<function>VertexDrawLastPoint</function> +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). +<function>XAppendVertex</function> +and +<function>XClearVertexFlag</function> +from X Version 10 also are not supported. +</para> +<para> +<!-- .LP --> +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 +<function>XDrawLines</function>). +The functions discussed here fail (return zero) only if they run out of memory +or are passed a +<structname>Vertex</structname> +list that has a +<structname>Vertex</structname> +with +<symbol>VertexStartClosed</symbol> +set that is not followed by a +<structname>Vertex</structname> +with +<symbol>VertexEndClosed</symbol> +set. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To achieve the effects of the X Version 10 +<function>XDraw</function>, +<indexterm ><primary>X10 compatibility</primary><secondary>XDraw</secondary></indexterm> +<function>XDrawDashed</function>, +<indexterm><primary>X10 compatibility</primary><secondary>XDrawDashed</secondary></indexterm> +and +<function>XDrawPatterned</function>, +<indexterm ><primary>X10 compatibility</primary><secondary>XDrawPatterned</secondary></indexterm> +use +<function>XDraw</function>. +</para> + +<para> +#include <X11/X10.h> +</para> + +<funcsynopsis id='xdraw'> +<funcprototype> + <funcdef>Status <function>XDraw</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>Vertex<parameter> *vlist</parameter></paramdef> + <paramdef>int<parameter> vcount</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>d</emphasis> + </term> + <listitem> + <para> +Specifies the drawable. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>vlist</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the list of vertices that indicate what to draw. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>vcount</emphasis> + </term> + <listitem> + <para> +Specifies how many vertices are in vlist. + </para> + </listitem> + </varlistentry> +</variablelist> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XDraw</function> +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. +</para> +<para> +<!-- .LP --> +Each Vertex, as defined in +<filename class="headerfile"><X11/X10.h></filename>, +<indexterm type="file"><primary><filename class="headerfile">X11/X10.h</filename></primary></indexterm> +<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/X10.h></filename></secondary></indexterm> +<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/X10.h></filename></secondary></indexterm> +is a structure with the following members: +<indexterm significance="preferred"><primary>Vertex</primary></indexterm> +<synopsis> +typedef struct _Vertex { + short x,y; + unsigned short flags; +} Vertex; +</synopsis> +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 +<symbol>VertexRelative</symbol> +is zero) or the previous vertex (if +<symbol>VertexRelative</symbol> +is one). +</para> +<para> +<!-- .LP --> +The flags, as defined in +<filename class="headerfile"><X11/X10.h></filename>, +<indexterm type="file"><primary><filename class="headerfile">X11/X10.h</filename></primary></indexterm> +<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/X10.h></filename></secondary></indexterm> +<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/X10.h></filename></secondary></indexterm> +are as follows: +<indexterm significance="preferred"><primary>VertexRelative</primary></indexterm> +<indexterm significance="preferred"><primary>VertexDontDraw</primary></indexterm> +<indexterm significance="preferred"><primary>VertexCurved</primary></indexterm> +<indexterm significance="preferred"><primary>VertexStartClosed</primary></indexterm> +<indexterm significance="preferred"><primary>VertexEndClosed</primary></indexterm> +<!-- .sM --> + +<synopsis> +VertexRelative 0x0001 /* else absolute */ +VertexDontDraw 0x0002 /* else draw */ +VertexCurved 0x0004 /* else straight */ +VertexStartClosed 0x0008 /* else not */ +VertexEndClosed 0x0010 /* else not */ +</synopsis> + +<itemizedlist> + <listitem> + <para> +If +<symbol>VertexRelative</symbol> +is not set, +the coordinates are absolute (that is, relative to the drawable's origin). +The first vertex must be an absolute vertex. + </para> + </listitem> + <listitem> + <para> +If +<symbol>VertexDontDraw</symbol> +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. + </para> + </listitem> + <listitem> + <para> +If +<symbol>VertexCurved</symbol> +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 +<symbol>VertexCurved</symbol> +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). + </para> + </listitem> + <listitem> + <para> +It is permissible for +<symbol>VertexDontDraw</symbol> +bits and +<symbol>VertexCurved</symbol> +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. + </para> + </listitem> + <listitem> + <para> +If +<symbol>VertexStartClosed</symbol> +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 +<symbol>VertexEndClosed</symbol> +bit of one. +The points in between form a cycle to determine predecessor +and successor vertices for the spline algorithm. + </para> + </listitem> +</itemizedlist> +</para> +<para> +<!-- .LP --> +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. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To achieve the effects of the X Version 10 +<function>XDrawTiled</function> +<indexterm><primary>X10 compatibility</primary><secondary>XDrawTiled</secondary></indexterm> +and +<function>XDrawFilled</function>, +<indexterm><primary>X10 compatibility</primary><secondary>XDrawFilled</secondary></indexterm> +use +<function>XDrawFilled</function>. +</para> + +<para>#include <X11/X10.h></para> + +<funcsynopsis id='xdrawfilled'> +<funcprototype> + <funcdef>Status <function>XDrawFilled</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>Vertex<parameter> *vlist</parameter></paramdef> + <paramdef>int<parameter> vcount</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>d</emphasis> + </term> + <listitem> + <para> +Specifies the drawable. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>vlist</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the list of vertices that indicate what to draw. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>vcount</emphasis> + </term> + <listitem> + <para> +Specifies how many vertices are in vlist. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XDrawFilled</function> +function draws arbitrary polygons or curves and then fills them. +</para> +<para> +<!-- .LP --> +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. +</para> +</sect2> +<sect2 id="Associating_User_Data_with_a_Value"> +<title>Associating User Data with a Value</title> +<para> +<!-- .LP --> +These functions have been superseded by the context management functions +(see section 16.10). +It is often necessary to associate arbitrary information with resource IDs. +Xlib provides the +<function>XAssocTable</function> +functions that you can use to make such an association. +<indexterm><primary>Hash Lookup</primary></indexterm> +<indexterm><primary>Window</primary><secondary>IDs</secondary></indexterm> +<indexterm><primary>Resource IDs</primary></indexterm> +Application programs often need to be able to easily refer to +their own data structures when an event arrives. +The +<function>XAssocTable</function> +system provides users of the X library with a method +for associating their own data structures with X resources +(<type>Pixmap</type>s, +<type>Font</type>s, +<type>Window</type>s, +and so on). +</para> +<para> +<!-- .LP --> +An +<function>XAssocTable</function> +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. +</para> +<para> +<!-- .LP --> +There are a few guidelines that should be observed when using an +<function>XAssocTable</function> : +</para> +<itemizedlist> + <listitem> + <para> +All XIDs are relative to the specified display. + </para> + </listitem> + <listitem> + <para> +Because of the hashing scheme used by the association mechanism, +the following rules for determining the size of a +<function>XAssocTable</function> +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. + </para> + </listitem> +</itemizedlist> + +<para> +<!-- .LP --> +<!-- .sp --> +To return a pointer to a new +<function>XAssocTable</function>, +use +<function>XCreateAssocTable</function>. +<indexterm significance="preferred"><primary>XCreateAssocTable</primary></indexterm> +<!-- .sM --> +</para> +<funcsynopsis id='xcreateassoctable'> +<funcprototype> + <funcdef>XAssocTable *<function>XCreateAssocTable</function></funcdef> + <paramdef>int<parameter> size</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>size</emphasis> + </term> + <listitem> + <para> +Specifies the number of buckets in the hash system of +<function>XAssocTable</function>. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<!-- .LP --> +<!-- .eM --> +The size argument specifies the number of buckets in the +hash system of +<function>XAssocTable</function>. +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 +<function>XAssocTable</function> +occurs, +a NULL pointer is returned. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To create an entry in a given +<function>XAssocTable</function>, +use +<function>XMakeAssoc</function>. +<indexterm significance="preferred"><primary>XMakeAssoc</primary></indexterm> +<!-- .sM --> +</para> +<funcsynopsis id='xmakeassoc'> +<funcprototype> + <funcdef><function>XMakeAssoc</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XAssocTable<parameter> *table</parameter></paramdef> + <paramdef>XID<parameter> x_id</parameter></paramdef> + <paramdef>char<parameter> *data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>table</emphasis> + </term> + <listitem> + <para> +Specifies the assoc table. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x_id</emphasis> + </term> + <listitem> + <para> +Specifies the X resource ID. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>data</emphasis> + </term> + <listitem> + <para> +Specifies the data to be associated with the X resource ID. + </para> + </listitem> + </varlistentry> +</variablelist> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XMakeAssoc</function> +function inserts data into an +<function>XAssocTable</function> +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. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To obtain data from a given +<function>XAssocTable</function>, +use +<function>XLookUpAssoc</function>. +<indexterm significance="preferred"><primary>XLookUpAssoc</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xlookupassoc'> +<funcprototype> + <funcdef>char *<function>XLookUpAssoc</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XAssocTable<parameter> *table</parameter></paramdef> + <paramdef>XID<parameter> x_id</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>table</emphasis> + </term> + <listitem> + <para> +Specifies the assoc table. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x_id</emphasis> + </term> + <listitem> + <para> +Specifies the X resource ID. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XLookUpAssoc</function> +function retrieves the data stored in an +<function>XAssocTable</function> +by its XID. +If an appropriately matching XID can be found in the table, +<function>XLookUpAssoc</function> +returns the data associated with it. +If the x_id cannot be found in the table, +it returns NULL. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To delete an entry from a given +<function>XAssocTable</function>, +use +<function>XDeleteAssoc</function>. +<indexterm significance="preferred"><primary>XDeleteAssoc</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xdeleteassoc'> +<funcprototype> + <funcdef><function>XDeleteAssoc</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XAssocTable<parameter> *table</parameter></paramdef> + <paramdef>XID<parameter> x_id</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>table</emphasis> + </term> + <listitem> + <para> +Specifies the assoc table. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x_id</emphasis> + </term> + <listitem> + <para> +Specifies the X resource ID. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XDeleteAssoc</function> +function deletes an association in an +<function>XAssocTable</function> +keyed on its XID. +Redundant deletes (and deletes of nonexistent XIDs) are ignored. +Deleting associations in no way impairs the performance of an +<function>XAssocTable</function>. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To free the memory associated with a given +<function>XAssocTable</function>, +use +<function>XDestroyAssocTable</function>. +</para> +<indexterm significance="preferred"><primary>XDestroyAssocTable</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xdestroyassoctable'> +<funcprototype> + <funcdef><function>XDestroyAssocTable</function></funcdef> + <paramdef>XAssocTable<parameter> *table</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>table</emphasis> + </term> + <listitem> + <para> +Specifies the assoc table. + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> +</sect1> +</appendix> |