diff options
Diffstat (limited to 'libX11/specs/libX11/CH08.xml')
| -rw-r--r-- | libX11/specs/libX11/CH08.xml | 11932 |
1 files changed, 5966 insertions, 5966 deletions
diff --git a/libX11/specs/libX11/CH08.xml b/libX11/specs/libX11/CH08.xml index 6cd6679f2..3d69b1420 100644 --- a/libX11/specs/libX11/CH08.xml +++ b/libX11/specs/libX11/CH08.xml @@ -1,5966 +1,5966 @@ -<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
-<chapter id="graphics_functions">
-<title>Graphics Functions</title>
-<para>
-Once you have established a connection to a display, you can use the Xlib graphics functions to:
-</para>
-<itemizedlist>
- <listitem><para>Clear and copy areas</para></listitem>
- <listitem><para>Draw points, lines, rectangles, and arcs</para></listitem>
- <listitem><para>Fill areas</para></listitem>
- <listitem><para>Manipulate fonts</para></listitem>
- <listitem><para>Draw text</para></listitem>
- <listitem><para>Transfer images between clients and the server</para></listitem>
-</itemizedlist>
-<para>
-If the same drawable and GC is used for each call, Xlib batches back-to-back
-calls to XDrawPoint, XDrawLine, XDrawRectangle, XFillArc, and XFillRectangle.
-Note that this reduces the total number of requests sent to the server.
-</para>
-<sect1 id="Clearing_Areas">
-<title>Clearing Areas</title>
-<!-- .XS -->
-<!-- (SN Clearing Areas -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-Xlib provides functions that you can use to clear an area or the entire window.
-Because pixmaps do not have defined backgrounds,
-they cannot be filled by using the functions described in this section.
-Instead, to accomplish an analogous operation on a pixmap,
-you should use
-<function>XFillRectangle</function>,
-which sets the pixmap to a known value.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To clear a rectangular area of a given window, use
-<function>XClearArea</function>.
-<indexterm><primary>Areas</primary><secondary>clearing</secondary></indexterm>
-<indexterm><primary>Clearing</primary><secondary>areas</secondary></indexterm>
-<indexterm significance="preferred"><primary>XClearArea</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XClearArea</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Window<parameter> w</parameter></paramdef>
- <paramdef>intx,<parameter> y</parameter></paramdef>
- <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
- <paramdef>Bool<parameter> exposures</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.
-<!-- .ds Xy , which are relative to the origin of the window \ -->
-and specify the upper-left corner of the rectangle
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates(Xy.
-<!-- .ds Wh , which are the dimensions of the rectangle -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>width</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>height</emphasis>
- </term>
- <listitem>
- <para>
-Specify the width and height(Wh.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>exposures</emphasis>
- </term>
- <listitem>
- <para>
-Specifies a Boolean value that indicates if
-<symbol>Expose</symbol>
-events are to be generated.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XClearArea</function>
-function paints a rectangular area in the specified window according to the
-specified dimensions with the window's background pixel or pixmap.
-The subwindow-mode effectively is
-<symbol>ClipByChildren</symbol>.
-If width is zero, it
-is replaced with the current width of the window minus x.
-If height is
-zero, it is replaced with the current height of the window minus y.
-If the window has a defined background tile,
-the rectangle clipped by any children is filled with this tile.
-If the window has
-background
-<symbol>None</symbol>,
-the contents of the window are not changed.
-In either
-case, if exposures is
-<symbol>True</symbol>,
-one or more
-<symbol>Expose</symbol>
-events are generated for regions of the rectangle that are either visible or are
-being retained in a backing store.
-If you specify a window whose class is
-<symbol>InputOnly</symbol>,
-a
-<errorname>BadMatch</errorname>
-error results.
-</para>
-<para>
-<!-- .LP -->
-<function>XClearArea</function>
-can generate
-<errorname>BadMatch</errorname>,
-<errorname>BadValue</errorname>,
-and
-<errorname>BadWindow</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To clear the entire area in a given window, use
-<function>XClearWindow</function>.
-<indexterm><primary>Window</primary><secondary>clearing</secondary></indexterm>
-<indexterm><primary>Clearing</primary><secondary>windows</secondary></indexterm>
-<indexterm significance="preferred"><primary>XClearWindow</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XClearWindow</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Window<parameter> w</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>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XClearWindow</function>
-function clears the entire area in the specified window and is
-equivalent to
-<function>XClearArea</function>
-(display, w, 0, 0, 0, 0,
-<symbol>False</symbol>).
-If the window has a defined background tile, the rectangle is tiled with a
-plane-mask of all ones and
-<symbol>GXcopy</symbol>
-function.
-If the window has
-background
-<symbol>None</symbol>,
-the contents of the window are not changed.
-If you specify a window whose class is
-<symbol>InputOnly</symbol>,
-a
-<errorname>BadMatch</errorname>
-error results.
-</para>
-<para>
-<!-- .LP -->
-<function>XClearWindow</function>
-can generate
-<errorname>BadMatch</errorname>
-and
-<errorname>BadWindow</errorname>
-errors.
-</para>
-</sect1>
-<sect1 id="Copying_Areas">
-<title>Copying Areas</title>
-<!-- .XS -->
-<!-- (SN Copying Areas -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-Xlib provides functions that you can use to copy an area or a bit plane.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To copy an area between drawables of the same
-root and depth, use
-<function>XCopyArea</function>.
-<indexterm><primary>Areas</primary><secondary>copying</secondary></indexterm>
-<indexterm><primary>Copying</primary><secondary>areas</secondary></indexterm>
-<indexterm significance="preferred"><primary>XCopyArea</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XCopyArea</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawablesrc,<parameter> dest</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>
- <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
- <paramdef>intdest_x,<parameter> dest_y</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'>src</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>dest</emphasis>
- </term>
- <listitem>
- <para>
-Specify the source and destination rectangles to be combined.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>src_x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>src_y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates,
-which are relative to the origin of the source rectangle
-and specify its upper-left corner.
-<!-- .ds Wh , which are the dimensions of both the source \ -->
-and destination rectangles
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>width</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>height</emphasis>
- </term>
- <listitem>
- <para>
-Specify the width and height(Wh.
-<!-- .ds Dx , which are relative to the origin of the destination rectangle \ -->
-and specify its upper-left corner
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>dest_x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>dest_y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates(Dx.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XCopyArea</function>
-function combines the specified rectangle of src with the specified rectangle
-of dest.
-The drawables must have the same root and depth,
-or a
-<errorname>BadMatch</errorname>
-error results.
-</para>
-<para>
-<!-- .LP -->
-If regions of the source rectangle are obscured and have not been
-retained in backing store
-or if regions outside the boundaries of the source drawable are specified,
-those regions are not copied.
-Instead, the
-following occurs on all corresponding destination regions that are either
-visible or are retained in backing store.
-If the destination is a window with a background other than
-<symbol>None</symbol>,
-corresponding regions
-of the destination are tiled with that background
-(with plane-mask of all ones and
-<symbol>GXcopy</symbol>
-function).
-Regardless of tiling or whether the destination is a window or a pixmap,
-if graphics-exposures is
-<symbol>True</symbol>,
-then
-<symbol>GraphicsExpose</symbol>
-events for all corresponding destination regions are generated.
-If graphics-exposures is
-<symbol>True</symbol>
-but no
-<symbol>GraphicsExpose</symbol>
-events are generated, a
-<symbol>NoExpose</symbol>
-event is generated.
-Note that by default graphics-exposures is
-<symbol>True</symbol>
-in new GCs.
-</para>
-<para>
-<!-- .LP -->
-This function uses these GC components: function, plane-mask,
-subwindow-mode, graphics-exposures, clip-x-origin,
-clip-y-origin, and clip-mask.
-</para>
-<para>
-<!-- .LP -->
-<function>XCopyArea</function>
-can generate
-<errorname>BadDrawable</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadMatch</errorname>
-errors.
-<!-- .sp -->
-</para>
-<para>
-<!-- .LP -->
-To copy a single bit plane of a given drawable, use
-<function>XCopyPlane</function>.
-<indexterm><primary>Plane</primary><secondary>copying</secondary></indexterm>
-<indexterm><primary>Copying</primary><secondary>planes</secondary></indexterm>
-<indexterm significance="preferred"><primary>XCopyPlane</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XCopyPlane</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawablesrc,<parameter> dest</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>
- <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
- <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>
- <paramdef>unsignedlong<parameter> plane</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'>src</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>dest</emphasis>
- </term>
- <listitem>
- <para>
-Specify the source and destination rectangles to be combined.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>src_x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>src_y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates,
-which are relative to the origin of the source rectangle
-and specify its upper-left corner.
-<!-- .ds Wh , which are the dimensions of both the source and destination rectangles -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>width</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>height</emphasis>
- </term>
- <listitem>
- <para>
-Specify the width and height(Wh.
-<!-- .ds Dx , which are relative to the origin of the destination rectangle \ -->
-and specify its upper-left corner
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>dest_x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>dest_y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates(Dx.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>plane</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the bit plane.
-You must set exactly one bit to 1.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XCopyPlane</function>
-function uses a single bit plane of the specified source rectangle
-combined with the specified GC to modify the specified rectangle of dest.
-The drawables must have the same root but need not have the same depth.
-If the drawables do not have the same root, a
-<errorname>BadMatch</errorname>
-error results.
-If plane does not have exactly one bit set to 1 and the value of plane
-is not less than %2 sup n%, where <emphasis remap='I'>n</emphasis> is the depth of src, a
-<errorname>BadValue</errorname>
-error results.
-</para>
-<para>
-<!-- .LP -->
-Effectively,
-<function>XCopyPlane</function>
-forms a pixmap of the same depth as the rectangle of dest and with a
-size specified by the source region.
-It uses the foreground/background pixels in the GC (foreground
-everywhere the bit plane in src contains a bit set to 1,
-background everywhere the bit plane in src contains a bit set to 0)
-and the equivalent of a
-<systemitem>CopyArea</systemitem>
-protocol request is performed with all the same exposure semantics.
-This can also be thought of as using the specified region of the source
-bit plane as a stipple with a fill-style of
-<symbol>FillOpaqueStippled</symbol>
-for filling a rectangular area of the destination.
-</para>
-<para>
-<!-- .LP -->
-This function uses these GC components: function, plane-mask, foreground,
-background, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin,
-and clip-mask.
-</para>
-<para>
-<!-- .LP -->
-<function>XCopyPlane</function>
-can generate
-<errorname>BadDrawable</errorname>,
-<errorname>BadGC</errorname>,
-<errorname>BadMatch</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-</sect1>
-<sect1 id="Drawing_Points_Lines_Rectangles_and_Arcs">
-<title>Drawing Points, Lines, Rectangles, and Arcs</title>
-<!-- .XS -->
-<!-- (SN Drawing Points, Lines, Rectangles, and Arcs -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-Xlib provides functions that you can use to draw:
-</para>
-<itemizedlist>
- <listitem>
- <para>
-A single point or multiple points
- </para>
- </listitem>
- <listitem>
- <para>
-A single line or multiple lines
- </para>
- </listitem>
- <listitem>
- <para>
-A single rectangle or multiple rectangles
- </para>
- </listitem>
- <listitem>
- <para>
-A single arc or multiple arcs
- </para>
- </listitem>
-</itemizedlist>
-<para>
-<!-- .LP -->
-Some of the functions described in the following sections
-use these structures:
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XSegment</primary></indexterm>
-<!-- .sM -->
-<literallayout class="monospaced">
-<!-- .TA .5i -->
-<!-- .ta .5i -->
-typedef struct {
- short x1, y1, x2, y2;
-} XSegment;
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<indexterm significance="preferred"><primary>XPoint</primary></indexterm>
-<!-- .sM -->
-<literallayout class="monospaced">
-<!-- .TA .5i -->
-<!-- .ta .5i -->
-typedef struct {
- short x, y;
-} XPoint;
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<indexterm significance="preferred"><primary>XRectangle</primary></indexterm>
-<!-- .sM -->
-<literallayout class="monospaced">
-<!-- .TA .5i -->
-<!-- .ta .5i -->
-typedef struct {
- short x, y;
- unsigned short width, height;
-} XRectangle;
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<indexterm significance="preferred"><primary>XArc</primary></indexterm>
-<!-- .sM -->
-<literallayout class="monospaced">
-<!-- .TA .5i 3i -->
-<!-- .ta .5i 3i -->
-typedef struct {
- short x, y;
- unsigned short width, height;
- short angle1, angle2; /* Degrees * 64 */
-} XArc;
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-All x and y members are signed integers.
-The width and height members are 16-bit unsigned integers.
-You should be careful not to generate coordinates and sizes
-out of the 16-bit ranges, because the protocol only has 16-bit fields
-for these values.
-</para>
-<sect2 id="Drawing_Single_and_Multiple_Points">
-<title>Drawing Single and Multiple Points</title>
-<!-- .XS -->
-<!-- (SN Drawing Single and Multiple Points -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm><primary>Points</primary><secondary>drawing</secondary></indexterm>
-<indexterm><primary>Drawing</primary><secondary>points</secondary></indexterm>
-<indexterm><primary>XDrawPoints</primary></indexterm>
-<indexterm><primary>XDrawPoint</primary></indexterm>
-</para>
-<para>
-<!-- .LP -->
-To draw a single point in a given drawable, use
-<function>XDrawPoint</function>.
-<indexterm significance="preferred"><primary>XDrawPoint</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XDrawPoint</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>intx,<parameter> y</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'>x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates where you want the point drawn.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-To draw multiple points in a given drawable, use
-<function>XDrawPoints</function>.
-<indexterm significance="preferred"><primary>XDrawPoints</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XDrawPoints</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>XPoint<parameter> *points</parameter></paramdef>
- <paramdef>int<parameter> npoints</parameter></paramdef>
- <paramdef>int<parameter> mode</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'>points</emphasis>
- </term>
- <listitem>
- <para>
-Specifies an array of points.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>npoints</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of points in the array.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>mode</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the coordinate mode.
-You can pass
-<symbol>CoordModeOrigin</symbol>
-or
-<symbol>CoordModePrevious</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XDrawPoint</function>
-function uses the foreground pixel and function components of the
-GC to draw a single point into the specified drawable;
-<function>XDrawPoints</function>
-draws multiple points this way.
-<symbol>CoordModeOrigin</symbol>
-treats all coordinates as relative to the origin,
-and
-<symbol>CoordModePrevious</symbol>
-treats all coordinates after the first as relative to the previous point.
-<function>XDrawPoints</function>
-draws the points in the order listed in the array.
-</para>
-<para>
-<!-- .LP -->
-Both functions use these GC components: function, plane-mask,
-foreground, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
-</para>
-<para>
-<!-- .LP -->
-<function>XDrawPoint</function>
-can generate
-<errorname>BadDrawable</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadMatch</errorname>
-errors.
-<function>XDrawPoints</function>
-can generate
-<errorname>BadDrawable</errorname>,
-<errorname>BadGC</errorname>,
-<errorname>BadMatch</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-</sect2>
-<sect2 id="Drawing_Single_and_Multiple_Lines">
-<title>Drawing Single and Multiple Lines</title>
-<!-- .XS -->
-<!-- (SN Drawing Single and Multiple Lines -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm><primary>Lines</primary><secondary>drawing</secondary></indexterm>
-<indexterm><primary>Drawing</primary><secondary>lines</secondary></indexterm>
-<indexterm><primary>XDrawLine</primary></indexterm>
-<indexterm><primary>XDrawLines</primary></indexterm>
-<indexterm><primary>Polygons</primary><secondary>drawing</secondary></indexterm>
-<indexterm><primary>Drawing</primary><secondary>polygons</secondary></indexterm>
-<indexterm><primary>XDrawSegments</primary></indexterm>
-</para>
-<para>
-<!-- .LP -->
-To draw a single line between two points in a given drawable, use
-<function>XDrawLine</function>.
-<indexterm significance="preferred"><primary>XDrawLine</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XDrawLine</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>intx1,y1,x2,<parameter> y2</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'>x1</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>y1</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>x2</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>y2</emphasis>
- </term>
- <listitem>
- <para>
-Specify the points (x1, y1) and (x2, y2) to be connected.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-To draw multiple lines in a given drawable, use
-<function>XDrawLines</function>.
-<indexterm significance="preferred"><primary>XDrawLines</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XDrawLines</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>XPoint<parameter> *points</parameter></paramdef>
- <paramdef>int<parameter> npoints</parameter></paramdef>
- <paramdef>int<parameter> mode</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'>points</emphasis>
- </term>
- <listitem>
- <para>
-Specifies an array of points.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>npoints</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of points in the array.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>mode</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the coordinate mode.
-You can pass
-<symbol>CoordModeOrigin</symbol>
-or
-<symbol>CoordModePrevious</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-To draw multiple, unconnected lines in a given drawable,
-use
-<function>XDrawSegments</function>.
-<indexterm significance="preferred"><primary>XDrawSegments</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XDrawSegments</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>XSegment<parameter> *segments</parameter></paramdef>
- <paramdef>int<parameter> nsegments</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'>segments</emphasis>
- </term>
- <listitem>
- <para>
-Specifies an array of segments.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>nsegments</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of segments in the array.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XDrawLine</function>
-function uses the components of the specified GC to
-draw a line between the specified set of points (x1, y1) and (x2, y2).
-It does not perform joining at coincident endpoints.
-For any given line,
-<function>XDrawLine</function>
-does not draw a pixel more than once.
-If lines intersect, the intersecting pixels are drawn multiple times.
-</para>
-<para>
-<!-- .LP -->
-The
-<function>XDrawLines</function>
-function uses the components of the specified GC to draw
-npoints-1 lines between each pair of points (point[i], point[i+1])
-in the array of
-<structname>XPoint</structname>
-structures.
-It draws the lines in the order listed in the array.
-The lines join correctly at all intermediate points, and if the first and last
-points coincide, the first and last lines also join correctly.
-For any given line,
-<function>XDrawLines</function>
-does not draw a pixel more than once.
-If thin (zero line-width) lines intersect,
-the intersecting pixels are drawn multiple times.
-If wide lines intersect, the intersecting pixels are drawn only once, as though
-the entire
-<systemitem>PolyLine</systemitem>
-protocol request were a single, filled shape.
-<symbol>CoordModeOrigin</symbol>
-treats all coordinates as relative to the origin,
-and
-<symbol>CoordModePrevious</symbol>
-treats all coordinates after the first as relative to the previous point.
-</para>
-<para>
-<!-- .LP -->
-The
-<function>XDrawSegments</function>
-function draws multiple, unconnected lines.
-For each segment,
-<function>XDrawSegments</function>
-draws a
-line between (x1, y1) and (x2, y2).
-It draws the lines in the order listed in the array of
-<structname>XSegment</structname>
-structures and does not perform joining at coincident endpoints.
-For any given line,
-<function>XDrawSegments</function>
-does not draw a pixel more than once.
-If lines intersect, the intersecting pixels are drawn multiple times.
-</para>
-<para>
-<!-- .LP -->
-All three functions use these GC components:
-function, plane-mask, line-width,
-line-style, cap-style, fill-style, subwindow-mode,
-clip-x-origin, clip-y-origin, and clip-mask.
-The
-<function>XDrawLines</function>
-function also uses the join-style GC component.
-All three functions also use these GC mode-dependent components:
-foreground, background, tile, stipple, tile-stipple-x-origin,
-tile-stipple-y-origin, dash-offset, and dash-list.
-</para>
-<para>
-<!-- .LP -->
-<function>XDrawLine</function>,
-<function>XDrawLines</function>,
-and
-<function>XDrawSegments</function>
-can generate
-<errorname>BadDrawable</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadMatch</errorname>
-errors.
-<function>XDrawLines</function>
-also can generate
-<errorname>BadValue</errorname>
-errors.
-</para>
-</sect2>
-<sect2 id="Drawing_Single_and_Multiple_Rectangles_">
-<title>Drawing Single and Multiple Rectangles </title>
-<!-- .XS -->
-<!-- (SN Drawing Single and Multiple Rectangles -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm><primary>Rectangles</primary><secondary>drawing</secondary></indexterm>
-<indexterm><primary>Drawing</primary><secondary>rectangles</secondary></indexterm>
-<indexterm><primary>XDrawRectangle</primary></indexterm>
-<indexterm><primary>XDrawRectangles</primary></indexterm>
-</para>
-<para>
-<!-- .LP -->
-To draw the outline of a single rectangle in a given drawable, use
-<function>XDrawRectangle</function>.
-<indexterm significance="preferred"><primary>XDrawRectangle</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XDrawRectangle</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>intx,<parameter> y</parameter></paramdef>
- <paramdef>unsignedintwidth,<parameter> height</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.
-<!-- .ds Xy , which specify the upper-left corner of the rectangle -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates(Xy.
-<!-- .ds Wh , which specify the dimensions of the rectangle -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>width</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>height</emphasis>
- </term>
- <listitem>
- <para>
-Specify the width and height(Wh.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-To draw the outline of multiple rectangles
-in a given drawable, use
-<function>XDrawRectangles</function>.
-<indexterm significance="preferred"><primary>XDrawRectangles</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XDrawRectangles</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>XRectangle<parameter> rectangles[]</parameter></paramdef>
- <paramdef>int<parameter> nrectangles</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'>rectangles</emphasis>
- </term>
- <listitem>
- <para>
-Specifies an array of rectangles.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>nrectangles</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of rectangles in the array.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XDrawRectangle</function>
-and
-<function>XDrawRectangles</function>
-functions draw the outlines of the specified rectangle or rectangles as
-if a five-point
-<systemitem>PolyLine</systemitem>
-protocol request were specified for each rectangle:
-</para>
-<itemizedlist>
- <listitem>
- <para>
-[x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y]
- </para>
- </listitem>
-</itemizedlist>
-<para>
-<!-- .LP -->
-For the specified rectangle or rectangles,
-these functions do not draw a pixel more than once.
-<function>XDrawRectangles</function>
-draws the rectangles in the order listed in the array.
-If rectangles intersect,
-the intersecting pixels are drawn multiple times.
-</para>
-<para>
-<!-- .LP -->
-Both functions use these GC components:
-function, plane-mask, line-width,
-line-style, cap-style, join-style, fill-style,
-subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
-They also use these GC mode-dependent components:
-foreground, background, tile, stipple, tile-stipple-x-origin,
-tile-stipple-y-origin, dash-offset, and dash-list.
-</para>
-<para>
-<!-- .LP -->
-<function>XDrawRectangle</function>
-and
-<function>XDrawRectangles</function>
-can generate
-<errorname>BadDrawable</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadMatch</errorname>
-errors.
-</para>
-</sect2>
-<sect2 id="Drawing_Single_and_Multiple_Arcs">
-<title>Drawing Single and Multiple Arcs</title>
-<!-- .XS -->
-<!-- (SN Drawing Single and Multiple Arcs -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm><primary>Drawing</primary><secondary>arcs</secondary></indexterm>
-<indexterm><primary>XDrawArc</primary></indexterm>
-<indexterm><primary>Arcs</primary><secondary>drawing</secondary></indexterm>
-<indexterm><primary>XDrawArcs</primary></indexterm>
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To draw a single arc in a given drawable, use
-<function>XDrawArc</function>.
-<indexterm significance="preferred"><primary>XDrawArc</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XDrawArc</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>intx,<parameter> y</parameter></paramdef>
- <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
- <paramdef>intangle1,<parameter> angle2</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.
-<!-- .ds Xy , which are relative to the origin of the drawable \ -->
-and specify the upper-left corner of the bounding rectangle
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates(Xy.
-<!-- .ds Wh , which are the major and minor axes of the arc -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>width</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>height</emphasis>
- </term>
- <listitem>
- <para>
-Specify the width and height(Wh.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>angle1</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the start of the arc relative to the three-o'clock position
-from the center, in units of degrees * 64.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>angle2</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the path and extent of the arc relative to the start of the
-arc, in units of degrees * 64.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-To draw multiple arcs in a given drawable, use
-<function>XDrawArcs</function>.
-<indexterm significance="preferred"><primary>XDrawArcs</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XDrawArcs</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>XArc<parameter> *arcs</parameter></paramdef>
- <paramdef>int<parameter> narcs</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'>arcs</emphasis>
- </term>
- <listitem>
- <para>
-Specifies an array of arcs.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>narcs</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of arcs in the array.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .EQ -->
-delim %%
-<!-- .EN -->
-<function>XDrawArc</function>
-draws a single circular or elliptical arc, and
-<function>XDrawArcs</function>
-draws multiple circular or elliptical arcs.
-Each arc is specified by a rectangle and two angles.
-The center of the circle or ellipse is the center of the
-rectangle, and the major and minor axes are specified by the width and height.
-Positive angles indicate counterclockwise motion,
-and negative angles indicate clockwise motion.
-If the magnitude of angle2 is greater than 360 degrees,
-<function>XDrawArc</function>
-or
-<function>XDrawArcs</function>
-truncates it to 360 degrees.
-</para>
-<para>
-<!-- .LP -->
-For an arc specified as %[ ~x, ~y, ~width , ~height, ~angle1, ~angle2 ]%,
-the origin of the major and minor axes is at
-% [ x +^ {width over 2} , ~y +^ {height over 2} ]%,
-and the infinitely thin path describing the entire circle or ellipse
-intersects the horizontal axis at % [ x, ~y +^ {height over 2} ]% and
-% [ x +^ width , ~y +^ { height over 2 }] %
-and intersects the vertical axis at % [ x +^ { width over 2 } , ~y ]% and
-% [ x +^ { width over 2 }, ~y +^ height ]%.
-These coordinates can be fractional
-and so are not truncated to discrete coordinates.
-The path should be defined by the ideal mathematical path.
-For a wide line with line-width lw,
-the bounding outlines for filling are given
-by the two infinitely thin paths consisting of all points whose perpendicular
-distance from the path of the circle/ellipse is equal to lw/2
-(which may be a fractional value).
-The cap-style and join-style are applied the same as for a line
-corresponding to the tangent of the circle/ellipse at the endpoint.
-</para>
-<para>
-<!-- .LP -->
-For an arc specified as % [ ~x, ~y, ~width, ~height, ~angle1, ~angle2 ]%,
-the angles must be specified
-in the effectively skewed coordinate system of the ellipse (for a
-circle, the angles and coordinate systems are identical). The
-relationship between these angles and angles expressed in the normal
-coordinate system of the screen (as measured with a protractor) is as
-follows:
-</para>
-<para>
-<!-- .LP -->
-<literallayout class="monospaced">
-% roman "skewed-angle" ~ = ~ atan left ( tan ( roman "normal-angle" )
- * width over height right ) +^ adjust%
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-The skewed-angle and normal-angle are expressed in radians (rather
-than in degrees scaled by 64) in the range % [ 0 , ~2 pi ]% and where atan
-returns a value in the range % [ - pi over 2 , ~pi over 2 ] %
-and adjust is:
-</para>
-<para>
-<!-- .LP -->
-<literallayout class="monospaced">
-<!-- .TA 1i 2i -->
-<!-- .ta 1i 2i -->
-%0% for normal-angle in the range % [ 0 , ~pi over 2 ]%
-%pi% for normal-angle in the range % [ pi over 2 , ~{3 pi} over 2 ]%
-%2 pi% for normal-angle in the range % [ {3 pi} over 2 , ~2 pi ]%
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-For any given arc,
-<function>XDrawArc</function>
-and
-<function>XDrawArcs</function>
-do not draw a pixel more than once.
-If two arcs join correctly and if the line-width is greater than zero
-and the arcs intersect,
-<function>XDrawArc</function>
-and
-<function>XDrawArcs</function>
-do not draw a pixel more than once.
-Otherwise,
-the intersecting pixels of intersecting arcs are drawn multiple times.
-Specifying an arc with one endpoint and a clockwise extent draws the same pixels
-as specifying the other endpoint and an equivalent counterclockwise extent,
-except as it affects joins.
-</para>
-<para>
-<!-- .LP -->
-If the last point in one arc coincides with the first point in the following
-arc, the two arcs will join correctly.
-If the first point in the first arc coincides with the last point in the last
-arc, the two arcs will join correctly.
-By specifying one axis to be zero, a horizontal or vertical line can be
-drawn.
-Angles are computed based solely on the coordinate system and ignore the
-aspect ratio.
-</para>
-<para>
-<!-- .LP -->
-Both functions use these GC components:
-function, plane-mask, line-width, line-style, cap-style, join-style,
-fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
-They also use these GC mode-dependent components:
-foreground, background, tile, stipple, tile-stipple-x-origin,
-tile-stipple-y-origin, dash-offset, and dash-list.
-</para>
-<para>
-<!-- .LP -->
-<function>XDrawArc</function>
-and
-<function>XDrawArcs</function>
-can generate
-<errorname>BadDrawable</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadMatch</errorname>
-errors.
-</para>
-</sect2>
-</sect1>
-<sect1 id="Filling_Areas">
-<title>Filling Areas</title>
-<!-- .XS -->
-<!-- (SN Filling Areas -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-Xlib provides functions that you can use to fill:
-</para>
-<itemizedlist>
- <listitem>
- <para>
-A single rectangle or multiple rectangles
- </para>
- </listitem>
- <listitem>
- <para>
-A single polygon
- </para>
- </listitem>
- <listitem>
- <para>
-A single arc or multiple arcs
- </para>
- </listitem>
-</itemizedlist>
-<sect2 id="Filling_Single_and_Multiple_Rectangles">
-<title>Filling Single and Multiple Rectangles</title>
-<!-- .XS -->
-<!-- (SN Filling Single and Multiple Rectangles -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm><primary>Filling</primary><secondary>rectangles</secondary></indexterm>
-<indexterm><primary>XFillRectangle</primary></indexterm>
-<indexterm><primary>Rectangle</primary><secondary>filling</secondary></indexterm>
-<indexterm><primary>XFillRectangles</primary></indexterm>
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To fill a single rectangular area in a given drawable, use
-<function>XFillRectangle</function>.
-<indexterm significance="preferred"><primary>XFillRectangle</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XFillRectangle</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>intx,<parameter> y</parameter></paramdef>
- <paramdef>unsignedintwidth,<parameter> height</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.
-<!-- .ds Xy , which are relative to the origin of the drawable \ -->
-and specify the upper-left corner of the rectangle
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates(Xy.
-<!-- .ds Wh , which are the dimensions of the rectangle to be filled -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>width</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>height</emphasis>
- </term>
- <listitem>
- <para>
-Specify the width and height(Wh.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-To fill multiple rectangular areas in a given drawable, use
-<function>XFillRectangles</function>.
-<indexterm significance="preferred"><primary>XFillRectangles</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XFillRectangles</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>XRectangle<parameter> *rectangles</parameter></paramdef>
- <paramdef>int<parameter> nrectangles</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'>rectangles</emphasis>
- </term>
- <listitem>
- <para>
-Specifies an array of rectangles.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>nrectangles</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of rectangles in the array.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XFillRectangle</function>
-and
-<function>XFillRectangles</function>
-functions fill the specified rectangle or rectangles
-as if a four-point
-<systemitem>FillPolygon</systemitem>
-protocol request were specified for each rectangle:
-</para>
-<para>
-<!-- .LP -->
-<literallayout class="monospaced">
-[x,y] [x+width,y] [x+width,y+height] [x,y+height]
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-Each function uses the x and y coordinates,
-width and height dimensions, and GC you specify.
-</para>
-<para>
-<!-- .LP -->
-<function>XFillRectangles</function>
-fills the rectangles in the order listed in the array.
-For any given rectangle,
-<function>XFillRectangle</function>
-and
-<function>XFillRectangles</function>
-do not draw a pixel more than once.
-If rectangles intersect, the intersecting pixels are
-drawn multiple times.
-</para>
-<para>
-<!-- .LP -->
-Both functions use these GC components:
-function, plane-mask, fill-style, subwindow-mode,
-clip-x-origin, clip-y-origin, and clip-mask.
-They also use these GC mode-dependent components:
-foreground, background, tile, stipple, tile-stipple-x-origin,
-and tile-stipple-y-origin.
-</para>
-<para>
-<!-- .LP -->
-<function>XFillRectangle</function>
-and
-<function>XFillRectangles</function>
-can generate
-<errorname>BadDrawable</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadMatch</errorname>
-errors.
-</para>
-</sect2>
-<sect2 id="Filling_a_Single_Polygon">
-<title>Filling a Single Polygon</title>
-<!-- .XS -->
-<!-- (SN Filling a Single Polygon -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To fill a polygon area in a given drawable, use
-<function>XFillPolygon</function>.
-<indexterm><primary>Polygons</primary><secondary>filling</secondary></indexterm>
-<indexterm><primary>Filling</primary><secondary>polygon</secondary></indexterm>
-<indexterm significance="preferred"><primary>XFillPolygon</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XFillPolygon</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>XPoint<parameter> *points</parameter></paramdef>
- <paramdef>int<parameter> npoints</parameter></paramdef>
- <paramdef>int<parameter> shape</parameter></paramdef>
- <paramdef>int<parameter> mode</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'>points</emphasis>
- </term>
- <listitem>
- <para>
-Specifies an array of points.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>npoints</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of points in the array.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>shape</emphasis>
- </term>
- <listitem>
- <para>
-Specifies a shape that helps the server to improve performance.
-You can pass
-<symbol>Complex</symbol>,
-<symbol>Convex</symbol>,
-or
-<symbol>Nonconvex</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>mode</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the coordinate mode.
-You can pass
-<symbol>CoordModeOrigin</symbol>
-or
-<symbol>CoordModePrevious</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<function>XFillPolygon</function>
-fills the region closed by the specified path.
-The path is closed
-automatically if the last point in the list does not coincide with the
-first point.
-<function>XFillPolygon</function>
-does not draw a pixel of the region more than once.
-<symbol>CoordModeOrigin</symbol>
-treats all coordinates as relative to the origin,
-and
-<symbol>CoordModePrevious</symbol>
-treats all coordinates after the first as relative to the previous point.
-</para>
-<para>
-<!-- .LP -->
-Depending on the specified shape, the following occurs:
-</para>
-<itemizedlist>
- <listitem>
- <para>
-If shape is
-<symbol>Complex</symbol>,
-the path may self-intersect.
-Note that contiguous coincident points in the path are not treated
-as self-intersection.
- </para>
- </listitem>
- <listitem>
- <para>
-If shape is
-<symbol>Convex</symbol>,
-for every pair of points inside the polygon,
-the line segment connecting them does not intersect the path.
-If known by the client,
-specifying
-<symbol>Convex</symbol>
-can improve performance.
-If you specify
-<symbol>Convex</symbol>
-for a path that is not convex,
-the graphics results are undefined.
- </para>
- </listitem>
- <listitem>
- <para>
-If shape is
-<symbol>Nonconvex</symbol>,
-the path does not self-intersect, but the shape is not
-wholly convex.
-If known by the client,
-specifying
-<symbol>Nonconvex</symbol>
-instead of
-<symbol>Complex</symbol>
-may improve performance.
-If you specify
-<symbol>Nonconvex</symbol>
-for a self-intersecting path, the graphics results are undefined.
- </para>
- </listitem>
-</itemizedlist>
-<para>
-<!-- .LP -->
-The fill-rule of the GC controls the filling behavior of
-self-intersecting polygons.
-</para>
-<para>
-<!-- .LP -->
-This function uses these GC components:
-function, plane-mask, fill-style, fill-rule, subwindow-mode, clip-x-origin,
-clip-y-origin, and clip-mask.
-It also uses these GC mode-dependent components:
-foreground, background, tile, stipple, tile-stipple-x-origin,
-and tile-stipple-y-origin.
-</para>
-<para>
-<!-- .LP -->
-<function>XFillPolygon</function>
-can generate
-<errorname>BadDrawable</errorname>,
-<errorname>BadGC</errorname>,
-<errorname>BadMatch</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-</sect2>
-<sect2 id="Filling_Single_and_Multiple_Arcs">
-<title>Filling Single and Multiple Arcs</title>
-<!-- .XS -->
-<!-- (SN Filling Single and Multiple Arcs -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm><primary>XFillArc</primary></indexterm>
-<indexterm><primary>Arcs</primary><secondary>filling</secondary></indexterm>
-<indexterm><primary>Filling</primary><secondary>arcs</secondary></indexterm>
-To fill a single arc in a given drawable, use
-<function>XFillArc</function>.
-<indexterm significance="preferred"><primary>XFillArc</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XFillArc</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>intx,<parameter> y</parameter></paramdef>
- <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
- <paramdef>intangle1,<parameter> angle2</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.
-<!-- .ds Xy , which are relative to the origin of the drawable \ -->
-and specify the upper-left corner of the bounding rectangle
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates(Xy.
-<!-- .ds Wh , which are the major and minor axes of the arc -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>width</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>height</emphasis>
- </term>
- <listitem>
- <para>
-Specify the width and height(Wh.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>angle1</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the start of the arc relative to the three-o'clock position
-from the center, in units of degrees * 64.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>angle2</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the path and extent of the arc relative to the start of the
-arc, in units of degrees * 64.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-To fill multiple arcs in a given drawable, use
-<function>XFillArcs</function>.
-<indexterm significance="preferred"><primary>XFillArcs</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XFillArcs</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>XArc<parameter> *arcs</parameter></paramdef>
- <paramdef>int<parameter> narcs</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'>arcs</emphasis>
- </term>
- <listitem>
- <para>
-Specifies an array of arcs.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>narcs</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of arcs in the array.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-For each arc,
-<function>XFillArc</function>
-or
-<function>XFillArcs</function>
-fills the region closed by the infinitely thin path
-described by the specified arc and, depending on the
-arc-mode specified in the GC, one or two line segments.
-For
-<symbol>ArcChord</symbol>,
-the single line segment joining the endpoints of the arc is used.
-For
-<symbol>ArcPieSlice</symbol>,
-the two line segments joining the endpoints of the arc with the center
-point are used.
-<function>XFillArcs</function>
-fills the arcs in the order listed in the array.
-For any given arc,
-<function>XFillArc</function>
-and
-<function>XFillArcs</function>
-do not draw a pixel more than once.
-If regions intersect,
-the intersecting pixels are drawn multiple times.
-</para>
-<para>
-<!-- .LP -->
-Both functions use these GC components:
-function, plane-mask, fill-style, arc-mode, subwindow-mode, clip-x-origin,
-clip-y-origin, and clip-mask.
-They also use these GC mode-dependent components:
-foreground, background, tile, stipple, tile-stipple-x-origin,
-and tile-stipple-y-origin.
-</para>
-<para>
-<!-- .LP -->
-<function>XFillArc</function>
-and
-<function>XFillArcs</function>
-can generate
-<errorname>BadDrawable</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadMatch</errorname>
-errors.
-</para>
-</sect2>
-</sect1>
-<sect1 id="Font_Metrics">
-<title>Font Metrics</title>
-<!-- .XS -->
-<!-- (SN Font Metrics -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm><primary>Font</primary></indexterm>
-A font is a graphical description of a set of characters that are used to
-increase efficiency whenever a set of small, similar sized patterns are
-repeatedly used.
-</para>
-<para>
-<!-- .LP -->
-This section discusses how to:
-</para>
-<itemizedlist>
- <listitem>
- <para>
-Load and free fonts
- </para>
- </listitem>
- <listitem>
- <para>
-Obtain and free font names
- </para>
- </listitem>
- <listitem>
- <para>
-Compute character string sizes
- </para>
- </listitem>
- <listitem>
- <para>
-Compute logical extents
- </para>
- </listitem>
- <listitem>
- <para>
-Query character string sizes
- </para>
- </listitem>
-</itemizedlist>
-<para>
-<!-- .LP -->
-The X server loads fonts whenever a program requests a new font.
-The server can cache fonts for quick lookup.
-Fonts are global across all screens in a server.
-Several levels are possible when dealing with fonts.
-Most applications simply use
-<function>XLoadQueryFont</function>
-to load a font and query the font metrics.
-</para>
-<para>
-<!-- .LP -->
-Characters in fonts are regarded as masks.
-Except for image text requests,
-the only pixels modified are those in which bits are set to 1 in the character.
-This means that it makes sense to draw text using stipples or tiles
-(for example, many menus gray-out unusable entries).
-</para>
-<para>
-<!-- .LP -->
-<!-- .sM -->
-The
-<structname>XFontStruct</structname>
-structure contains all of the information for the font
-and consists of the font-specific information as well as
-a pointer to an array of
-<structname>XCharStruct</structname>
-structures for the
-characters contained in the font.
-The
-<structname>XFontStruct</structname>,
-<structname>XFontProp</structname>,
-and
-<structname>XCharStruct</structname>
-structures contain:
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XCharStruct</primary></indexterm>
-<literallayout class="monospaced">
-<!-- .TA .5i 3i -->
-<!-- .ta .5i 3i -->
-typedef struct {
- short lbearing; /* origin to left edge of raster */
- short rbearing; /* origin to right edge of raster */
- short width; /* advance to next char's origin */
- short ascent; /* baseline to top edge of raster */
- short descent; /* baseline to bottom edge of raster */
- unsigned short attributes; /* per char flags (not predefined) */
-} XCharStruct;
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XFontProp</primary></indexterm>
-<literallayout class="monospaced">
-<!-- .TA .5i 1i 3i -->
-<!-- .ta .5i 1i 3i -->
-typedef struct {
- Atom name;
- unsigned long card32;
-} XFontProp;
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XChar2b</primary></indexterm>
-<literallayout class="monospaced">
-<!-- .TA .5i 3i -->
-<!-- .ta .5i 3i -->
-typedef struct { /* normal 16 bit characters are two bytes */
- unsigned char byte1;
- unsigned char byte2;
-} XChar2b;
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XFontStruct</primary></indexterm>
-<literallayout class="monospaced">
-<!-- .TA .5i 3i -->
-<!-- .ta .5i 3i -->
-typedef struct {
- XExtData *ext_data; /* hook for extension to hang data */
- Font fid; /* Font id for this font */
- unsigned direction; /* hint about the direction font is painted */
- unsigned min_char_or_byte2; /* first character */
- unsigned max_char_or_byte2; /* last character */
- unsigned min_byte1; /* first row that exists */
- unsigned max_byte1; /* last row that exists */
- Bool all_chars_exist; /* flag if all characters have nonzero size */
- unsigned default_char; /* char to print for undefined character */
- int n_properties; /* how many properties there are */
- XFontProp *properties; /* pointer to array of additional properties */
- XCharStruct min_bounds; /* minimum bounds over all existing char */
- XCharStruct max_bounds; /* maximum bounds over all existing char */
- XCharStruct *per_char; /* first_char to last_char information */
- int ascent; /* logical extent above baseline for spacing */
- int descent; /* logical descent below baseline for spacing */
-} XFontStruct;
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-X supports single byte/character, two bytes/character matrix,
-and 16-bit character text operations.
-Note that any of these forms can be used with a font, but a
-single byte/character text request can only specify a single byte
-(that is, the first row of a 2-byte font).
-You should view 2-byte fonts as a two-dimensional matrix of defined
-characters: byte1 specifies the range of defined rows and
-byte2 defines the range of defined columns of the font.
-Single byte/character fonts have one row defined, and the byte2 range
-specified in the structure defines a range of characters.
-</para>
-<para>
-<!-- .LP -->
-The bounding box of a character is defined by the
-<structname>XCharStruct</structname>
-of that character.
-When characters are absent from a font,
-the default_char is used.
-When fonts have all characters of the same size,
-only the information in the
-<structname>XFontStruct</structname>
-min and max bounds are used.
-</para>
-<para>
-<!-- .LP -->
-The members of the
-<structname>XFontStruct</structname>
-have the following semantics:
-</para>
-<itemizedlist>
- <listitem>
- <para>
-The direction member can be either
-<symbol>FontLeftToRight</symbol>
-or
-<symbol>FontRightToLeft</symbol>.
-It is just a hint as to whether most
-<structname>XCharStruct</structname>
-elements
-have a positive
-(<symbol>FontLeftToRight</symbol>)
-or a negative
-(<symbol>FontRightToLeft</symbol>)
-character width
-metric.
-The core protocol defines no support for vertical text.
- </para>
- </listitem>
- <listitem>
- <para>
-If the min_byte1 and max_byte1 members are both zero, min_char_or_byte2
-specifies the linear character index corresponding to the first element
-of the per_char array, and max_char_or_byte2 specifies the linear character
-index of the last element.
- </para>
- </listitem>
- <listitem>
- <para>
-If either min_byte1 or max_byte1 are nonzero, both
-min_char_or_byte2 and max_char_or_byte2 are less than 256,
-and the 2-byte character index values corresponding to the
-per_char array element N (counting from 0) are:
- </para>
- </listitem>
- <listitem>
- <para>
-<!-- .nf -->
- byte1 = N/D + min_byte1
-<!-- .br -->
- byte2 = N\\D + min_char_or_byte2
- </para>
- </listitem>
- <listitem>
- <para>
-<!-- .fi -->
-where:
- </para>
- </listitem>
- <listitem>
- <para>
-<!-- .nf -->
- D = max_char_or_byte2 - min_char_or_byte2 + 1
- / = integer division
- \\ = integer modulus
-<!-- .fi -->
- </para>
- </listitem>
- <listitem>
- <para>
-If the per_char pointer is NULL,
-all glyphs between the first and last character indexes
-inclusive have the same information,
-as given by both min_bounds and max_bounds.
- </para>
- </listitem>
- <listitem>
- <para>
-If all_chars_exist is
-<symbol>True</symbol>,
-all characters in the per_char array have nonzero bounding boxes.
- </para>
- </listitem>
- <listitem>
- <para>
-The default_char member specifies the character that will be used when an
-undefined or nonexistent character is printed.
-The default_char is a 16-bit character (not a 2-byte character).
-For a font using 2-byte matrix format,
-the default_char has byte1 in the most-significant byte
-and byte2 in the least significant byte.
-If the default_char itself specifies an undefined or nonexistent character,
-no printing is performed for an undefined or nonexistent character.
- </para>
- </listitem>
- <listitem>
- <para>
-The min_bounds and max_bounds members contain the most extreme values of
-each individual
-<structname>XCharStruct</structname>
-component over all elements of this array
-(and ignore nonexistent characters).
-The bounding box of the font (the smallest
-rectangle enclosing the shape obtained by superimposing all of the
-characters at the same origin [x,y]) has its upper-left coordinate at:
-<literallayout class="monospaced">
- [x + min_bounds.lbearing, y - max_bounds.ascent]
-</literallayout>
- </para>
- </listitem>
- <listitem>
- <para>
-Its width is:
-<literallayout class="monospaced">
- max_bounds.rbearing - min_bounds.lbearing
-</literallayout>
- </para>
- </listitem>
- <listitem>
- <para>
-Its height is:
-<literallayout class="monospaced">
- max_bounds.ascent + max_bounds.descent
-</literallayout>
- </para>
- </listitem>
- <listitem>
- <para>
-The ascent member is the logical extent of the font above the baseline that is
-used for determining line spacing.
-Specific characters may extend beyond
-this.
- </para>
- </listitem>
- <listitem>
- <para>
-The descent member is the logical extent of the font at or below the
-baseline that is used for determining line spacing.
-Specific characters may extend beyond this.
- </para>
- </listitem>
- <listitem>
- <para>
-If the baseline is at Y-coordinate y,
-the logical extent of the font is inclusive between the Y-coordinate
-values (y - font.ascent) and (y + font.descent - 1).
-Typically,
-the minimum interline spacing between rows of text is given
-by ascent + descent.
- </para>
- </listitem>
-</itemizedlist>
-<para>
-<!-- .LP -->
-For a character origin at [x,y],
-the bounding box of a character (that is,
-the smallest rectangle that encloses the character's shape)
-described in terms of
-<structname>XCharStruct</structname>
-components is a rectangle with its upper-left corner at:
-</para>
-<para>
-<!-- .LP -->
-<literallayout class="monospaced">
-[x + lbearing, y - ascent]
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-Its width is:
-</para>
-<para>
-<!-- .LP -->
-<literallayout class="monospaced">
-rbearing - lbearing
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-Its height is:
-</para>
-<para>
-<!-- .LP -->
-<literallayout class="monospaced">
-ascent + descent
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-The origin for the next character is defined to be:
-</para>
-<para>
-<!-- .LP -->
-<literallayout class="monospaced">
-[x + width, y]
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-The lbearing member defines the extent of the left edge of the character ink
-from the origin.
-The rbearing member defines the extent of the right edge of the character ink
-from the origin.
-The ascent member defines the extent of the top edge of the character ink
-from the origin.
-The descent member defines the extent of the bottom edge of the character ink
-from the origin.
-The width member defines the logical width of the character.
-</para>
-<para>
-<!-- .LP -->
-Note that the baseline (the y position of the character origin)
-is logically viewed as being the scanline just below nondescending characters.
-When descent is zero,
-only pixels with Y-coordinates less than y are drawn,
-and the origin is logically viewed as being coincident with the left edge of
-a nonkerned character.
-When lbearing is zero,
-no pixels with X-coordinate less than x are drawn.
-Any of the
-<structname>XCharStruct</structname>
-metric members could be negative.
-If the width is negative,
-the next character will be placed to the left of the current origin.
-</para>
-<para>
-<!-- .LP -->
-The X protocol does not define the interpretation of the attributes member
-in the
-<structname>XCharStruct</structname>
-structure.
-A nonexistent character is represented with all members of its
-<structname>XCharStruct</structname>
-set to zero.
-</para>
-<para>
-<!-- .LP -->
-A font is not guaranteed to have any properties.
-The interpretation of the property value (for example, long or unsigned long)
-must be derived from <emphasis remap='I'>a priori</emphasis> knowledge of the property.
-A basic set of font properties is specified in the X Consortium standard
-<emphasis remap='I'>X Logical Font Description Conventions</emphasis>.
-</para>
-<sect2 id="Loading_and_Freeing_Fonts">
-<title>Loading and Freeing Fonts</title>
-<!-- .XS -->
-<!-- (SN Loading and Freeing Fonts -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-Xlib provides functions that you can use to load fonts, get font information,
-unload fonts, and free font information.
-<indexterm><primary>Fonts</primary><secondary>getting information</secondary></indexterm>
-<indexterm><primary>Fonts</primary><secondary>unloading</secondary></indexterm>
-<indexterm><primary>Fonts</primary><secondary>freeing font information</secondary></indexterm>
-A few font functions use a
-<type>GContext</type>
-resource ID or a font ID interchangeably.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To load a given font, use
-<function>XLoadFont</function>.
-<indexterm significance="preferred"><primary>XLoadFont</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>Font <function>XLoadFont</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>char<parameter> *name</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'>name</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the name of the font,
-which is a null-terminated string.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XLoadFont</function>
-function loads the specified font and returns its associated font ID.
-If the font name is not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-Use of uppercase or lowercase does not matter.
-When the characters ``?'' and ``*'' are used in a font name, a
-pattern match is performed and any matching font is used.
-In the pattern,
-the ``?'' character will match any single character,
-and the ``*'' character will match any number of characters.
-A structured format for font names is specified in the X Consortium standard
-<emphasis remap='I'>X Logical Font Description Conventions</emphasis>.
-If
-<function>XLoadFont</function>
-was unsuccessful at loading the specified font,
-a
-<errorname>BadName</errorname>
-error results.
-Fonts are not associated with a particular screen
-and can be stored as a component
-of any GC.
-When the font is no longer needed, call
-<function>XUnloadFont</function>.
-</para>
-<para>
-<!-- .LP -->
-<function>XLoadFont</function>
-can generate
-<errorname>BadAlloc</errorname>
-and
-<errorname>BadName</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To return information about an available font, use
-<function>XQueryFont</function>.
-<indexterm significance="preferred"><primary>XQueryFont</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>XFontStruct *<function>XQueryFont</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>XID<parameter> font_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'>font_ID</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the font ID or the
-<type>GContext</type>
-ID.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XQueryFont</function>
-function returns a pointer to the
-<structname>XFontStruct</structname>
-structure, which contains information associated with the font.
-You can query a font or the font stored in a GC.
-The font ID stored in the
-<structname>XFontStruct</structname>
-structure will be the
-<type>GContext</type>
-ID, and you need to be careful when using this ID in other functions
-(see
-<function>XGContextFromGC</function>).
-If the font does not exist,
-<function>XQueryFont</function>
-returns NULL.
-To free this data, use
-<function>XFreeFontInfo</function>.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To perform a
-<function>XLoadFont</function>
-and
-<function>XQueryFont</function>
-in a single operation, use
-<function>XLoadQueryFont</function>.
-<indexterm significance="preferred"><primary>XLoadQueryFont</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>XFontStruct *<function>XLoadQueryFont</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>char<parameter> *name</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'>name</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the name of the font,
-which is a null-terminated string.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XLoadQueryFont</function>
-function provides the most common way for accessing a font.
-<function>XLoadQueryFont</function>
-both opens (loads) the specified font and returns a pointer to the
-appropriate
-<structname>XFontStruct</structname>
-structure.
-If the font name is not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-If the font does not exist,
-<function>XLoadQueryFont</function>
-returns NULL.
-</para>
-<para>
-<!-- .LP -->
-<function>XLoadQueryFont</function>
-can generate a
-<errorname>BadAlloc</errorname>
-error.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To unload the font and free the storage used by the font structure
-that was allocated by
-<function>XQueryFont</function>
-or
-<function>XLoadQueryFont</function>,
-use
-<function>XFreeFont</function>.
-<indexterm significance="preferred"><primary>XFreeFont</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XFreeFont</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>XFontStruct<parameter> *font_struct</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'>font_struct</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the storage associated with the font.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XFreeFont</function>
-function deletes the association between the font resource ID and the specified
-font and frees the
-<structname>XFontStruct</structname>
-structure.
-The font itself will be freed when no other resource references it.
-The data and the font should not be referenced again.
-</para>
-<para>
-<!-- .LP -->
-<function>XFreeFont</function>
-can generate a
-<errorname>BadFont</errorname>
-error.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To return a given font property, use
-<function>XGetFontProperty</function>.
-<indexterm significance="preferred"><primary>XGetFontProperty</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function>XGetFontProperty</function></funcdef>
- <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>
- <paramdef>Atom<parameter> atom</parameter></paramdef>
- <paramdef>unsignedlong<parameter> *value_return</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>font_struct</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the storage associated with the font.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>atom</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the atom for the property name you want returned.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>value_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the value of the font property.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-Given the atom for that property,
-the
-<function>XGetFontProperty</function>
-function returns the value of the specified font property.
-<function>XGetFontProperty</function>
-also returns
-<symbol>False</symbol>
-if the property was not defined or
-<symbol>True</symbol>
-if it was defined.
-A set of predefined atoms exists for font properties,
-which can be found in
-<filename class="headerfile"><X11/Xatom.h></filename>.
-<indexterm type="file"><primary><filename class="headerfile">X11/Xatom.h</filename></primary></indexterm>
-<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xatom.h></filename></secondary></indexterm>
-<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xatom.h></filename></secondary></indexterm>
-This set contains the standard properties associated with
-a font.
-Although it is not guaranteed,
-it is likely that the predefined font properties will be present.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To unload a font that was loaded by
-<function>XLoadFont</function>,
-use
-<function>XUnloadFont</function>.
-<indexterm significance="preferred"><primary>XUnloadFont</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XUnloadFont</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Font<parameter> font</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'>font</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the font.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XUnloadFont</function>
-function deletes the association between the font resource ID and the specified font.
-The font itself will be freed when no other resource references it.
-The font should not be referenced again.
-</para>
-<para>
-<!-- .LP -->
-<function>XUnloadFont</function>
-can generate a
-<errorname>BadFont</errorname>
-error.
-</para>
-</sect2>
-<sect2 id="Obtaining_and_Freeing_Font_Names_and_Information">
-<title>Obtaining and Freeing Font Names and Information</title>
-<!-- .XS -->
-<!-- (SN Obtaining and Freeing Font Names and Information -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-You obtain font names and information by matching a wildcard specification
-when querying a font type for a list of available sizes and so on.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To return a list of the available font names, use
-<function>XListFonts</function>.
-<indexterm significance="preferred"><primary>XListFonts</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>char **<function>XListFonts</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>char<parameter> *pattern</parameter></paramdef>
- <paramdef>int<parameter> maxnames</parameter></paramdef>
- <paramdef>int<parameter> *actual_count_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'>pattern</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the null-terminated pattern string that can contain wildcard
-characters.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>maxnames</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the maximum number of names to be returned.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>actual_count_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the actual number of font names.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XListFonts</function>
-function returns an array of available font names
-(as controlled by the font search path; see
-<function>XSetFontPath</function>)
-that match the string you passed to the pattern argument.
-The pattern string can contain any characters,
-but each asterisk (*) is a wildcard for any number of characters,
-and each question mark (?) is a wildcard for a single character.
-If the pattern string is not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-Use of uppercase or lowercase does not matter.
-Each returned string is null-terminated.
-If the data returned by the server is in the Latin Portable Character Encoding,
-then the returned strings are in the Host Portable Character Encoding.
-Otherwise, the result is implementation-dependent.
-If there are no matching font names,
-<function>XListFonts</function>
-returns NULL.
-The client should call
-<function>XFreeFontNames</function>
-when finished with the result to free the memory.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To free a font name array, use
-<function>XFreeFontNames</function>.
-<indexterm significance="preferred"><primary>XFreeFontNames</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XFreeFontNames</function></funcdef>
- <paramdef>char<parameter> *list[]</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>list</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the array of strings you want to free.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XFreeFontNames</function>
-function frees the array and strings returned by
-<function>XListFonts</function>
-or
-<function>XListFontsWithInfo</function>.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To obtain the names and information about available fonts, use
-<function>XListFontsWithInfo</function>.
-<indexterm significance="preferred"><primary>XListFontsWithInfo</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>char **<function>XListFontsWithInfo</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>char<parameter> *pattern</parameter></paramdef>
- <paramdef>int<parameter> maxnames</parameter></paramdef>
- <paramdef>int<parameter> *count_return</parameter></paramdef>
- <paramdef>XFontStruct<parameter> **info_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'>pattern</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the null-terminated pattern string that can contain wildcard
-characters.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>maxnames</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the maximum number of names to be returned.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>count_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the actual number of matched font names.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>info_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the font information.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XListFontsWithInfo</function>
-function returns a list of font names that match the specified pattern and their
-associated font information.
-The list of names is limited to size specified by maxnames.
-The information returned for each font is identical to what
-<function>XLoadQueryFont</function>
-would return except that the per-character metrics are not returned.
-The pattern string can contain any characters,
-but each asterisk (*) is a wildcard for any number of characters,
-and each question mark (?) is a wildcard for a single character.
-If the pattern string is not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-Use of uppercase or lowercase does not matter.
-Each returned string is null-terminated.
-If the data returned by the server is in the Latin Portable Character Encoding,
-then the returned strings are in the Host Portable Character Encoding.
-Otherwise, the result is implementation-dependent.
-If there are no matching font names,
-<function>XListFontsWithInfo</function>
-returns NULL.
-</para>
-<para>
-<!-- .LP -->
-To free only the allocated name array,
-the client should call
-<function>XFreeFontNames</function>.
-To free both the name array and the font information array
-or to free just the font information array,
-the client should call
-<function>XFreeFontInfo</function>.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To free font structures and font names, use
-<function>XFreeFontInfo</function>.
-<indexterm significance="preferred"><primary>XFreeFontInfo</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XFreeFontInfo</function></funcdef>
- <paramdef>char<parameter> **names</parameter></paramdef>
- <paramdef>XFontStruct<parameter> *free_info</parameter></paramdef>
- <paramdef>int<parameter> actual_count</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>names</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the list of font names.
-
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>free_info</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the font information.
-
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>actual_count</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the actual number of font names.
-
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XFreeFontInfo</function>
-function frees a font structure or an array of font structures
-and optionally an array of font names.
-If NULL is passed for names, no font names are freed.
-If a font structure for an open font (returned by
-<function>XLoadQueryFont</function>)
-is passed, the structure is freed,
-but the font is not closed; use
-<function>XUnloadFont</function>
-to close the font.
-</para>
-</sect2>
-<sect2 id="Computing_Character_String_Sizes">
-<title>Computing Character String Sizes</title>
-<!-- .XS -->
-<!-- (SN Computing Character String Sizes -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-Xlib provides functions that you can use to compute the width,
-the logical extents,
-and the server information about 8-bit and 2-byte text strings.
-<indexterm><primary>XTextWidth</primary></indexterm>
-<indexterm><primary>XTextWidth16</primary></indexterm>
-The width is computed by adding the character widths of all the characters.
-It does not matter if the font is an 8-bit or 2-byte font.
-These functions return the sum of the character metrics in pixels.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To determine the width of an 8-bit character string, use
-<function>XTextWidth</function>.
-<indexterm significance="preferred"><primary>XTextWidth</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>int <function>XTextWidth</function></funcdef>
- <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>
- <paramdef>char<parameter> *string</parameter></paramdef>
- <paramdef>int<parameter> count</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>font_struct</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the font used for the width computation.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>string</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the character string.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>count</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the character count in the specified string.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-To determine the width of a 2-byte character string, use
-<function>XTextWidth16</function>.
-<indexterm significance="preferred"><primary>XTextWidth16</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>int <function>XTextWidth16</function></funcdef>
- <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>
- <paramdef>XChar2b<parameter> *string</parameter></paramdef>
- <paramdef>int<parameter> count</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>font_struct</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the font used for the width computation.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>string</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the character string.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>count</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the character count in the specified string.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-</para>
-</sect2>
-<sect2 id="Computing_Logical_Extents">
-<title>Computing Logical Extents</title>
-<!-- .XS -->
-<!-- (SN Computing Logical Extents -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-To compute the bounding box of an 8-bit character string in a given font, use
-<function>XTextExtents</function>.
-<indexterm significance="preferred"><primary>XTextExtents</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XTextExtents</function></funcdef>
- <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>
- <paramdef>char<parameter> *string</parameter></paramdef>
- <paramdef>int<parameter> nchars</parameter></paramdef>
- <paramdef>int<parameter> *direction_return</parameter></paramdef>
- <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>
- <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>font_struct</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the
-<structname>XFontStruct</structname>
-structure.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>string</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the character string.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>nchars</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of characters in the character string.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>direction_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the value of the direction hint
-(<symbol>FontLeftToRight</symbol>
-or
-<symbol>FontRightToLeft</symbol>).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>font_ascent_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the font ascent.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>font_descent_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the font descent.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>overall_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the overall size in the specified
-<structname>XCharStruct</structname>
-structure.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-To compute the bounding box of a 2-byte character string in a given font, use
-<function>XTextExtents16</function>.
-<indexterm significance="preferred"><primary>XTextExtents16</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XTextExtents16</function></funcdef>
- <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef>
- <paramdef>XChar2b<parameter> *string</parameter></paramdef>
- <paramdef>int<parameter> nchars</parameter></paramdef>
- <paramdef>int<parameter> *direction_return</parameter></paramdef>
- <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>
- <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>font_struct</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the
-<structname>XFontStruct</structname>
-structure.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>string</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the character string.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>nchars</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of characters in the character string.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>direction_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the value of the direction hint
-(<symbol>FontLeftToRight</symbol>
-or
-<symbol>FontRightToLeft</symbol>).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>font_ascent_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the font ascent.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>font_descent_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the font descent.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>overall_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the overall size in the specified
-<structname>XCharStruct</structname>
-structure.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XTextExtents</function>
-and
-<function>XTextExtents16</function>
-functions
-perform the size computation locally and, thereby,
-avoid the round-trip overhead of
-<function>XQueryTextExtents</function>
-and
-<function>XQueryTextExtents16</function>.
-Both functions return an
-<structname>XCharStruct</structname>
-structure, whose members are set to the values as follows.
-</para>
-<para>
-<!-- .LP -->
-The ascent member is set to the maximum of the ascent metrics of all
-characters in the string.
-The descent member is set to the maximum of the descent metrics.
-The width member is set to the sum of the character-width metrics of all
-characters in the string.
-For each character in the string,
-let W be the sum of the character-width metrics of all characters preceding
-it in the string.
-Let L be the left-side-bearing metric of the character plus W.
-Let R be the right-side-bearing metric of the character plus W.
-The lbearing member is set to the minimum L of all characters in the string.
-The rbearing member is set to the maximum R.
-</para>
-<para>
-<!-- .LP -->
-For fonts defined with linear indexing rather than 2-byte matrix indexing,
-each
-<structname>XChar2b</structname>
-structure is interpreted as a 16-bit number with byte1 as the
-most significant byte.
-If the font has no defined default character,
-undefined characters in the string are taken to have all zero metrics.
-</para>
-</sect2>
-<sect2 id="Querying_Character_String_Sizes">
-<title>Querying Character String Sizes</title>
-<!-- .XS -->
-<!-- (SN Querying Character String Sizes -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-To query the server for the bounding box of an 8-bit character string in a
-given font, use
-<function>XQueryTextExtents</function>.
-<indexterm significance="preferred"><primary>XQueryTextExtents</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XQueryTextExtents</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>XID<parameter> font_ID</parameter></paramdef>
- <paramdef>char<parameter> *string</parameter></paramdef>
- <paramdef>int<parameter> nchars</parameter></paramdef>
- <paramdef>int<parameter> *direction_return</parameter></paramdef>
- <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>
- <paramdef>XCharStruct<parameter> *overall_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'>font_ID</emphasis>
- </term>
- <listitem>
- <para>
-Specifies either the font ID or the
-<type>GContext</type>
-ID that contains the font.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>string</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the character string.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>nchars</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of characters in the character string.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>direction_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the value of the direction hint
-(<symbol>FontLeftToRight</symbol>
-or
-<symbol>FontRightToLeft</symbol>).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>font_ascent_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the font ascent.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>font_descent_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the font descent.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>overall_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the overall size in the specified
-<structname>XCharStruct</structname>
-structure.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-To query the server for the bounding box of a 2-byte character string
-in a given font, use
-<function>XQueryTextExtents16</function>.
-<indexterm significance="preferred"><primary>XQueryTextExtents16</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XQueryTextExtents16</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>XID<parameter> font_ID</parameter></paramdef>
- <paramdef>XChar2b<parameter> *string</parameter></paramdef>
- <paramdef>int<parameter> nchars</parameter></paramdef>
- <paramdef>int<parameter> *direction_return</parameter></paramdef>
- <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef>
- <paramdef>XCharStruct<parameter> *overall_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'>font_ID</emphasis>
- </term>
- <listitem>
- <para>
-Specifies either the font ID or the
-<type>GContext</type>
-ID that contains the font.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>string</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the character string.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>nchars</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of characters in the character string.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>direction_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the value of the direction hint
-(<symbol>FontLeftToRight</symbol>
-or
-<symbol>FontRightToLeft</symbol>).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>font_ascent_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the font ascent.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>font_descent_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the font descent.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>overall_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the overall size in the specified
-<structname>XCharStruct</structname>
-structure.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XQueryTextExtents</function>
-and
-<function>XQueryTextExtents16</function>
-functions return the bounding box of the specified 8-bit and 16-bit
-character string in the specified font or the font contained in the
-specified GC.
-These functions query the X server and, therefore, suffer the round-trip
-overhead that is avoided by
-<function>XTextExtents</function>
-and
-<function>XTextExtents16</function>.
-Both functions return a
-<structname>XCharStruct</structname>
-structure, whose members are set to the values as follows.
-</para>
-<para>
-<!-- .LP -->
-The ascent member is set to the maximum of the ascent metrics
-of all characters in the string.
-The descent member is set to the maximum of the descent metrics.
-The width member is set to the sum of the character-width metrics
-of all characters in the string.
-For each character in the string,
-let W be the sum of the character-width metrics of all characters preceding
-it in the string.
-Let L be the left-side-bearing metric of the character plus W.
-Let R be the right-side-bearing metric of the character plus W.
-The lbearing member is set to the minimum L of all characters in the string.
-The rbearing member is set to the maximum R.
-</para>
-<para>
-<!-- .LP -->
-For fonts defined with linear indexing rather than 2-byte matrix indexing,
-each
-<structname>XChar2b</structname>
-structure is interpreted as a 16-bit number with byte1 as the
-most significant byte.
-If the font has no defined default character,
-undefined characters in the string are taken to have all zero metrics.
-</para>
-<para>
-<!-- .LP -->
-Characters with all zero metrics are ignored.
-If the font has no defined default_char,
-the undefined characters in the string are also ignored.
-</para>
-<para>
-<!-- .LP -->
-<function>XQueryTextExtents</function>
-and
-<function>XQueryTextExtents16</function>
-can generate
-<errorname>BadFont</errorname>
-and
-<errorname>BadGC</errorname>
-errors.
-</para>
-</sect2>
-</sect1>
-<sect1 id="Drawing_Text">
-<title>Drawing Text</title>
-<!-- .XS -->
-<!-- (SN Drawing Text -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-This section discusses how to draw:
-</para>
-<itemizedlist>
- <listitem>
- <para>
-Complex text
- </para>
- </listitem>
- <listitem>
- <para>
-Text characters
- </para>
- </listitem>
- <listitem>
- <para>
-Image text characters
- </para>
- </listitem>
-</itemizedlist>
-<para>
-<!-- .LP -->
-The fundamental text functions
-<function>XDrawText</function>
-and
-<function>XDrawText16</function>
-use the following structures:
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XTextItem</primary></indexterm>
-<!-- .sM -->
-<literallayout class="monospaced">
-<!-- .TA .5i 3i -->
-<!-- .ta .5i 3i -->
-typedef struct {
- char *chars; /* pointer to string */
- int nchars; /* number of characters */
- int delta; /* delta between strings */
- Font font; /* Font to print it in, None don't change */
-} XTextItem;
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XTextItem16</primary></indexterm>
-<literallayout class="monospaced">
-<!-- .TA .5i 3i -->
-<!-- .ta .5i 3i -->
-typedef struct {
- XChar2b *chars; /* pointer to two-byte characters */
- int nchars; /* number of characters */
- int delta; /* delta between strings */
- Font font; /* font to print it in, None don't change */
-} XTextItem16;
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-If the font member is not
-<symbol>None</symbol>,
-the font is changed before printing and also is stored in the GC.
-If an error was generated during text drawing,
-the previous items may have been drawn.
-The baseline of the characters are drawn starting at the x and y
-coordinates that you pass in the text drawing functions.
-</para>
-<para>
-<!-- .LP -->
-For example, consider the background rectangle drawn by
-<function>XDrawImageString</function>.
-If you want the upper-left corner of the background rectangle
-to be at pixel coordinate (x,y), pass the (x,y + ascent)
-as the baseline origin coordinates to the text functions.
-The ascent is the font ascent, as given in the
-<structname>XFontStruct</structname>
-structure.
-If you want the lower-left corner of the background rectangle
-to be at pixel coordinate (x,y), pass the (x,y - descent + 1)
-as the baseline origin coordinates to the text functions.
-The descent is the font descent, as given in the
-<structname>XFontStruct</structname>
-structure.
-</para>
-<sect2 id="Drawing_Complex_Text">
-<title>Drawing Complex Text</title>
-<!-- .XS -->
-<!-- (SN Drawing Complex Text -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm><primary>Text</primary><secondary>drawing</secondary></indexterm>
-<indexterm><primary>Drawing</primary><secondary>text items</secondary></indexterm>
-</para>
-<para>
-<!-- .LP -->
-To draw 8-bit characters in a given drawable, use
-<function>XDrawText</function>.
-<indexterm significance="preferred"><primary>XDrawText</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XDrawText</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>intx,<parameter> y</parameter></paramdef>
- <paramdef>XTextItem<parameter> *items</parameter></paramdef>
- <paramdef>int<parameter> nitems</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.
-<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->
-and define the origin of the first character
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates(Xy.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>items</emphasis>
- </term>
- <listitem>
- <para>
-Specifies an array of text items.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>nitems</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of text items in the array.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-To draw 2-byte characters in a given drawable, use
-<function>XDrawText16</function>.
-<indexterm significance="preferred"><primary>XDrawText16</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XDrawText16</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>intx,<parameter> y</parameter></paramdef>
- <paramdef>XTextItem16<parameter> *items</parameter></paramdef>
- <paramdef>int<parameter> nitems</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.
-<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->
-and define the origin of the first character
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates(Xy.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>items</emphasis>
- </term>
- <listitem>
- <para>
-Specifies an array of text items.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>nitems</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of text items in the array.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XDrawText16</function>
-function is similar to
-<function>XDrawText</function>
-except that it uses 2-byte or 16-bit characters.
-Both functions allow complex spacing and font shifts between counted strings.
-</para>
-<para>
-<!-- .LP -->
-Each text item is processed in turn.
-A font member other than
-<symbol>None</symbol>
-in an item causes the font to be stored in the GC
-and used for subsequent text.
-A text element delta specifies an additional change
-in the position along the x axis before the string is drawn.
-The delta is always added to the character origin
-and is not dependent on any characteristics of the font.
-Each character image, as defined by the font in the GC, is treated as an
-additional mask for a fill operation on the drawable.
-The drawable is modified only where the font character has a bit set to 1.
-If a text item generates a
-<errorname>BadFont</errorname>
-error, the previous text items may have been drawn.
-</para>
-<para>
-<!-- .LP -->
-For fonts defined with linear indexing rather than 2-byte matrix indexing,
-each
-<structname>XChar2b</structname>
-structure is interpreted as a 16-bit number with byte1 as the
-most significant byte.
-</para>
-<para>
-<!-- .LP -->
-Both functions use these GC components:
-function, plane-mask, fill-style, font, subwindow-mode,
-clip-x-origin, clip-y-origin, and clip-mask.
-They also use these GC mode-dependent components:
-foreground, background, tile, stipple, tile-stipple-x-origin,
-and tile-stipple-y-origin.
-</para>
-<para>
-<!-- .LP -->
-<function>XDrawText</function>
-and
-<function>XDrawText16</function>
-can generate
-<errorname>BadDrawable</errorname>,
-<errorname>BadFont</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadMatch</errorname>
-errors.
-</para>
-</sect2>
-<sect2 id="Drawing_Text_Characters">
-<title>Drawing Text Characters</title>
-<!-- .XS -->
-<!-- (SN Drawing Text Characters -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm><primary>Strings</primary><secondary>drawing</secondary></indexterm>
-<indexterm><primary>Drawing</primary><secondary>strings</secondary></indexterm>
-To draw 8-bit characters in a given drawable, use
-<function>XDrawString</function>.
-<indexterm significance="preferred"><primary>XDrawString</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XDrawString</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>intx,<parameter> y</parameter></paramdef>
- <paramdef>char<parameter> *string</parameter></paramdef>
- <paramdef>int<parameter> length</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.
-<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->
-and define the origin of the first character
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates(Xy.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>string</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the character string.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>length</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of characters in the string argument.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-To draw 2-byte characters in a given drawable, use
-<function>XDrawString16</function>.
-<indexterm significance="preferred"><primary>XDrawString16</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XDrawString16</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>intx,<parameter> y</parameter></paramdef>
- <paramdef>XChar2b<parameter> *string</parameter></paramdef>
- <paramdef>int<parameter> length</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.
-<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->
-and define the origin of the first character
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates(Xy.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>string</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the character string.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>length</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of characters in the string argument.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-Each character image, as defined by the font in the GC, is treated as an
-additional mask for a fill operation on the drawable.
-The drawable is modified only where the font character has a bit set to 1.
-For fonts defined with 2-byte matrix indexing
-and used with
-<function>XDrawString16</function>,
-each byte is used as a byte2 with a byte1 of zero.
-</para>
-<para>
-<!-- .LP -->
-Both functions use these GC components:
-function, plane-mask, fill-style, font, subwindow-mode, clip-x-origin,
-clip-y-origin, and clip-mask.
-They also use these GC mode-dependent components:
-foreground, background, tile, stipple, tile-stipple-x-origin,
-and tile-stipple-y-origin.
-</para>
-<para>
-<!-- .LP -->
-<function>XDrawString</function>
-and
-<function>XDrawString16</function>
-can generate
-<errorname>BadDrawable</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadMatch</errorname>
-errors.
-</para>
-</sect2>
-<sect2 id="Drawing_Image_Text_Characters">
-<title>Drawing Image Text Characters</title>
-<!-- .XS -->
-<!-- (SN Drawing Image Text Characters -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm><primary>Image text</primary><secondary>drawing</secondary></indexterm>
-<indexterm><primary>Drawing</primary><secondary>image text</secondary></indexterm>
-Some applications, in particular terminal emulators, need to
-print image text in which both the foreground and background bits of
-each character are painted.
-This prevents annoying flicker on many displays.
-<indexterm><primary>XDrawImageString</primary></indexterm>
-<indexterm><primary>XDrawImageString16</primary></indexterm>
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To draw 8-bit image text characters in a given drawable, use
-<function>XDrawImageString</function>.
-<indexterm significance="preferred"><primary>XDrawImageString</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XDrawImageString</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>intx,<parameter> y</parameter></paramdef>
- <paramdef>char<parameter> *string</parameter></paramdef>
- <paramdef>int<parameter> length</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.
-<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->
-and define the origin of the first character
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates(Xy.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>string</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the character string.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>length</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of characters in the string argument.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-To draw 2-byte image text characters in a given drawable, use
-<function>XDrawImageString16</function>.
-<indexterm significance="preferred"><primary>XDrawImageString16</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XDrawImageString16</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>intx,<parameter> y</parameter></paramdef>
- <paramdef>XChar2b<parameter> *string</parameter></paramdef>
- <paramdef>int<parameter> length</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.
-<!-- .ds Xy , which are relative to the origin of the specified drawable \ -->
-and define the origin of the first character
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates(Xy.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>string</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the character string.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>length</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of characters in the string argument.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XDrawImageString16</function>
-function is similar to
-<function>XDrawImageString</function>
-except that it uses 2-byte or 16-bit characters.
-Both functions also use both the foreground and background pixels
-of the GC in the destination.
-</para>
-<para>
-<!-- .LP -->
-The effect is first to fill a
-destination rectangle with the background pixel defined in the GC and then
-to paint the text with the foreground pixel.
-The upper-left corner of the filled rectangle is at:
-</para>
-<para>
-<!-- .LP -->
-<literallayout class="monospaced">
-[x, y - font-ascent]
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-The width is:
-</para>
-<para>
-<!-- .LP -->
-<literallayout class="monospaced">
-overall-width
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-The height is:
-</para>
-<para>
-<!-- .LP -->
-<literallayout class="monospaced">
-font-ascent + font-descent
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-The overall-width, font-ascent, and font-descent
-are as would be returned by
-<function>XQueryTextExtents</function>
-using gc and string.
-The function and fill-style defined in the GC are ignored for these functions.
-The effective function is
-<symbol>GXcopy</symbol>,
-and the effective fill-style is
-<symbol>FillSolid</symbol>.
-</para>
-<para>
-<!-- .LP -->
-For fonts defined with 2-byte matrix indexing
-and used with
-<function>XDrawImageString</function>,
-each byte is used as a byte2 with a byte1 of zero.
-</para>
-<para>
-<!-- .LP -->
-Both functions use these GC components:
-plane-mask, foreground, background, font, subwindow-mode, clip-x-origin,
-clip-y-origin, and clip-mask.
-</para>
-<para>
-<!-- .LP -->
-<function>XDrawImageString</function>
-and
-<function>XDrawImageString16</function>
-can generate
-<errorname>BadDrawable</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadMatch</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-</para>
-</sect2>
-</sect1>
-<sect1 id="Transferring_Images_between_Client_and_Server">
-<title>Transferring Images between Client and Server</title>
-<!-- .XS -->
-<!-- (SN Transferring Images between Client and Server -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-Xlib provides functions that you can use to transfer images between a client
-and the server.
-Because the server may require diverse data formats,
-Xlib provides an image object that fully describes the data in memory
-and that provides for basic operations on that data.
-You should reference the data
-through the image object rather than referencing the data directly.
-However, some implementations of the Xlib library may efficiently deal with
-frequently used data formats by replacing
-functions in the procedure vector with special case functions.
-Supported operations include destroying the image, getting a pixel,
-storing a pixel, extracting a subimage of an image, and adding a constant
-to an image (see section 16.8).
-</para>
-<para>
-<!-- .LP -->
-All the image manipulation functions discussed in this section make use of
-the
-<structname>XImage</structname>
-structure,
-which describes an image as it exists in the client's memory.
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XImage</primary></indexterm>
-<!-- .sM -->
-<literallayout class="monospaced">
-<!-- .TA .5i 1i 3i -->
-<!-- .ta .5i 1i 3i -->
-typedef struct _XImage {
- int width, height; /* size of image */
- int xoffset; /* number of pixels offset in X direction */
- int format; /* XYBitmap, XYPixmap, ZPixmap */
- char *data; /* pointer to image data */
- int byte_order; /* data byte order, LSBFirst, MSBFirst */
- int bitmap_unit; /* quant. of scanline 8, 16, 32 */
- int bitmap_bit_order; /* LSBFirst, MSBFirst */
- int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */
- int depth; /* depth of image */
- int bytes_per_line; /* accelerator to next scanline */
- int bits_per_pixel; /* bits per pixel (ZPixmap) */
- unsigned long red_mask; /* bits in z arrangement */
- unsigned long green_mask;
- unsigned long blue_mask;
- XPointer obdata; /* hook for the object routines to hang on */
- struct funcs { /* image manipulation routines */
- struct _XImage *(*create_image)();
- int (*destroy_image)();
- unsigned long (*get_pixel)();
- int (*put_pixel)();
- struct _XImage *(*sub_image)();
- int (*add_pixel)();
- } f;
-} XImage;
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-To initialize the image manipulation routines of an image structure, use
-<function>XInitImage</function>.
-<indexterm significance="preferred"><primary>XInitImage</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>Status <function>XInitImage</function></funcdef>
- <paramdef>XImage<parameter> *image</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>ximage</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the image.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XInitImage</function>
-function initializes the internal image manipulation routines of an
-image structure, based on the values of the various structure members.
-All fields other than the manipulation routines must already be initialized.
-If the bytes_per_line member is zero,
-<function>XInitImage</function>
-will assume the image data is contiguous in memory and set the
-bytes_per_line member to an appropriate value based on the other
-members; otherwise, the value of bytes_per_line is not changed.
-All of the manipulation routines are initialized to functions
-that other Xlib image manipulation functions need to operate on the
-type of image specified by the rest of the structure.
-</para>
-<para>
-<!-- .LP -->
-This function must be called for any image constructed by the client
-before passing it to any other Xlib function.
-Image structures created or returned by Xlib do not need to be
-initialized in this fashion.
-</para>
-<para>
-<!-- .LP -->
-This function returns a nonzero status if initialization of the
-structure is successful. It returns zero if it detected some error
-or inconsistency in the structure, in which case the image is not changed.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To combine an image with a rectangle of a drawable on the display,
-use
-<function>XPutImage</function>.
-<indexterm significance="preferred"><primary>XPutImage</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XPutImage</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>XImage<parameter> *image</parameter></paramdef>
- <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>
- <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef>
- <paramdef>unsignedintwidth,<parameter> height</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'>image</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the image you want combined with the rectangle.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>src_x</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the offset in X from the left edge of the image defined
-by the
-<structname>XImage</structname>
-structure.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>src_y</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the offset in Y from the top edge of the image defined
-by the
-<structname>XImage</structname>
-structure.
-<!-- .ds Dx , which are relative to the origin of the drawable \ -->
-and are the coordinates of the subimage
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>dest_x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>dest_y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates(Dx.
-<!-- .ds Wh \ of the subimage, which define the dimensions of the rectangle -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>width</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>height</emphasis>
- </term>
- <listitem>
- <para>
-Specify the width and height(Wh.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XPutImage</function>
-function
-combines an image with a rectangle of the specified drawable.
-The section of the image defined by the src_x, src_y, width, and height
-arguments is drawn on the specified part of the drawable.
-If
-<symbol>XYBitmap</symbol>
-format is used, the depth of the image must be one,
-or a
-<errorname>BadMatch</errorname>
-error results.
-The foreground pixel in the GC defines the source for the one bits in the image,
-and the background pixel defines the source for the zero bits.
-For
-<symbol>XYPixmap</symbol>
-and
-<symbol>ZPixmap</symbol>,
-the depth of the image must match the depth of the drawable,
-or a
-<errorname>BadMatch</errorname>
-error results.
-</para>
-<para>
-<!-- .LP -->
-If the characteristics of the image (for example, byte_order and bitmap_unit)
-differ from what the server requires,
-<function>XPutImage</function>
-automatically makes the appropriate
-conversions.
-</para>
-<para>
-<!-- .LP -->
-This function uses these GC components:
-function, plane-mask, subwindow-mode, clip-x-origin, clip-y-origin,
-and clip-mask.
-It also uses these GC mode-dependent components:
-foreground and background.
-</para>
-<para>
-<!-- .LP -->
-<function>XPutImage</function>
-can generate
-<errorname>BadDrawable</errorname>,
-<errorname>BadGC</errorname>,
-<errorname>BadMatch</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To return the contents of a rectangle in a given drawable on the display,
-use
-<function>XGetImage</function>.
-This function specifically supports rudimentary screen dumps.
-<indexterm significance="preferred"><primary>XGetImage</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>XImage *<function>XGetImage</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>intx,<parameter> y</parameter></paramdef>
- <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
- <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>
- <paramdef>int<parameter> format</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.
-<!-- .ds Xy , which are relative to the origin of the drawable \ -->
-and define the upper-left corner of the rectangle
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates(Xy.
-<!-- .ds Wh \ of the subimage, which define the dimensions of the rectangle -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>width</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>height</emphasis>
- </term>
- <listitem>
- <para>
-Specify the width and height(Wh.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>plane_mask</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the plane mask.
-<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>format</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the format for the image.
-You can pass
-<symbol>XYPixmap</symbol>
-or
-<symbol>ZPixmap</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XGetImage</function>
-function returns a pointer to an
-<structname>XImage</structname>
-structure.
-This structure provides you with the contents of the specified rectangle of
-the drawable in the format you specify.
-If the format argument is
-<symbol>XYPixmap</symbol>,
-the image contains only the bit planes you passed to the plane_mask argument.
-If the plane_mask argument only requests a subset of the planes of the
-display, the depth of the returned image will be the number of planes
-requested.
-If the format argument is
-<symbol>ZPixmap</symbol>,
-<function>XGetImage</function>
-returns as zero the bits in all planes not
-specified in the plane_mask argument.
-The function performs no range checking on the values in plane_mask and ignores
-extraneous bits.
-</para>
-<para>
-<!-- .LP -->
-<function>XGetImage</function>
-returns the depth of the image to the depth member of the
-<structname>XImage</structname>
-structure.
-The depth of the image is as specified when the drawable was created,
-except when getting a subset of the planes in
-<symbol>XYPixmap</symbol>
-format, when the depth is given by the number of bits set to 1 in plane_mask.
-</para>
-<para>
-<!-- .LP -->
-If the drawable is a pixmap,
-the given rectangle must be wholly contained within the pixmap,
-or a
-<errorname>BadMatch</errorname>
-error results.
-If the drawable is a window,
-the window must be viewable,
-and it must be the case that if there were no inferiors or overlapping windows,
-the specified rectangle of the window would be fully visible on the screen
-and wholly contained within the outside edges of the window,
-or a
-<errorname>BadMatch</errorname>
-error results.
-Note that the borders of the window can be included and read with
-this request.
-If the window has backing-store, the backing-store contents are
-returned for regions of the window that are obscured by noninferior
-windows.
-If the window does not have backing-store,
-the returned contents of such obscured regions are undefined.
-The returned contents of visible regions of inferiors
-of a different depth than the specified window's depth are also undefined.
-The pointer cursor image is not included in the returned contents.
-If a problem occurs,
-<function>XGetImage</function>
-returns NULL.
-</para>
-<para>
-<!-- .LP -->
-<function>XGetImage</function>
-can generate
-<errorname>BadDrawable</errorname>,
-<errorname>BadMatch</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-<!-- .sp -->
-</para>
-<para>
-<!-- .LP -->
-To copy the contents of a rectangle on the display
-to a location within a preexisting image structure, use
-<function>XGetSubImage</function>.
-<indexterm significance="preferred"><primary>XGetSubImage</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>XImage *<function>XGetSubImage</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>intx,<parameter> y</parameter></paramdef>
- <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
- <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>
- <paramdef>int<parameter> format</parameter></paramdef>
- <paramdef>XImage<parameter> *dest_image</parameter></paramdef>
- <paramdef>intdest_x,<parameter> dest_y</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.
-<!-- .ds Xy , which are relative to the origin of the drawable \ -->
-and define the upper-left corner of the rectangle
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates(Xy.
-<!-- .ds Wh \ of the subimage, which define the dimensions of the rectangle -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>width</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>height</emphasis>
- </term>
- <listitem>
- <para>
-Specify the width and height(Wh.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>plane_mask</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the plane mask.
-<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>format</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the format for the image.
-You can pass
-<symbol>XYPixmap</symbol>
-or
-<symbol>ZPixmap</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>dest_image</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the destination image.
-<!-- .ds Dx , which are relative to the origin of the destination rectangle, \ -->
-specify its upper-left corner, and determine where the subimage \
-is placed in the destination image
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>dest_x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>dest_y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates(Dx.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XGetSubImage</function>
-function updates dest_image with the specified subimage in the same manner as
-<function>XGetImage</function>.
-If the format argument is
-<symbol>XYPixmap</symbol>,
-the image contains only the bit planes you passed to the plane_mask argument.
-If the format argument is
-<symbol>ZPixmap</symbol>,
-<function>XGetSubImage</function>
-returns as zero the bits in all planes not
-specified in the plane_mask argument.
-The function performs no range checking on the values in plane_mask and ignores
-extraneous bits.
-As a convenience,
-<function>XGetSubImage</function>
-returns a pointer to the same
-<structname>XImage</structname>
-structure specified by dest_image.
-</para>
-<para>
-<!-- .LP -->
-The depth of the destination
-<structname>XImage</structname>
-structure must be the same as that of the drawable.
-If the specified subimage does not fit at the specified location
-on the destination image, the right and bottom edges are clipped.
-If the drawable is a pixmap,
-the given rectangle must be wholly contained within the pixmap,
-or a
-<errorname>BadMatch</errorname>
-error results.
-If the drawable is a window,
-the window must be viewable,
-and it must be the case that if there were no inferiors or overlapping windows,
-the specified rectangle of the window would be fully visible on the screen
-and wholly contained within the outside edges of the window,
-or a
-<errorname>BadMatch</errorname>
-error results.
-If the window has backing-store,
-then the backing-store contents are returned for regions of the window
-that are obscured by noninferior windows.
-If the window does not have backing-store,
-the returned contents of such obscured regions are undefined.
-The returned contents of visible regions of inferiors
-of a different depth than the specified window's depth are also undefined.
-If a problem occurs,
-<function>XGetSubImage</function>
-returns NULL.
-</para>
-<para>
-<!-- .LP -->
-<function>XGetSubImage</function>
-can generate
-<errorname>BadDrawable</errorname>,
-<errorname>BadGC</errorname>,
-<errorname>BadMatch</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-<!-- .bp -->
-
-
-</para>
-</sect1>
-</chapter>
+<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> +<chapter id="graphics_functions"> +<title>Graphics Functions</title> +<para> +Once you have established a connection to a display, you can use the Xlib graphics functions to: +</para> +<itemizedlist> + <listitem><para>Clear and copy areas</para></listitem> + <listitem><para>Draw points, lines, rectangles, and arcs</para></listitem> + <listitem><para>Fill areas</para></listitem> + <listitem><para>Manipulate fonts</para></listitem> + <listitem><para>Draw text</para></listitem> + <listitem><para>Transfer images between clients and the server</para></listitem> +</itemizedlist> +<para> +If the same drawable and GC is used for each call, Xlib batches back-to-back +calls to XDrawPoint, XDrawLine, XDrawRectangle, XFillArc, and XFillRectangle. +Note that this reduces the total number of requests sent to the server. +</para> +<sect1 id="Clearing_Areas"> +<title>Clearing Areas</title> +<!-- .XS --> +<!-- (SN Clearing Areas --> +<!-- .XE --> +<para> +<!-- .LP --> +Xlib provides functions that you can use to clear an area or the entire window. +Because pixmaps do not have defined backgrounds, +they cannot be filled by using the functions described in this section. +Instead, to accomplish an analogous operation on a pixmap, +you should use +<function>XFillRectangle</function>, +which sets the pixmap to a known value. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To clear a rectangular area of a given window, use +<function>XClearArea</function>. +<indexterm><primary>Areas</primary><secondary>clearing</secondary></indexterm> +<indexterm><primary>Clearing</primary><secondary>areas</secondary></indexterm> +<indexterm significance="preferred"><primary>XClearArea</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xcleararea'> +<funcprototype> + <funcdef><function>XClearArea</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> w</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> + <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef> + <paramdef>Bool<parameter> exposures</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. +<!-- .ds Xy , which are relative to the origin of the window \ --> +and specify the upper-left corner of the rectangle + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Xy. +<!-- .ds Wh , which are the dimensions of the rectangle --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>width</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>height</emphasis> + </term> + <listitem> + <para> +Specify the width and height(Wh. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>exposures</emphasis> + </term> + <listitem> + <para> +Specifies a Boolean value that indicates if +<symbol>Expose</symbol> +events are to be generated. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XClearArea</function> +function paints a rectangular area in the specified window according to the +specified dimensions with the window's background pixel or pixmap. +The subwindow-mode effectively is +<symbol>ClipByChildren</symbol>. +If width is zero, it +is replaced with the current width of the window minus x. +If height is +zero, it is replaced with the current height of the window minus y. +If the window has a defined background tile, +the rectangle clipped by any children is filled with this tile. +If the window has +background +<symbol>None</symbol>, +the contents of the window are not changed. +In either +case, if exposures is +<symbol>True</symbol>, +one or more +<symbol>Expose</symbol> +events are generated for regions of the rectangle that are either visible or are +being retained in a backing store. +If you specify a window whose class is +<symbol>InputOnly</symbol>, +a +<errorname>BadMatch</errorname> +error results. +</para> +<para> +<!-- .LP --> +<function>XClearArea</function> +can generate +<errorname>BadMatch</errorname>, +<errorname>BadValue</errorname>, +and +<errorname>BadWindow</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To clear the entire area in a given window, use +<function>XClearWindow</function>. +<indexterm><primary>Window</primary><secondary>clearing</secondary></indexterm> +<indexterm><primary>Clearing</primary><secondary>windows</secondary></indexterm> +<indexterm significance="preferred"><primary>XClearWindow</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xclearwindow'> +<funcprototype> + <funcdef><function>XClearWindow</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> w</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> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XClearWindow</function> +function clears the entire area in the specified window and is +equivalent to +<function>XClearArea</function> +(display, w, 0, 0, 0, 0, +<symbol>False</symbol>). +If the window has a defined background tile, the rectangle is tiled with a +plane-mask of all ones and +<symbol>GXcopy</symbol> +function. +If the window has +background +<symbol>None</symbol>, +the contents of the window are not changed. +If you specify a window whose class is +<symbol>InputOnly</symbol>, +a +<errorname>BadMatch</errorname> +error results. +</para> +<para> +<!-- .LP --> +<function>XClearWindow</function> +can generate +<errorname>BadMatch</errorname> +and +<errorname>BadWindow</errorname> +errors. +</para> +</sect1> +<sect1 id="Copying_Areas"> +<title>Copying Areas</title> +<!-- .XS --> +<!-- (SN Copying Areas --> +<!-- .XE --> +<para> +<!-- .LP --> +Xlib provides functions that you can use to copy an area or a bit plane. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To copy an area between drawables of the same +root and depth, use +<function>XCopyArea</function>. +<indexterm><primary>Areas</primary><secondary>copying</secondary></indexterm> +<indexterm><primary>Copying</primary><secondary>areas</secondary></indexterm> +<indexterm significance="preferred"><primary>XCopyArea</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xcopyarea'> +<funcprototype> + <funcdef><function>XCopyArea</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawablesrc,<parameter> dest</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef> + <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef> + <paramdef>intdest_x,<parameter> dest_y</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'>src</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dest</emphasis> + </term> + <listitem> + <para> +Specify the source and destination rectangles to be combined. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>src_x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>src_y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates, +which are relative to the origin of the source rectangle +and specify its upper-left corner. +<!-- .ds Wh , which are the dimensions of both the source \ --> +and destination rectangles + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>width</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>height</emphasis> + </term> + <listitem> + <para> +Specify the width and height(Wh. +<!-- .ds Dx , which are relative to the origin of the destination rectangle \ --> +and specify its upper-left corner + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dest_x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dest_y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Dx. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XCopyArea</function> +function combines the specified rectangle of src with the specified rectangle +of dest. +The drawables must have the same root and depth, +or a +<errorname>BadMatch</errorname> +error results. +</para> +<para> +<!-- .LP --> +If regions of the source rectangle are obscured and have not been +retained in backing store +or if regions outside the boundaries of the source drawable are specified, +those regions are not copied. +Instead, the +following occurs on all corresponding destination regions that are either +visible or are retained in backing store. +If the destination is a window with a background other than +<symbol>None</symbol>, +corresponding regions +of the destination are tiled with that background +(with plane-mask of all ones and +<symbol>GXcopy</symbol> +function). +Regardless of tiling or whether the destination is a window or a pixmap, +if graphics-exposures is +<symbol>True</symbol>, +then +<symbol>GraphicsExpose</symbol> +events for all corresponding destination regions are generated. +If graphics-exposures is +<symbol>True</symbol> +but no +<symbol>GraphicsExpose</symbol> +events are generated, a +<symbol>NoExpose</symbol> +event is generated. +Note that by default graphics-exposures is +<symbol>True</symbol> +in new GCs. +</para> +<para> +<!-- .LP --> +This function uses these GC components: function, plane-mask, +subwindow-mode, graphics-exposures, clip-x-origin, +clip-y-origin, and clip-mask. +</para> +<para> +<!-- .LP --> +<function>XCopyArea</function> +can generate +<errorname>BadDrawable</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadMatch</errorname> +errors. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To copy a single bit plane of a given drawable, use +<function>XCopyPlane</function>. +<indexterm><primary>Plane</primary><secondary>copying</secondary></indexterm> +<indexterm><primary>Copying</primary><secondary>planes</secondary></indexterm> +<indexterm significance="preferred"><primary>XCopyPlane</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xcopyplane'> +<funcprototype> + <funcdef><function>XCopyPlane</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawablesrc,<parameter> dest</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef> + <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef> + <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef> + <paramdef>unsignedlong<parameter> plane</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'>src</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dest</emphasis> + </term> + <listitem> + <para> +Specify the source and destination rectangles to be combined. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>src_x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>src_y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates, +which are relative to the origin of the source rectangle +and specify its upper-left corner. +<!-- .ds Wh , which are the dimensions of both the source and destination rectangles --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>width</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>height</emphasis> + </term> + <listitem> + <para> +Specify the width and height(Wh. +<!-- .ds Dx , which are relative to the origin of the destination rectangle \ --> +and specify its upper-left corner + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dest_x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dest_y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Dx. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>plane</emphasis> + </term> + <listitem> + <para> +Specifies the bit plane. +You must set exactly one bit to 1. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XCopyPlane</function> +function uses a single bit plane of the specified source rectangle +combined with the specified GC to modify the specified rectangle of dest. +The drawables must have the same root but need not have the same depth. +If the drawables do not have the same root, a +<errorname>BadMatch</errorname> +error results. +If plane does not have exactly one bit set to 1 and the value of plane +is not less than %2 sup n%, where <emphasis remap='I'>n</emphasis> is the depth of src, a +<errorname>BadValue</errorname> +error results. +</para> +<para> +<!-- .LP --> +Effectively, +<function>XCopyPlane</function> +forms a pixmap of the same depth as the rectangle of dest and with a +size specified by the source region. +It uses the foreground/background pixels in the GC (foreground +everywhere the bit plane in src contains a bit set to 1, +background everywhere the bit plane in src contains a bit set to 0) +and the equivalent of a +<systemitem>CopyArea</systemitem> +protocol request is performed with all the same exposure semantics. +This can also be thought of as using the specified region of the source +bit plane as a stipple with a fill-style of +<symbol>FillOpaqueStippled</symbol> +for filling a rectangular area of the destination. +</para> +<para> +<!-- .LP --> +This function uses these GC components: function, plane-mask, foreground, +background, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin, +and clip-mask. +</para> +<para> +<!-- .LP --> +<function>XCopyPlane</function> +can generate +<errorname>BadDrawable</errorname>, +<errorname>BadGC</errorname>, +<errorname>BadMatch</errorname>, +and +<errorname>BadValue</errorname> +errors. +</para> +</sect1> +<sect1 id="Drawing_Points_Lines_Rectangles_and_Arcs"> +<title>Drawing Points, Lines, Rectangles, and Arcs</title> +<!-- .XS --> +<!-- (SN Drawing Points, Lines, Rectangles, and Arcs --> +<!-- .XE --> +<para> +<!-- .LP --> +Xlib provides functions that you can use to draw: +</para> +<itemizedlist> + <listitem> + <para> +A single point or multiple points + </para> + </listitem> + <listitem> + <para> +A single line or multiple lines + </para> + </listitem> + <listitem> + <para> +A single rectangle or multiple rectangles + </para> + </listitem> + <listitem> + <para> +A single arc or multiple arcs + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +Some of the functions described in the following sections +use these structures: +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XSegment</primary></indexterm> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + short x1, y1, x2, y2; +} XSegment; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<indexterm significance="preferred"><primary>XPoint</primary></indexterm> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + short x, y; +} XPoint; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<indexterm significance="preferred"><primary>XRectangle</primary></indexterm> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + short x, y; + unsigned short width, height; +} XRectangle; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<indexterm significance="preferred"><primary>XArc</primary></indexterm> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + short x, y; + unsigned short width, height; + short angle1, angle2; /* Degrees * 64 */ +} XArc; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +All x and y members are signed integers. +The width and height members are 16-bit unsigned integers. +You should be careful not to generate coordinates and sizes +out of the 16-bit ranges, because the protocol only has 16-bit fields +for these values. +</para> +<sect2 id="Drawing_Single_and_Multiple_Points"> +<title>Drawing Single and Multiple Points</title> +<!-- .XS --> +<!-- (SN Drawing Single and Multiple Points --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>Points</primary><secondary>drawing</secondary></indexterm> +<indexterm><primary>Drawing</primary><secondary>points</secondary></indexterm> +<indexterm><primary>XDrawPoints</primary></indexterm> +<indexterm><primary>XDrawPoint</primary></indexterm> +</para> +<para> +<!-- .LP --> +To draw a single point in a given drawable, use +<function>XDrawPoint</function>. +<indexterm significance="preferred"><primary>XDrawPoint</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xdrawpoint'> +<funcprototype> + <funcdef><function>XDrawPoint</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intx,<parameter> y</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'>x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates where you want the point drawn. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<!-- .sp --> +To draw multiple points in a given drawable, use +<function>XDrawPoints</function>. +<indexterm significance="preferred"><primary>XDrawPoints</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xdrawpoints'> +<funcprototype> + <funcdef><function>XDrawPoints</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>XPoint<parameter> *points</parameter></paramdef> + <paramdef>int<parameter> npoints</parameter></paramdef> + <paramdef>int<parameter> mode</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'>points</emphasis> + </term> + <listitem> + <para> +Specifies an array of points. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>npoints</emphasis> + </term> + <listitem> + <para> +Specifies the number of points in the array. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>mode</emphasis> + </term> + <listitem> + <para> +Specifies the coordinate mode. +You can pass +<symbol>CoordModeOrigin</symbol> +or +<symbol>CoordModePrevious</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XDrawPoint</function> +function uses the foreground pixel and function components of the +GC to draw a single point into the specified drawable; +<function>XDrawPoints</function> +draws multiple points this way. +<symbol>CoordModeOrigin</symbol> +treats all coordinates as relative to the origin, +and +<symbol>CoordModePrevious</symbol> +treats all coordinates after the first as relative to the previous point. +<function>XDrawPoints</function> +draws the points in the order listed in the array. +</para> +<para> +<!-- .LP --> +Both functions use these GC components: function, plane-mask, +foreground, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. +</para> +<para> +<!-- .LP --> +<function>XDrawPoint</function> +can generate +<errorname>BadDrawable</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadMatch</errorname> +errors. +<function>XDrawPoints</function> +can generate +<errorname>BadDrawable</errorname>, +<errorname>BadGC</errorname>, +<errorname>BadMatch</errorname>, +and +<errorname>BadValue</errorname> +errors. +</para> +</sect2> +<sect2 id="Drawing_Single_and_Multiple_Lines"> +<title>Drawing Single and Multiple Lines</title> +<!-- .XS --> +<!-- (SN Drawing Single and Multiple Lines --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>Lines</primary><secondary>drawing</secondary></indexterm> +<indexterm><primary>Drawing</primary><secondary>lines</secondary></indexterm> +<indexterm><primary>XDrawLine</primary></indexterm> +<indexterm><primary>XDrawLines</primary></indexterm> +<indexterm><primary>Polygons</primary><secondary>drawing</secondary></indexterm> +<indexterm><primary>Drawing</primary><secondary>polygons</secondary></indexterm> +<indexterm><primary>XDrawSegments</primary></indexterm> +</para> +<para> +<!-- .LP --> +To draw a single line between two points in a given drawable, use +<function>XDrawLine</function>. +<indexterm significance="preferred"><primary>XDrawLine</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xdrawline'> +<funcprototype> + <funcdef><function>XDrawLine</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intx1,y1,x2,<parameter> y2</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'>x1</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y1</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x2</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y2</emphasis> + </term> + <listitem> + <para> +Specify the points (x1, y1) and (x2, y2) to be connected. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<!-- .sp --> +To draw multiple lines in a given drawable, use +<function>XDrawLines</function>. +<indexterm significance="preferred"><primary>XDrawLines</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xdrawlines'> +<funcprototype> + <funcdef><function>XDrawLines</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>XPoint<parameter> *points</parameter></paramdef> + <paramdef>int<parameter> npoints</parameter></paramdef> + <paramdef>int<parameter> mode</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'>points</emphasis> + </term> + <listitem> + <para> +Specifies an array of points. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>npoints</emphasis> + </term> + <listitem> + <para> +Specifies the number of points in the array. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>mode</emphasis> + </term> + <listitem> + <para> +Specifies the coordinate mode. +You can pass +<symbol>CoordModeOrigin</symbol> +or +<symbol>CoordModePrevious</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<!-- .sp --> +To draw multiple, unconnected lines in a given drawable, +use +<function>XDrawSegments</function>. +<indexterm significance="preferred"><primary>XDrawSegments</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xdrawsegments'> +<funcprototype> + <funcdef><function>XDrawSegments</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>XSegment<parameter> *segments</parameter></paramdef> + <paramdef>int<parameter> nsegments</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'>segments</emphasis> + </term> + <listitem> + <para> +Specifies an array of segments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>nsegments</emphasis> + </term> + <listitem> + <para> +Specifies the number of segments in the array. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XDrawLine</function> +function uses the components of the specified GC to +draw a line between the specified set of points (x1, y1) and (x2, y2). +It does not perform joining at coincident endpoints. +For any given line, +<function>XDrawLine</function> +does not draw a pixel more than once. +If lines intersect, the intersecting pixels are drawn multiple times. +</para> +<para> +<!-- .LP --> +The +<function>XDrawLines</function> +function uses the components of the specified GC to draw +npoints-1 lines between each pair of points (point[i], point[i+1]) +in the array of +<structname>XPoint</structname> +structures. +It draws the lines in the order listed in the array. +The lines join correctly at all intermediate points, and if the first and last +points coincide, the first and last lines also join correctly. +For any given line, +<function>XDrawLines</function> +does not draw a pixel more than once. +If thin (zero line-width) lines intersect, +the intersecting pixels are drawn multiple times. +If wide lines intersect, the intersecting pixels are drawn only once, as though +the entire +<systemitem>PolyLine</systemitem> +protocol request were a single, filled shape. +<symbol>CoordModeOrigin</symbol> +treats all coordinates as relative to the origin, +and +<symbol>CoordModePrevious</symbol> +treats all coordinates after the first as relative to the previous point. +</para> +<para> +<!-- .LP --> +The +<function>XDrawSegments</function> +function draws multiple, unconnected lines. +For each segment, +<function>XDrawSegments</function> +draws a +line between (x1, y1) and (x2, y2). +It draws the lines in the order listed in the array of +<structname>XSegment</structname> +structures and does not perform joining at coincident endpoints. +For any given line, +<function>XDrawSegments</function> +does not draw a pixel more than once. +If lines intersect, the intersecting pixels are drawn multiple times. +</para> +<para> +<!-- .LP --> +All three functions use these GC components: +function, plane-mask, line-width, +line-style, cap-style, fill-style, subwindow-mode, +clip-x-origin, clip-y-origin, and clip-mask. +The +<function>XDrawLines</function> +function also uses the join-style GC component. +All three functions also use these GC mode-dependent components: +foreground, background, tile, stipple, tile-stipple-x-origin, +tile-stipple-y-origin, dash-offset, and dash-list. +</para> +<para> +<!-- .LP --> +<function>XDrawLine</function>, +<function>XDrawLines</function>, +and +<function>XDrawSegments</function> +can generate +<errorname>BadDrawable</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadMatch</errorname> +errors. +<function>XDrawLines</function> +also can generate +<errorname>BadValue</errorname> +errors. +</para> +</sect2> +<sect2 id="Drawing_Single_and_Multiple_Rectangles_"> +<title>Drawing Single and Multiple Rectangles </title> +<!-- .XS --> +<!-- (SN Drawing Single and Multiple Rectangles --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>Rectangles</primary><secondary>drawing</secondary></indexterm> +<indexterm><primary>Drawing</primary><secondary>rectangles</secondary></indexterm> +<indexterm><primary>XDrawRectangle</primary></indexterm> +<indexterm><primary>XDrawRectangles</primary></indexterm> +</para> +<para> +<!-- .LP --> +To draw the outline of a single rectangle in a given drawable, use +<function>XDrawRectangle</function>. +<indexterm significance="preferred"><primary>XDrawRectangle</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xdrawrectangle'> +<funcprototype> + <funcdef><function>XDrawRectangle</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> + <paramdef>unsignedintwidth,<parameter> height</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. +<!-- .ds Xy , which specify the upper-left corner of the rectangle --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Xy. +<!-- .ds Wh , which specify the dimensions of the rectangle --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>width</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>height</emphasis> + </term> + <listitem> + <para> +Specify the width and height(Wh. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<!-- .sp --> +To draw the outline of multiple rectangles +in a given drawable, use +<function>XDrawRectangles</function>. +<indexterm significance="preferred"><primary>XDrawRectangles</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xdrawrectangles'> +<funcprototype> + <funcdef><function>XDrawRectangles</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>XRectangle<parameter> rectangles[]</parameter></paramdef> + <paramdef>int<parameter> nrectangles</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'>rectangles</emphasis> + </term> + <listitem> + <para> +Specifies an array of rectangles. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>nrectangles</emphasis> + </term> + <listitem> + <para> +Specifies the number of rectangles in the array. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XDrawRectangle</function> +and +<function>XDrawRectangles</function> +functions draw the outlines of the specified rectangle or rectangles as +if a five-point +<systemitem>PolyLine</systemitem> +protocol request were specified for each rectangle: +</para> +<itemizedlist> + <listitem> + <para> +[x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y] + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +For the specified rectangle or rectangles, +these functions do not draw a pixel more than once. +<function>XDrawRectangles</function> +draws the rectangles in the order listed in the array. +If rectangles intersect, +the intersecting pixels are drawn multiple times. +</para> +<para> +<!-- .LP --> +Both functions use these GC components: +function, plane-mask, line-width, +line-style, cap-style, join-style, fill-style, +subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. +They also use these GC mode-dependent components: +foreground, background, tile, stipple, tile-stipple-x-origin, +tile-stipple-y-origin, dash-offset, and dash-list. +</para> +<para> +<!-- .LP --> +<function>XDrawRectangle</function> +and +<function>XDrawRectangles</function> +can generate +<errorname>BadDrawable</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadMatch</errorname> +errors. +</para> +</sect2> +<sect2 id="Drawing_Single_and_Multiple_Arcs"> +<title>Drawing Single and Multiple Arcs</title> +<!-- .XS --> +<!-- (SN Drawing Single and Multiple Arcs --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>Drawing</primary><secondary>arcs</secondary></indexterm> +<indexterm><primary>XDrawArc</primary></indexterm> +<indexterm><primary>Arcs</primary><secondary>drawing</secondary></indexterm> +<indexterm><primary>XDrawArcs</primary></indexterm> +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To draw a single arc in a given drawable, use +<function>XDrawArc</function>. +<indexterm significance="preferred"><primary>XDrawArc</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xdrawarc'> +<funcprototype> + <funcdef><function>XDrawArc</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> + <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef> + <paramdef>intangle1,<parameter> angle2</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. +<!-- .ds Xy , which are relative to the origin of the drawable \ --> +and specify the upper-left corner of the bounding rectangle + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Xy. +<!-- .ds Wh , which are the major and minor axes of the arc --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>width</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>height</emphasis> + </term> + <listitem> + <para> +Specify the width and height(Wh. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>angle1</emphasis> + </term> + <listitem> + <para> +Specifies the start of the arc relative to the three-o'clock position +from the center, in units of degrees * 64. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>angle2</emphasis> + </term> + <listitem> + <para> +Specifies the path and extent of the arc relative to the start of the +arc, in units of degrees * 64. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<!-- .sp --> +To draw multiple arcs in a given drawable, use +<function>XDrawArcs</function>. +<indexterm significance="preferred"><primary>XDrawArcs</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xdrawarcs'> +<funcprototype> + <funcdef><function>XDrawArcs</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>XArc<parameter> *arcs</parameter></paramdef> + <paramdef>int<parameter> narcs</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'>arcs</emphasis> + </term> + <listitem> + <para> +Specifies an array of arcs. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>narcs</emphasis> + </term> + <listitem> + <para> +Specifies the number of arcs in the array. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<!-- .EQ --> +delim %% +<!-- .EN --> +<function>XDrawArc</function> +draws a single circular or elliptical arc, and +<function>XDrawArcs</function> +draws multiple circular or elliptical arcs. +Each arc is specified by a rectangle and two angles. +The center of the circle or ellipse is the center of the +rectangle, and the major and minor axes are specified by the width and height. +Positive angles indicate counterclockwise motion, +and negative angles indicate clockwise motion. +If the magnitude of angle2 is greater than 360 degrees, +<function>XDrawArc</function> +or +<function>XDrawArcs</function> +truncates it to 360 degrees. +</para> +<para> +<!-- .LP --> +For an arc specified as %[ ~x, ~y, ~width , ~height, ~angle1, ~angle2 ]%, +the origin of the major and minor axes is at +% [ x +^ {width over 2} , ~y +^ {height over 2} ]%, +and the infinitely thin path describing the entire circle or ellipse +intersects the horizontal axis at % [ x, ~y +^ {height over 2} ]% and +% [ x +^ width , ~y +^ { height over 2 }] % +and intersects the vertical axis at % [ x +^ { width over 2 } , ~y ]% and +% [ x +^ { width over 2 }, ~y +^ height ]%. +These coordinates can be fractional +and so are not truncated to discrete coordinates. +The path should be defined by the ideal mathematical path. +For a wide line with line-width lw, +the bounding outlines for filling are given +by the two infinitely thin paths consisting of all points whose perpendicular +distance from the path of the circle/ellipse is equal to lw/2 +(which may be a fractional value). +The cap-style and join-style are applied the same as for a line +corresponding to the tangent of the circle/ellipse at the endpoint. +</para> +<para> +<!-- .LP --> +For an arc specified as % [ ~x, ~y, ~width, ~height, ~angle1, ~angle2 ]%, +the angles must be specified +in the effectively skewed coordinate system of the ellipse (for a +circle, the angles and coordinate systems are identical). The +relationship between these angles and angles expressed in the normal +coordinate system of the screen (as measured with a protractor) is as +follows: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +% roman "skewed-angle" ~ = ~ atan left ( tan ( roman "normal-angle" ) + * width over height right ) +^ adjust% +</literallayout> +</para> +<para> +<!-- .LP --> +The skewed-angle and normal-angle are expressed in radians (rather +than in degrees scaled by 64) in the range % [ 0 , ~2 pi ]% and where atan +returns a value in the range % [ - pi over 2 , ~pi over 2 ] % +and adjust is: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 1i 2i --> +<!-- .ta 1i 2i --> +%0% for normal-angle in the range % [ 0 , ~pi over 2 ]% +%pi% for normal-angle in the range % [ pi over 2 , ~{3 pi} over 2 ]% +%2 pi% for normal-angle in the range % [ {3 pi} over 2 , ~2 pi ]% +</literallayout> +</para> +<para> +<!-- .LP --> +For any given arc, +<function>XDrawArc</function> +and +<function>XDrawArcs</function> +do not draw a pixel more than once. +If two arcs join correctly and if the line-width is greater than zero +and the arcs intersect, +<function>XDrawArc</function> +and +<function>XDrawArcs</function> +do not draw a pixel more than once. +Otherwise, +the intersecting pixels of intersecting arcs are drawn multiple times. +Specifying an arc with one endpoint and a clockwise extent draws the same pixels +as specifying the other endpoint and an equivalent counterclockwise extent, +except as it affects joins. +</para> +<para> +<!-- .LP --> +If the last point in one arc coincides with the first point in the following +arc, the two arcs will join correctly. +If the first point in the first arc coincides with the last point in the last +arc, the two arcs will join correctly. +By specifying one axis to be zero, a horizontal or vertical line can be +drawn. +Angles are computed based solely on the coordinate system and ignore the +aspect ratio. +</para> +<para> +<!-- .LP --> +Both functions use these GC components: +function, plane-mask, line-width, line-style, cap-style, join-style, +fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. +They also use these GC mode-dependent components: +foreground, background, tile, stipple, tile-stipple-x-origin, +tile-stipple-y-origin, dash-offset, and dash-list. +</para> +<para> +<!-- .LP --> +<function>XDrawArc</function> +and +<function>XDrawArcs</function> +can generate +<errorname>BadDrawable</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadMatch</errorname> +errors. +</para> +</sect2> +</sect1> +<sect1 id="Filling_Areas"> +<title>Filling Areas</title> +<!-- .XS --> +<!-- (SN Filling Areas --> +<!-- .XE --> +<para> +<!-- .LP --> +Xlib provides functions that you can use to fill: +</para> +<itemizedlist> + <listitem> + <para> +A single rectangle or multiple rectangles + </para> + </listitem> + <listitem> + <para> +A single polygon + </para> + </listitem> + <listitem> + <para> +A single arc or multiple arcs + </para> + </listitem> +</itemizedlist> +<sect2 id="Filling_Single_and_Multiple_Rectangles"> +<title>Filling Single and Multiple Rectangles</title> +<!-- .XS --> +<!-- (SN Filling Single and Multiple Rectangles --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>Filling</primary><secondary>rectangles</secondary></indexterm> +<indexterm><primary>XFillRectangle</primary></indexterm> +<indexterm><primary>Rectangle</primary><secondary>filling</secondary></indexterm> +<indexterm><primary>XFillRectangles</primary></indexterm> +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To fill a single rectangular area in a given drawable, use +<function>XFillRectangle</function>. +<indexterm significance="preferred"><primary>XFillRectangle</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xfillrectangle'> +<funcprototype> + <funcdef><function>XFillRectangle</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> + <paramdef>unsignedintwidth,<parameter> height</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. +<!-- .ds Xy , which are relative to the origin of the drawable \ --> +and specify the upper-left corner of the rectangle + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Xy. +<!-- .ds Wh , which are the dimensions of the rectangle to be filled --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>width</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>height</emphasis> + </term> + <listitem> + <para> +Specify the width and height(Wh. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<!-- .sp --> +To fill multiple rectangular areas in a given drawable, use +<function>XFillRectangles</function>. +<indexterm significance="preferred"><primary>XFillRectangles</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xfillrectangles'> +<funcprototype> + <funcdef><function>XFillRectangles</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>XRectangle<parameter> *rectangles</parameter></paramdef> + <paramdef>int<parameter> nrectangles</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'>rectangles</emphasis> + </term> + <listitem> + <para> +Specifies an array of rectangles. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>nrectangles</emphasis> + </term> + <listitem> + <para> +Specifies the number of rectangles in the array. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XFillRectangle</function> +and +<function>XFillRectangles</function> +functions fill the specified rectangle or rectangles +as if a four-point +<systemitem>FillPolygon</systemitem> +protocol request were specified for each rectangle: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +[x,y] [x+width,y] [x+width,y+height] [x,y+height] +</literallayout> +</para> +<para> +<!-- .LP --> +Each function uses the x and y coordinates, +width and height dimensions, and GC you specify. +</para> +<para> +<!-- .LP --> +<function>XFillRectangles</function> +fills the rectangles in the order listed in the array. +For any given rectangle, +<function>XFillRectangle</function> +and +<function>XFillRectangles</function> +do not draw a pixel more than once. +If rectangles intersect, the intersecting pixels are +drawn multiple times. +</para> +<para> +<!-- .LP --> +Both functions use these GC components: +function, plane-mask, fill-style, subwindow-mode, +clip-x-origin, clip-y-origin, and clip-mask. +They also use these GC mode-dependent components: +foreground, background, tile, stipple, tile-stipple-x-origin, +and tile-stipple-y-origin. +</para> +<para> +<!-- .LP --> +<function>XFillRectangle</function> +and +<function>XFillRectangles</function> +can generate +<errorname>BadDrawable</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadMatch</errorname> +errors. +</para> +</sect2> +<sect2 id="Filling_a_Single_Polygon"> +<title>Filling a Single Polygon</title> +<!-- .XS --> +<!-- (SN Filling a Single Polygon --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .sp --> +To fill a polygon area in a given drawable, use +<function>XFillPolygon</function>. +<indexterm><primary>Polygons</primary><secondary>filling</secondary></indexterm> +<indexterm><primary>Filling</primary><secondary>polygon</secondary></indexterm> +<indexterm significance="preferred"><primary>XFillPolygon</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xfillpolygon'> +<funcprototype> + <funcdef><function>XFillPolygon</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>XPoint<parameter> *points</parameter></paramdef> + <paramdef>int<parameter> npoints</parameter></paramdef> + <paramdef>int<parameter> shape</parameter></paramdef> + <paramdef>int<parameter> mode</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'>points</emphasis> + </term> + <listitem> + <para> +Specifies an array of points. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>npoints</emphasis> + </term> + <listitem> + <para> +Specifies the number of points in the array. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>shape</emphasis> + </term> + <listitem> + <para> +Specifies a shape that helps the server to improve performance. +You can pass +<symbol>Complex</symbol>, +<symbol>Convex</symbol>, +or +<symbol>Nonconvex</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>mode</emphasis> + </term> + <listitem> + <para> +Specifies the coordinate mode. +You can pass +<symbol>CoordModeOrigin</symbol> +or +<symbol>CoordModePrevious</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XFillPolygon</function> +fills the region closed by the specified path. +The path is closed +automatically if the last point in the list does not coincide with the +first point. +<function>XFillPolygon</function> +does not draw a pixel of the region more than once. +<symbol>CoordModeOrigin</symbol> +treats all coordinates as relative to the origin, +and +<symbol>CoordModePrevious</symbol> +treats all coordinates after the first as relative to the previous point. +</para> +<para> +<!-- .LP --> +Depending on the specified shape, the following occurs: +</para> +<itemizedlist> + <listitem> + <para> +If shape is +<symbol>Complex</symbol>, +the path may self-intersect. +Note that contiguous coincident points in the path are not treated +as self-intersection. + </para> + </listitem> + <listitem> + <para> +If shape is +<symbol>Convex</symbol>, +for every pair of points inside the polygon, +the line segment connecting them does not intersect the path. +If known by the client, +specifying +<symbol>Convex</symbol> +can improve performance. +If you specify +<symbol>Convex</symbol> +for a path that is not convex, +the graphics results are undefined. + </para> + </listitem> + <listitem> + <para> +If shape is +<symbol>Nonconvex</symbol>, +the path does not self-intersect, but the shape is not +wholly convex. +If known by the client, +specifying +<symbol>Nonconvex</symbol> +instead of +<symbol>Complex</symbol> +may improve performance. +If you specify +<symbol>Nonconvex</symbol> +for a self-intersecting path, the graphics results are undefined. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +The fill-rule of the GC controls the filling behavior of +self-intersecting polygons. +</para> +<para> +<!-- .LP --> +This function uses these GC components: +function, plane-mask, fill-style, fill-rule, subwindow-mode, clip-x-origin, +clip-y-origin, and clip-mask. +It also uses these GC mode-dependent components: +foreground, background, tile, stipple, tile-stipple-x-origin, +and tile-stipple-y-origin. +</para> +<para> +<!-- .LP --> +<function>XFillPolygon</function> +can generate +<errorname>BadDrawable</errorname>, +<errorname>BadGC</errorname>, +<errorname>BadMatch</errorname>, +and +<errorname>BadValue</errorname> +errors. +</para> +</sect2> +<sect2 id="Filling_Single_and_Multiple_Arcs"> +<title>Filling Single and Multiple Arcs</title> +<!-- .XS --> +<!-- (SN Filling Single and Multiple Arcs --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>XFillArc</primary></indexterm> +<indexterm><primary>Arcs</primary><secondary>filling</secondary></indexterm> +<indexterm><primary>Filling</primary><secondary>arcs</secondary></indexterm> +To fill a single arc in a given drawable, use +<function>XFillArc</function>. +<indexterm significance="preferred"><primary>XFillArc</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xfillarc'> +<funcprototype> + <funcdef><function>XFillArc</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> + <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef> + <paramdef>intangle1,<parameter> angle2</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. +<!-- .ds Xy , which are relative to the origin of the drawable \ --> +and specify the upper-left corner of the bounding rectangle + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Xy. +<!-- .ds Wh , which are the major and minor axes of the arc --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>width</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>height</emphasis> + </term> + <listitem> + <para> +Specify the width and height(Wh. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>angle1</emphasis> + </term> + <listitem> + <para> +Specifies the start of the arc relative to the three-o'clock position +from the center, in units of degrees * 64. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>angle2</emphasis> + </term> + <listitem> + <para> +Specifies the path and extent of the arc relative to the start of the +arc, in units of degrees * 64. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<!-- .sp --> +To fill multiple arcs in a given drawable, use +<function>XFillArcs</function>. +<indexterm significance="preferred"><primary>XFillArcs</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xfillarcs'> +<funcprototype> + <funcdef><function>XFillArcs</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>XArc<parameter> *arcs</parameter></paramdef> + <paramdef>int<parameter> narcs</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'>arcs</emphasis> + </term> + <listitem> + <para> +Specifies an array of arcs. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>narcs</emphasis> + </term> + <listitem> + <para> +Specifies the number of arcs in the array. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +For each arc, +<function>XFillArc</function> +or +<function>XFillArcs</function> +fills the region closed by the infinitely thin path +described by the specified arc and, depending on the +arc-mode specified in the GC, one or two line segments. +For +<symbol>ArcChord</symbol>, +the single line segment joining the endpoints of the arc is used. +For +<symbol>ArcPieSlice</symbol>, +the two line segments joining the endpoints of the arc with the center +point are used. +<function>XFillArcs</function> +fills the arcs in the order listed in the array. +For any given arc, +<function>XFillArc</function> +and +<function>XFillArcs</function> +do not draw a pixel more than once. +If regions intersect, +the intersecting pixels are drawn multiple times. +</para> +<para> +<!-- .LP --> +Both functions use these GC components: +function, plane-mask, fill-style, arc-mode, subwindow-mode, clip-x-origin, +clip-y-origin, and clip-mask. +They also use these GC mode-dependent components: +foreground, background, tile, stipple, tile-stipple-x-origin, +and tile-stipple-y-origin. +</para> +<para> +<!-- .LP --> +<function>XFillArc</function> +and +<function>XFillArcs</function> +can generate +<errorname>BadDrawable</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadMatch</errorname> +errors. +</para> +</sect2> +</sect1> +<sect1 id="Font_Metrics"> +<title>Font Metrics</title> +<!-- .XS --> +<!-- (SN Font Metrics --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>Font</primary></indexterm> +A font is a graphical description of a set of characters that are used to +increase efficiency whenever a set of small, similar sized patterns are +repeatedly used. +</para> +<para> +<!-- .LP --> +This section discusses how to: +</para> +<itemizedlist> + <listitem> + <para> +Load and free fonts + </para> + </listitem> + <listitem> + <para> +Obtain and free font names + </para> + </listitem> + <listitem> + <para> +Compute character string sizes + </para> + </listitem> + <listitem> + <para> +Compute logical extents + </para> + </listitem> + <listitem> + <para> +Query character string sizes + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +The X server loads fonts whenever a program requests a new font. +The server can cache fonts for quick lookup. +Fonts are global across all screens in a server. +Several levels are possible when dealing with fonts. +Most applications simply use +<function>XLoadQueryFont</function> +to load a font and query the font metrics. +</para> +<para> +<!-- .LP --> +Characters in fonts are regarded as masks. +Except for image text requests, +the only pixels modified are those in which bits are set to 1 in the character. +This means that it makes sense to draw text using stipples or tiles +(for example, many menus gray-out unusable entries). +</para> +<para> +<!-- .LP --> +<!-- .sM --> +The +<structname>XFontStruct</structname> +structure contains all of the information for the font +and consists of the font-specific information as well as +a pointer to an array of +<structname>XCharStruct</structname> +structures for the +characters contained in the font. +The +<structname>XFontStruct</structname>, +<structname>XFontProp</structname>, +and +<structname>XCharStruct</structname> +structures contain: +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XCharStruct</primary></indexterm> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + short lbearing; /* origin to left edge of raster */ + short rbearing; /* origin to right edge of raster */ + short width; /* advance to next char's origin */ + short ascent; /* baseline to top edge of raster */ + short descent; /* baseline to bottom edge of raster */ + unsigned short attributes; /* per char flags (not predefined) */ +} XCharStruct; +</literallayout> +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XFontProp</primary></indexterm> +<literallayout class="monospaced"> +<!-- .TA .5i 1i 3i --> +<!-- .ta .5i 1i 3i --> +typedef struct { + Atom name; + unsigned long card32; +} XFontProp; +</literallayout> +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XChar2b</primary></indexterm> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { /* normal 16 bit characters are two bytes */ + unsigned char byte1; + unsigned char byte2; +} XChar2b; +</literallayout> +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XFontStruct</primary></indexterm> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + XExtData *ext_data; /* hook for extension to hang data */ + Font fid; /* Font id for this font */ + unsigned direction; /* hint about the direction font is painted */ + unsigned min_char_or_byte2; /* first character */ + unsigned max_char_or_byte2; /* last character */ + unsigned min_byte1; /* first row that exists */ + unsigned max_byte1; /* last row that exists */ + Bool all_chars_exist; /* flag if all characters have nonzero size */ + unsigned default_char; /* char to print for undefined character */ + int n_properties; /* how many properties there are */ + XFontProp *properties; /* pointer to array of additional properties */ + XCharStruct min_bounds; /* minimum bounds over all existing char */ + XCharStruct max_bounds; /* maximum bounds over all existing char */ + XCharStruct *per_char; /* first_char to last_char information */ + int ascent; /* logical extent above baseline for spacing */ + int descent; /* logical descent below baseline for spacing */ +} XFontStruct; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +X supports single byte/character, two bytes/character matrix, +and 16-bit character text operations. +Note that any of these forms can be used with a font, but a +single byte/character text request can only specify a single byte +(that is, the first row of a 2-byte font). +You should view 2-byte fonts as a two-dimensional matrix of defined +characters: byte1 specifies the range of defined rows and +byte2 defines the range of defined columns of the font. +Single byte/character fonts have one row defined, and the byte2 range +specified in the structure defines a range of characters. +</para> +<para> +<!-- .LP --> +The bounding box of a character is defined by the +<structname>XCharStruct</structname> +of that character. +When characters are absent from a font, +the default_char is used. +When fonts have all characters of the same size, +only the information in the +<structname>XFontStruct</structname> +min and max bounds are used. +</para> +<para> +<!-- .LP --> +The members of the +<structname>XFontStruct</structname> +have the following semantics: +</para> +<itemizedlist> + <listitem> + <para> +The direction member can be either +<symbol>FontLeftToRight</symbol> +or +<symbol>FontRightToLeft</symbol>. +It is just a hint as to whether most +<structname>XCharStruct</structname> +elements +have a positive +(<symbol>FontLeftToRight</symbol>) +or a negative +(<symbol>FontRightToLeft</symbol>) +character width +metric. +The core protocol defines no support for vertical text. + </para> + </listitem> + <listitem> + <para> +If the min_byte1 and max_byte1 members are both zero, min_char_or_byte2 +specifies the linear character index corresponding to the first element +of the per_char array, and max_char_or_byte2 specifies the linear character +index of the last element. + </para> + </listitem> + <listitem> + <para> +If either min_byte1 or max_byte1 are nonzero, both +min_char_or_byte2 and max_char_or_byte2 are less than 256, +and the 2-byte character index values corresponding to the +per_char array element N (counting from 0) are: + </para> + </listitem> + <listitem> + <para> +<!-- .nf --> + byte1 = N/D + min_byte1 +<!-- .br --> + byte2 = N\\D + min_char_or_byte2 + </para> + </listitem> + <listitem> + <para> +<!-- .fi --> +where: + </para> + </listitem> + <listitem> + <para> +<!-- .nf --> + D = max_char_or_byte2 - min_char_or_byte2 + 1 + / = integer division + \\ = integer modulus +<!-- .fi --> + </para> + </listitem> + <listitem> + <para> +If the per_char pointer is NULL, +all glyphs between the first and last character indexes +inclusive have the same information, +as given by both min_bounds and max_bounds. + </para> + </listitem> + <listitem> + <para> +If all_chars_exist is +<symbol>True</symbol>, +all characters in the per_char array have nonzero bounding boxes. + </para> + </listitem> + <listitem> + <para> +The default_char member specifies the character that will be used when an +undefined or nonexistent character is printed. +The default_char is a 16-bit character (not a 2-byte character). +For a font using 2-byte matrix format, +the default_char has byte1 in the most-significant byte +and byte2 in the least significant byte. +If the default_char itself specifies an undefined or nonexistent character, +no printing is performed for an undefined or nonexistent character. + </para> + </listitem> + <listitem> + <para> +The min_bounds and max_bounds members contain the most extreme values of +each individual +<structname>XCharStruct</structname> +component over all elements of this array +(and ignore nonexistent characters). +The bounding box of the font (the smallest +rectangle enclosing the shape obtained by superimposing all of the +characters at the same origin [x,y]) has its upper-left coordinate at: +<literallayout class="monospaced"> + [x + min_bounds.lbearing, y - max_bounds.ascent] +</literallayout> + </para> + </listitem> + <listitem> + <para> +Its width is: +<literallayout class="monospaced"> + max_bounds.rbearing - min_bounds.lbearing +</literallayout> + </para> + </listitem> + <listitem> + <para> +Its height is: +<literallayout class="monospaced"> + max_bounds.ascent + max_bounds.descent +</literallayout> + </para> + </listitem> + <listitem> + <para> +The ascent member is the logical extent of the font above the baseline that is +used for determining line spacing. +Specific characters may extend beyond +this. + </para> + </listitem> + <listitem> + <para> +The descent member is the logical extent of the font at or below the +baseline that is used for determining line spacing. +Specific characters may extend beyond this. + </para> + </listitem> + <listitem> + <para> +If the baseline is at Y-coordinate y, +the logical extent of the font is inclusive between the Y-coordinate +values (y - font.ascent) and (y + font.descent - 1). +Typically, +the minimum interline spacing between rows of text is given +by ascent + descent. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +For a character origin at [x,y], +the bounding box of a character (that is, +the smallest rectangle that encloses the character's shape) +described in terms of +<structname>XCharStruct</structname> +components is a rectangle with its upper-left corner at: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +[x + lbearing, y - ascent] +</literallayout> +</para> +<para> +<!-- .LP --> +Its width is: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +rbearing - lbearing +</literallayout> +</para> +<para> +<!-- .LP --> +Its height is: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +ascent + descent +</literallayout> +</para> +<para> +<!-- .LP --> +The origin for the next character is defined to be: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +[x + width, y] +</literallayout> +</para> +<para> +<!-- .LP --> +The lbearing member defines the extent of the left edge of the character ink +from the origin. +The rbearing member defines the extent of the right edge of the character ink +from the origin. +The ascent member defines the extent of the top edge of the character ink +from the origin. +The descent member defines the extent of the bottom edge of the character ink +from the origin. +The width member defines the logical width of the character. +</para> +<para> +<!-- .LP --> +Note that the baseline (the y position of the character origin) +is logically viewed as being the scanline just below nondescending characters. +When descent is zero, +only pixels with Y-coordinates less than y are drawn, +and the origin is logically viewed as being coincident with the left edge of +a nonkerned character. +When lbearing is zero, +no pixels with X-coordinate less than x are drawn. +Any of the +<structname>XCharStruct</structname> +metric members could be negative. +If the width is negative, +the next character will be placed to the left of the current origin. +</para> +<para> +<!-- .LP --> +The X protocol does not define the interpretation of the attributes member +in the +<structname>XCharStruct</structname> +structure. +A nonexistent character is represented with all members of its +<structname>XCharStruct</structname> +set to zero. +</para> +<para> +<!-- .LP --> +A font is not guaranteed to have any properties. +The interpretation of the property value (for example, long or unsigned long) +must be derived from <emphasis remap='I'>a priori</emphasis> knowledge of the property. +A basic set of font properties is specified in the X Consortium standard +<emphasis remap='I'>X Logical Font Description Conventions</emphasis>. +</para> +<sect2 id="Loading_and_Freeing_Fonts"> +<title>Loading and Freeing Fonts</title> +<!-- .XS --> +<!-- (SN Loading and Freeing Fonts --> +<!-- .XE --> +<para> +<!-- .LP --> +Xlib provides functions that you can use to load fonts, get font information, +unload fonts, and free font information. +<indexterm><primary>Fonts</primary><secondary>getting information</secondary></indexterm> +<indexterm><primary>Fonts</primary><secondary>unloading</secondary></indexterm> +<indexterm><primary>Fonts</primary><secondary>freeing font information</secondary></indexterm> +A few font functions use a +<type>GContext</type> +resource ID or a font ID interchangeably. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To load a given font, use +<function>XLoadFont</function>. +<indexterm significance="preferred"><primary>XLoadFont</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xloadfont'> +<funcprototype> + <funcdef>Font <function>XLoadFont</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>char<parameter> *name</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'>name</emphasis> + </term> + <listitem> + <para> +Specifies the name of the font, +which is a null-terminated string. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XLoadFont</function> +function loads the specified font and returns its associated font ID. +If the font name is not in the Host Portable Character Encoding, +the result is implementation-dependent. +Use of uppercase or lowercase does not matter. +When the characters ``?'' and ``*'' are used in a font name, a +pattern match is performed and any matching font is used. +In the pattern, +the ``?'' character will match any single character, +and the ``*'' character will match any number of characters. +A structured format for font names is specified in the X Consortium standard +<emphasis remap='I'>X Logical Font Description Conventions</emphasis>. +If +<function>XLoadFont</function> +was unsuccessful at loading the specified font, +a +<errorname>BadName</errorname> +error results. +Fonts are not associated with a particular screen +and can be stored as a component +of any GC. +When the font is no longer needed, call +<function>XUnloadFont</function>. +</para> +<para> +<!-- .LP --> +<function>XLoadFont</function> +can generate +<errorname>BadAlloc</errorname> +and +<errorname>BadName</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To return information about an available font, use +<function>XQueryFont</function>. +<indexterm significance="preferred"><primary>XQueryFont</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xqueryfont'> +<funcprototype> + <funcdef>XFontStruct *<function>XQueryFont</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XID<parameter> font_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'>font_ID</emphasis> + </term> + <listitem> + <para> +Specifies the font ID or the +<type>GContext</type> +ID. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XQueryFont</function> +function returns a pointer to the +<structname>XFontStruct</structname> +structure, which contains information associated with the font. +You can query a font or the font stored in a GC. +The font ID stored in the +<structname>XFontStruct</structname> +structure will be the +<type>GContext</type> +ID, and you need to be careful when using this ID in other functions +(see +<function>XGContextFromGC</function>). +If the font does not exist, +<function>XQueryFont</function> +returns NULL. +To free this data, use +<function>XFreeFontInfo</function>. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To perform a +<function>XLoadFont</function> +and +<function>XQueryFont</function> +in a single operation, use +<function>XLoadQueryFont</function>. +<indexterm significance="preferred"><primary>XLoadQueryFont</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xloadqueryfont'> +<funcprototype> + <funcdef>XFontStruct *<function>XLoadQueryFont</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>char<parameter> *name</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'>name</emphasis> + </term> + <listitem> + <para> +Specifies the name of the font, +which is a null-terminated string. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XLoadQueryFont</function> +function provides the most common way for accessing a font. +<function>XLoadQueryFont</function> +both opens (loads) the specified font and returns a pointer to the +appropriate +<structname>XFontStruct</structname> +structure. +If the font name is not in the Host Portable Character Encoding, +the result is implementation-dependent. +If the font does not exist, +<function>XLoadQueryFont</function> +returns NULL. +</para> +<para> +<!-- .LP --> +<function>XLoadQueryFont</function> +can generate a +<errorname>BadAlloc</errorname> +error. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To unload the font and free the storage used by the font structure +that was allocated by +<function>XQueryFont</function> +or +<function>XLoadQueryFont</function>, +use +<function>XFreeFont</function>. +<indexterm significance="preferred"><primary>XFreeFont</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xfreefont'> +<funcprototype> + <funcdef><function>XFreeFont</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XFontStruct<parameter> *font_struct</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'>font_struct</emphasis> + </term> + <listitem> + <para> +Specifies the storage associated with the font. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XFreeFont</function> +function deletes the association between the font resource ID and the specified +font and frees the +<structname>XFontStruct</structname> +structure. +The font itself will be freed when no other resource references it. +The data and the font should not be referenced again. +</para> +<para> +<!-- .LP --> +<function>XFreeFont</function> +can generate a +<errorname>BadFont</errorname> +error. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To return a given font property, use +<function>XGetFontProperty</function>. +<indexterm significance="preferred"><primary>XGetFontProperty</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xgetfontproperty'> +<funcprototype> + <funcdef>Bool <function>XGetFontProperty</function></funcdef> + <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef> + <paramdef>Atom<parameter> atom</parameter></paramdef> + <paramdef>unsignedlong<parameter> *value_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>font_struct</emphasis> + </term> + <listitem> + <para> +Specifies the storage associated with the font. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>atom</emphasis> + </term> + <listitem> + <para> +Specifies the atom for the property name you want returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>value_return</emphasis> + </term> + <listitem> + <para> +Returns the value of the font property. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +Given the atom for that property, +the +<function>XGetFontProperty</function> +function returns the value of the specified font property. +<function>XGetFontProperty</function> +also returns +<symbol>False</symbol> +if the property was not defined or +<symbol>True</symbol> +if it was defined. +A set of predefined atoms exists for font properties, +which can be found in +<filename class="headerfile"><X11/Xatom.h></filename>. +<indexterm type="file"><primary><filename class="headerfile">X11/Xatom.h</filename></primary></indexterm> +<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xatom.h></filename></secondary></indexterm> +<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xatom.h></filename></secondary></indexterm> +This set contains the standard properties associated with +a font. +Although it is not guaranteed, +it is likely that the predefined font properties will be present. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To unload a font that was loaded by +<function>XLoadFont</function>, +use +<function>XUnloadFont</function>. +<indexterm significance="preferred"><primary>XUnloadFont</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xunloadfont'> +<funcprototype> + <funcdef><function>XUnloadFont</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Font<parameter> font</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'>font</emphasis> + </term> + <listitem> + <para> +Specifies the font. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XUnloadFont</function> +function deletes the association between the font resource ID and the specified font. +The font itself will be freed when no other resource references it. +The font should not be referenced again. +</para> +<para> +<!-- .LP --> +<function>XUnloadFont</function> +can generate a +<errorname>BadFont</errorname> +error. +</para> +</sect2> +<sect2 id="Obtaining_and_Freeing_Font_Names_and_Information"> +<title>Obtaining and Freeing Font Names and Information</title> +<!-- .XS --> +<!-- (SN Obtaining and Freeing Font Names and Information --> +<!-- .XE --> +<para> +<!-- .LP --> +You obtain font names and information by matching a wildcard specification +when querying a font type for a list of available sizes and so on. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To return a list of the available font names, use +<function>XListFonts</function>. +<indexterm significance="preferred"><primary>XListFonts</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xlistfonts'> +<funcprototype> + <funcdef>char **<function>XListFonts</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>char<parameter> *pattern</parameter></paramdef> + <paramdef>int<parameter> maxnames</parameter></paramdef> + <paramdef>int<parameter> *actual_count_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'>pattern</emphasis> + </term> + <listitem> + <para> +Specifies the null-terminated pattern string that can contain wildcard +characters. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>maxnames</emphasis> + </term> + <listitem> + <para> +Specifies the maximum number of names to be returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>actual_count_return</emphasis> + </term> + <listitem> + <para> +Returns the actual number of font names. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XListFonts</function> +function returns an array of available font names +(as controlled by the font search path; see +<function>XSetFontPath</function>) +that match the string you passed to the pattern argument. +The pattern string can contain any characters, +but each asterisk (*) is a wildcard for any number of characters, +and each question mark (?) is a wildcard for a single character. +If the pattern string is not in the Host Portable Character Encoding, +the result is implementation-dependent. +Use of uppercase or lowercase does not matter. +Each returned string is null-terminated. +If the data returned by the server is in the Latin Portable Character Encoding, +then the returned strings are in the Host Portable Character Encoding. +Otherwise, the result is implementation-dependent. +If there are no matching font names, +<function>XListFonts</function> +returns NULL. +The client should call +<function>XFreeFontNames</function> +when finished with the result to free the memory. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To free a font name array, use +<function>XFreeFontNames</function>. +<indexterm significance="preferred"><primary>XFreeFontNames</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xfreefontnames'> +<funcprototype> + <funcdef><function>XFreeFontNames</function></funcdef> + <paramdef>char<parameter> *list[]</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>list</emphasis> + </term> + <listitem> + <para> +Specifies the array of strings you want to free. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XFreeFontNames</function> +function frees the array and strings returned by +<function>XListFonts</function> +or +<function>XListFontsWithInfo</function>. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To obtain the names and information about available fonts, use +<function>XListFontsWithInfo</function>. +<indexterm significance="preferred"><primary>XListFontsWithInfo</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xlistfontswithinfo'> +<funcprototype> + <funcdef>char **<function>XListFontsWithInfo</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>char<parameter> *pattern</parameter></paramdef> + <paramdef>int<parameter> maxnames</parameter></paramdef> + <paramdef>int<parameter> *count_return</parameter></paramdef> + <paramdef>XFontStruct<parameter> **info_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'>pattern</emphasis> + </term> + <listitem> + <para> +Specifies the null-terminated pattern string that can contain wildcard +characters. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>maxnames</emphasis> + </term> + <listitem> + <para> +Specifies the maximum number of names to be returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>count_return</emphasis> + </term> + <listitem> + <para> +Returns the actual number of matched font names. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>info_return</emphasis> + </term> + <listitem> + <para> +Returns the font information. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XListFontsWithInfo</function> +function returns a list of font names that match the specified pattern and their +associated font information. +The list of names is limited to size specified by maxnames. +The information returned for each font is identical to what +<function>XLoadQueryFont</function> +would return except that the per-character metrics are not returned. +The pattern string can contain any characters, +but each asterisk (*) is a wildcard for any number of characters, +and each question mark (?) is a wildcard for a single character. +If the pattern string is not in the Host Portable Character Encoding, +the result is implementation-dependent. +Use of uppercase or lowercase does not matter. +Each returned string is null-terminated. +If the data returned by the server is in the Latin Portable Character Encoding, +then the returned strings are in the Host Portable Character Encoding. +Otherwise, the result is implementation-dependent. +If there are no matching font names, +<function>XListFontsWithInfo</function> +returns NULL. +</para> +<para> +<!-- .LP --> +To free only the allocated name array, +the client should call +<function>XFreeFontNames</function>. +To free both the name array and the font information array +or to free just the font information array, +the client should call +<function>XFreeFontInfo</function>. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To free font structures and font names, use +<function>XFreeFontInfo</function>. +<indexterm significance="preferred"><primary>XFreeFontInfo</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xfreefontinfo'> +<funcprototype> + <funcdef><function>XFreeFontInfo</function></funcdef> + <paramdef>char<parameter> **names</parameter></paramdef> + <paramdef>XFontStruct<parameter> *free_info</parameter></paramdef> + <paramdef>int<parameter> actual_count</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>names</emphasis> + </term> + <listitem> + <para> +Specifies the list of font names. + + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>free_info</emphasis> + </term> + <listitem> + <para> +Specifies the font information. + + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>actual_count</emphasis> + </term> + <listitem> + <para> +Specifies the actual number of font names. + + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XFreeFontInfo</function> +function frees a font structure or an array of font structures +and optionally an array of font names. +If NULL is passed for names, no font names are freed. +If a font structure for an open font (returned by +<function>XLoadQueryFont</function>) +is passed, the structure is freed, +but the font is not closed; use +<function>XUnloadFont</function> +to close the font. +</para> +</sect2> +<sect2 id="Computing_Character_String_Sizes"> +<title>Computing Character String Sizes</title> +<!-- .XS --> +<!-- (SN Computing Character String Sizes --> +<!-- .XE --> +<para> +<!-- .LP --> +Xlib provides functions that you can use to compute the width, +the logical extents, +and the server information about 8-bit and 2-byte text strings. +<indexterm><primary>XTextWidth</primary></indexterm> +<indexterm><primary>XTextWidth16</primary></indexterm> +The width is computed by adding the character widths of all the characters. +It does not matter if the font is an 8-bit or 2-byte font. +These functions return the sum of the character metrics in pixels. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To determine the width of an 8-bit character string, use +<function>XTextWidth</function>. +<indexterm significance="preferred"><primary>XTextWidth</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xtextwidth'> +<funcprototype> + <funcdef>int <function>XTextWidth</function></funcdef> + <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef> + <paramdef>char<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> count</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>font_struct</emphasis> + </term> + <listitem> + <para> +Specifies the font used for the width computation. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>string</emphasis> + </term> + <listitem> + <para> +Specifies the character string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>count</emphasis> + </term> + <listitem> + <para> +Specifies the character count in the specified string. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<!-- .sp --> +To determine the width of a 2-byte character string, use +<function>XTextWidth16</function>. +<indexterm significance="preferred"><primary>XTextWidth16</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xtextwidth16'> +<funcprototype> + <funcdef>int <function>XTextWidth16</function></funcdef> + <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef> + <paramdef>XChar2b<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> count</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>font_struct</emphasis> + </term> + <listitem> + <para> +Specifies the font used for the width computation. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>string</emphasis> + </term> + <listitem> + <para> +Specifies the character string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>count</emphasis> + </term> + <listitem> + <para> +Specifies the character count in the specified string. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +</para> +</sect2> +<sect2 id="Computing_Logical_Extents"> +<title>Computing Logical Extents</title> +<!-- .XS --> +<!-- (SN Computing Logical Extents --> +<!-- .XE --> +<para> +<!-- .LP --> +To compute the bounding box of an 8-bit character string in a given font, use +<function>XTextExtents</function>. +<indexterm significance="preferred"><primary>XTextExtents</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xtextextents'> +<funcprototype> + <funcdef><function>XTextExtents</function></funcdef> + <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef> + <paramdef>char<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> nchars</parameter></paramdef> + <paramdef>int<parameter> *direction_return</parameter></paramdef> + <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef> + <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>font_struct</emphasis> + </term> + <listitem> + <para> +Specifies the +<structname>XFontStruct</structname> +structure. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>string</emphasis> + </term> + <listitem> + <para> +Specifies the character string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>nchars</emphasis> + </term> + <listitem> + <para> +Specifies the number of characters in the character string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>direction_return</emphasis> + </term> + <listitem> + <para> +Returns the value of the direction hint +(<symbol>FontLeftToRight</symbol> +or +<symbol>FontRightToLeft</symbol>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>font_ascent_return</emphasis> + </term> + <listitem> + <para> +Returns the font ascent. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>font_descent_return</emphasis> + </term> + <listitem> + <para> +Returns the font descent. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>overall_return</emphasis> + </term> + <listitem> + <para> +Returns the overall size in the specified +<structname>XCharStruct</structname> +structure. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<!-- .sp --> +To compute the bounding box of a 2-byte character string in a given font, use +<function>XTextExtents16</function>. +<indexterm significance="preferred"><primary>XTextExtents16</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xtextextents16'> +<funcprototype> + <funcdef><function>XTextExtents16</function></funcdef> + <paramdef>XFontStruct<parameter> *font_struct</parameter></paramdef> + <paramdef>XChar2b<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> nchars</parameter></paramdef> + <paramdef>int<parameter> *direction_return</parameter></paramdef> + <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef> + <paramdef>XCharStruct<parameter> *overall_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>font_struct</emphasis> + </term> + <listitem> + <para> +Specifies the +<structname>XFontStruct</structname> +structure. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>string</emphasis> + </term> + <listitem> + <para> +Specifies the character string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>nchars</emphasis> + </term> + <listitem> + <para> +Specifies the number of characters in the character string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>direction_return</emphasis> + </term> + <listitem> + <para> +Returns the value of the direction hint +(<symbol>FontLeftToRight</symbol> +or +<symbol>FontRightToLeft</symbol>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>font_ascent_return</emphasis> + </term> + <listitem> + <para> +Returns the font ascent. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>font_descent_return</emphasis> + </term> + <listitem> + <para> +Returns the font descent. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>overall_return</emphasis> + </term> + <listitem> + <para> +Returns the overall size in the specified +<structname>XCharStruct</structname> +structure. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XTextExtents</function> +and +<function>XTextExtents16</function> +functions +perform the size computation locally and, thereby, +avoid the round-trip overhead of +<function>XQueryTextExtents</function> +and +<function>XQueryTextExtents16</function>. +Both functions return an +<structname>XCharStruct</structname> +structure, whose members are set to the values as follows. +</para> +<para> +<!-- .LP --> +The ascent member is set to the maximum of the ascent metrics of all +characters in the string. +The descent member is set to the maximum of the descent metrics. +The width member is set to the sum of the character-width metrics of all +characters in the string. +For each character in the string, +let W be the sum of the character-width metrics of all characters preceding +it in the string. +Let L be the left-side-bearing metric of the character plus W. +Let R be the right-side-bearing metric of the character plus W. +The lbearing member is set to the minimum L of all characters in the string. +The rbearing member is set to the maximum R. +</para> +<para> +<!-- .LP --> +For fonts defined with linear indexing rather than 2-byte matrix indexing, +each +<structname>XChar2b</structname> +structure is interpreted as a 16-bit number with byte1 as the +most significant byte. +If the font has no defined default character, +undefined characters in the string are taken to have all zero metrics. +</para> +</sect2> +<sect2 id="Querying_Character_String_Sizes"> +<title>Querying Character String Sizes</title> +<!-- .XS --> +<!-- (SN Querying Character String Sizes --> +<!-- .XE --> +<para> +<!-- .LP --> +To query the server for the bounding box of an 8-bit character string in a +given font, use +<function>XQueryTextExtents</function>. +<indexterm significance="preferred"><primary>XQueryTextExtents</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xquerytextextents'> +<funcprototype> + <funcdef><function>XQueryTextExtents</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XID<parameter> font_ID</parameter></paramdef> + <paramdef>char<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> nchars</parameter></paramdef> + <paramdef>int<parameter> *direction_return</parameter></paramdef> + <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef> + <paramdef>XCharStruct<parameter> *overall_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'>font_ID</emphasis> + </term> + <listitem> + <para> +Specifies either the font ID or the +<type>GContext</type> +ID that contains the font. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>string</emphasis> + </term> + <listitem> + <para> +Specifies the character string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>nchars</emphasis> + </term> + <listitem> + <para> +Specifies the number of characters in the character string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>direction_return</emphasis> + </term> + <listitem> + <para> +Returns the value of the direction hint +(<symbol>FontLeftToRight</symbol> +or +<symbol>FontRightToLeft</symbol>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>font_ascent_return</emphasis> + </term> + <listitem> + <para> +Returns the font ascent. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>font_descent_return</emphasis> + </term> + <listitem> + <para> +Returns the font descent. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>overall_return</emphasis> + </term> + <listitem> + <para> +Returns the overall size in the specified +<structname>XCharStruct</structname> +structure. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<!-- .sp --> +To query the server for the bounding box of a 2-byte character string +in a given font, use +<function>XQueryTextExtents16</function>. +<indexterm significance="preferred"><primary>XQueryTextExtents16</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xquerytextextents16'> +<funcprototype> + <funcdef><function>XQueryTextExtents16</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XID<parameter> font_ID</parameter></paramdef> + <paramdef>XChar2b<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> nchars</parameter></paramdef> + <paramdef>int<parameter> *direction_return</parameter></paramdef> + <paramdef>int*font_ascent_return,<parameter> *font_descent_return</parameter></paramdef> + <paramdef>XCharStruct<parameter> *overall_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'>font_ID</emphasis> + </term> + <listitem> + <para> +Specifies either the font ID or the +<type>GContext</type> +ID that contains the font. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>string</emphasis> + </term> + <listitem> + <para> +Specifies the character string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>nchars</emphasis> + </term> + <listitem> + <para> +Specifies the number of characters in the character string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>direction_return</emphasis> + </term> + <listitem> + <para> +Returns the value of the direction hint +(<symbol>FontLeftToRight</symbol> +or +<symbol>FontRightToLeft</symbol>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>font_ascent_return</emphasis> + </term> + <listitem> + <para> +Returns the font ascent. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>font_descent_return</emphasis> + </term> + <listitem> + <para> +Returns the font descent. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>overall_return</emphasis> + </term> + <listitem> + <para> +Returns the overall size in the specified +<structname>XCharStruct</structname> +structure. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XQueryTextExtents</function> +and +<function>XQueryTextExtents16</function> +functions return the bounding box of the specified 8-bit and 16-bit +character string in the specified font or the font contained in the +specified GC. +These functions query the X server and, therefore, suffer the round-trip +overhead that is avoided by +<function>XTextExtents</function> +and +<function>XTextExtents16</function>. +Both functions return a +<structname>XCharStruct</structname> +structure, whose members are set to the values as follows. +</para> +<para> +<!-- .LP --> +The ascent member is set to the maximum of the ascent metrics +of all characters in the string. +The descent member is set to the maximum of the descent metrics. +The width member is set to the sum of the character-width metrics +of all characters in the string. +For each character in the string, +let W be the sum of the character-width metrics of all characters preceding +it in the string. +Let L be the left-side-bearing metric of the character plus W. +Let R be the right-side-bearing metric of the character plus W. +The lbearing member is set to the minimum L of all characters in the string. +The rbearing member is set to the maximum R. +</para> +<para> +<!-- .LP --> +For fonts defined with linear indexing rather than 2-byte matrix indexing, +each +<structname>XChar2b</structname> +structure is interpreted as a 16-bit number with byte1 as the +most significant byte. +If the font has no defined default character, +undefined characters in the string are taken to have all zero metrics. +</para> +<para> +<!-- .LP --> +Characters with all zero metrics are ignored. +If the font has no defined default_char, +the undefined characters in the string are also ignored. +</para> +<para> +<!-- .LP --> +<function>XQueryTextExtents</function> +and +<function>XQueryTextExtents16</function> +can generate +<errorname>BadFont</errorname> +and +<errorname>BadGC</errorname> +errors. +</para> +</sect2> +</sect1> +<sect1 id="Drawing_Text"> +<title>Drawing Text</title> +<!-- .XS --> +<!-- (SN Drawing Text --> +<!-- .XE --> +<para> +<!-- .LP --> +This section discusses how to draw: +</para> +<itemizedlist> + <listitem> + <para> +Complex text + </para> + </listitem> + <listitem> + <para> +Text characters + </para> + </listitem> + <listitem> + <para> +Image text characters + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +The fundamental text functions +<function>XDrawText</function> +and +<function>XDrawText16</function> +use the following structures: +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XTextItem</primary></indexterm> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + char *chars; /* pointer to string */ + int nchars; /* number of characters */ + int delta; /* delta between strings */ + Font font; /* Font to print it in, None don't change */ +} XTextItem; +</literallayout> +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XTextItem16</primary></indexterm> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + XChar2b *chars; /* pointer to two-byte characters */ + int nchars; /* number of characters */ + int delta; /* delta between strings */ + Font font; /* font to print it in, None don't change */ +} XTextItem16; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +If the font member is not +<symbol>None</symbol>, +the font is changed before printing and also is stored in the GC. +If an error was generated during text drawing, +the previous items may have been drawn. +The baseline of the characters are drawn starting at the x and y +coordinates that you pass in the text drawing functions. +</para> +<para> +<!-- .LP --> +For example, consider the background rectangle drawn by +<function>XDrawImageString</function>. +If you want the upper-left corner of the background rectangle +to be at pixel coordinate (x,y), pass the (x,y + ascent) +as the baseline origin coordinates to the text functions. +The ascent is the font ascent, as given in the +<structname>XFontStruct</structname> +structure. +If you want the lower-left corner of the background rectangle +to be at pixel coordinate (x,y), pass the (x,y - descent + 1) +as the baseline origin coordinates to the text functions. +The descent is the font descent, as given in the +<structname>XFontStruct</structname> +structure. +</para> +<sect2 id="Drawing_Complex_Text"> +<title>Drawing Complex Text</title> +<!-- .XS --> +<!-- (SN Drawing Complex Text --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>Text</primary><secondary>drawing</secondary></indexterm> +<indexterm><primary>Drawing</primary><secondary>text items</secondary></indexterm> +</para> +<para> +<!-- .LP --> +To draw 8-bit characters in a given drawable, use +<function>XDrawText</function>. +<indexterm significance="preferred"><primary>XDrawText</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xdrawtext'> +<funcprototype> + <funcdef><function>XDrawText</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> + <paramdef>XTextItem<parameter> *items</parameter></paramdef> + <paramdef>int<parameter> nitems</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. +<!-- .ds Xy , which are relative to the origin of the specified drawable \ --> +and define the origin of the first character + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Xy. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>items</emphasis> + </term> + <listitem> + <para> +Specifies an array of text items. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>nitems</emphasis> + </term> + <listitem> + <para> +Specifies the number of text items in the array. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<!-- .sp --> +To draw 2-byte characters in a given drawable, use +<function>XDrawText16</function>. +<indexterm significance="preferred"><primary>XDrawText16</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xdrawtext16'> +<funcprototype> + <funcdef><function>XDrawText16</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> + <paramdef>XTextItem16<parameter> *items</parameter></paramdef> + <paramdef>int<parameter> nitems</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. +<!-- .ds Xy , which are relative to the origin of the specified drawable \ --> +and define the origin of the first character + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Xy. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>items</emphasis> + </term> + <listitem> + <para> +Specifies an array of text items. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>nitems</emphasis> + </term> + <listitem> + <para> +Specifies the number of text items in the array. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XDrawText16</function> +function is similar to +<function>XDrawText</function> +except that it uses 2-byte or 16-bit characters. +Both functions allow complex spacing and font shifts between counted strings. +</para> +<para> +<!-- .LP --> +Each text item is processed in turn. +A font member other than +<symbol>None</symbol> +in an item causes the font to be stored in the GC +and used for subsequent text. +A text element delta specifies an additional change +in the position along the x axis before the string is drawn. +The delta is always added to the character origin +and is not dependent on any characteristics of the font. +Each character image, as defined by the font in the GC, is treated as an +additional mask for a fill operation on the drawable. +The drawable is modified only where the font character has a bit set to 1. +If a text item generates a +<errorname>BadFont</errorname> +error, the previous text items may have been drawn. +</para> +<para> +<!-- .LP --> +For fonts defined with linear indexing rather than 2-byte matrix indexing, +each +<structname>XChar2b</structname> +structure is interpreted as a 16-bit number with byte1 as the +most significant byte. +</para> +<para> +<!-- .LP --> +Both functions use these GC components: +function, plane-mask, fill-style, font, subwindow-mode, +clip-x-origin, clip-y-origin, and clip-mask. +They also use these GC mode-dependent components: +foreground, background, tile, stipple, tile-stipple-x-origin, +and tile-stipple-y-origin. +</para> +<para> +<!-- .LP --> +<function>XDrawText</function> +and +<function>XDrawText16</function> +can generate +<errorname>BadDrawable</errorname>, +<errorname>BadFont</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadMatch</errorname> +errors. +</para> +</sect2> +<sect2 id="Drawing_Text_Characters"> +<title>Drawing Text Characters</title> +<!-- .XS --> +<!-- (SN Drawing Text Characters --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>Strings</primary><secondary>drawing</secondary></indexterm> +<indexterm><primary>Drawing</primary><secondary>strings</secondary></indexterm> +To draw 8-bit characters in a given drawable, use +<function>XDrawString</function>. +<indexterm significance="preferred"><primary>XDrawString</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xdrawstring'> +<funcprototype> + <funcdef><function>XDrawString</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> + <paramdef>char<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> length</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. +<!-- .ds Xy , which are relative to the origin of the specified drawable \ --> +and define the origin of the first character + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Xy. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>string</emphasis> + </term> + <listitem> + <para> +Specifies the character string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>length</emphasis> + </term> + <listitem> + <para> +Specifies the number of characters in the string argument. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<!-- .sp --> +To draw 2-byte characters in a given drawable, use +<function>XDrawString16</function>. +<indexterm significance="preferred"><primary>XDrawString16</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xdrawstring16'> +<funcprototype> + <funcdef><function>XDrawString16</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> + <paramdef>XChar2b<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> length</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. +<!-- .ds Xy , which are relative to the origin of the specified drawable \ --> +and define the origin of the first character + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Xy. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>string</emphasis> + </term> + <listitem> + <para> +Specifies the character string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>length</emphasis> + </term> + <listitem> + <para> +Specifies the number of characters in the string argument. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +Each character image, as defined by the font in the GC, is treated as an +additional mask for a fill operation on the drawable. +The drawable is modified only where the font character has a bit set to 1. +For fonts defined with 2-byte matrix indexing +and used with +<function>XDrawString16</function>, +each byte is used as a byte2 with a byte1 of zero. +</para> +<para> +<!-- .LP --> +Both functions use these GC components: +function, plane-mask, fill-style, font, subwindow-mode, clip-x-origin, +clip-y-origin, and clip-mask. +They also use these GC mode-dependent components: +foreground, background, tile, stipple, tile-stipple-x-origin, +and tile-stipple-y-origin. +</para> +<para> +<!-- .LP --> +<function>XDrawString</function> +and +<function>XDrawString16</function> +can generate +<errorname>BadDrawable</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadMatch</errorname> +errors. +</para> +</sect2> +<sect2 id="Drawing_Image_Text_Characters"> +<title>Drawing Image Text Characters</title> +<!-- .XS --> +<!-- (SN Drawing Image Text Characters --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>Image text</primary><secondary>drawing</secondary></indexterm> +<indexterm><primary>Drawing</primary><secondary>image text</secondary></indexterm> +Some applications, in particular terminal emulators, need to +print image text in which both the foreground and background bits of +each character are painted. +This prevents annoying flicker on many displays. +<indexterm><primary>XDrawImageString</primary></indexterm> +<indexterm><primary>XDrawImageString16</primary></indexterm> +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To draw 8-bit image text characters in a given drawable, use +<function>XDrawImageString</function>. +<indexterm significance="preferred"><primary>XDrawImageString</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xdrawimagestring'> +<funcprototype> + <funcdef><function>XDrawImageString</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> + <paramdef>char<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> length</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. +<!-- .ds Xy , which are relative to the origin of the specified drawable \ --> +and define the origin of the first character + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Xy. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>string</emphasis> + </term> + <listitem> + <para> +Specifies the character string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>length</emphasis> + </term> + <listitem> + <para> +Specifies the number of characters in the string argument. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<!-- .sp --> +To draw 2-byte image text characters in a given drawable, use +<function>XDrawImageString16</function>. +<indexterm significance="preferred"><primary>XDrawImageString16</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xdrawimagestring16'> +<funcprototype> + <funcdef><function>XDrawImageString16</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> + <paramdef>XChar2b<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> length</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. +<!-- .ds Xy , which are relative to the origin of the specified drawable \ --> +and define the origin of the first character + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Xy. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>string</emphasis> + </term> + <listitem> + <para> +Specifies the character string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>length</emphasis> + </term> + <listitem> + <para> +Specifies the number of characters in the string argument. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XDrawImageString16</function> +function is similar to +<function>XDrawImageString</function> +except that it uses 2-byte or 16-bit characters. +Both functions also use both the foreground and background pixels +of the GC in the destination. +</para> +<para> +<!-- .LP --> +The effect is first to fill a +destination rectangle with the background pixel defined in the GC and then +to paint the text with the foreground pixel. +The upper-left corner of the filled rectangle is at: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +[x, y - font-ascent] +</literallayout> +</para> +<para> +<!-- .LP --> +The width is: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +overall-width +</literallayout> +</para> +<para> +<!-- .LP --> +The height is: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +font-ascent + font-descent +</literallayout> +</para> +<para> +<!-- .LP --> +The overall-width, font-ascent, and font-descent +are as would be returned by +<function>XQueryTextExtents</function> +using gc and string. +The function and fill-style defined in the GC are ignored for these functions. +The effective function is +<symbol>GXcopy</symbol>, +and the effective fill-style is +<symbol>FillSolid</symbol>. +</para> +<para> +<!-- .LP --> +For fonts defined with 2-byte matrix indexing +and used with +<function>XDrawImageString</function>, +each byte is used as a byte2 with a byte1 of zero. +</para> +<para> +<!-- .LP --> +Both functions use these GC components: +plane-mask, foreground, background, font, subwindow-mode, clip-x-origin, +clip-y-origin, and clip-mask. +</para> +<para> +<!-- .LP --> +<function>XDrawImageString</function> +and +<function>XDrawImageString16</function> +can generate +<errorname>BadDrawable</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadMatch</errorname> +errors. +</para> +<para> +<!-- .LP --> +</para> +</sect2> +</sect1> +<sect1 id="Transferring_Images_between_Client_and_Server"> +<title>Transferring Images between Client and Server</title> +<!-- .XS --> +<!-- (SN Transferring Images between Client and Server --> +<!-- .XE --> +<para> +<!-- .LP --> +Xlib provides functions that you can use to transfer images between a client +and the server. +Because the server may require diverse data formats, +Xlib provides an image object that fully describes the data in memory +and that provides for basic operations on that data. +You should reference the data +through the image object rather than referencing the data directly. +However, some implementations of the Xlib library may efficiently deal with +frequently used data formats by replacing +functions in the procedure vector with special case functions. +Supported operations include destroying the image, getting a pixel, +storing a pixel, extracting a subimage of an image, and adding a constant +to an image (see section 16.8). +</para> +<para> +<!-- .LP --> +All the image manipulation functions discussed in this section make use of +the +<structname>XImage</structname> +structure, +which describes an image as it exists in the client's memory. +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XImage</primary></indexterm> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 1i 3i --> +<!-- .ta .5i 1i 3i --> +typedef struct _XImage { + int width, height; /* size of image */ + int xoffset; /* number of pixels offset in X direction */ + int format; /* XYBitmap, XYPixmap, ZPixmap */ + char *data; /* pointer to image data */ + int byte_order; /* data byte order, LSBFirst, MSBFirst */ + int bitmap_unit; /* quant. of scanline 8, 16, 32 */ + int bitmap_bit_order; /* LSBFirst, MSBFirst */ + int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */ + int depth; /* depth of image */ + int bytes_per_line; /* accelerator to next scanline */ + int bits_per_pixel; /* bits per pixel (ZPixmap) */ + unsigned long red_mask; /* bits in z arrangement */ + unsigned long green_mask; + unsigned long blue_mask; + XPointer obdata; /* hook for the object routines to hang on */ + struct funcs { /* image manipulation routines */ + struct _XImage *(*create_image)(); + int (*destroy_image)(); + unsigned long (*get_pixel)(); + int (*put_pixel)(); + struct _XImage *(*sub_image)(); + int (*add_pixel)(); + } f; +} XImage; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<!-- .sp --> +To initialize the image manipulation routines of an image structure, use +<function>XInitImage</function>. +<indexterm significance="preferred"><primary>XInitImage</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xinitimage'> +<funcprototype> + <funcdef>Status <function>XInitImage</function></funcdef> + <paramdef>XImage<parameter> *image</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ximage</emphasis> + </term> + <listitem> + <para> +Specifies the image. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XInitImage</function> +function initializes the internal image manipulation routines of an +image structure, based on the values of the various structure members. +All fields other than the manipulation routines must already be initialized. +If the bytes_per_line member is zero, +<function>XInitImage</function> +will assume the image data is contiguous in memory and set the +bytes_per_line member to an appropriate value based on the other +members; otherwise, the value of bytes_per_line is not changed. +All of the manipulation routines are initialized to functions +that other Xlib image manipulation functions need to operate on the +type of image specified by the rest of the structure. +</para> +<para> +<!-- .LP --> +This function must be called for any image constructed by the client +before passing it to any other Xlib function. +Image structures created or returned by Xlib do not need to be +initialized in this fashion. +</para> +<para> +<!-- .LP --> +This function returns a nonzero status if initialization of the +structure is successful. It returns zero if it detected some error +or inconsistency in the structure, in which case the image is not changed. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To combine an image with a rectangle of a drawable on the display, +use +<function>XPutImage</function>. +<indexterm significance="preferred"><primary>XPutImage</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xputimage'> +<funcprototype> + <funcdef><function>XPutImage</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>XImage<parameter> *image</parameter></paramdef> + <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef> + <paramdef>intdest_x,<parameter> dest_y</parameter></paramdef> + <paramdef>unsignedintwidth,<parameter> height</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'>image</emphasis> + </term> + <listitem> + <para> +Specifies the image you want combined with the rectangle. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>src_x</emphasis> + </term> + <listitem> + <para> +Specifies the offset in X from the left edge of the image defined +by the +<structname>XImage</structname> +structure. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>src_y</emphasis> + </term> + <listitem> + <para> +Specifies the offset in Y from the top edge of the image defined +by the +<structname>XImage</structname> +structure. +<!-- .ds Dx , which are relative to the origin of the drawable \ --> +and are the coordinates of the subimage + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dest_x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dest_y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Dx. +<!-- .ds Wh \ of the subimage, which define the dimensions of the rectangle --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>width</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>height</emphasis> + </term> + <listitem> + <para> +Specify the width and height(Wh. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XPutImage</function> +function +combines an image with a rectangle of the specified drawable. +The section of the image defined by the src_x, src_y, width, and height +arguments is drawn on the specified part of the drawable. +If +<symbol>XYBitmap</symbol> +format is used, the depth of the image must be one, +or a +<errorname>BadMatch</errorname> +error results. +The foreground pixel in the GC defines the source for the one bits in the image, +and the background pixel defines the source for the zero bits. +For +<symbol>XYPixmap</symbol> +and +<symbol>ZPixmap</symbol>, +the depth of the image must match the depth of the drawable, +or a +<errorname>BadMatch</errorname> +error results. +</para> +<para> +<!-- .LP --> +If the characteristics of the image (for example, byte_order and bitmap_unit) +differ from what the server requires, +<function>XPutImage</function> +automatically makes the appropriate +conversions. +</para> +<para> +<!-- .LP --> +This function uses these GC components: +function, plane-mask, subwindow-mode, clip-x-origin, clip-y-origin, +and clip-mask. +It also uses these GC mode-dependent components: +foreground and background. +</para> +<para> +<!-- .LP --> +<function>XPutImage</function> +can generate +<errorname>BadDrawable</errorname>, +<errorname>BadGC</errorname>, +<errorname>BadMatch</errorname>, +and +<errorname>BadValue</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To return the contents of a rectangle in a given drawable on the display, +use +<function>XGetImage</function>. +This function specifically supports rudimentary screen dumps. +<indexterm significance="preferred"><primary>XGetImage</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xgetimage'> +<funcprototype> + <funcdef>XImage *<function>XGetImage</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> + <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef> + <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef> + <paramdef>int<parameter> format</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. +<!-- .ds Xy , which are relative to the origin of the drawable \ --> +and define the upper-left corner of the rectangle + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Xy. +<!-- .ds Wh \ of the subimage, which define the dimensions of the rectangle --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>width</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>height</emphasis> + </term> + <listitem> + <para> +Specify the width and height(Wh. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>plane_mask</emphasis> + </term> + <listitem> + <para> +Specifies the plane mask. +<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>format</emphasis> + </term> + <listitem> + <para> +Specifies the format for the image. +You can pass +<symbol>XYPixmap</symbol> +or +<symbol>ZPixmap</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XGetImage</function> +function returns a pointer to an +<structname>XImage</structname> +structure. +This structure provides you with the contents of the specified rectangle of +the drawable in the format you specify. +If the format argument is +<symbol>XYPixmap</symbol>, +the image contains only the bit planes you passed to the plane_mask argument. +If the plane_mask argument only requests a subset of the planes of the +display, the depth of the returned image will be the number of planes +requested. +If the format argument is +<symbol>ZPixmap</symbol>, +<function>XGetImage</function> +returns as zero the bits in all planes not +specified in the plane_mask argument. +The function performs no range checking on the values in plane_mask and ignores +extraneous bits. +</para> +<para> +<!-- .LP --> +<function>XGetImage</function> +returns the depth of the image to the depth member of the +<structname>XImage</structname> +structure. +The depth of the image is as specified when the drawable was created, +except when getting a subset of the planes in +<symbol>XYPixmap</symbol> +format, when the depth is given by the number of bits set to 1 in plane_mask. +</para> +<para> +<!-- .LP --> +If the drawable is a pixmap, +the given rectangle must be wholly contained within the pixmap, +or a +<errorname>BadMatch</errorname> +error results. +If the drawable is a window, +the window must be viewable, +and it must be the case that if there were no inferiors or overlapping windows, +the specified rectangle of the window would be fully visible on the screen +and wholly contained within the outside edges of the window, +or a +<errorname>BadMatch</errorname> +error results. +Note that the borders of the window can be included and read with +this request. +If the window has backing-store, the backing-store contents are +returned for regions of the window that are obscured by noninferior +windows. +If the window does not have backing-store, +the returned contents of such obscured regions are undefined. +The returned contents of visible regions of inferiors +of a different depth than the specified window's depth are also undefined. +The pointer cursor image is not included in the returned contents. +If a problem occurs, +<function>XGetImage</function> +returns NULL. +</para> +<para> +<!-- .LP --> +<function>XGetImage</function> +can generate +<errorname>BadDrawable</errorname>, +<errorname>BadMatch</errorname>, +and +<errorname>BadValue</errorname> +errors. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To copy the contents of a rectangle on the display +to a location within a preexisting image structure, use +<function>XGetSubImage</function>. +<indexterm significance="preferred"><primary>XGetSubImage</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xgetsubimage'> +<funcprototype> + <funcdef>XImage *<function>XGetSubImage</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> + <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef> + <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef> + <paramdef>int<parameter> format</parameter></paramdef> + <paramdef>XImage<parameter> *dest_image</parameter></paramdef> + <paramdef>intdest_x,<parameter> dest_y</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. +<!-- .ds Xy , which are relative to the origin of the drawable \ --> +and define the upper-left corner of the rectangle + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Xy. +<!-- .ds Wh \ of the subimage, which define the dimensions of the rectangle --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>width</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>height</emphasis> + </term> + <listitem> + <para> +Specify the width and height(Wh. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>plane_mask</emphasis> + </term> + <listitem> + <para> +Specifies the plane mask. +<!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>format</emphasis> + </term> + <listitem> + <para> +Specifies the format for the image. +You can pass +<symbol>XYPixmap</symbol> +or +<symbol>ZPixmap</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dest_image</emphasis> + </term> + <listitem> + <para> +Specifies the destination image. +<!-- .ds Dx , which are relative to the origin of the destination rectangle, \ --> +specify its upper-left corner, and determine where the subimage \ +is placed in the destination image + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dest_x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dest_y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Dx. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XGetSubImage</function> +function updates dest_image with the specified subimage in the same manner as +<function>XGetImage</function>. +If the format argument is +<symbol>XYPixmap</symbol>, +the image contains only the bit planes you passed to the plane_mask argument. +If the format argument is +<symbol>ZPixmap</symbol>, +<function>XGetSubImage</function> +returns as zero the bits in all planes not +specified in the plane_mask argument. +The function performs no range checking on the values in plane_mask and ignores +extraneous bits. +As a convenience, +<function>XGetSubImage</function> +returns a pointer to the same +<structname>XImage</structname> +structure specified by dest_image. +</para> +<para> +<!-- .LP --> +The depth of the destination +<structname>XImage</structname> +structure must be the same as that of the drawable. +If the specified subimage does not fit at the specified location +on the destination image, the right and bottom edges are clipped. +If the drawable is a pixmap, +the given rectangle must be wholly contained within the pixmap, +or a +<errorname>BadMatch</errorname> +error results. +If the drawable is a window, +the window must be viewable, +and it must be the case that if there were no inferiors or overlapping windows, +the specified rectangle of the window would be fully visible on the screen +and wholly contained within the outside edges of the window, +or a +<errorname>BadMatch</errorname> +error results. +If the window has backing-store, +then the backing-store contents are returned for regions of the window +that are obscured by noninferior windows. +If the window does not have backing-store, +the returned contents of such obscured regions are undefined. +The returned contents of visible regions of inferiors +of a different depth than the specified window's depth are also undefined. +If a problem occurs, +<function>XGetSubImage</function> +returns NULL. +</para> +<para> +<!-- .LP --> +<function>XGetSubImage</function> +can generate +<errorname>BadDrawable</errorname>, +<errorname>BadGC</errorname>, +<errorname>BadMatch</errorname>, +and +<errorname>BadValue</errorname> +errors. +<!-- .bp --> + + +</para> +</sect1> +</chapter> |