diff options
Diffstat (limited to 'libX11/specs/libX11/CH07.xml')
| -rw-r--r-- | libX11/specs/libX11/CH07.xml | 6814 |
1 files changed, 3407 insertions, 3407 deletions
diff --git a/libX11/specs/libX11/CH07.xml b/libX11/specs/libX11/CH07.xml index 505a565a2..ff1a9d836 100644 --- a/libX11/specs/libX11/CH07.xml +++ b/libX11/specs/libX11/CH07.xml @@ -1,3407 +1,3407 @@ -<?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_context_functions">
-<title>Graphics Context Functions</title>
-
-<para>
-A number of resources are used when performing graphics operations in X. Most information
-about performing graphics (for example, foreground color, background color, line style, and so
-on) is stored in resources called graphics contexts (GCs). Most graphics operations (see chapter
-8) take a GC as an argument. Although in theory the X protocol permits sharing of GCs between
-applications, it is expected that applications will use their own GCs when performing operations.
-Sharing of GCs is highly discouraged because the library may cache GC state.
-</para>
-<para>
-Graphics operations can be performed to either windows or pixmaps, which collectively are
-called drawables. Each drawable exists on a single screen. A GC is created for a specific screen
-and drawable depth and can only be used with drawables of matching screen and depth.
-</para>
-<para>
-This chapter discusses how to:
-</para>
-<itemizedlist>
- <listitem><para>Manipulate graphics context/state</para></listitem>
- <listitem><para>Use graphics context convenience functions</para></listitem>
-</itemizedlist>
-
-<sect1 id="Manipulating_Graphics_Context_State">
-<title>Manipulating Graphics Context/State</title>
-<!-- .XS -->
-<!-- (SN Manipulating Graphics Context/State -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-Most attributes of graphics operations are stored in GCs.
-These include line width, line style, plane mask, foreground, background,
-tile, stipple, clipping region, end style, join style, and so on.
-Graphics operations (for example, drawing lines) use these values
-to determine the actual drawing operation.
-Extensions to X may add additional components to GCs.
-The contents of a GC are private to Xlib.
-</para>
-<para>
-<!-- .LP -->
-Xlib implements a write-back cache for all elements of a GC that are not
-resource IDs to allow Xlib to implement the transparent coalescing of changes
-to GCs.
-For example,
-a call to
-<function>XSetForeground</function>
-of a GC followed by a call to
-<function>XSetLineAttributes</function>
-results in only a single-change GC protocol request to the server.
-GCs are neither expected nor encouraged to be shared between client
-applications, so this write-back caching should present no problems.
-Applications cannot share GCs without external synchronization.
-Therefore,
-sharing GCs between applications is highly discouraged.
-</para>
-<para>
-<!-- .LP -->
-To set an attribute of a GC,
-set the appropriate member of the
-<structname>XGCValues</structname>
-structure and OR in the corresponding value bitmask in your subsequent calls to
-<function>XCreateGC</function>.
-The symbols for the value mask bits and the
-<structname>XGCValues</structname>
-structure are:
-<!-- .sM -->
-</para>
-
-
-<literallayout class="monospaced">
-/* GC attribute value mask bits */
-
-#define GCFunction (1L<<0)
-#define GCPlaneMask (1L<<1)
-#define GCForeground (1L<<2)
-#define GCBackground (1L<<3)
-#define GCLineWidth (1L<<4)
-#define GCLineStyle (1L<<5)
-#define GCCapStyle (1L<<6)
-#define GCJoinStyle (1L<<7)
-#define GCFillStyle (1L<<8)
-#define GCFillRule (1L<<9)
-#define GCTile (1L<<10)
-#define GCStipple (1L<<11)
-#define GCTileStipXOrigin (1L<<12)
-#define GCTileStipYOrigin (1L<<13)
-#define GCFont (1L<<14)
-#define GCSubwindowMode (1L<<15)
-#define GCGraphicsExposures (1L<<16)
-#define GCClipXOrigin (1L<<17)
-#define GCClipYOrigin (1L<<18)
-#define GCClipMask (1L<<19)
-#define GCDashOffset (1L<<20)
-#define GCDashList (1L<<21)
-#define GCArcMode (1L<<22)
-</literallayout>
-
-<literallayout class="monospaced">
-<!-- .TA .5i 3i -->
-<!-- .ta .5i 3i -->
-/* Values */
-
-typedef struct {
- int function; /* logical operation */
- unsigned long plane_mask; /* plane mask */
- unsigned long foreground; /* foreground pixel */
- unsigned long background; /* background pixel */
- int line_width; /* line width (in pixels) */
- int line_style; /* LineSolid, LineOnOffDash, LineDoubleDash */
- int cap_style; /* CapNotLast, CapButt, CapRound, CapProjecting */
- int join_style; /* JoinMiter, JoinRound, JoinBevel */
- int fill_style; /* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/
- int fill_rule; /* EvenOddRule, WindingRule */
- int arc_mode; /* ArcChord, ArcPieSlice */
- Pixmap tile; /* tile pixmap for tiling operations */
- Pixmap stipple; /* stipple 1 plane pixmap for stippling */
- int ts_x_origin; /* offset for tile or stipple operations */
- int ts_y_origin
- Font font; /* default text font for text operations */
- int subwindow_mode; /* ClipByChildren, IncludeInferiors */
- Bool graphics_exposures; /* boolean, should exposures be generated */
- int clip_x_origin; /* origin for clipping */
- int clip_y_origin;
- Pixmap clip_mask; /* bitmap clipping; other calls for rects */
- int dash_offset; /* patterned/dashed line information */
- char dashes;
-} XGCValues;
-</literallayout>
-
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The default GC values are:
-</para>
-<informaltable>
- <tgroup cols='3' align='center'>
- <colspec colname='c1'/>
- <colspec colname='c2'/>
- <colspec colname='c3'/>
- <thead>
- <row>
- <entry>Component</entry>
- <entry>Default</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>function</entry>
- <entry><symbol>GXcopy</symbol></entry>
- </row>
- <row>
- <entry>plane_mask</entry>
- <entry>All ones</entry>
- </row>
- <row>
- <entry>foreground</entry>
- <entry>0</entry>
- </row>
- <row>
- <entry>background</entry>
- <entry>1</entry>
- </row>
- <row>
- <entry>line_width</entry>
- <entry>0</entry>
- </row>
- <row>
- <entry>line_style</entry>
- <entry><symbol>LineSolid</symbol></entry>
- </row>
- <row>
- <entry>cap_style</entry>
- <entry><symbol>CapButt</symbol></entry>
- </row>
- <row>
- <entry>join_style</entry>
- <entry><symbol>JoinMiter</symbol></entry>
- </row>
- <row>
- <entry>fill_style</entry>
- <entry><symbol>FillSolid</symbol></entry>
- </row>
- <row>
- <entry>fill_rule</entry>
- <entry><symbol>EvenOddRule</symbol></entry>
- </row>
- <row>
- <entry>arc_mode</entry>
- <entry><symbol>ArcPieSlice</symbol></entry>
- </row>
- <row>
- <entry>tile</entry>
- <entry>Pixmap of unspecified size filled with foreground pixel</entry>
- </row>
- <row>
- <entry></entry>
- <entry>(that is, client specified pixel if any, else 0)</entry>
- </row>
- <row>
- <entry></entry>
- <entry>(subsequent changes to foreground do not affect this pixmap)</entry>
- </row>
- <row>
- <entry>stipple</entry>
- <entry>Pixmap of unspecified size filled with ones</entry>
- </row>
- <row>
- <entry>ts_x_origin</entry>
- <entry>0</entry>
- </row>
- <row>
- <entry>ts_y_origin</entry>
- <entry>0</entry>
- </row>
- <row>
- <entry>font</entry>
- <entry><implementation dependent></entry>
- </row>
- <row>
- <entry>subwindow_mode</entry>
- <entry><symbol>ClipByChildren</symbol></entry>
- </row>
- <row>
- <entry>graphics_exposures</entry>
- <entry><symbol>True</symbol></entry>
- </row>
- <row>
- <entry>clip_x_origin</entry>
- <entry>0</entry>
- </row>
- <row>
- <entry>clip_y_origin</entry>
- <entry>0</entry>
- </row>
- <row>
- <entry>clip_mask</entry>
- <entry><symbol>None</symbol></entry>
- </row>
- <row>
- <entry>dash_offset</entry>
- <entry>0</entry>
- </row>
- <row>
- <entry>dashes</entry>
- <entry>4 (that is, the list [4, 4])</entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>
-
-<para>
-<!-- .LP -->
-Note that foreground and background are not set to any values likely
-to be useful in a window.
-</para>
-
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>Display Functions</primary></indexterm>
-<indexterm significance="preferred"><primary>Source</primary></indexterm>
-<indexterm significance="preferred"><primary>Destination</primary></indexterm>
-The function attributes of a GC are used when you update a section of
-a drawable (the destination) with bits from somewhere else (the source).
-The function in a GC defines how the new destination bits are to be
-computed from the source bits and the old destination bits.
-<symbol>GXcopy</symbol>
-is typically the most useful because it will work on a color display,
-but special applications may use other functions,
-particularly in concert with particular planes of a color display.
-The 16 GC functions, defined in
-<filename class="headerfile"><X11/X.h></filename>,
-<indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm>
-<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
-<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
-are:
-</para>
-<!-- .\" are listed in Table 5-1 along with the -->
-<!-- .\"the associated hexadecimal code -->
-<!-- .\" and operation. -->
-<!-- .\".CP T 1 -->
-<!-- .\"Display Functions -->
-<informaltable>
- <tgroup cols='3' align='center'>
- <colspec colname='c1'/>
- <colspec colname='c2'/>
- <colspec colname='c3'/>
- <thead>
- <row>
- <entry>Function Name</entry>
- <entry>Value</entry>
- <entry>Operation</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><symbol>GXclear</symbol></entry>
- <entry>0x0</entry>
- <entry>0</entry>
- </row>
- <row>
- <entry><symbol>GXand</symbol></entry>
- <entry>0x1</entry>
- <entry>src AND dst</entry>
- </row>
- <row>
- <entry><symbol>GXandReverse</symbol></entry>
- <entry>0x2</entry>
- <entry>src AND NOT dst</entry>
- </row>
- <row>
- <entry><symbol>GXcopy</symbol></entry>
- <entry>0x3</entry>
- <entry>src</entry>
- </row>
- <row>
- <entry><symbol>GXandInverted</symbol></entry>
- <entry>0x4</entry>
- <entry>(NOT src) AND dst</entry>
- </row>
- <row>
- <entry><symbol>GXnoop</symbol></entry>
- <entry>0x5</entry>
- <entry>dst</entry>
- </row>
- <row>
- <entry><symbol>GXxor</symbol></entry>
- <entry>0x6</entry>
- <entry>src XOR dst</entry>
- </row>
- <row>
- <entry><symbol>GXor</symbol></entry>
- <entry>0x7</entry>
- <entry>src OR dst</entry>
- </row>
- <row>
- <entry><symbol>GXnor</symbol></entry>
- <entry>0x8</entry>
- <entry>(NOT src) AND (NOT dst)</entry>
- </row>
- <row>
- <entry><symbol>GXequiv</symbol></entry>
- <entry>0x9</entry>
- <entry>(NOT src) XOR dst</entry>
- </row>
- <row>
- <entry><symbol>GXinvert</symbol></entry>
- <entry>0xa</entry>
- <entry>NOT dst</entry>
- </row>
- <row>
- <entry><symbol>GXorReverse</symbol></entry>
- <entry>0xb</entry>
- <entry>src OR (NOT dst)</entry>
- </row>
- <row>
- <entry><symbol>GXcopyInverted</symbol></entry>
- <entry>0xc</entry>
- <entry>NOT src</entry>
- </row>
- <row>
- <entry><symbol>GXorInverted</symbol></entry>
- <entry>0xd</entry>
- <entry>(NOT src) OR dst</entry>
- </row>
- <row>
- <entry><symbol>GXnand</symbol></entry>
- <entry>0xe</entry>
- <entry>(NOT src) OR (NOT dst)</entry>
- </row>
- <row>
- <entry><symbol>GXset</symbol></entry>
- <entry>0xf</entry>
- <entry>1</entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>
-
-<para>
-<!-- .LP -->
-Many graphics operations depend on either pixel values or planes in a GC.
-<indexterm><primary>Pixel value</primary></indexterm>
-The planes attribute is of type long, and it specifies which planes of the
-destination are to be modified, one bit per plane.
-<indexterm><primary>Plane</primary><secondary>mask</secondary></indexterm>
-A monochrome display has only one plane and
-will be the least significant bit of the word.
-As planes are added to the display hardware, they will occupy more
-significant bits in the plane mask.
-</para>
-<para>
-<!-- .LP -->
-In graphics operations, given a source and destination pixel,
-the result is computed bitwise on corresponding bits of the pixels.
-That is, a Boolean operation is performed in each bit plane.
-The plane_mask restricts the operation to a subset of planes.
-A macro constant
-<symbol>AllPlanes</symbol>
-can be used to refer to all planes of the screen simultaneously.
-The result is computed by the following:
-</para>
-<para>
-<!-- .LP -->
-<literallayout class="monospaced">
-((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-Range checking is not performed on the values for foreground,
-background, or plane_mask.
-They are simply truncated to the appropriate
-number of bits.
-The line-width is measured in pixels and either can be greater than or equal to
-one (wide line) or can be the special value zero (thin line).
-</para>
-<para>
-<!-- .LP -->
-Wide lines are drawn centered on the path described by the graphics request.
-Unless otherwise specified by the join-style or cap-style,
-the bounding box of a wide line with endpoints [x1, y1], [x2, y2] and
-width w is a rectangle with vertices at the following real coordinates:
-</para>
-<para>
-<!-- .LP -->
-<literallayout class="monospaced">
-<!-- .TA .5i 2.5i -->
-<!-- .ta .5i 2.5i -->
-[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)],
-[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-Here sn is the sine of the angle of the line,
-and cs is the cosine of the angle of the line.
-A pixel is part of the line and so is drawn
-if the center of the pixel is fully inside the bounding box
-(which is viewed as having infinitely thin edges).
-If the center of the pixel is exactly on the bounding box,
-it is part of the line if and only if the interior is immediately to its right
-(x increasing direction).
-Pixels with centers on a horizontal edge are a special case and are part of
-the line if and only if the interior or the boundary is immediately below
-(y increasing direction) and the interior or the boundary is immediately
-to the right (x increasing direction).
-</para>
-<para>
-<!-- .LP -->
-Thin lines (zero line-width) are one-pixel-wide lines drawn using an
-unspecified, device-dependent algorithm.
-There are only two constraints on this algorithm.
-</para>
-<itemizedlist>
- <listitem>
- <para>
-If a line is drawn unclipped from [x1,y1] to [x2,y2] and
-if another line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy],
-a point [x,y] is touched by drawing the first line
-if and only if the point [x+dx,y+dy] is touched by drawing the second line.
- </para>
- </listitem>
- <listitem>
- <para>
-The effective set of points comprising a line cannot be affected by clipping.
-That is, a point is touched in a clipped line if and only if the point
-lies inside the clipping region and the point would be touched
-by the line when drawn unclipped.
- </para>
- </listitem>
-</itemizedlist>
-<para>
-<!-- .LP -->
-A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels
-as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style
-and join-style.
-It is recommended that this property be true for thin lines,
-but this is not required.
-A line-width of zero may differ from a line-width of one in which pixels are
-drawn.
-This permits the use of many manufacturers' line drawing hardware,
-which may run many times faster than the more precisely specified
-wide lines.
-</para>
-<para>
-<!-- .LP -->
-In general,
-drawing a thin line will be faster than drawing a wide line of width one.
-However, because of their different drawing algorithms,
-thin lines may not mix well aesthetically with wide lines.
-If it is desirable to obtain precise and uniform results across all displays,
-a client should always use a line-width of one rather than a line-width of zero.
-</para>
-<para>
-<!-- .LP -->
-The line-style defines which sections of a line are drawn:
-</para>
-
-<variablelist>
- <varlistentry>
- <term><symbol>LineSolid</symbol></term>
- <listitem>
- <para>The full path of the line is drawn.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><symbol>LineDoubleDash</symbol></term>
- <listitem>
- <para>
-The full path of the line is drawn,
-but the even dashes are filled differently
-from the odd dashes (see fill-style) with <!-- xref -->
-<symbol>CapButt</symbol>
-style used where even and odd dashes meet.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><symbol>LineOnOffDash</symbol></term>
- <listitem>
- <para>
-Only the even dashes are drawn,
-and cap-style applies to
-all internal ends of the individual dashes,
-except
-<symbol>CapNotLast</symbol>
-is treated as
-<symbol>CapButt</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-<para>
-The cap-style defines how the endpoints of a path are drawn:
-</para>
-
-<variablelist>
- <varlistentry>
- <term><symbol>CapNotLast</symbol></term>
- <listitem>
- <para>
-This is equivalent to
-<symbol>CapButt</symbol>
-except that for a line-width of zero the final endpoint is not drawn.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><symbol>CapButt</symbol></term>
- <listitem>
- <para>
-The line is square at the endpoint (perpendicular to the slope of the line)
-with no projection beyond.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><symbol>CapRound</symbol></term>
- <listitem>
- <para>
-The line has a circular arc with the diameter equal to the line-width,
-centered on the endpoint.
-(This is equivalent to
-<symbol>CapButt</symbol>
-for line-width of zero).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><symbol>CapProjecting</symbol></term>
- <listitem>
- <para>
-The line is square at the end, but the path continues beyond the endpoint
-for a distance equal to half the line-width.
-(This is equivalent to
-<symbol>CapButt</symbol>
-for line-width of zero).
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-The join-style defines how corners are drawn for wide lines:
-</para>
-
-<variablelist>
- <varlistentry>
- <term><symbol>JoinMiter</symbol></term>
- <listitem>
- <para>
-The outer edges of two lines extend to meet at an angle.
-However, if the angle is less than 11 degrees,
-then a
-<symbol>JoinBevel</symbol>
-join-style is used instead.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><symbol>JoinRound</symbol></term>
- <listitem>
- <para>
-The corner is a circular arc with the diameter equal to the line-width,
-centered on the joinpoint.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><symbol>JoinBevel</symbol></term>
- <listitem>
- <para>
-The corner has
-<symbol>CapButt</symbol>
-endpoint styles with the triangular notch filled.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-
-<para>
-<!-- .LP -->
-For a line with coincident endpoints (x1=x2, y1=y2),
-when the cap-style is applied to both endpoints,
-the semantics depends on the line-width and the cap-style:
-</para>
-
-<informaltable>
- <tgroup cols='3' align='center'>
- <colspec colname='c1'/>
- <colspec colname='c2'/>
- <colspec colname='c3'/>
- <tbody>
- <row>
- <entry><symbol>CapNotLast</symbol></entry>
- <entry>thin</entry>
- <entry>The results are device dependent,
- but the desired effect is that nothing is drawn.</entry>
- </row>
- <row>
- <entry><symbol>CapButt</symbol></entry>
- <entry>thin</entry>
- <entry>The results are device dependent,
- but the desired effect is that a single pixel is drawn.</entry>
- </row>
- <row>
- <entry><symbol>CapRound</symbol></entry>
- <entry>thin</entry>
- <entry>The results are the same as for
- <symbol>CapButt</symbol> /thin.</entry>
- </row>
- <row>
- <entry><symbol>CapProjecting</symbol></entry>
- <entry>thin</entry>
- <entry>The results are the same as for
- <symbol>CapButt</symbol> /thin.</entry>
- </row>
- <row>
- <entry><symbol>CapButt</symbol></entry>
- <entry>wide</entry>
- <entry>Nothing is drawn.</entry>
- </row>
- <row>
- <entry><symbol>CapRound</symbol></entry>
- <entry>wide</entry>
- <entry>The closed path is a circle, centered at the endpoint, and
- with the diameter equal to the line-width.</entry>
- </row>
- <row>
- <entry><symbol>CapProjecting</symbol></entry>
- <entry>wide</entry>
- <entry>The closed path is a square, aligned with the coordinate axes, centered at the
- endpoint, and with the sides equal to the line-width.</entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>
-
-<para>
-<!-- .LP -->
-For a line with coincident endpoints (x1=x2, y1=y2),
-when the join-style is applied at one or both endpoints,
-the effect is as if the line was removed from the overall path.
-However, if the total path consists of or is reduced to a single point joined
-with itself, the effect is the same as when the cap-style is applied at both
-endpoints.
-</para>
-<para>
-<!-- .LP -->
-The tile/stipple represents an infinite two-dimensional plane,
-with the tile/stipple replicated in all dimensions.
-When that plane is superimposed on the drawable
-for use in a graphics operation, the upper-left corner
-of some instance of the tile/stipple is at the coordinates within
-the drawable specified by the tile/stipple origin.
-The tile/stipple and clip origins are interpreted relative to the
-origin of whatever destination drawable is specified in a graphics
-request.
-The tile pixmap must have the same root and depth as the GC,
-or a
-<errorname>BadMatch</errorname>
-error results.
-The stipple pixmap must have depth one and must have the same root as the
-GC, or a
-<errorname>BadMatch</errorname>
-error results.
-For stipple operations where the fill-style is
-<symbol>FillStippled</symbol>
-but not
-<symbol>FillOpaqueStippled</symbol>,
-the stipple pattern is tiled in a
-single plane and acts as an additional clip mask to be ANDed with the clip-mask.
-Although some sizes may be faster to use than others,
-any size pixmap can be used for tiling or stippling.
-</para>
-
-<para>
-<!-- .LP -->
-The fill-style defines the contents of the source for line, text, and
-fill requests.
-For all text and fill requests (for example,
-<function>XDrawText</function>,
-<function>XDrawText16</function>,
-<function>XFillRectangle</function>,
-<function>XFillPolygon</function>,
-and
-<function>XFillArc</function>);
-for line requests
-with line-style
-<symbol>LineSolid</symbol>
-(for example,
-<function>XDrawLine</function>,
-<function>XDrawSegments</function>,
-<function>XDrawRectangle</function>,
-<function>XDrawArc</function>);
-and for the even dashes for line requests with line-style
-<symbol>LineOnOffDash</symbol>
-or
-<symbol>LineDoubleDash</symbol>,
-the following apply:
-</para>
-
-<informaltable>
- <tgroup cols='2' align='center'>
- <colspec colname='c1'/>
- <colspec colname='c2'/>
- <tbody>
- <row>
- <entry><symbol>FillSolid</symbol></entry>
- <entry>Foreground</entry>
- </row>
- <row>
- <entry><symbol>FillTiled</symbol></entry>
- <entry>Tile</entry>
- </row>
- <row>
- <entry><symbol>FillOpaqueStippled</symbol></entry>
- <entry>A tile with the same width and height as stipple,
- but with background everywhere stipple has a zero
- and with foreground everywhere stipple has a one</entry>
- </row>
- <row>
- <entry><symbol>FillStippled</symbol></entry>
- <entry>Foreground masked by stipple</entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>
-
-<para>
-<!-- .LP -->
-When drawing lines with line-style
-<symbol>LineDoubleDash</symbol>,
-the odd dashes are controlled by the fill-style in the following manner:
-</para>
-
-<informaltable>
- <tgroup cols='2' align='center'>
- <colspec colname='c1'/>
- <colspec colname='c2'/>
- <tbody>
- <row>
- <entry><symbol>FillSolid</symbol></entry>
- <entry>Background</entry>
- </row>
- <row>
- <entry><symbol>FillTiled</symbol></entry>
- <entry>Same as for even dashes</entry>
- </row>
- <row>
- <entry><symbol>FillOpaqueStippled</symbol></entry>
- <entry>Same as for even dashes</entry>
- </row>
- <row>
- <entry><symbol>FillStippled</symbol></entry>
- <entry>Background masked by stipple</entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>
-
-<para>
-<!-- .LP -->
-Storing a pixmap in a GC might or might not result in a copy
-being made.
-If the pixmap is later used as the destination for a graphics request,
-the change might or might not be reflected in the GC.
-If the pixmap is used simultaneously in a graphics request both as
-a destination and as a tile or stipple,
-the results are undefined.
-</para>
-<para>
-<!-- .LP -->
-For optimum performance,
-you should draw as much as possible with the same GC
-(without changing its components).
-The costs of changing GC components relative to using different GCs
-depend on the display hardware and the server implementation.
-It is quite likely that some amount of GC information will be
-cached in display hardware and that such hardware can only cache a small number
-of GCs.
-</para>
-<para>
-<!-- .LP -->
-The dashes value is actually a simplified form of the
-more general patterns that can be set with
-<function>XSetDashes</function>.
-Specifying a
-value of N is equivalent to specifying the two-element list [N, N] in
-<function>XSetDashes</function>.
-The value must be nonzero,
-or a
-<errorname>BadValue</errorname>
-error results.
-</para>
-<para>
-<!-- .LP -->
-The clip-mask restricts writes to the destination drawable.
-If the clip-mask is set to a pixmap,
-it must have depth one and have the same root as the GC,
-or a
-<errorname>BadMatch</errorname>
-error results.
-If clip-mask is set to
-<symbol>None</symbol>,
-the pixels are always drawn regardless of the clip origin.
-The clip-mask also can be set by calling the
-<function>XSetClipRectangles</function>
-or
-<function>XSetRegion</function>
-functions.
-Only pixels where the clip-mask has a bit set to 1 are drawn.
-Pixels are not drawn outside the area covered by the clip-mask
-or where the clip-mask has a bit set to 0.
-The clip-mask affects all graphics requests.
-The clip-mask does not clip sources.
-The clip-mask origin is interpreted relative to the origin of whatever
-destination drawable is specified in a graphics request.
-</para>
-<para>
-<!-- .LP -->
-You can set the subwindow-mode to
-<symbol>ClipByChildren</symbol>
-or
-<symbol>IncludeInferiors</symbol>.
-For
-<symbol>ClipByChildren</symbol>,
-both source and destination windows are
-additionally clipped by all viewable
-<symbol>InputOutput</symbol>
-children.
-For
-<symbol>IncludeInferiors</symbol>,
-neither source nor destination window is clipped by inferiors.
-This will result in including subwindow contents in the source
-and drawing through subwindow boundaries of the destination.
-The use of
-<symbol>IncludeInferiors</symbol>
-on a window of one depth with mapped
-inferiors of differing depth is not illegal, but the semantics are
-undefined by the core protocol.
-</para>
-<para>
-<!-- .LP -->
-The fill-rule defines what pixels are inside (drawn) for
-paths given in
-<function>XFillPolygon</function>
-requests and can be set to
-<symbol>EvenOddRule</symbol>
-or
-<symbol>WindingRule</symbol>.
-For
-<symbol>EvenOddRule</symbol>,
-a point is inside if
-an infinite ray with the point as origin crosses the path an odd number
-of times.
-For
-<symbol>WindingRule</symbol>,
-a point is inside if an infinite ray with the
-point as origin crosses an unequal number of clockwise and
-counterclockwise directed path segments.
-A clockwise directed path segment is one that crosses the ray from left to
-right as observed from the point.
-A counterclockwise segment is one that crosses the ray from right to left
-as observed from the point.
-The case where a directed line segment is coincident with the ray is
-uninteresting because you can simply choose a different ray that is not
-coincident with a segment.
-</para>
-<para>
-<!-- .LP -->
-For both
-<symbol>EvenOddRule</symbol>
-and
-<symbol>WindingRule</symbol>,
-a point is infinitely small,
-and the path is an infinitely thin line.
-A pixel is inside if the center point of the pixel is inside
-and the center point is not on the boundary.
-If the center point is on the boundary,
-the pixel is inside if and only if the polygon interior is immediately to
-its right (x increasing direction).
-Pixels with centers on a horizontal edge are a special case
-and are inside if and only if the polygon interior is immediately below
-(y increasing direction).
-</para>
-<para>
-<!-- .LP -->
-The arc-mode controls filling in the
-<function>XFillArcs</function>
-function and can be set to
-<symbol>ArcPieSlice</symbol>
-or
-<symbol>ArcChord</symbol>.
-For
-<symbol>ArcPieSlice</symbol>,
-the arcs are pie-slice filled.
-For
-<symbol>ArcChord</symbol>,
-the arcs are chord filled.
-</para>
-<para>
-<!-- .LP -->
-The graphics-exposure flag controls
-<symbol>GraphicsExpose</symbol>
-event generation
-for
-<function>XCopyArea</function>
-and
-<function>XCopyPlane</function>
-requests (and any similar requests defined by extensions).
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To create a new GC that is usable on a given screen with a
-depth of drawable, use
-<function>XCreateGC</function>.
-<indexterm><primary>Graphics context</primary><secondary>initializing</secondary></indexterm>
-<indexterm significance="preferred"><primary>XCreateGC</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>GC <function>XCreateGC</function></funcdef>
- <paramdef>Display <parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> d</parameter></paramdef>
- <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>
- <paramdef>XGCValues *<parameter>values</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 Vm set using the information in the specified values structure -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>valuemask</emphasis>
- </term>
- <listitem>
- <para>
-Specifies which components in the GC are to be (Vm.
-This argument is the bitwise inclusive OR of zero or more of the valid
-GC component mask bits.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>values</emphasis>
- </term>
- <listitem>
- <para>
-Specifies any values as specified by the valuemask.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XCreateGC</function>
-function creates a graphics context and returns a GC.
-The GC can be used with any destination drawable having the same root
-and depth as the specified drawable.
-Use with other drawables results in a
-<errorname>BadMatch</errorname>
-error.
-</para>
-<para>
-<!-- .LP -->
-<function>XCreateGC</function>
-can generate
-<errorname>BadAlloc</errorname>,
-<errorname>BadDrawable</errorname>,
-<errorname>BadFont</errorname>,
-<errorname>BadMatch</errorname>,
-<errorname>BadPixmap</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To copy components from a source GC to a destination GC, use
-<function>XCopyGC</function>.
-<indexterm significance="preferred"><primary>XCopyGC</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XCopyGC</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GCsrc,<parameter> dest</parameter></paramdef>
- <paramdef>unsignedlong<parameter> valuemask</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>
-Specifies the components of the source GC.
-<!-- .ds Vm copied to the destination GC -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>valuemask</emphasis>
- </term>
- <listitem>
- <para>
-Specifies which components in the GC are to be (Vm.
-This argument is the bitwise inclusive OR of zero or more of the valid
-GC component mask bits.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>dest</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the destination GC.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XCopyGC</function>
-function copies the specified components from the source GC
-to the destination GC.
-The source and destination GCs must have the same root and depth,
-or a
-<errorname>BadMatch</errorname>
-error results.
-The valuemask specifies which component to copy, as for
-<function>XCreateGC</function>.
-</para>
-<para>
-<!-- .LP -->
-<function>XCopyGC</function>
-can generate
-<errorname>BadAlloc</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadMatch</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To change the components in a given GC, use
-<function>XChangeGC</function>.
-<indexterm significance="preferred"><primary>XChangeGC</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XChangeGC</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>
- <paramdef>XGCValues<parameter> *values</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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
-<!-- .ds Vm changed using information in the specified values structure -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>valuemask</emphasis>
- </term>
- <listitem>
- <para>
-Specifies which components in the GC are to be (Vm.
-This argument is the bitwise inclusive OR of zero or more of the valid
-GC component mask bits.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>values</emphasis>
- </term>
- <listitem>
- <para>
-Specifies any values as specified by the valuemask.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XChangeGC</function>
-function changes the components specified by valuemask for
-the specified GC.
-The values argument contains the values to be set.
-The values and restrictions are the same as for
-<function>XCreateGC</function>.
-Changing the clip-mask overrides any previous
-<function>XSetClipRectangles</function>
-request on the context.
-Changing the dash-offset or dash-list
-overrides any previous
-<function>XSetDashes</function>
-request on the context.
-The order in which components are verified and altered is server dependent.
-If an error is generated, a subset of the components may have been altered.
-</para>
-<para>
-<!-- .LP -->
-<function>XChangeGC</function>
-can generate
-<errorname>BadAlloc</errorname>,
-<errorname>BadFont</errorname>,
-<errorname>BadGC</errorname>,
-<errorname>BadMatch</errorname>,
-<errorname>BadPixmap</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To obtain components of a given GC, use
-<function>XGetGCValues</function>.
-<indexterm significance="preferred"><primary>XGetGCValues</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>Status <function>XGetGCValues</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>
- <paramdef>XGCValues<parameter> *values_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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
-<!-- .ds Vm returned in the values_return argument -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>valuemask</emphasis>
- </term>
- <listitem>
- <para>
-Specifies which components in the GC are to be (Vm.
-This argument is the bitwise inclusive OR of zero or more of the valid
-GC component mask bits.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>values_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the GC values in the specified
-<structname>XGCValues</structname>
-structure.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XGetGCValues</function>
-function returns the components specified by valuemask for the specified GC.
-If the valuemask contains a valid set of GC mask bits
-(<symbol>GCFunction</symbol>,
-<symbol>GCPlaneMask</symbol>,
-<symbol>GCForeground</symbol>,
-<symbol>GCBackground</symbol>,
-<symbol>GCLineWidth</symbol>,
-<symbol>GCLineStyle</symbol>,
-<symbol>GCCapStyle</symbol>,
-<symbol>GCJoinStyle</symbol>,
-<symbol>GCFillStyle</symbol>,
-<symbol>GCFillRule</symbol>,
-<symbol>GCTile</symbol>,
-<symbol>GCStipple</symbol>,
-<symbol>GCTileStipXOrigin</symbol>,
-<symbol>GCTileStipYOrigin</symbol>,
-<symbol>GCFont</symbol>,
-<symbol>GCSubwindowMode</symbol>,
-<symbol>GCGraphicsExposures</symbol>,
-<symbol>GCClipXOrigin</symbol>,
-<symbol>GCClipYOrigin</symbol>,
-<symbol>GCDashOffset</symbol>,
-or
-<symbol>GCArcMode</symbol>)
-and no error occurs,
-<function>XGetGCValues</function>
-sets the requested components in values_return and returns a nonzero status.
-Otherwise, it returns a zero status.
-Note that the clip-mask and dash-list (represented by the
-<symbol>GCClipMask</symbol>
-and
-<symbol>GCDashList</symbol>
-bits, respectively, in the valuemask)
-cannot be requested.
-Also note that an invalid resource ID (with one or more of the three
-most significant bits set to 1) will be returned for
-<symbol>GCFont</symbol>,
-<symbol>GCTile</symbol>,
-and
-<symbol>GCStipple</symbol>
-if the component has never been explicitly set by the client.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To free a given GC, use
-<function>XFreeGC</function>.
-<indexterm significance="preferred"><primary>XFreeGC</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XFreeGC</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XFreeGC</function>
-function destroys the specified GC as well as all the associated storage.
-</para>
-<para>
-<!-- .LP -->
-<function>XFreeGC</function>
-can generate a
-<errorname>BadGC</errorname>
-error.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To obtain the
-<type>GContext</type>
-resource ID for a given GC, use
-<function>XGContextFromGC</function>.
-<indexterm significance="preferred"><primary>XGContextFromGC</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>GContext <function>XGContextFromGC</function></funcdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<!-- .ds Gc for which you want the resource ID -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC (Gc.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-Xlib usually defers sending changes to the components of a GC to the server
-until a graphics function is actually called with that GC.
-This permits batching of component changes into a single server request.
-In some circumstances, however, it may be necessary for the client
-to explicitly force sending the changes to the server.
-An example might be when a protocol extension uses the GC indirectly,
-in such a way that the extension interface cannot know what GC will be used.
-To force sending GC component changes, use
-<function>XFlushGC</function>.
-<indexterm significance="preferred"><primary>XFlushGC</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>void <function>XFlushGC</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-</para>
-</sect1>
-<sect1 id="Using_Graphics_Context_Convenience_Routines">
-<title>Using Graphics Context Convenience Routines</title>
-<!-- .XS -->
-<!-- (SN Using Graphics Context Convenience Routines -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-This section discusses how to set the:
-</para>
-<itemizedlist>
- <listitem>
- <para>
-Foreground, background, plane mask, or function components
- </para>
- </listitem>
- <listitem>
- <para>
-Line attributes and dashes components
- </para>
- </listitem>
- <listitem>
- <para>
-Fill style and fill rule components
- </para>
- </listitem>
- <listitem>
- <para>
-Fill tile and stipple components
- </para>
- </listitem>
- <listitem>
- <para>
-Font component
- </para>
- </listitem>
- <listitem>
- <para>
-Clip region component
- </para>
- </listitem>
- <listitem>
- <para>
-Arc mode, subwindow mode, and graphics exposure components
- </para>
- </listitem>
-</itemizedlist>
-<sect2 id="Setting_the_Foreground_Background_Function_or_Plane_Mask">
-<title>Setting the Foreground, Background, Function, or Plane Mask</title>
-<!-- .XS -->
-<!-- (SN Setting the Foreground, Background, Function, or Plane Mask -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-To set the foreground, background, plane mask, and function components
-for a given GC, use
-<function>XSetState</function>.
-<indexterm significance="preferred"><primary>XSetState</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetState</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>unsignedlongforeground,<parameter> background</parameter></paramdef>
- <paramdef>int<parameter> function</parameter></paramdef>
- <paramdef>unsignedlong<parameter> plane_mask</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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>foreground</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the foreground you want to set for the specified GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>background</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the background you want to set for the specified GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>function</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the function you want to set for the specified GC.
- </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>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<function>XSetState</function>
-can generate
-<errorname>BadAlloc</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To set the foreground of a given GC, use
-<function>XSetForeground</function>.
-<indexterm significance="preferred"><primary>XSetForeground</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetForeground</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>unsignedlong<parameter> foreground</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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>foreground</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the foreground you want to set for the specified GC.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<function>XSetForeground</function>
-can generate
-<errorname>BadAlloc</errorname>
-and
-<errorname>BadGC</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To set the background of a given GC, use
-<function>XSetBackground</function>.
-<indexterm significance="preferred"><primary>XSetBackground</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetBackground</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>unsignedlong<parameter> background</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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>background</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the background you want to set for the specified GC.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<function>XSetBackground</function>
-can generate
-<errorname>BadAlloc</errorname>
-and
-<errorname>BadGC</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To set the display function in a given GC, use
-<function>XSetFunction</function>.
-<indexterm significance="preferred"><primary>XSetFunction</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetFunction</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>int<parameter> function</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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>function</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the function you want to set for the specified GC.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<function>XSetFunction</function>
-can generate
-<errorname>BadAlloc</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To set the plane mask of a given GC, use
-<function>XSetPlaneMask</function>.
-<indexterm significance="preferred"><primary>XSetPlaneMask</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetPlaneMask</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>unsignedlong<parameter> plane_mask</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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </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>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<function>XSetPlaneMask</function>
-can generate
-<errorname>BadAlloc</errorname>
-and
-<errorname>BadGC</errorname>
-errors.
-</para>
-</sect2>
-<sect2 id="Setting_the_Line_Attributes_and_Dashes">
-<title>Setting the Line Attributes and Dashes</title>
-<!-- .XS -->
-<!-- (SN Setting the Line Attributes and Dashes -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-To set the line drawing components of a given GC, use
-<function>XSetLineAttributes</function>.
-<indexterm significance="preferred"><primary>XSetLineAttributes</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetLineAttributes</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>unsignedint<parameter> line_width</parameter></paramdef>
- <paramdef>int<parameter> line_style</parameter></paramdef>
- <paramdef>int<parameter> cap_style</parameter></paramdef>
- <paramdef>int<parameter> join_style</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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>line_width</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the line-width you want to set for the specified GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>line_style</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the line-style you want to set for the specified GC.
-You can pass
-<symbol>LineSolid</symbol>,
-<symbol>LineOnOffDash</symbol>,
-or
-<symbol>LineDoubleDash</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>cap_style</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the line-style and cap-style you want to set for the specified GC.
-You can pass
-<symbol>CapNotLast</symbol>,
-<symbol>CapButt</symbol>,
-<symbol>CapRound</symbol>,
-or
-<symbol>CapProjecting</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>join_style</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the line join-style you want to set for the specified GC.
-You can pass
-<symbol>JoinMiter</symbol>,
-<symbol>JoinRound</symbol>,
-or
-<symbol>JoinBevel</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<function>XSetLineAttributes</function>
-can generate
-<errorname>BadAlloc</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To set the dash-offset and dash-list for dashed line styles of a given GC, use
-<function>XSetDashes</function>.
-<indexterm significance="preferred"><primary>XSetDashes</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetDashes</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>int<parameter> dash_offset</parameter></paramdef>
- <paramdef>char<parameter> dash_list[]</parameter></paramdef>
- <paramdef>int<parameter> n</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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>dash_offset</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the phase of the pattern for the dashed line-style you want to set
-for the specified GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>dash_list</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the dash-list for the dashed line-style
-you want to set for the specified GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>n</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of elements in dash_list.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XSetDashes</function>
-function sets the dash-offset and dash-list attributes for dashed line styles
-in the specified GC.
-There must be at least one element in the specified dash_list,
-or a
-<errorname>BadValue</errorname>
-error results.
-The initial and alternating elements (second, fourth, and so on)
-of the dash_list are the even dashes, and
-the others are the odd dashes.
-Each element specifies a dash length in pixels.
-All of the elements must be nonzero,
-or a
-<errorname>BadValue</errorname>
-error results.
-Specifying an odd-length list is equivalent to specifying the same list
-concatenated with itself to produce an even-length list.
-</para>
-<para>
-<!-- .LP -->
-The dash-offset defines the phase of the pattern,
-specifying how many pixels into the dash-list the pattern
-should actually begin in any single graphics request.
-Dashing is continuous through path elements combined with a join-style
-but is reset to the dash-offset between each sequence of joined lines.
-</para>
-<para>
-<!-- .LP -->
-The unit of measure for dashes is the same for the ordinary coordinate system.
-Ideally, a dash length is measured along the slope of the line, but implementations
-are only required to match this ideal for horizontal and vertical lines.
-Failing the ideal semantics, it is suggested that the length be measured along the
-major axis of the line.
-The major axis is defined as the x axis for lines drawn at an angle of between
-−45 and +45 degrees or between 135 and 225 degrees from the x axis.
-For all other lines, the major axis is the y axis.
-</para>
-<para>
-<!-- .LP -->
-<function>XSetDashes</function>
-can generate
-<errorname>BadAlloc</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-</sect2>
-<sect2 id="Setting_the_Fill_Style_and_Fill_Rule_">
-<title>Setting the Fill Style and Fill Rule </title>
-<!-- .XS -->
-<!-- (SN Setting the Fill Style and Fill Rule -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-To set the fill-style of a given GC, use
-<function>XSetFillStyle</function>.
-<indexterm significance="preferred"><primary>XSetFillStyle</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetFillStyle</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>int<parameter> fill_style</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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>fill_style</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the fill-style you want to set for the specified GC.
-You can pass
-<symbol>FillSolid</symbol>,
-<symbol>FillTiled</symbol>,
-<symbol>FillStippled</symbol>,
-or
-<symbol>FillOpaqueStippled</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<function>XSetFillStyle</function>
-can generate
-<errorname>BadAlloc</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To set the fill-rule of a given GC, use
-<function>XSetFillRule</function>.
-<indexterm significance="preferred"><primary>XSetFillRule</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetFillRule</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>int<parameter> fill_rule</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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>fill_rule</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the fill-rule you want to set for the specified GC.
-You can pass
-<symbol>EvenOddRule</symbol>
-or
-<symbol>WindingRule</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<function>XSetFillRule</function>
-can generate
-<errorname>BadAlloc</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-</sect2>
-<sect2 id="Setting_the_Fill_Tile_and_Stipple_">
-<title>Setting the Fill Tile and Stipple </title>
-<!-- .XS -->
-<!-- (SN Setting the Fill Tile and Stipple -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-Some displays have hardware support for tiling or
-stippling with patterns of specific sizes.
-Tiling and stippling operations that restrict themselves to those specific
-sizes run much faster than such operations with arbitrary size patterns.
-Xlib provides functions that you can use to determine the best size,
-tile, or stipple for the display
-as well as to set the tile or stipple shape and the tile or stipple origin.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To obtain the best size of a tile, stipple, or cursor, use
-<function>XQueryBestSize</function>.
-<indexterm significance="preferred"><primary>XQueryBestSize</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>Status <function>XQueryBestSize</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>int<parameter> class</parameter></paramdef>
- <paramdef>Drawable<parameter> which_screen</parameter></paramdef>
- <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
- <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>class</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the class that you are interested in.
-You can pass
-<symbol>TileShape</symbol>,
-<symbol>CursorShape</symbol>,
-or
-<symbol>StippleShape</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>which_screen</emphasis>
- </term>
- <listitem>
- <para>
-Specifies any drawable on the screen.
- </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.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>width_return</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>height_return</emphasis>
- </term>
- <listitem>
- <para>
-Return the width and height of the object best supported
-by the display hardware.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XQueryBestSize</function>
-function returns the best or closest size to the specified size.
-For
-<symbol>CursorShape</symbol>,
-this is the largest size that can be fully displayed on the screen specified by
-which_screen.
-For
-<symbol>TileShape</symbol>,
-this is the size that can be tiled fastest.
-For
-<symbol>StippleShape</symbol>,
-this is the size that can be stippled fastest.
-For
-<symbol>CursorShape</symbol>,
-the drawable indicates the desired screen.
-For
-<symbol>TileShape</symbol>
-and
-<symbol>StippleShape</symbol>,
-the drawable indicates the screen and possibly the window class and depth.
-An
-<symbol>InputOnly</symbol>
-window cannot be used as the drawable for
-<symbol>TileShape</symbol>
-or
-<symbol>StippleShape</symbol>,
-or a
-<errorname>BadMatch</errorname>
-error results.
-</para>
-<para>
-<!-- .LP -->
-<function>XQueryBestSize</function>
-can generate
-<errorname>BadDrawable</errorname>,
-<errorname>BadMatch</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To obtain the best fill tile shape, use
-<function>XQueryBestTile</function>.
-<indexterm significance="preferred"><primary>XQueryBestTile</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>Status <function>XQueryBestTile</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> which_screen</parameter></paramdef>
- <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
- <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>which_screen</emphasis>
- </term>
- <listitem>
- <para>
-Specifies any drawable on the screen.
- </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.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>width_return</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>height_return</emphasis>
- </term>
- <listitem>
- <para>
-Return the width and height of the object best supported
-by the display hardware.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XQueryBestTile</function>
-function returns the best or closest size, that is, the size that can be
-tiled fastest on the screen specified by which_screen.
-The drawable indicates the screen and possibly the window class and depth.
-If an
-<symbol>InputOnly</symbol>
-window is used as the drawable, a
-<errorname>BadMatch</errorname>
-error results.
-</para>
-<para>
-<!-- .LP -->
-<function>XQueryBestTile</function>
-can generate
-<errorname>BadDrawable</errorname>
-and
-<errorname>BadMatch</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To obtain the best stipple shape, use
-<function>XQueryBestStipple</function>.
-<indexterm significance="preferred"><primary>XQueryBestStipple</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>Status <function>XQueryBestStipple</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Drawable<parameter> which_screen</parameter></paramdef>
- <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
- <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>which_screen</emphasis>
- </term>
- <listitem>
- <para>
-Specifies any drawable on the screen.
- </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.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>width_return</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>height_return</emphasis>
- </term>
- <listitem>
- <para>
-Return the width and height of the object best supported
-by the display hardware.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XQueryBestStipple</function>
-function returns the best or closest size, that is, the size that can be
-stippled fastest on the screen specified by which_screen.
-The drawable indicates the screen and possibly the window class and depth.
-If an
-<symbol>InputOnly</symbol>
-window is used as the drawable, a
-<errorname>BadMatch</errorname>
-error results.
-</para>
-<para>
-<!-- .LP -->
-<function>XQueryBestStipple</function>
-can generate
-<errorname>BadDrawable</errorname>
-and
-<errorname>BadMatch</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To set the fill tile of a given GC, use
-<function>XSetTile</function>.
-<indexterm significance="preferred"><primary>XSetTile</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetTile</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>Pixmap<parameter> tile</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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>tile</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the fill tile you want to set for the specified GC.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The tile and GC must have the same depth,
-or a
-<errorname>BadMatch</errorname>
-error results.
-</para>
-<para>
-<!-- .LP -->
-<function>XSetTile</function>
-can generate
-<errorname>BadAlloc</errorname>,
-<errorname>BadGC</errorname>,
-<errorname>BadMatch</errorname>,
-and
-<errorname>BadPixmap</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To set the stipple of a given GC, use
-<function>XSetStipple</function>.
-<indexterm significance="preferred"><primary>XSetStipple</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetStipple</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>Pixmap<parameter> stipple</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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>stipple</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the stipple you want to set for the specified GC.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The stipple must have a depth of one,
-or a
-<errorname>BadMatch</errorname>
-error results.
-</para>
-<para>
-<!-- .LP -->
-<function>XSetStipple</function>
-can generate
-<errorname>BadAlloc</errorname>,
-<errorname>BadGC</errorname>,
-<errorname>BadMatch</errorname>,
-and
-<errorname>BadPixmap</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To set the tile or stipple origin of a given GC, use
-<function>XSetTSOrigin</function>.
-<indexterm significance="preferred"><primary>XSetTSOrigin</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetTSOrigin</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>intts_x_origin,<parameter> ts_y_origin</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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>ts_x_origin</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>ts_y_origin</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates of the tile and stipple origin.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-When graphics requests call for tiling or stippling,
-the parent's origin will be interpreted relative to whatever destination
-drawable is specified in the graphics request.
-</para>
-<para>
-<!-- .LP -->
-<function>XSetTSOrigin</function>
-can generate
-<errorname>BadAlloc</errorname>
-and
-<errorname>BadGC</errorname>
-errors.
-</para>
-</sect2>
-<sect2 id="Setting_the_Current_Font_">
-<title>Setting the Current Font </title>
-<!-- .XS -->
-<!-- (SN Setting the Current Font -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-To set the current font of a given GC, use
-<function>XSetFont</function>.
-<indexterm significance="preferred"><primary>XSetFont</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetFont</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>font</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the font.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<function>XSetFont</function>
-can generate
-<errorname>BadAlloc</errorname>,
-<errorname>BadFont</errorname>,
-and
-<errorname>BadGC</errorname>
-errors.
-</para>
-</sect2>
-<sect2 id="Setting_the_Clip_Region">
-<title>Setting the Clip Region</title>
-<!-- .XS -->
-<!-- (SN Setting the Clip Region -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-Xlib provides functions that you can use to set the clip-origin
-and the clip-mask or set the clip-mask to a list of rectangles.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To set the clip-origin of a given GC, use
-<function>XSetClipOrigin</function>.
-<indexterm significance="preferred"><primary>XSetClipOrigin</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetClipOrigin</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>intclip_x_origin,<parameter> clip_y_origin</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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>clip_x_origin</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>clip_y_origin</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates of the clip-mask origin.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The clip-mask origin is interpreted relative to the origin of whatever
-destination drawable is specified in the graphics request.
-</para>
-<para>
-<!-- .LP -->
-<function>XSetClipOrigin</function>
-can generate
-<errorname>BadAlloc</errorname>
-and
-<errorname>BadGC</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To set the clip-mask of a given GC to the specified pixmap, use
-<function>XSetClipMask</function>.
-<indexterm significance="preferred"><primary>XSetClipMask</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetClipMask</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>Pixmap<parameter> pixmap</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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>pixmap</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the pixmap or
-<symbol>None</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-If the clip-mask is set to
-<symbol>None</symbol>,
-the pixels are always drawn (regardless of the clip-origin).
-</para>
-<para>
-<!-- .LP -->
-<function>XSetClipMask</function>
-can generate
-<errorname>BadAlloc</errorname>,
-<errorname>BadGC</errorname>,
-<errorname>BadMatch</errorname>,
-and
-<errorname>BadPixmap</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To set the clip-mask of a given GC to the specified list of rectangles, use
-<function>XSetClipRectangles</function>.
-<indexterm significance="preferred"><primary>XSetClipRectangles</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetClipRectangles</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>intclip_x_origin,<parameter> clip_y_origin</parameter></paramdef>
- <paramdef>XRectangle<parameter> rectangles[]</parameter></paramdef>
- <paramdef>int<parameter> n</parameter></paramdef>
- <paramdef>int<parameter> ordering</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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>clip_x_origin</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>clip_y_origin</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates of the clip-mask origin.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>rectangles</emphasis>
- </term>
- <listitem>
- <para>
-Specifies an array of rectangles that define the clip-mask.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>n</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of rectangles.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>ordering</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the ordering relations on the rectangles.
-You can pass
-<symbol>Unsorted</symbol>,
-<symbol>YSorted</symbol>,
-<symbol>YXSorted</symbol>,
-or
-<symbol>YXBanded</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XSetClipRectangles</function>
-function changes the clip-mask in the specified GC
-to the specified list of rectangles and sets the clip origin.
-The output is clipped to remain contained within the
-rectangles.
-The clip-origin is interpreted relative to the origin of
-whatever destination drawable is specified in a graphics request.
-The rectangle coordinates are interpreted relative to the clip-origin.
-The rectangles should be nonintersecting, or the graphics results will be
-undefined.
-Note that the list of rectangles can be empty,
-which effectively disables output.
-This is the opposite of passing
-<symbol>None</symbol>
-as the clip-mask in
-<function>XCreateGC</function>,
-<function>XChangeGC</function>,
-and
-<function>XSetClipMask</function>.
-</para>
-<para>
-<!-- .LP -->
-If known by the client, ordering relations on the rectangles can be
-specified with the ordering argument.
-This may provide faster operation
-by the server.
-If an incorrect ordering is specified, the X server may generate a
-<errorname>BadMatch</errorname>
-error, but it is not required to do so.
-If no error is generated, the graphics
-results are undefined.
-<symbol>Unsorted</symbol>
-means the rectangles are in arbitrary order.
-<symbol>YSorted</symbol>
-means that the rectangles are nondecreasing in their Y origin.
-<symbol>YXSorted</symbol>
-additionally constrains
-<symbol>YSorted</symbol>
-order in that all
-rectangles with an equal Y origin are nondecreasing in their X
-origin.
-<symbol>YXBanded</symbol>
-additionally constrains
-<symbol>YXSorted</symbol>
-by requiring that,
-for every possible Y scanline, all rectangles that include that
-scanline have an identical Y origins and Y extents.
-</para>
-<para>
-<!-- .LP -->
-<function>XSetClipRectangles</function>
-can generate
-<errorname>BadAlloc</errorname>,
-<errorname>BadGC</errorname>,
-<errorname>BadMatch</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-Xlib provides a set of basic functions for performing
-region arithmetic.
-For information about these functions,
-see section 16.5.
-</para>
-</sect2>
-<sect2 id="Setting_the_Arc_Mode_Subwindow_Mode_and_Graphics_Exposure_">
-<title>Setting the Arc Mode, Subwindow Mode, and Graphics Exposure </title>
-<!-- .XS -->
-<!-- (SN Setting the Arc Mode, Subwindow Mode, and Graphics Exposure -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-To set the arc mode of a given GC, use
-<function>XSetArcMode</function>.
-<indexterm significance="preferred"><primary>XSetArcMode</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetArcMode</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>int<parameter> arc_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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>arc_mode</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the arc mode.
-You can pass
-<symbol>ArcChord</symbol>
-or
-<symbol>ArcPieSlice</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<function>XSetArcMode</function>
-can generate
-<errorname>BadAlloc</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To set the subwindow mode of a given GC, use
-<function>XSetSubwindowMode</function>.
-<indexterm significance="preferred"><primary>XSetSubwindowMode</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetSubwindowMode</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>int<parameter> subwindow_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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>subwindow_mode</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the subwindow mode.
-You can pass
-<symbol>ClipByChildren</symbol>
-or
-<symbol>IncludeInferiors</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<function>XSetSubwindowMode</function>
-can generate
-<errorname>BadAlloc</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To set the graphics-exposures flag of a given GC, use
-<function>XSetGraphicsExposures</function>.
-<indexterm significance="preferred"><primary>XSetGraphicsExposures</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetGraphicsExposures</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>GC<parameter> gc</parameter></paramdef>
- <paramdef>Bool<parameter> graphics_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'>gc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the GC.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>graphics_exposures</emphasis>
- </term>
- <listitem>
- <para>
-Specifies a Boolean value that indicates whether you want
-<symbol>GraphicsExpose</symbol>
-and
-<symbol>NoExpose</symbol>
-events to be reported when calling
-<function>XCopyArea</function>
-and
-<function>XCopyPlane</function>
-with this GC.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<function>XSetGraphicsExposures</function>
-can generate
-<errorname>BadAlloc</errorname>,
-<errorname>BadGC</errorname>,
-and
-<errorname>BadValue</errorname>
-errors.
-<!-- .bp -->
-
-</para>
-</sect2>
-</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_context_functions"> +<title>Graphics Context Functions</title> + +<para> +A number of resources are used when performing graphics operations in X. Most information +about performing graphics (for example, foreground color, background color, line style, and so +on) is stored in resources called graphics contexts (GCs). Most graphics operations (see chapter +8) take a GC as an argument. Although in theory the X protocol permits sharing of GCs between +applications, it is expected that applications will use their own GCs when performing operations. +Sharing of GCs is highly discouraged because the library may cache GC state. +</para> +<para> +Graphics operations can be performed to either windows or pixmaps, which collectively are +called drawables. Each drawable exists on a single screen. A GC is created for a specific screen +and drawable depth and can only be used with drawables of matching screen and depth. +</para> +<para> +This chapter discusses how to: +</para> +<itemizedlist> + <listitem><para>Manipulate graphics context/state</para></listitem> + <listitem><para>Use graphics context convenience functions</para></listitem> +</itemizedlist> + +<sect1 id="Manipulating_Graphics_Context_State"> +<title>Manipulating Graphics Context/State</title> +<!-- .XS --> +<!-- (SN Manipulating Graphics Context/State --> +<!-- .XE --> +<para> +<!-- .LP --> +Most attributes of graphics operations are stored in GCs. +These include line width, line style, plane mask, foreground, background, +tile, stipple, clipping region, end style, join style, and so on. +Graphics operations (for example, drawing lines) use these values +to determine the actual drawing operation. +Extensions to X may add additional components to GCs. +The contents of a GC are private to Xlib. +</para> +<para> +<!-- .LP --> +Xlib implements a write-back cache for all elements of a GC that are not +resource IDs to allow Xlib to implement the transparent coalescing of changes +to GCs. +For example, +a call to +<function>XSetForeground</function> +of a GC followed by a call to +<function>XSetLineAttributes</function> +results in only a single-change GC protocol request to the server. +GCs are neither expected nor encouraged to be shared between client +applications, so this write-back caching should present no problems. +Applications cannot share GCs without external synchronization. +Therefore, +sharing GCs between applications is highly discouraged. +</para> +<para> +<!-- .LP --> +To set an attribute of a GC, +set the appropriate member of the +<structname>XGCValues</structname> +structure and OR in the corresponding value bitmask in your subsequent calls to +<function>XCreateGC</function>. +The symbols for the value mask bits and the +<structname>XGCValues</structname> +structure are: +<!-- .sM --> +</para> + + +<literallayout class="monospaced"> +/* GC attribute value mask bits */ + +#define GCFunction (1L<<0) +#define GCPlaneMask (1L<<1) +#define GCForeground (1L<<2) +#define GCBackground (1L<<3) +#define GCLineWidth (1L<<4) +#define GCLineStyle (1L<<5) +#define GCCapStyle (1L<<6) +#define GCJoinStyle (1L<<7) +#define GCFillStyle (1L<<8) +#define GCFillRule (1L<<9) +#define GCTile (1L<<10) +#define GCStipple (1L<<11) +#define GCTileStipXOrigin (1L<<12) +#define GCTileStipYOrigin (1L<<13) +#define GCFont (1L<<14) +#define GCSubwindowMode (1L<<15) +#define GCGraphicsExposures (1L<<16) +#define GCClipXOrigin (1L<<17) +#define GCClipYOrigin (1L<<18) +#define GCClipMask (1L<<19) +#define GCDashOffset (1L<<20) +#define GCDashList (1L<<21) +#define GCArcMode (1L<<22) +</literallayout> + +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +/* Values */ + +typedef struct { + int function; /* logical operation */ + unsigned long plane_mask; /* plane mask */ + unsigned long foreground; /* foreground pixel */ + unsigned long background; /* background pixel */ + int line_width; /* line width (in pixels) */ + int line_style; /* LineSolid, LineOnOffDash, LineDoubleDash */ + int cap_style; /* CapNotLast, CapButt, CapRound, CapProjecting */ + int join_style; /* JoinMiter, JoinRound, JoinBevel */ + int fill_style; /* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/ + int fill_rule; /* EvenOddRule, WindingRule */ + int arc_mode; /* ArcChord, ArcPieSlice */ + Pixmap tile; /* tile pixmap for tiling operations */ + Pixmap stipple; /* stipple 1 plane pixmap for stippling */ + int ts_x_origin; /* offset for tile or stipple operations */ + int ts_y_origin + Font font; /* default text font for text operations */ + int subwindow_mode; /* ClipByChildren, IncludeInferiors */ + Bool graphics_exposures; /* boolean, should exposures be generated */ + int clip_x_origin; /* origin for clipping */ + int clip_y_origin; + Pixmap clip_mask; /* bitmap clipping; other calls for rects */ + int dash_offset; /* patterned/dashed line information */ + char dashes; +} XGCValues; +</literallayout> + +<para> +<!-- .LP --> +<!-- .eM --> +The default GC values are: +</para> +<informaltable> + <tgroup cols='3' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <thead> + <row> + <entry>Component</entry> + <entry>Default</entry> + </row> + </thead> + <tbody> + <row> + <entry>function</entry> + <entry><symbol>GXcopy</symbol></entry> + </row> + <row> + <entry>plane_mask</entry> + <entry>All ones</entry> + </row> + <row> + <entry>foreground</entry> + <entry>0</entry> + </row> + <row> + <entry>background</entry> + <entry>1</entry> + </row> + <row> + <entry>line_width</entry> + <entry>0</entry> + </row> + <row> + <entry>line_style</entry> + <entry><symbol>LineSolid</symbol></entry> + </row> + <row> + <entry>cap_style</entry> + <entry><symbol>CapButt</symbol></entry> + </row> + <row> + <entry>join_style</entry> + <entry><symbol>JoinMiter</symbol></entry> + </row> + <row> + <entry>fill_style</entry> + <entry><symbol>FillSolid</symbol></entry> + </row> + <row> + <entry>fill_rule</entry> + <entry><symbol>EvenOddRule</symbol></entry> + </row> + <row> + <entry>arc_mode</entry> + <entry><symbol>ArcPieSlice</symbol></entry> + </row> + <row> + <entry>tile</entry> + <entry>Pixmap of unspecified size filled with foreground pixel</entry> + </row> + <row> + <entry></entry> + <entry>(that is, client specified pixel if any, else 0)</entry> + </row> + <row> + <entry></entry> + <entry>(subsequent changes to foreground do not affect this pixmap)</entry> + </row> + <row> + <entry>stipple</entry> + <entry>Pixmap of unspecified size filled with ones</entry> + </row> + <row> + <entry>ts_x_origin</entry> + <entry>0</entry> + </row> + <row> + <entry>ts_y_origin</entry> + <entry>0</entry> + </row> + <row> + <entry>font</entry> + <entry><implementation dependent></entry> + </row> + <row> + <entry>subwindow_mode</entry> + <entry><symbol>ClipByChildren</symbol></entry> + </row> + <row> + <entry>graphics_exposures</entry> + <entry><symbol>True</symbol></entry> + </row> + <row> + <entry>clip_x_origin</entry> + <entry>0</entry> + </row> + <row> + <entry>clip_y_origin</entry> + <entry>0</entry> + </row> + <row> + <entry>clip_mask</entry> + <entry><symbol>None</symbol></entry> + </row> + <row> + <entry>dash_offset</entry> + <entry>0</entry> + </row> + <row> + <entry>dashes</entry> + <entry>4 (that is, the list [4, 4])</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +<!-- .LP --> +Note that foreground and background are not set to any values likely +to be useful in a window. +</para> + +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>Display Functions</primary></indexterm> +<indexterm significance="preferred"><primary>Source</primary></indexterm> +<indexterm significance="preferred"><primary>Destination</primary></indexterm> +The function attributes of a GC are used when you update a section of +a drawable (the destination) with bits from somewhere else (the source). +The function in a GC defines how the new destination bits are to be +computed from the source bits and the old destination bits. +<symbol>GXcopy</symbol> +is typically the most useful because it will work on a color display, +but special applications may use other functions, +particularly in concert with particular planes of a color display. +The 16 GC functions, defined in +<filename class="headerfile"><X11/X.h></filename>, +<indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm> +<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm> +<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm> +are: +</para> +<!-- .\" are listed in Table 5-1 along with the --> +<!-- .\"the associated hexadecimal code --> +<!-- .\" and operation. --> +<!-- .\".CP T 1 --> +<!-- .\"Display Functions --> +<informaltable> + <tgroup cols='3' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <thead> + <row> + <entry>Function Name</entry> + <entry>Value</entry> + <entry>Operation</entry> + </row> + </thead> + <tbody> + <row> + <entry><symbol>GXclear</symbol></entry> + <entry>0x0</entry> + <entry>0</entry> + </row> + <row> + <entry><symbol>GXand</symbol></entry> + <entry>0x1</entry> + <entry>src AND dst</entry> + </row> + <row> + <entry><symbol>GXandReverse</symbol></entry> + <entry>0x2</entry> + <entry>src AND NOT dst</entry> + </row> + <row> + <entry><symbol>GXcopy</symbol></entry> + <entry>0x3</entry> + <entry>src</entry> + </row> + <row> + <entry><symbol>GXandInverted</symbol></entry> + <entry>0x4</entry> + <entry>(NOT src) AND dst</entry> + </row> + <row> + <entry><symbol>GXnoop</symbol></entry> + <entry>0x5</entry> + <entry>dst</entry> + </row> + <row> + <entry><symbol>GXxor</symbol></entry> + <entry>0x6</entry> + <entry>src XOR dst</entry> + </row> + <row> + <entry><symbol>GXor</symbol></entry> + <entry>0x7</entry> + <entry>src OR dst</entry> + </row> + <row> + <entry><symbol>GXnor</symbol></entry> + <entry>0x8</entry> + <entry>(NOT src) AND (NOT dst)</entry> + </row> + <row> + <entry><symbol>GXequiv</symbol></entry> + <entry>0x9</entry> + <entry>(NOT src) XOR dst</entry> + </row> + <row> + <entry><symbol>GXinvert</symbol></entry> + <entry>0xa</entry> + <entry>NOT dst</entry> + </row> + <row> + <entry><symbol>GXorReverse</symbol></entry> + <entry>0xb</entry> + <entry>src OR (NOT dst)</entry> + </row> + <row> + <entry><symbol>GXcopyInverted</symbol></entry> + <entry>0xc</entry> + <entry>NOT src</entry> + </row> + <row> + <entry><symbol>GXorInverted</symbol></entry> + <entry>0xd</entry> + <entry>(NOT src) OR dst</entry> + </row> + <row> + <entry><symbol>GXnand</symbol></entry> + <entry>0xe</entry> + <entry>(NOT src) OR (NOT dst)</entry> + </row> + <row> + <entry><symbol>GXset</symbol></entry> + <entry>0xf</entry> + <entry>1</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +<!-- .LP --> +Many graphics operations depend on either pixel values or planes in a GC. +<indexterm><primary>Pixel value</primary></indexterm> +The planes attribute is of type long, and it specifies which planes of the +destination are to be modified, one bit per plane. +<indexterm><primary>Plane</primary><secondary>mask</secondary></indexterm> +A monochrome display has only one plane and +will be the least significant bit of the word. +As planes are added to the display hardware, they will occupy more +significant bits in the plane mask. +</para> +<para> +<!-- .LP --> +In graphics operations, given a source and destination pixel, +the result is computed bitwise on corresponding bits of the pixels. +That is, a Boolean operation is performed in each bit plane. +The plane_mask restricts the operation to a subset of planes. +A macro constant +<symbol>AllPlanes</symbol> +can be used to refer to all planes of the screen simultaneously. +The result is computed by the following: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask)) +</literallayout> +</para> +<para> +<!-- .LP --> +Range checking is not performed on the values for foreground, +background, or plane_mask. +They are simply truncated to the appropriate +number of bits. +The line-width is measured in pixels and either can be greater than or equal to +one (wide line) or can be the special value zero (thin line). +</para> +<para> +<!-- .LP --> +Wide lines are drawn centered on the path described by the graphics request. +Unless otherwise specified by the join-style or cap-style, +the bounding box of a wide line with endpoints [x1, y1], [x2, y2] and +width w is a rectangle with vertices at the following real coordinates: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i 2.5i --> +<!-- .ta .5i 2.5i --> +[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)], +[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)] +</literallayout> +</para> +<para> +<!-- .LP --> +Here sn is the sine of the angle of the line, +and cs is the cosine of the angle of the line. +A pixel is part of the line and so is drawn +if the center of the pixel is fully inside the bounding box +(which is viewed as having infinitely thin edges). +If the center of the pixel is exactly on the bounding box, +it is part of the line if and only if the interior is immediately to its right +(x increasing direction). +Pixels with centers on a horizontal edge are a special case and are part of +the line if and only if the interior or the boundary is immediately below +(y increasing direction) and the interior or the boundary is immediately +to the right (x increasing direction). +</para> +<para> +<!-- .LP --> +Thin lines (zero line-width) are one-pixel-wide lines drawn using an +unspecified, device-dependent algorithm. +There are only two constraints on this algorithm. +</para> +<itemizedlist> + <listitem> + <para> +If a line is drawn unclipped from [x1,y1] to [x2,y2] and +if another line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy], +a point [x,y] is touched by drawing the first line +if and only if the point [x+dx,y+dy] is touched by drawing the second line. + </para> + </listitem> + <listitem> + <para> +The effective set of points comprising a line cannot be affected by clipping. +That is, a point is touched in a clipped line if and only if the point +lies inside the clipping region and the point would be touched +by the line when drawn unclipped. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels +as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style +and join-style. +It is recommended that this property be true for thin lines, +but this is not required. +A line-width of zero may differ from a line-width of one in which pixels are +drawn. +This permits the use of many manufacturers' line drawing hardware, +which may run many times faster than the more precisely specified +wide lines. +</para> +<para> +<!-- .LP --> +In general, +drawing a thin line will be faster than drawing a wide line of width one. +However, because of their different drawing algorithms, +thin lines may not mix well aesthetically with wide lines. +If it is desirable to obtain precise and uniform results across all displays, +a client should always use a line-width of one rather than a line-width of zero. +</para> +<para> +<!-- .LP --> +The line-style defines which sections of a line are drawn: +</para> + +<variablelist> + <varlistentry> + <term><symbol>LineSolid</symbol></term> + <listitem> + <para>The full path of the line is drawn.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><symbol>LineDoubleDash</symbol></term> + <listitem> + <para> +The full path of the line is drawn, +but the even dashes are filled differently +from the odd dashes (see fill-style) with <!-- xref --> +<symbol>CapButt</symbol> +style used where even and odd dashes meet. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><symbol>LineOnOffDash</symbol></term> + <listitem> + <para> +Only the even dashes are drawn, +and cap-style applies to +all internal ends of the individual dashes, +except +<symbol>CapNotLast</symbol> +is treated as +<symbol>CapButt</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +<para> +The cap-style defines how the endpoints of a path are drawn: +</para> + +<variablelist> + <varlistentry> + <term><symbol>CapNotLast</symbol></term> + <listitem> + <para> +This is equivalent to +<symbol>CapButt</symbol> +except that for a line-width of zero the final endpoint is not drawn. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><symbol>CapButt</symbol></term> + <listitem> + <para> +The line is square at the endpoint (perpendicular to the slope of the line) +with no projection beyond. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><symbol>CapRound</symbol></term> + <listitem> + <para> +The line has a circular arc with the diameter equal to the line-width, +centered on the endpoint. +(This is equivalent to +<symbol>CapButt</symbol> +for line-width of zero). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><symbol>CapProjecting</symbol></term> + <listitem> + <para> +The line is square at the end, but the path continues beyond the endpoint +for a distance equal to half the line-width. +(This is equivalent to +<symbol>CapButt</symbol> +for line-width of zero). + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The join-style defines how corners are drawn for wide lines: +</para> + +<variablelist> + <varlistentry> + <term><symbol>JoinMiter</symbol></term> + <listitem> + <para> +The outer edges of two lines extend to meet at an angle. +However, if the angle is less than 11 degrees, +then a +<symbol>JoinBevel</symbol> +join-style is used instead. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><symbol>JoinRound</symbol></term> + <listitem> + <para> +The corner is a circular arc with the diameter equal to the line-width, +centered on the joinpoint. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><symbol>JoinBevel</symbol></term> + <listitem> + <para> +The corner has +<symbol>CapButt</symbol> +endpoint styles with the triangular notch filled. + </para> + </listitem> + </varlistentry> +</variablelist> + + +<para> +<!-- .LP --> +For a line with coincident endpoints (x1=x2, y1=y2), +when the cap-style is applied to both endpoints, +the semantics depends on the line-width and the cap-style: +</para> + +<informaltable> + <tgroup cols='3' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <tbody> + <row> + <entry><symbol>CapNotLast</symbol></entry> + <entry>thin</entry> + <entry>The results are device dependent, + but the desired effect is that nothing is drawn.</entry> + </row> + <row> + <entry><symbol>CapButt</symbol></entry> + <entry>thin</entry> + <entry>The results are device dependent, + but the desired effect is that a single pixel is drawn.</entry> + </row> + <row> + <entry><symbol>CapRound</symbol></entry> + <entry>thin</entry> + <entry>The results are the same as for + <symbol>CapButt</symbol> /thin.</entry> + </row> + <row> + <entry><symbol>CapProjecting</symbol></entry> + <entry>thin</entry> + <entry>The results are the same as for + <symbol>CapButt</symbol> /thin.</entry> + </row> + <row> + <entry><symbol>CapButt</symbol></entry> + <entry>wide</entry> + <entry>Nothing is drawn.</entry> + </row> + <row> + <entry><symbol>CapRound</symbol></entry> + <entry>wide</entry> + <entry>The closed path is a circle, centered at the endpoint, and + with the diameter equal to the line-width.</entry> + </row> + <row> + <entry><symbol>CapProjecting</symbol></entry> + <entry>wide</entry> + <entry>The closed path is a square, aligned with the coordinate axes, centered at the + endpoint, and with the sides equal to the line-width.</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +<!-- .LP --> +For a line with coincident endpoints (x1=x2, y1=y2), +when the join-style is applied at one or both endpoints, +the effect is as if the line was removed from the overall path. +However, if the total path consists of or is reduced to a single point joined +with itself, the effect is the same as when the cap-style is applied at both +endpoints. +</para> +<para> +<!-- .LP --> +The tile/stipple represents an infinite two-dimensional plane, +with the tile/stipple replicated in all dimensions. +When that plane is superimposed on the drawable +for use in a graphics operation, the upper-left corner +of some instance of the tile/stipple is at the coordinates within +the drawable specified by the tile/stipple origin. +The tile/stipple and clip origins are interpreted relative to the +origin of whatever destination drawable is specified in a graphics +request. +The tile pixmap must have the same root and depth as the GC, +or a +<errorname>BadMatch</errorname> +error results. +The stipple pixmap must have depth one and must have the same root as the +GC, or a +<errorname>BadMatch</errorname> +error results. +For stipple operations where the fill-style is +<symbol>FillStippled</symbol> +but not +<symbol>FillOpaqueStippled</symbol>, +the stipple pattern is tiled in a +single plane and acts as an additional clip mask to be ANDed with the clip-mask. +Although some sizes may be faster to use than others, +any size pixmap can be used for tiling or stippling. +</para> + +<para> +<!-- .LP --> +The fill-style defines the contents of the source for line, text, and +fill requests. +For all text and fill requests (for example, +<function>XDrawText</function>, +<function>XDrawText16</function>, +<function>XFillRectangle</function>, +<function>XFillPolygon</function>, +and +<function>XFillArc</function>); +for line requests +with line-style +<symbol>LineSolid</symbol> +(for example, +<function>XDrawLine</function>, +<function>XDrawSegments</function>, +<function>XDrawRectangle</function>, +<function>XDrawArc</function>); +and for the even dashes for line requests with line-style +<symbol>LineOnOffDash</symbol> +or +<symbol>LineDoubleDash</symbol>, +the following apply: +</para> + +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <tbody> + <row> + <entry><symbol>FillSolid</symbol></entry> + <entry>Foreground</entry> + </row> + <row> + <entry><symbol>FillTiled</symbol></entry> + <entry>Tile</entry> + </row> + <row> + <entry><symbol>FillOpaqueStippled</symbol></entry> + <entry>A tile with the same width and height as stipple, + but with background everywhere stipple has a zero + and with foreground everywhere stipple has a one</entry> + </row> + <row> + <entry><symbol>FillStippled</symbol></entry> + <entry>Foreground masked by stipple</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +<!-- .LP --> +When drawing lines with line-style +<symbol>LineDoubleDash</symbol>, +the odd dashes are controlled by the fill-style in the following manner: +</para> + +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <tbody> + <row> + <entry><symbol>FillSolid</symbol></entry> + <entry>Background</entry> + </row> + <row> + <entry><symbol>FillTiled</symbol></entry> + <entry>Same as for even dashes</entry> + </row> + <row> + <entry><symbol>FillOpaqueStippled</symbol></entry> + <entry>Same as for even dashes</entry> + </row> + <row> + <entry><symbol>FillStippled</symbol></entry> + <entry>Background masked by stipple</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +<!-- .LP --> +Storing a pixmap in a GC might or might not result in a copy +being made. +If the pixmap is later used as the destination for a graphics request, +the change might or might not be reflected in the GC. +If the pixmap is used simultaneously in a graphics request both as +a destination and as a tile or stipple, +the results are undefined. +</para> +<para> +<!-- .LP --> +For optimum performance, +you should draw as much as possible with the same GC +(without changing its components). +The costs of changing GC components relative to using different GCs +depend on the display hardware and the server implementation. +It is quite likely that some amount of GC information will be +cached in display hardware and that such hardware can only cache a small number +of GCs. +</para> +<para> +<!-- .LP --> +The dashes value is actually a simplified form of the +more general patterns that can be set with +<function>XSetDashes</function>. +Specifying a +value of N is equivalent to specifying the two-element list [N, N] in +<function>XSetDashes</function>. +The value must be nonzero, +or a +<errorname>BadValue</errorname> +error results. +</para> +<para> +<!-- .LP --> +The clip-mask restricts writes to the destination drawable. +If the clip-mask is set to a pixmap, +it must have depth one and have the same root as the GC, +or a +<errorname>BadMatch</errorname> +error results. +If clip-mask is set to +<symbol>None</symbol>, +the pixels are always drawn regardless of the clip origin. +The clip-mask also can be set by calling the +<function>XSetClipRectangles</function> +or +<function>XSetRegion</function> +functions. +Only pixels where the clip-mask has a bit set to 1 are drawn. +Pixels are not drawn outside the area covered by the clip-mask +or where the clip-mask has a bit set to 0. +The clip-mask affects all graphics requests. +The clip-mask does not clip sources. +The clip-mask origin is interpreted relative to the origin of whatever +destination drawable is specified in a graphics request. +</para> +<para> +<!-- .LP --> +You can set the subwindow-mode to +<symbol>ClipByChildren</symbol> +or +<symbol>IncludeInferiors</symbol>. +For +<symbol>ClipByChildren</symbol>, +both source and destination windows are +additionally clipped by all viewable +<symbol>InputOutput</symbol> +children. +For +<symbol>IncludeInferiors</symbol>, +neither source nor destination window is clipped by inferiors. +This will result in including subwindow contents in the source +and drawing through subwindow boundaries of the destination. +The use of +<symbol>IncludeInferiors</symbol> +on a window of one depth with mapped +inferiors of differing depth is not illegal, but the semantics are +undefined by the core protocol. +</para> +<para> +<!-- .LP --> +The fill-rule defines what pixels are inside (drawn) for +paths given in +<function>XFillPolygon</function> +requests and can be set to +<symbol>EvenOddRule</symbol> +or +<symbol>WindingRule</symbol>. +For +<symbol>EvenOddRule</symbol>, +a point is inside if +an infinite ray with the point as origin crosses the path an odd number +of times. +For +<symbol>WindingRule</symbol>, +a point is inside if an infinite ray with the +point as origin crosses an unequal number of clockwise and +counterclockwise directed path segments. +A clockwise directed path segment is one that crosses the ray from left to +right as observed from the point. +A counterclockwise segment is one that crosses the ray from right to left +as observed from the point. +The case where a directed line segment is coincident with the ray is +uninteresting because you can simply choose a different ray that is not +coincident with a segment. +</para> +<para> +<!-- .LP --> +For both +<symbol>EvenOddRule</symbol> +and +<symbol>WindingRule</symbol>, +a point is infinitely small, +and the path is an infinitely thin line. +A pixel is inside if the center point of the pixel is inside +and the center point is not on the boundary. +If the center point is on the boundary, +the pixel is inside if and only if the polygon interior is immediately to +its right (x increasing direction). +Pixels with centers on a horizontal edge are a special case +and are inside if and only if the polygon interior is immediately below +(y increasing direction). +</para> +<para> +<!-- .LP --> +The arc-mode controls filling in the +<function>XFillArcs</function> +function and can be set to +<symbol>ArcPieSlice</symbol> +or +<symbol>ArcChord</symbol>. +For +<symbol>ArcPieSlice</symbol>, +the arcs are pie-slice filled. +For +<symbol>ArcChord</symbol>, +the arcs are chord filled. +</para> +<para> +<!-- .LP --> +The graphics-exposure flag controls +<symbol>GraphicsExpose</symbol> +event generation +for +<function>XCopyArea</function> +and +<function>XCopyPlane</function> +requests (and any similar requests defined by extensions). +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To create a new GC that is usable on a given screen with a +depth of drawable, use +<function>XCreateGC</function>. +<indexterm><primary>Graphics context</primary><secondary>initializing</secondary></indexterm> +<indexterm significance="preferred"><primary>XCreateGC</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xcreategc'> +<funcprototype> + <funcdef>GC <function>XCreateGC</function></funcdef> + <paramdef>Display <parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef> + <paramdef>XGCValues *<parameter>values</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 Vm set using the information in the specified values structure --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>valuemask</emphasis> + </term> + <listitem> + <para> +Specifies which components in the GC are to be (Vm. +This argument is the bitwise inclusive OR of zero or more of the valid +GC component mask bits. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>values</emphasis> + </term> + <listitem> + <para> +Specifies any values as specified by the valuemask. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XCreateGC</function> +function creates a graphics context and returns a GC. +The GC can be used with any destination drawable having the same root +and depth as the specified drawable. +Use with other drawables results in a +<errorname>BadMatch</errorname> +error. +</para> +<para> +<!-- .LP --> +<function>XCreateGC</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadDrawable</errorname>, +<errorname>BadFont</errorname>, +<errorname>BadMatch</errorname>, +<errorname>BadPixmap</errorname>, +and +<errorname>BadValue</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To copy components from a source GC to a destination GC, use +<function>XCopyGC</function>. +<indexterm significance="preferred"><primary>XCopyGC</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xcopygc'> +<funcprototype> + <funcdef><function>XCopyGC</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GCsrc,<parameter> dest</parameter></paramdef> + <paramdef>unsignedlong<parameter> valuemask</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> +Specifies the components of the source GC. +<!-- .ds Vm copied to the destination GC --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>valuemask</emphasis> + </term> + <listitem> + <para> +Specifies which components in the GC are to be (Vm. +This argument is the bitwise inclusive OR of zero or more of the valid +GC component mask bits. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dest</emphasis> + </term> + <listitem> + <para> +Specifies the destination GC. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XCopyGC</function> +function copies the specified components from the source GC +to the destination GC. +The source and destination GCs must have the same root and depth, +or a +<errorname>BadMatch</errorname> +error results. +The valuemask specifies which component to copy, as for +<function>XCreateGC</function>. +</para> +<para> +<!-- .LP --> +<function>XCopyGC</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadMatch</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To change the components in a given GC, use +<function>XChangeGC</function>. +<indexterm significance="preferred"><primary>XChangeGC</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xchangegc'> +<funcprototype> + <funcdef><function>XChangeGC</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef> + <paramdef>XGCValues<parameter> *values</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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. +<!-- .ds Vm changed using information in the specified values structure --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>valuemask</emphasis> + </term> + <listitem> + <para> +Specifies which components in the GC are to be (Vm. +This argument is the bitwise inclusive OR of zero or more of the valid +GC component mask bits. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>values</emphasis> + </term> + <listitem> + <para> +Specifies any values as specified by the valuemask. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XChangeGC</function> +function changes the components specified by valuemask for +the specified GC. +The values argument contains the values to be set. +The values and restrictions are the same as for +<function>XCreateGC</function>. +Changing the clip-mask overrides any previous +<function>XSetClipRectangles</function> +request on the context. +Changing the dash-offset or dash-list +overrides any previous +<function>XSetDashes</function> +request on the context. +The order in which components are verified and altered is server dependent. +If an error is generated, a subset of the components may have been altered. +</para> +<para> +<!-- .LP --> +<function>XChangeGC</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadFont</errorname>, +<errorname>BadGC</errorname>, +<errorname>BadMatch</errorname>, +<errorname>BadPixmap</errorname>, +and +<errorname>BadValue</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To obtain components of a given GC, use +<function>XGetGCValues</function>. +<indexterm significance="preferred"><primary>XGetGCValues</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xgetgcvalues'> +<funcprototype> + <funcdef>Status <function>XGetGCValues</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef> + <paramdef>XGCValues<parameter> *values_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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. +<!-- .ds Vm returned in the values_return argument --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>valuemask</emphasis> + </term> + <listitem> + <para> +Specifies which components in the GC are to be (Vm. +This argument is the bitwise inclusive OR of zero or more of the valid +GC component mask bits. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>values_return</emphasis> + </term> + <listitem> + <para> +Returns the GC values in the specified +<structname>XGCValues</structname> +structure. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XGetGCValues</function> +function returns the components specified by valuemask for the specified GC. +If the valuemask contains a valid set of GC mask bits +(<symbol>GCFunction</symbol>, +<symbol>GCPlaneMask</symbol>, +<symbol>GCForeground</symbol>, +<symbol>GCBackground</symbol>, +<symbol>GCLineWidth</symbol>, +<symbol>GCLineStyle</symbol>, +<symbol>GCCapStyle</symbol>, +<symbol>GCJoinStyle</symbol>, +<symbol>GCFillStyle</symbol>, +<symbol>GCFillRule</symbol>, +<symbol>GCTile</symbol>, +<symbol>GCStipple</symbol>, +<symbol>GCTileStipXOrigin</symbol>, +<symbol>GCTileStipYOrigin</symbol>, +<symbol>GCFont</symbol>, +<symbol>GCSubwindowMode</symbol>, +<symbol>GCGraphicsExposures</symbol>, +<symbol>GCClipXOrigin</symbol>, +<symbol>GCClipYOrigin</symbol>, +<symbol>GCDashOffset</symbol>, +or +<symbol>GCArcMode</symbol>) +and no error occurs, +<function>XGetGCValues</function> +sets the requested components in values_return and returns a nonzero status. +Otherwise, it returns a zero status. +Note that the clip-mask and dash-list (represented by the +<symbol>GCClipMask</symbol> +and +<symbol>GCDashList</symbol> +bits, respectively, in the valuemask) +cannot be requested. +Also note that an invalid resource ID (with one or more of the three +most significant bits set to 1) will be returned for +<symbol>GCFont</symbol>, +<symbol>GCTile</symbol>, +and +<symbol>GCStipple</symbol> +if the component has never been explicitly set by the client. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To free a given GC, use +<function>XFreeGC</function>. +<indexterm significance="preferred"><primary>XFreeGC</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xfreegc'> +<funcprototype> + <funcdef><function>XFreeGC</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XFreeGC</function> +function destroys the specified GC as well as all the associated storage. +</para> +<para> +<!-- .LP --> +<function>XFreeGC</function> +can generate a +<errorname>BadGC</errorname> +error. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To obtain the +<type>GContext</type> +resource ID for a given GC, use +<function>XGContextFromGC</function>. +<indexterm significance="preferred"><primary>XGContextFromGC</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xgcontextfromgc'> +<funcprototype> + <funcdef>GContext <function>XGContextFromGC</function></funcdef> + <paramdef>GC<parameter> gc</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<!-- .ds Gc for which you want the resource ID --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC (Gc. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<!-- .sp --> +Xlib usually defers sending changes to the components of a GC to the server +until a graphics function is actually called with that GC. +This permits batching of component changes into a single server request. +In some circumstances, however, it may be necessary for the client +to explicitly force sending the changes to the server. +An example might be when a protocol extension uses the GC indirectly, +in such a way that the extension interface cannot know what GC will be used. +To force sending GC component changes, use +<function>XFlushGC</function>. +<indexterm significance="preferred"><primary>XFlushGC</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xflushgc'> +<funcprototype> + <funcdef>void <function>XFlushGC</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +</para> +</sect1> +<sect1 id="Using_Graphics_Context_Convenience_Routines"> +<title>Using Graphics Context Convenience Routines</title> +<!-- .XS --> +<!-- (SN Using Graphics Context Convenience Routines --> +<!-- .XE --> +<para> +<!-- .LP --> +This section discusses how to set the: +</para> +<itemizedlist> + <listitem> + <para> +Foreground, background, plane mask, or function components + </para> + </listitem> + <listitem> + <para> +Line attributes and dashes components + </para> + </listitem> + <listitem> + <para> +Fill style and fill rule components + </para> + </listitem> + <listitem> + <para> +Fill tile and stipple components + </para> + </listitem> + <listitem> + <para> +Font component + </para> + </listitem> + <listitem> + <para> +Clip region component + </para> + </listitem> + <listitem> + <para> +Arc mode, subwindow mode, and graphics exposure components + </para> + </listitem> +</itemizedlist> +<sect2 id="Setting_the_Foreground_Background_Function_or_Plane_Mask"> +<title>Setting the Foreground, Background, Function, or Plane Mask</title> +<!-- .XS --> +<!-- (SN Setting the Foreground, Background, Function, or Plane Mask --> +<!-- .XE --> +<para> +<!-- .LP --> +To set the foreground, background, plane mask, and function components +for a given GC, use +<function>XSetState</function>. +<indexterm significance="preferred"><primary>XSetState</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetstate'> +<funcprototype> + <funcdef><function>XSetState</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>unsignedlongforeground,<parameter> background</parameter></paramdef> + <paramdef>int<parameter> function</parameter></paramdef> + <paramdef>unsignedlong<parameter> plane_mask</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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>foreground</emphasis> + </term> + <listitem> + <para> +Specifies the foreground you want to set for the specified GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>background</emphasis> + </term> + <listitem> + <para> +Specifies the background you want to set for the specified GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>function</emphasis> + </term> + <listitem> + <para> +Specifies the function you want to set for the specified GC. + </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> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XSetState</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadValue</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set the foreground of a given GC, use +<function>XSetForeground</function>. +<indexterm significance="preferred"><primary>XSetForeground</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetforeground'> +<funcprototype> + <funcdef><function>XSetForeground</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>unsignedlong<parameter> foreground</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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>foreground</emphasis> + </term> + <listitem> + <para> +Specifies the foreground you want to set for the specified GC. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XSetForeground</function> +can generate +<errorname>BadAlloc</errorname> +and +<errorname>BadGC</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set the background of a given GC, use +<function>XSetBackground</function>. +<indexterm significance="preferred"><primary>XSetBackground</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetbackground'> +<funcprototype> + <funcdef><function>XSetBackground</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>unsignedlong<parameter> background</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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>background</emphasis> + </term> + <listitem> + <para> +Specifies the background you want to set for the specified GC. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XSetBackground</function> +can generate +<errorname>BadAlloc</errorname> +and +<errorname>BadGC</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set the display function in a given GC, use +<function>XSetFunction</function>. +<indexterm significance="preferred"><primary>XSetFunction</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetfunction'> +<funcprototype> + <funcdef><function>XSetFunction</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>int<parameter> function</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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>function</emphasis> + </term> + <listitem> + <para> +Specifies the function you want to set for the specified GC. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XSetFunction</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadValue</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set the plane mask of a given GC, use +<function>XSetPlaneMask</function>. +<indexterm significance="preferred"><primary>XSetPlaneMask</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetplanemask'> +<funcprototype> + <funcdef><function>XSetPlaneMask</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>unsignedlong<parameter> plane_mask</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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </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> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XSetPlaneMask</function> +can generate +<errorname>BadAlloc</errorname> +and +<errorname>BadGC</errorname> +errors. +</para> +</sect2> +<sect2 id="Setting_the_Line_Attributes_and_Dashes"> +<title>Setting the Line Attributes and Dashes</title> +<!-- .XS --> +<!-- (SN Setting the Line Attributes and Dashes --> +<!-- .XE --> +<para> +<!-- .LP --> +To set the line drawing components of a given GC, use +<function>XSetLineAttributes</function>. +<indexterm significance="preferred"><primary>XSetLineAttributes</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetlineattributes'> +<funcprototype> + <funcdef><function>XSetLineAttributes</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>unsignedint<parameter> line_width</parameter></paramdef> + <paramdef>int<parameter> line_style</parameter></paramdef> + <paramdef>int<parameter> cap_style</parameter></paramdef> + <paramdef>int<parameter> join_style</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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>line_width</emphasis> + </term> + <listitem> + <para> +Specifies the line-width you want to set for the specified GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>line_style</emphasis> + </term> + <listitem> + <para> +Specifies the line-style you want to set for the specified GC. +You can pass +<symbol>LineSolid</symbol>, +<symbol>LineOnOffDash</symbol>, +or +<symbol>LineDoubleDash</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>cap_style</emphasis> + </term> + <listitem> + <para> +Specifies the line-style and cap-style you want to set for the specified GC. +You can pass +<symbol>CapNotLast</symbol>, +<symbol>CapButt</symbol>, +<symbol>CapRound</symbol>, +or +<symbol>CapProjecting</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>join_style</emphasis> + </term> + <listitem> + <para> +Specifies the line join-style you want to set for the specified GC. +You can pass +<symbol>JoinMiter</symbol>, +<symbol>JoinRound</symbol>, +or +<symbol>JoinBevel</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XSetLineAttributes</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadValue</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set the dash-offset and dash-list for dashed line styles of a given GC, use +<function>XSetDashes</function>. +<indexterm significance="preferred"><primary>XSetDashes</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetdashes'> +<funcprototype> + <funcdef><function>XSetDashes</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>int<parameter> dash_offset</parameter></paramdef> + <paramdef>char<parameter> dash_list[]</parameter></paramdef> + <paramdef>int<parameter> n</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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dash_offset</emphasis> + </term> + <listitem> + <para> +Specifies the phase of the pattern for the dashed line-style you want to set +for the specified GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dash_list</emphasis> + </term> + <listitem> + <para> +Specifies the dash-list for the dashed line-style +you want to set for the specified GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>n</emphasis> + </term> + <listitem> + <para> +Specifies the number of elements in dash_list. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XSetDashes</function> +function sets the dash-offset and dash-list attributes for dashed line styles +in the specified GC. +There must be at least one element in the specified dash_list, +or a +<errorname>BadValue</errorname> +error results. +The initial and alternating elements (second, fourth, and so on) +of the dash_list are the even dashes, and +the others are the odd dashes. +Each element specifies a dash length in pixels. +All of the elements must be nonzero, +or a +<errorname>BadValue</errorname> +error results. +Specifying an odd-length list is equivalent to specifying the same list +concatenated with itself to produce an even-length list. +</para> +<para> +<!-- .LP --> +The dash-offset defines the phase of the pattern, +specifying how many pixels into the dash-list the pattern +should actually begin in any single graphics request. +Dashing is continuous through path elements combined with a join-style +but is reset to the dash-offset between each sequence of joined lines. +</para> +<para> +<!-- .LP --> +The unit of measure for dashes is the same for the ordinary coordinate system. +Ideally, a dash length is measured along the slope of the line, but implementations +are only required to match this ideal for horizontal and vertical lines. +Failing the ideal semantics, it is suggested that the length be measured along the +major axis of the line. +The major axis is defined as the x axis for lines drawn at an angle of between +−45 and +45 degrees or between 135 and 225 degrees from the x axis. +For all other lines, the major axis is the y axis. +</para> +<para> +<!-- .LP --> +<function>XSetDashes</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadValue</errorname> +errors. +</para> +</sect2> +<sect2 id="Setting_the_Fill_Style_and_Fill_Rule_"> +<title>Setting the Fill Style and Fill Rule </title> +<!-- .XS --> +<!-- (SN Setting the Fill Style and Fill Rule --> +<!-- .XE --> +<para> +<!-- .LP --> +To set the fill-style of a given GC, use +<function>XSetFillStyle</function>. +<indexterm significance="preferred"><primary>XSetFillStyle</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetfillstyle'> +<funcprototype> + <funcdef><function>XSetFillStyle</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>int<parameter> fill_style</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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>fill_style</emphasis> + </term> + <listitem> + <para> +Specifies the fill-style you want to set for the specified GC. +You can pass +<symbol>FillSolid</symbol>, +<symbol>FillTiled</symbol>, +<symbol>FillStippled</symbol>, +or +<symbol>FillOpaqueStippled</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XSetFillStyle</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadValue</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set the fill-rule of a given GC, use +<function>XSetFillRule</function>. +<indexterm significance="preferred"><primary>XSetFillRule</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetfillrule'> +<funcprototype> + <funcdef><function>XSetFillRule</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>int<parameter> fill_rule</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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>fill_rule</emphasis> + </term> + <listitem> + <para> +Specifies the fill-rule you want to set for the specified GC. +You can pass +<symbol>EvenOddRule</symbol> +or +<symbol>WindingRule</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XSetFillRule</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadValue</errorname> +errors. +</para> +</sect2> +<sect2 id="Setting_the_Fill_Tile_and_Stipple_"> +<title>Setting the Fill Tile and Stipple </title> +<!-- .XS --> +<!-- (SN Setting the Fill Tile and Stipple --> +<!-- .XE --> +<para> +<!-- .LP --> +Some displays have hardware support for tiling or +stippling with patterns of specific sizes. +Tiling and stippling operations that restrict themselves to those specific +sizes run much faster than such operations with arbitrary size patterns. +Xlib provides functions that you can use to determine the best size, +tile, or stipple for the display +as well as to set the tile or stipple shape and the tile or stipple origin. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To obtain the best size of a tile, stipple, or cursor, use +<function>XQueryBestSize</function>. +<indexterm significance="preferred"><primary>XQueryBestSize</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xquerybestsize'> +<funcprototype> + <funcdef>Status <function>XQueryBestSize</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>int<parameter> class</parameter></paramdef> + <paramdef>Drawable<parameter> which_screen</parameter></paramdef> + <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef> + <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>class</emphasis> + </term> + <listitem> + <para> +Specifies the class that you are interested in. +You can pass +<symbol>TileShape</symbol>, +<symbol>CursorShape</symbol>, +or +<symbol>StippleShape</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>which_screen</emphasis> + </term> + <listitem> + <para> +Specifies any drawable on the screen. + </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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>width_return</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>height_return</emphasis> + </term> + <listitem> + <para> +Return the width and height of the object best supported +by the display hardware. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XQueryBestSize</function> +function returns the best or closest size to the specified size. +For +<symbol>CursorShape</symbol>, +this is the largest size that can be fully displayed on the screen specified by +which_screen. +For +<symbol>TileShape</symbol>, +this is the size that can be tiled fastest. +For +<symbol>StippleShape</symbol>, +this is the size that can be stippled fastest. +For +<symbol>CursorShape</symbol>, +the drawable indicates the desired screen. +For +<symbol>TileShape</symbol> +and +<symbol>StippleShape</symbol>, +the drawable indicates the screen and possibly the window class and depth. +An +<symbol>InputOnly</symbol> +window cannot be used as the drawable for +<symbol>TileShape</symbol> +or +<symbol>StippleShape</symbol>, +or a +<errorname>BadMatch</errorname> +error results. +</para> +<para> +<!-- .LP --> +<function>XQueryBestSize</function> +can generate +<errorname>BadDrawable</errorname>, +<errorname>BadMatch</errorname>, +and +<errorname>BadValue</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To obtain the best fill tile shape, use +<function>XQueryBestTile</function>. +<indexterm significance="preferred"><primary>XQueryBestTile</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xquerybesttile'> +<funcprototype> + <funcdef>Status <function>XQueryBestTile</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> which_screen</parameter></paramdef> + <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef> + <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>which_screen</emphasis> + </term> + <listitem> + <para> +Specifies any drawable on the screen. + </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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>width_return</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>height_return</emphasis> + </term> + <listitem> + <para> +Return the width and height of the object best supported +by the display hardware. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XQueryBestTile</function> +function returns the best or closest size, that is, the size that can be +tiled fastest on the screen specified by which_screen. +The drawable indicates the screen and possibly the window class and depth. +If an +<symbol>InputOnly</symbol> +window is used as the drawable, a +<errorname>BadMatch</errorname> +error results. +</para> +<para> +<!-- .LP --> +<function>XQueryBestTile</function> +can generate +<errorname>BadDrawable</errorname> +and +<errorname>BadMatch</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To obtain the best stipple shape, use +<function>XQueryBestStipple</function>. +<indexterm significance="preferred"><primary>XQueryBestStipple</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xquerybeststipple'> +<funcprototype> + <funcdef>Status <function>XQueryBestStipple</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> which_screen</parameter></paramdef> + <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef> + <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>which_screen</emphasis> + </term> + <listitem> + <para> +Specifies any drawable on the screen. + </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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>width_return</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>height_return</emphasis> + </term> + <listitem> + <para> +Return the width and height of the object best supported +by the display hardware. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XQueryBestStipple</function> +function returns the best or closest size, that is, the size that can be +stippled fastest on the screen specified by which_screen. +The drawable indicates the screen and possibly the window class and depth. +If an +<symbol>InputOnly</symbol> +window is used as the drawable, a +<errorname>BadMatch</errorname> +error results. +</para> +<para> +<!-- .LP --> +<function>XQueryBestStipple</function> +can generate +<errorname>BadDrawable</errorname> +and +<errorname>BadMatch</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set the fill tile of a given GC, use +<function>XSetTile</function>. +<indexterm significance="preferred"><primary>XSetTile</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsettile'> +<funcprototype> + <funcdef><function>XSetTile</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>Pixmap<parameter> tile</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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>tile</emphasis> + </term> + <listitem> + <para> +Specifies the fill tile you want to set for the specified GC. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The tile and GC must have the same depth, +or a +<errorname>BadMatch</errorname> +error results. +</para> +<para> +<!-- .LP --> +<function>XSetTile</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadGC</errorname>, +<errorname>BadMatch</errorname>, +and +<errorname>BadPixmap</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set the stipple of a given GC, use +<function>XSetStipple</function>. +<indexterm significance="preferred"><primary>XSetStipple</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetstipple'> +<funcprototype> + <funcdef><function>XSetStipple</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>Pixmap<parameter> stipple</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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>stipple</emphasis> + </term> + <listitem> + <para> +Specifies the stipple you want to set for the specified GC. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The stipple must have a depth of one, +or a +<errorname>BadMatch</errorname> +error results. +</para> +<para> +<!-- .LP --> +<function>XSetStipple</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadGC</errorname>, +<errorname>BadMatch</errorname>, +and +<errorname>BadPixmap</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set the tile or stipple origin of a given GC, use +<function>XSetTSOrigin</function>. +<indexterm significance="preferred"><primary>XSetTSOrigin</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsettsorigin'> +<funcprototype> + <funcdef><function>XSetTSOrigin</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intts_x_origin,<parameter> ts_y_origin</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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>ts_x_origin</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>ts_y_origin</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates of the tile and stipple origin. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +When graphics requests call for tiling or stippling, +the parent's origin will be interpreted relative to whatever destination +drawable is specified in the graphics request. +</para> +<para> +<!-- .LP --> +<function>XSetTSOrigin</function> +can generate +<errorname>BadAlloc</errorname> +and +<errorname>BadGC</errorname> +errors. +</para> +</sect2> +<sect2 id="Setting_the_Current_Font_"> +<title>Setting the Current Font </title> +<!-- .XS --> +<!-- (SN Setting the Current Font --> +<!-- .XE --> +<para> +<!-- .LP --> +To set the current font of a given GC, use +<function>XSetFont</function>. +<indexterm significance="preferred"><primary>XSetFont</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetfont'> +<funcprototype> + <funcdef><function>XSetFont</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>font</emphasis> + </term> + <listitem> + <para> +Specifies the font. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XSetFont</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadFont</errorname>, +and +<errorname>BadGC</errorname> +errors. +</para> +</sect2> +<sect2 id="Setting_the_Clip_Region"> +<title>Setting the Clip Region</title> +<!-- .XS --> +<!-- (SN Setting the Clip Region --> +<!-- .XE --> +<para> +<!-- .LP --> +Xlib provides functions that you can use to set the clip-origin +and the clip-mask or set the clip-mask to a list of rectangles. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set the clip-origin of a given GC, use +<function>XSetClipOrigin</function>. +<indexterm significance="preferred"><primary>XSetClipOrigin</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetcliporigin'> +<funcprototype> + <funcdef><function>XSetClipOrigin</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intclip_x_origin,<parameter> clip_y_origin</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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>clip_x_origin</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>clip_y_origin</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates of the clip-mask origin. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The clip-mask origin is interpreted relative to the origin of whatever +destination drawable is specified in the graphics request. +</para> +<para> +<!-- .LP --> +<function>XSetClipOrigin</function> +can generate +<errorname>BadAlloc</errorname> +and +<errorname>BadGC</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set the clip-mask of a given GC to the specified pixmap, use +<function>XSetClipMask</function>. +<indexterm significance="preferred"><primary>XSetClipMask</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetclipmask'> +<funcprototype> + <funcdef><function>XSetClipMask</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>Pixmap<parameter> pixmap</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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>pixmap</emphasis> + </term> + <listitem> + <para> +Specifies the pixmap or +<symbol>None</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +If the clip-mask is set to +<symbol>None</symbol>, +the pixels are always drawn (regardless of the clip-origin). +</para> +<para> +<!-- .LP --> +<function>XSetClipMask</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadGC</errorname>, +<errorname>BadMatch</errorname>, +and +<errorname>BadPixmap</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set the clip-mask of a given GC to the specified list of rectangles, use +<function>XSetClipRectangles</function>. +<indexterm significance="preferred"><primary>XSetClipRectangles</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetcliprectangles'> +<funcprototype> + <funcdef><function>XSetClipRectangles</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intclip_x_origin,<parameter> clip_y_origin</parameter></paramdef> + <paramdef>XRectangle<parameter> rectangles[]</parameter></paramdef> + <paramdef>int<parameter> n</parameter></paramdef> + <paramdef>int<parameter> ordering</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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>clip_x_origin</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>clip_y_origin</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates of the clip-mask origin. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>rectangles</emphasis> + </term> + <listitem> + <para> +Specifies an array of rectangles that define the clip-mask. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>n</emphasis> + </term> + <listitem> + <para> +Specifies the number of rectangles. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>ordering</emphasis> + </term> + <listitem> + <para> +Specifies the ordering relations on the rectangles. +You can pass +<symbol>Unsorted</symbol>, +<symbol>YSorted</symbol>, +<symbol>YXSorted</symbol>, +or +<symbol>YXBanded</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XSetClipRectangles</function> +function changes the clip-mask in the specified GC +to the specified list of rectangles and sets the clip origin. +The output is clipped to remain contained within the +rectangles. +The clip-origin is interpreted relative to the origin of +whatever destination drawable is specified in a graphics request. +The rectangle coordinates are interpreted relative to the clip-origin. +The rectangles should be nonintersecting, or the graphics results will be +undefined. +Note that the list of rectangles can be empty, +which effectively disables output. +This is the opposite of passing +<symbol>None</symbol> +as the clip-mask in +<function>XCreateGC</function>, +<function>XChangeGC</function>, +and +<function>XSetClipMask</function>. +</para> +<para> +<!-- .LP --> +If known by the client, ordering relations on the rectangles can be +specified with the ordering argument. +This may provide faster operation +by the server. +If an incorrect ordering is specified, the X server may generate a +<errorname>BadMatch</errorname> +error, but it is not required to do so. +If no error is generated, the graphics +results are undefined. +<symbol>Unsorted</symbol> +means the rectangles are in arbitrary order. +<symbol>YSorted</symbol> +means that the rectangles are nondecreasing in their Y origin. +<symbol>YXSorted</symbol> +additionally constrains +<symbol>YSorted</symbol> +order in that all +rectangles with an equal Y origin are nondecreasing in their X +origin. +<symbol>YXBanded</symbol> +additionally constrains +<symbol>YXSorted</symbol> +by requiring that, +for every possible Y scanline, all rectangles that include that +scanline have an identical Y origins and Y extents. +</para> +<para> +<!-- .LP --> +<function>XSetClipRectangles</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadGC</errorname>, +<errorname>BadMatch</errorname>, +and +<errorname>BadValue</errorname> +errors. +</para> +<para> +<!-- .LP --> +Xlib provides a set of basic functions for performing +region arithmetic. +For information about these functions, +see section 16.5. +</para> +</sect2> +<sect2 id="Setting_the_Arc_Mode_Subwindow_Mode_and_Graphics_Exposure_"> +<title>Setting the Arc Mode, Subwindow Mode, and Graphics Exposure </title> +<!-- .XS --> +<!-- (SN Setting the Arc Mode, Subwindow Mode, and Graphics Exposure --> +<!-- .XE --> +<para> +<!-- .LP --> +To set the arc mode of a given GC, use +<function>XSetArcMode</function>. +<indexterm significance="preferred"><primary>XSetArcMode</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetarcmode'> +<funcprototype> + <funcdef><function>XSetArcMode</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>int<parameter> arc_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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>arc_mode</emphasis> + </term> + <listitem> + <para> +Specifies the arc mode. +You can pass +<symbol>ArcChord</symbol> +or +<symbol>ArcPieSlice</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XSetArcMode</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadValue</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set the subwindow mode of a given GC, use +<function>XSetSubwindowMode</function>. +<indexterm significance="preferred"><primary>XSetSubwindowMode</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetsubwindowmode'> +<funcprototype> + <funcdef><function>XSetSubwindowMode</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>int<parameter> subwindow_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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>subwindow_mode</emphasis> + </term> + <listitem> + <para> +Specifies the subwindow mode. +You can pass +<symbol>ClipByChildren</symbol> +or +<symbol>IncludeInferiors</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XSetSubwindowMode</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadValue</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set the graphics-exposures flag of a given GC, use +<function>XSetGraphicsExposures</function>. +<indexterm significance="preferred"><primary>XSetGraphicsExposures</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetgraphicsexposures'> +<funcprototype> + <funcdef><function>XSetGraphicsExposures</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>Bool<parameter> graphics_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'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>graphics_exposures</emphasis> + </term> + <listitem> + <para> +Specifies a Boolean value that indicates whether you want +<symbol>GraphicsExpose</symbol> +and +<symbol>NoExpose</symbol> +events to be reported when calling +<function>XCopyArea</function> +and +<function>XCopyPlane</function> +with this GC. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XSetGraphicsExposures</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadGC</errorname>, +and +<errorname>BadValue</errorname> +errors. +<!-- .bp --> + +</para> +</sect2> +</sect1> +</chapter> |