specs/libX11/CH07.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3           "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
   4 <chapter id='Graphics_Context_Functions'>
   5 <title>Graphics Context Functions</title>
   6
   7 <para>
   8 A number of resources are used when performing graphics operations in X. Most information
   9 about performing graphics (for example, foreground color, background color, line style, and so
  10 on) is stored in resources called graphics contexts (GCs). Most graphics operations (see chapter
  11 8) take a GC as an argument. Although in theory the X protocol permits sharing of GCs between
  12 applications, it is expected that applications will use their own GCs when performing operations.
  13 Sharing of GCs is highly discouraged because the library may cache GC state.
  14 </para>
  15 <para>
  16 Graphics operations can be performed to either windows or pixmaps, which collectively are
  17 called drawables. Each drawable exists on a single screen. A GC is created for a specific screen
  18 and drawable depth and can only be used with drawables of matching screen and depth.
  19 </para>
  20 <para>
  21 This chapter discusses how to:
  22 </para>
  23 <itemizedlist>
  24   <listitem><para>Manipulate graphics context/state</para></listitem>
  25   <listitem><para>Use graphics context convenience functions</para></listitem>
  26 </itemizedlist>
  27
  28 <sect1 id='Manipulating_Graphics_ContextState'>
  29 <title>Manipulating Graphics Context/State</title>
  30 <!-- .XS -->
  31 <!-- (SN Manipulating Graphics Context/State  -->
  32 <!-- .XE -->
  33 <para>
  34 <!-- .LP -->
  35 Most attributes of graphics operations are stored in GCs.
  36 These include line width, line style, plane mask, foreground, background,
  37 tile, stipple, clipping region, end style, join style, and so on.
  38 Graphics operations (for example, drawing lines) use these values
  39 to determine the actual drawing operation.
  40 Extensions to X may add additional components to GCs.
  41 The contents of a GC are private to Xlib.
  42 </para>
  43 <para>
  44 <!-- .LP -->
  45 Xlib implements a write-back cache for all elements of a GC that are not
  46 resource IDs to allow Xlib to implement the transparent coalescing of changes
  47 to GCs.
  48 For example,
  49 a call to
  50 <xref linkend='XSetForeground' xrefstyle='select: title'/>
  51 of a GC followed by a call to
  52 <xref linkend='XSetLineAttributes' xrefstyle='select: title'/>
  53 results in only a single-change GC protocol request to the server.
  54 GCs are neither expected nor encouraged to be shared between client
  55 applications, so this write-back caching should present no problems.
  56 Applications cannot share GCs without external synchronization.
  57 Therefore,
  58 sharing GCs between applications is highly discouraged.
  59 </para>
  60 <para>
  61 <!-- .LP -->
  62 To set an attribute of a GC,
  63 set the appropriate member of the
  64 <structname>XGCValues</structname>
  65 structure and OR in the corresponding value bitmask in your subsequent calls to
  66 <xref linkend='XCreateGC' xrefstyle='select: title'/>.
  67 The symbols for the value mask bits and the
  68 <structname>XGCValues</structname>
  69 structure are:
  70 <!-- .sM -->
  71 </para>
  72
  73
  74 <literallayout class="monospaced">
  75 /* GC attribute value mask bits */
  76
  77 #define     GCFunction              (1L&lt;&lt;0)
  78 #define     GCPlaneMask             (1L&lt;&lt;1)
  79 #define     GCForeground            (1L&lt;&lt;2)
  80 #define     GCBackground            (1L&lt;&lt;3)
  81 #define     GCLineWidth             (1L&lt;&lt;4)
  82 #define     GCLineStyle             (1L&lt;&lt;5)
  83 #define     GCCapStyle              (1L&lt;&lt;6)
  84 #define     GCJoinStyle             (1L&lt;&lt;7)
  85 #define     GCFillStyle             (1L&lt;&lt;8)
  86 #define     GCFillRule              (1L&lt;&lt;9)
  87 #define     GCTile                  (1L&lt;&lt;10)
  88 #define     GCStipple               (1L&lt;&lt;11)
  89 #define     GCTileStipXOrigin       (1L&lt;&lt;12)
  90 #define     GCTileStipYOrigin       (1L&lt;&lt;13)
  91 #define     GCFont                  (1L&lt;&lt;14)
  92 #define     GCSubwindowMode         (1L&lt;&lt;15)
  93 #define     GCGraphicsExposures     (1L&lt;&lt;16)
  94 #define     GCClipXOrigin           (1L&lt;&lt;17)
  95 #define     GCClipYOrigin           (1L&lt;&lt;18)
  96 #define     GCClipMask              (1L&lt;&lt;19)
  97 #define     GCDashOffset            (1L&lt;&lt;20)
  98 #define     GCDashList              (1L&lt;&lt;21)
  99 #define     GCArcMode               (1L&lt;&lt;22)
 100 </literallayout>
 101
 102 <literallayout class="monospaced">
 103 <!-- .TA .5i 3i -->
 104 <!-- .ta .5i 3i -->
 105 /* Values */
 106
 107 typedef struct {
 108      int function;                 /* logical operation */
 109      unsigned long plane_mask;     /* plane mask */
 110      unsigned long foreground;     /* foreground pixel */
 111      unsigned long background;     /* background pixel */
 112      int line_width;               /* line width (in pixels) */
 113      int line_style;               /* LineSolid, LineOnOffDash, LineDoubleDash */
 114      int cap_style;                /* CapNotLast, CapButt, CapRound, CapProjecting */
 115      int join_style;               /* JoinMiter, JoinRound, JoinBevel */
 116      int fill_style;               /* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/
 117      int fill_rule;                /* EvenOddRule, WindingRule */
 118      int arc_mode;                 /* ArcChord, ArcPieSlice */
 119      Pixmap tile;                  /* tile pixmap for tiling operations */
 120      Pixmap stipple;               /* stipple 1 plane pixmap for stippling */
 121      int ts_x_origin;              /* offset for tile or stipple operations */
 122      int ts_y_origin
 123      Font font;                    /* default text font for text operations */
 124      int subwindow_mode;           /* ClipByChildren, IncludeInferiors */
 125      Bool graphics_exposures;      /* boolean, should exposures be generated */
 126      int clip_x_origin;            /* origin for clipping */
 127      int clip_y_origin;
 128      Pixmap clip_mask;             /* bitmap clipping; other calls for rects */
 129      int dash_offset;              /* patterned/dashed line information */
 130      char dashes;
 131 } XGCValues;
 132 </literallayout>
 133
 134 <para>
 135 <!-- .LP -->
 136 <!-- .eM  -->
 137 The default GC values are:
 138 </para>
 139 <informaltable frame='topbot'>
 140   <?dbfo keep-together="auto" ?>
 141   <tgroup cols='2' align='left' colsep='0' rowsep='0'>
 142   <colspec colname='c1' colwidth='1.0*'/>
 143   <colspec colname='c2' colwidth='1.0*'/>
 144   <thead>
 145     <row rowsep='1'>
 146       <entry>Component</entry>
 147       <entry>Default</entry>
 148     </row>
 149   </thead>
 150   <tbody>
 151     <row>
 152       <entry>function</entry>
 153       <entry><symbol>GXcopy</symbol></entry>
 154     </row>
 155     <row>
 156       <entry>plane_mask</entry>
 157       <entry>All ones</entry>
 158     </row>
 159     <row>
 160       <entry>foreground</entry>
 161       <entry>0</entry>
 162     </row>
 163     <row>
 164       <entry>background</entry>
 165       <entry>1</entry>
 166     </row>
 167     <row>
 168       <entry>line_width</entry>
 169       <entry>0</entry>
 170     </row>
 171     <row>
 172       <entry>line_style</entry>
 173       <entry><symbol>LineSolid</symbol></entry>
 174     </row>
 175     <row>
 176       <entry>cap_style</entry>
 177       <entry><symbol>CapButt</symbol></entry>
 178     </row>
 179     <row>
 180       <entry>join_style</entry>
 181       <entry><symbol>JoinMiter</symbol></entry>
 182     </row>
 183     <row>
 184       <entry>fill_style</entry>
 185       <entry><symbol>FillSolid</symbol></entry>
 186     </row>
 187     <row>
 188       <entry>fill_rule</entry>
 189       <entry><symbol>EvenOddRule</symbol></entry>
 190     </row>
 191     <row>
 192       <entry>arc_mode</entry>
 193       <entry><symbol>ArcPieSlice</symbol></entry>
 194     </row>
 195     <row>
 196       <entry>tile</entry>
 197       <entry>
 198       <para>Pixmap of unspecified size filled with foreground pixel</para>
 199       <para>(that is, client specified pixel if any, else 0)</para>
 200       <para>(subsequent changes to foreground do not affect this pixmap)</para>
 201       </entry>
 202     </row>
 203     <row>
 204       <entry>stipple</entry>
 205       <entry>Pixmap of unspecified size filled with ones</entry>
 206     </row>
 207     <row>
 208       <entry>ts_x_origin</entry>
 209       <entry>0</entry>
 210     </row>
 211     <row>
 212       <entry>ts_y_origin</entry>
 213       <entry>0</entry>
 214     </row>
 215     <row>
 216       <entry>font</entry>
 217       <entry>&lt;implementation dependent&gt;</entry>
 218     </row>
 219     <row>
 220       <entry>subwindow_mode</entry>
 221       <entry><symbol>ClipByChildren</symbol></entry>
 222     </row>
 223     <row>
 224       <entry>graphics_exposures</entry>
 225       <entry><symbol>True</symbol></entry>
 226     </row>
 227     <row>
 228       <entry>clip_x_origin</entry>
 229       <entry>0</entry>
 230     </row>
 231     <row>
 232       <entry>clip_y_origin</entry>
 233       <entry>0</entry>
 234     </row>
 235     <row>
 236       <entry>clip_mask</entry>
 237       <entry><symbol>None</symbol></entry>
 238     </row>
 239     <row>
 240       <entry>dash_offset</entry>
 241       <entry>0</entry>
 242     </row>
 243     <row>
 244       <entry>dashes</entry>
 245       <entry>4 (that is, the list [4, 4])</entry>
 246     </row>
 247   </tbody>
 248   </tgroup>
 249 </informaltable>
 250
 251 <para>
 252 <!-- .LP -->
 253 Note that foreground and background are not set to any values likely
 254 to be useful in a window.
 255 </para>
 256
 257 <para>
 258 <!-- .LP -->
 259 <indexterm significance="preferred"><primary>Display Functions</primary></indexterm>
 260 <indexterm significance="preferred"><primary>Source</primary></indexterm>
 261 <indexterm significance="preferred"><primary>Destination</primary></indexterm>
 262 The function attributes of a GC are used when you update a section of
 263 a drawable (the destination) with bits from somewhere else (the source).
 264 The function in a GC defines how the new destination bits are to be
 265 computed from the source bits and the old destination bits.
 266 <symbol>GXcopy</symbol>
 267 is typically the most useful because it will work on a color display,
 268 but special applications may use other functions,
 269 particularly in concert with particular planes of a color display.
 270 The 16 GC functions, defined in
 271 <filename class="headerfile">&lt;X11/X.h&gt;</filename>,
 272 <indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm>
 273 <indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/X.h&gt;</filename></secondary></indexterm>
 274 <indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/X.h&gt;</filename></secondary></indexterm>
 275 are:
 276 </para>
 277 <!-- .\" are listed in Table 5-1 along with the  -->
 278 <!-- .\"the associated hexadecimal code -->
 279 <!-- .\" and operation. -->
 280 <!-- .\".CP T 1 -->
 281 <!-- .\"Display Functions -->
 282 <informaltable frame='topbot'>
 283   <?dbfo keep-together="auto" ?>
 284   <tgroup cols='3' align='left' colsep='0' rowsep='0'>
 285   <colspec colname='c1' colwidth='1.0*'/>
 286   <colspec colname='c2' colwidth='1.0*'/>
 287   <colspec colname='c3' colwidth='1.0*'/>
 288   <thead>
 289     <row rowsep='1'>
 290       <entry>Function Name</entry>
 291       <entry>Value</entry>
 292       <entry>Operation</entry>
 293     </row>
 294   </thead>
 295   <tbody>
 296     <row>
 297       <entry><symbol>GXclear</symbol></entry>
 298       <entry>0x0</entry>
 299       <entry>0</entry>
 300     </row>
 301     <row>
 302       <entry><symbol>GXand</symbol></entry>
 303       <entry>0x1</entry>
 304       <entry>src AND dst</entry>
 305     </row>
 306     <row>
 307       <entry><symbol>GXandReverse</symbol></entry>
 308       <entry>0x2</entry>
 309       <entry>src AND NOT dst</entry>
 310     </row>
 311     <row>
 312       <entry><symbol>GXcopy</symbol></entry>
 313       <entry>0x3</entry>
 314       <entry>src</entry>
 315     </row>
 316     <row>
 317       <entry><symbol>GXandInverted</symbol></entry>
 318       <entry>0x4</entry>
 319       <entry>(NOT src) AND dst</entry>
 320     </row>
 321     <row>
 322       <entry><symbol>GXnoop</symbol></entry>
 323       <entry>0x5</entry>
 324       <entry>dst</entry>
 325     </row>
 326     <row>
 327       <entry><symbol>GXxor</symbol></entry>
 328       <entry>0x6</entry>
 329       <entry>src XOR dst</entry>
 330     </row>
 331     <row>
 332       <entry><symbol>GXor</symbol></entry>
 333       <entry>0x7</entry>
 334       <entry>src OR dst</entry>
 335     </row>
 336     <row>
 337       <entry><symbol>GXnor</symbol></entry>
 338       <entry>0x8</entry>
 339       <entry>(NOT src) AND (NOT dst)</entry>
 340     </row>
 341     <row>
 342       <entry><symbol>GXequiv</symbol></entry>
 343       <entry>0x9</entry>
 344       <entry>(NOT src) XOR dst</entry>
 345     </row>
 346     <row>
 347       <entry><symbol>GXinvert</symbol></entry>
 348       <entry>0xa</entry>
 349       <entry>NOT dst</entry>
 350     </row>
 351     <row>
 352       <entry><symbol>GXorReverse</symbol></entry>
 353       <entry>0xb</entry>
 354       <entry>src OR (NOT dst)</entry>
 355     </row>
 356     <row>
 357       <entry><symbol>GXcopyInverted</symbol></entry>
 358       <entry>0xc</entry>
 359       <entry>NOT src</entry>
 360     </row>
 361     <row>
 362       <entry><symbol>GXorInverted</symbol></entry>
 363       <entry>0xd</entry>
 364       <entry>(NOT src) OR dst</entry>
 365     </row>
 366     <row>
 367       <entry><symbol>GXnand</symbol></entry>
 368       <entry>0xe</entry>
 369       <entry>(NOT src) OR (NOT dst)</entry>
 370     </row>
 371     <row>
 372       <entry><symbol>GXset</symbol></entry>
 373       <entry>0xf</entry>
 374       <entry>1</entry>
 375     </row>
 376   </tbody>
 377   </tgroup>
 378 </informaltable>
 379
 380 <para>
 381 <!-- .LP -->
 382 Many graphics operations depend on either pixel values or planes in a GC.
 383 <indexterm><primary>Pixel value</primary></indexterm>
 384 The planes attribute is of type long, and it specifies which planes of the
 385 destination are to be modified, one bit per plane.
 386 <indexterm><primary>Plane</primary><secondary>mask</secondary></indexterm>
 387 A monochrome display has only one plane and
 388 will be the least significant bit of the word.
 389 As planes are added to the display hardware, they will occupy more
 390 significant bits in the plane mask.
 391 </para>
 392 <para>
 393 <!-- .LP -->
 394 In graphics operations, given a source and destination pixel,
 395 the result is computed bitwise on corresponding bits of the pixels.
 396 That is, a Boolean operation is performed in each bit plane.
 397 The plane_mask restricts the operation to a subset of planes.
 398 A macro constant
 399 <symbol>AllPlanes</symbol>
 400 can be used to refer to all planes of the screen simultaneously.
 401 The result is computed by the following:
 402 </para>
 403 <para>
 404 <!-- .LP -->
 405 <literallayout class="monospaced">
 406 ((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))
 407 </literallayout>
 408 </para>
 409 <para>
 410 <!-- .LP -->
 411 Range checking is not performed on the values for foreground,
 412 background, or plane_mask.
 413 They are simply truncated to the appropriate
 414 number of bits.
 415 The line-width is measured in pixels and either can be greater than or equal to
 416 one (wide line) or can be the special value zero (thin line).
 417 </para>
 418 <para>
 419 <!-- .LP -->
 420 Wide lines are drawn centered on the path described by the graphics request.
 421 Unless otherwise specified by the join-style or cap-style,
 422 the bounding box of a wide line with endpoints [x1, y1], [x2, y2] and
 423 width w is a rectangle with vertices at the following real coordinates:
 424 </para>
 425 <para>
 426 <!-- .LP -->
 427 <literallayout class="monospaced">
 428 <!-- .TA .5i 2.5i -->
 429 <!-- .ta .5i 2.5i -->
 430 [x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)],
 431 [x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]
 432 </literallayout>
 433 </para>
 434 <para>
 435 <!-- .LP -->
 436 Here sn is the sine of the angle of the line,
 437 and cs is the cosine of the angle of the line.
 438 A pixel is part of the line and so is drawn
 439 if the center of the pixel is fully inside the bounding box
 440 (which is viewed as having infinitely thin edges).
 441 If the center of the pixel is exactly on the bounding box,
 442 it is part of the line if and only if the interior is immediately to its right
 443 (x increasing direction).
 444 Pixels with centers on a horizontal edge are a special case and are part of
 445 the line if and only if the interior or the boundary is immediately below
 446 (y increasing direction) and the interior or the boundary is immediately
 447 to the right (x increasing direction).
 448 </para>
 449 <para>
 450 <!-- .LP -->
 451 Thin lines (zero line-width) are one-pixel-wide lines drawn using an
 452 unspecified, device-dependent algorithm.
 453 There are only two constraints on this algorithm.
 454 </para>
 455 <itemizedlist>
 456   <listitem>
 457     <para>
 458 If a line is drawn unclipped from [x1,y1] to [x2,y2] and
 459 if another line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy],
 460 a point [x,y] is touched by drawing the first line
 461 if and only if the point [x+dx,y+dy] is touched by drawing the second line.
 462     </para>
 463   </listitem>
 464   <listitem>
 465     <para>
 466 The effective set of points comprising a line cannot be affected by clipping.
 467 That is, a point is touched in a clipped line if and only if the point
 468 lies inside the clipping region and the point would be touched
 469 by the line when drawn unclipped.
 470     </para>
 471   </listitem>
 472 </itemizedlist>
 473 <para>
 474 <!-- .LP -->
 475 A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels
 476 as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style
 477 and join-style.
 478 It is recommended that this property be true for thin lines,
 479 but this is not required.
 480 A line-width of zero may differ from a line-width of one in which pixels are
 481 drawn.
 482 This permits the use of many manufacturers' line drawing hardware,
 483 which may run many times faster than the more precisely specified
 484 wide lines.
 485 </para>
 486 <para>
 487 <!-- .LP -->
 488 In general,
 489 drawing a thin line will be faster than drawing a wide line of width one.
 490 However, because of their different drawing algorithms,
 491 thin lines may not mix well aesthetically with wide lines.
 492 If it is desirable to obtain precise and uniform results across all displays,
 493 a client should always use a line-width of one rather than a line-width of zero.
 494 </para>
 495 <para>
 496 <!-- .LP -->
 497 The line-style defines which sections of a line are drawn:
 498 </para>
 499
 500 <variablelist>
 501   <varlistentry>
 502     <term><symbol>LineSolid</symbol></term>
 503     <listitem>
 504       <para>The full path of the line is drawn.</para>
 505     </listitem>
 506   </varlistentry>
 507   <varlistentry>
 508     <term><symbol>LineDoubleDash</symbol></term>
 509     <listitem>
 510       <para>
 511 The full path of the line is drawn,
 512 but the even dashes are filled differently
 513 from the odd dashes (see fill-style) with <!-- xref -->
 514 <symbol>CapButt</symbol>
 515 style used where even and odd dashes meet.
 516       </para>
 517     </listitem>
 518   </varlistentry>
 519   <varlistentry>
 520     <term><symbol>LineOnOffDash</symbol></term>
 521     <listitem>
 522       <para>
 523 Only the even dashes are drawn,
 524 and cap-style applies to
 525 all internal ends of the individual dashes,
 526 except
 527 <symbol>CapNotLast</symbol>
 528 is treated as
 529 <symbol>CapButt</symbol>.
 530       </para>
 531     </listitem>
 532   </varlistentry>
 533 </variablelist>
 534 <para>
 535 The cap-style defines how the endpoints of a path are drawn:
 536 </para>
 537
 538 <variablelist>
 539   <varlistentry>
 540     <term><symbol>CapNotLast</symbol></term>
 541     <listitem>
 542       <para>
 543 This is equivalent to
 544 <symbol>CapButt</symbol>
 545 except that for a line-width of zero the final endpoint is not drawn.
 546      </para>
 547     </listitem>
 548   </varlistentry>
 549
 550   <varlistentry>
 551     <term><symbol>CapButt</symbol></term>
 552     <listitem>
 553       <para>
 554 The line is square at the endpoint (perpendicular to the slope of the line)
 555 with no projection beyond.
 556       </para>
 557     </listitem>
 558   </varlistentry>
 559   <varlistentry>
 560     <term><symbol>CapRound</symbol></term>
 561     <listitem>
 562       <para>
 563 The line has a circular arc with the diameter equal to the line-width,
 564 centered on the endpoint.
 565 (This is equivalent to
 566 <symbol>CapButt</symbol>
 567 for line-width of zero).
 568       </para>
 569     </listitem>
 570   </varlistentry>
 571   <varlistentry>
 572     <term><symbol>CapProjecting</symbol></term>
 573     <listitem>
 574       <para>
 575 The line is square at the end, but the path continues beyond the endpoint
 576 for a distance equal to half the line-width.
 577 (This is equivalent to
 578 <symbol>CapButt</symbol>
 579 for line-width of zero).
 580       </para>
 581     </listitem>
 582   </varlistentry>
 583 </variablelist>
 584
 585 <para>
 586 The join-style defines how corners are drawn for wide lines:
 587 </para>
 588
 589 <variablelist>
 590   <varlistentry>
 591     <term><symbol>JoinMiter</symbol></term>
 592     <listitem>
 593       <para>
 594 The outer edges of two lines extend to meet at an angle.
 595 However, if the angle is less than 11 degrees,
 596 then a
 597 <symbol>JoinBevel</symbol>
 598 join-style is used instead.
 599       </para>
 600     </listitem>
 601   </varlistentry>
 602   <varlistentry>
 603     <term><symbol>JoinRound</symbol></term>
 604     <listitem>
 605       <para>
 606 The corner is a circular arc with the diameter equal to the line-width,
 607 centered on the joinpoint.
 608       </para>
 609     </listitem>
 610   </varlistentry>
 611   <varlistentry>
 612     <term><symbol>JoinBevel</symbol></term>
 613     <listitem>
 614       <para>
 615 The corner has
 616 <symbol>CapButt</symbol>
 617 endpoint styles with the triangular notch filled.
 618       </para>
 619     </listitem>
 620   </varlistentry>
 621 </variablelist>
 622
 623
 624 <para>
 625 <!-- .LP -->
 626 For a line with coincident endpoints (x1=x2, y1=y2),
 627 when the cap-style is applied to both endpoints,
 628 the semantics depends on the line-width and the cap-style:
 629 </para>
 630
 631 <informaltable frame='none'>
 632   <?dbfo keep-together="always" ?>
 633   <tgroup cols='3' align='left' colsep='0' rowsep='0'>
 634   <colspec colname='c1' colwidth='1.0*'/>
 635   <colspec colname='c2' colwidth='1.0*'/>
 636   <colspec colname='c3' colwidth='3.0*'/>
 637   <tbody>
 638     <row>
 639       <entry><symbol>CapNotLast</symbol></entry>
 640       <entry>thin</entry>
 641       <entry>The results are device dependent,
 642       but the desired effect is that nothing is drawn.</entry>
 643     </row>
 644     <row>
 645       <entry><symbol>CapButt</symbol></entry>
 646       <entry>thin</entry>
 647       <entry>The results are device dependent,
 648       but the desired effect is that a single pixel is drawn.</entry>
 649     </row>
 650     <row>
 651       <entry><symbol>CapRound</symbol></entry>
 652       <entry>thin</entry>
 653       <entry>The results are the same as for
 654       <symbol>CapButt</symbol> /thin.</entry>
 655     </row>
 656     <row>
 657       <entry><symbol>CapProjecting</symbol></entry>
 658       <entry>thin</entry>
 659       <entry>The results are the same as for
 660       <symbol>CapButt</symbol> /thin.</entry>
 661     </row>
 662     <row>
 663       <entry><symbol>CapButt</symbol></entry>
 664       <entry>wide</entry>
 665       <entry>Nothing is drawn.</entry>
 666     </row>
 667     <row>
 668       <entry><symbol>CapRound</symbol></entry>
 669       <entry>wide</entry>
 670       <entry>The closed path is a circle, centered at the endpoint, and
 671       with the diameter equal to the line-width.</entry>
 672     </row>
 673     <row>
 674       <entry><symbol>CapProjecting</symbol></entry>
 675       <entry>wide</entry>
 676       <entry>The closed path is a square, aligned with the coordinate axes, centered at the
 677       endpoint, and with the sides equal to the line-width.</entry>
 678     </row>
 679   </tbody>
 680   </tgroup>
 681 </informaltable>
 682
 683 <para>
 684 <!-- .LP -->
 685 For a line with coincident endpoints (x1=x2, y1=y2),
 686 when the join-style is applied at one or both endpoints,
 687 the effect is as if the line was removed from the overall path.
 688 However, if the total path consists of or is reduced to a single point joined
 689 with itself, the effect is the same as when the cap-style is applied at both
 690 endpoints.
 691 </para>
 692 <para>
 693 <!-- .LP -->
 694 The tile/stipple represents an infinite two-dimensional plane,
 695 with the tile/stipple replicated in all dimensions.
 696 When that plane is superimposed on the drawable
 697 for use in a graphics operation, the upper-left corner
 698 of some instance of the tile/stipple is at the coordinates within
 699 the drawable specified by the tile/stipple origin.
 700 The tile/stipple and clip origins are interpreted relative to the
 701 origin of whatever destination drawable is specified in a graphics
 702 request.
 703 The tile pixmap must have the same root and depth as the GC,
 704 or a
 705 <errorname>BadMatch</errorname>
 706 error results.
 707 The stipple pixmap must have depth one and must have the same root as the
 708 GC, or a
 709 <errorname>BadMatch</errorname>
 710 error results.
 711 For stipple operations where the fill-style is
 712 <symbol>FillStippled</symbol>
 713 but not
 714 <symbol>FillOpaqueStippled</symbol>,
 715 the stipple pattern is tiled in a
 716 single plane and acts as an additional clip mask to be ANDed with the clip-mask.
 717 Although some sizes may be faster to use than others,
 718 any size pixmap can be used for tiling or stippling.
 719 </para>
 720
 721 <para>
 722 <!-- .LP -->
 723 The fill-style defines the contents of the source for line, text, and
 724 fill requests.
 725 For all text and fill requests (for example,
 726 <xref linkend='XDrawText' xrefstyle='select: title'/>,
 727 <xref linkend='XDrawText16' xrefstyle='select: title'/>,
 728 <xref linkend='XFillRectangle' xrefstyle='select: title'/>,
 729 <xref linkend='XFillPolygon' xrefstyle='select: title'/>,
 730 and
 731 <xref linkend='XFillArc' xrefstyle='select: title'/>);
 732 for line requests
 733 with line-style
 734 <symbol>LineSolid</symbol>
 735 (for example,
 736 <xref linkend='XDrawLine' xrefstyle='select: title'/>,
 737 <xref linkend='XDrawSegments' xrefstyle='select: title'/>,
 738 <xref linkend='XDrawRectangle' xrefstyle='select: title'/>,
 739 <xref linkend='XDrawArc' xrefstyle='select: title'/>);
 740 and for the even dashes for line requests with line-style
 741 <symbol>LineOnOffDash</symbol>
 742 or
 743 <symbol>LineDoubleDash</symbol>,
 744 the following apply:
 745 </para>
 746
 747 <informaltable frame='none'>
 748   <?dbfo keep-together="always" ?>
 749   <tgroup cols='2' align='left' colsep='0' rowsep='0'>
 750   <colspec colname='c1' colwidth='1.0*'/>
 751   <colspec colname='c2' colwidth='2.0*'/>
 752   <tbody>
 753     <row>
 754       <entry><symbol>FillSolid</symbol></entry>
 755       <entry>Foreground</entry>
 756     </row>
 757     <row>
 758       <entry><symbol>FillTiled</symbol></entry>
 759       <entry>Tile</entry>
 760     </row>
 761     <row>
 762       <entry><symbol>FillOpaqueStippled</symbol></entry>
 763       <entry>A tile with the same width and height as stipple,
 764       but with background everywhere stipple has a zero
 765       and with foreground everywhere stipple has a one</entry>
 766     </row>
 767     <row>
 768       <entry><symbol>FillStippled</symbol></entry>
 769       <entry>Foreground masked by stipple</entry>
 770     </row>
 771   </tbody>
 772   </tgroup>
 773 </informaltable>
 774
 775 <para>
 776 <!-- .LP -->
 777 When drawing lines with line-style
 778 <symbol>LineDoubleDash</symbol>,
 779 the odd dashes are controlled by the fill-style in the following manner:
 780 </para>
 781
 782 <informaltable frame='none'>
 783   <?dbfo keep-together="always" ?>
 784   <tgroup cols='2' align='left' colsep='0' rowsep='0'>
 785   <colspec colname='c1' colwidth='1.0*'/>
 786   <colspec colname='c2' colwidth='2.0*'/>
 787   <tbody>
 788     <row>
 789       <entry><symbol>FillSolid</symbol></entry>
 790       <entry>Background</entry>
 791     </row>
 792     <row>
 793       <entry><symbol>FillTiled</symbol></entry>
 794       <entry>Same as for even dashes</entry>
 795     </row>
 796     <row>
 797       <entry><symbol>FillOpaqueStippled</symbol></entry>
 798       <entry>Same as for even dashes</entry>
 799     </row>
 800     <row>
 801       <entry><symbol>FillStippled</symbol></entry>
 802       <entry>Background masked by stipple</entry>
 803     </row>
 804   </tbody>
 805   </tgroup>
 806 </informaltable>
 807
 808 <para>
 809 <!-- .LP -->
 810 Storing a pixmap in a GC might or might not result in a copy
 811 being made.
 812 If the pixmap is later used as the destination for a graphics request,
 813 the change might or might not be reflected in the GC.
 814 If the pixmap is used simultaneously in a graphics request both as
 815 a destination and as a tile or stipple,
 816 the results are undefined.
 817 </para>
 818 <para>
 819 <!-- .LP -->
 820 For optimum performance,
 821 you should draw as much as possible with the same GC
 822 (without changing its components).
 823 The costs of changing GC components relative to using different GCs
 824 depend on the display hardware and the server implementation.
 825 It is quite likely that some amount of GC information will be
 826 cached in display hardware and that such hardware can only cache a small number
 827 of GCs.
 828 </para>
 829 <para>
 830 <!-- .LP -->
 831 The dashes value is actually a simplified form of the
 832 more general patterns that can be set with
 833 <xref linkend='XSetDashes' xrefstyle='select: title'/>.
 834 Specifying a
 835 value of N is equivalent to specifying the two-element list [N, N] in
 836 <xref linkend='XSetDashes' xrefstyle='select: title'/>.
 837 The value must be nonzero,
 838 or a
 839 <errorname>BadValue</errorname>
 840 error results.
 841 </para>
 842 <para>
 843 <!-- .LP -->
 844 The clip-mask restricts writes to the destination drawable.
 845 If the clip-mask is set to a pixmap,
 846 it must have depth one and have the same root as the GC,
 847 or a
 848 <errorname>BadMatch</errorname>
 849 error results.
 850 If clip-mask is set to
 851 <symbol>None</symbol>,
 852 the pixels are always drawn regardless of the clip origin.
 853 The clip-mask also can be set by calling the
 854 <xref linkend='XSetClipRectangles' xrefstyle='select: title'/>
 855 or
 856 <xref linkend='XSetRegion' xrefstyle='select: title'/>
 857 functions.
 858 Only pixels where the clip-mask has a bit set to 1 are drawn.
 859 Pixels are not drawn outside the area covered by the clip-mask
 860 or where the clip-mask has a bit set to 0.
 861 The clip-mask affects all graphics requests.
 862 The clip-mask does not clip sources.
 863 The clip-mask origin is interpreted relative to the origin of whatever
 864 destination drawable is specified in a graphics request.
 865 </para>
 866 <para>
 867 <!-- .LP -->
 868 You can set the subwindow-mode to
 869 <symbol>ClipByChildren</symbol>
 870 or
 871 <symbol>IncludeInferiors</symbol>.
 872 For
 873 <symbol>ClipByChildren</symbol>,
 874 both source and destination windows are
 875 additionally clipped by all viewable
 876 <symbol>InputOutput</symbol>
 877 children.
 878 For
 879 <symbol>IncludeInferiors</symbol>,
 880 neither source nor destination window is clipped by inferiors.
 881 This will result in including subwindow contents in the source
 882 and drawing through subwindow boundaries of the destination.
 883 The use of
 884 <symbol>IncludeInferiors</symbol>
 885 on a window of one depth with mapped
 886 inferiors of differing depth is not illegal, but the semantics are
 887 undefined by the core protocol.
 888 </para>
 889 <para>
 890 <!-- .LP -->
 891 The fill-rule defines what pixels are inside (drawn) for
 892 paths given in
 893 <xref linkend='XFillPolygon' xrefstyle='select: title'/>
 894 requests and can be set to
 895 <symbol>EvenOddRule</symbol>
 896 or
 897 <symbol>WindingRule</symbol>.
 898 For
 899 <symbol>EvenOddRule</symbol>,
 900 a point is inside if
 901 an infinite ray with the point as origin crosses the path an odd number
 902 of times.
 903 For
 904 <symbol>WindingRule</symbol>,
 905 a point is inside if an infinite ray with the
 906 point as origin crosses an unequal number of clockwise and
 907 counterclockwise directed path segments.
 908 A clockwise directed path segment is one that crosses the ray from left to
 909 right as observed from the point.
 910 A counterclockwise segment is one that crosses the ray from right to left
 911 as observed from the point.
 912 The case where a directed line segment is coincident with the ray is
 913 uninteresting because you can simply choose a different ray that is not
 914 coincident with a segment.
 915 </para>
 916 <para>
 917 <!-- .LP -->
 918 For both
 919 <symbol>EvenOddRule</symbol>
 920 and
 921 <symbol>WindingRule</symbol>,
 922 a point is infinitely small,
 923 and the path is an infinitely thin line.
 924 A pixel is inside if the center point of the pixel is inside
 925 and the center point is not on the boundary.
 926 If the center point is on the boundary,
 927 the pixel is inside if and only if the polygon interior is immediately to
 928 its right (x increasing direction).
 929 Pixels with centers on a horizontal edge are a special case
 930 and are inside if and only if the polygon interior is immediately below
 931 (y increasing direction).
 932 </para>
 933 <para>
 934 <!-- .LP -->
 935 The arc-mode controls filling in the
 936 <xref linkend='XFillArcs' xrefstyle='select: title'/>
 937 function and can be set to
 938 <symbol>ArcPieSlice</symbol>
 939 or
 940 <symbol>ArcChord</symbol>.
 941 For
 942 <symbol>ArcPieSlice</symbol>,
 943 the arcs are pie-slice filled.
 944 For
 945 <symbol>ArcChord</symbol>,
 946 the arcs are chord filled.
 947 </para>
 948 <para>
 949 <!-- .LP -->
 950 The graphics-exposure flag controls
 951 <symbol>GraphicsExpose</symbol>
 952 event generation
 953 for
 954 <xref linkend='XCopyArea' xrefstyle='select: title'/>
 955 and
 956 <xref linkend='XCopyPlane' xrefstyle='select: title'/>
 957 requests (and any similar requests defined by extensions).
 958 </para>
 959 <para>
 960 <!-- .LP -->
 961 <!-- .sp -->
 962 To create a new GC that is usable on a given screen with a
 963 depth of drawable, use
 964 <xref linkend='XCreateGC' xrefstyle='select: title'/>.
 965 </para>
 966 <indexterm><primary>Graphics context</primary><secondary>initializing</secondary></indexterm>
 967 <indexterm significance="preferred"><primary>XCreateGC</primary></indexterm>
 968 <!-- .sM -->
 969 <funcsynopsis id='XCreateGC'>
 970 <funcprototype>
 971   <funcdef>GC <function>XCreateGC</function></funcdef>
 972   <paramdef>Display <parameter> *display</parameter></paramdef>
 973   <paramdef>Drawable<parameter> d</parameter></paramdef>
 974   <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>
 975   <paramdef>XGCValues *<parameter>values</parameter></paramdef>
 976 </funcprototype>
 977 </funcsynopsis>
 978 <!-- .FN -->
 979 <variablelist>
 980   <varlistentry>
 981     <term>
 982       <emphasis remap='I'>display</emphasis>
 983     </term>
 984     <listitem>
 985       <para>
 986 Specifies the connection to the X server.
 987       </para>
 988     </listitem>
 989   </varlistentry>
 990   <varlistentry>
 991     <term>
 992       <emphasis remap='I'>d</emphasis>
 993     </term>
 994     <listitem>
 995       <para>
 996 Specifies the drawable.
 997 <!-- .ds Vm set using the information in the specified values structure -->
 998       </para>
 999     </listitem>
1000   </varlistentry>
1001   <varlistentry>
1002     <term>
1003       <emphasis remap='I'>valuemask</emphasis>
1004     </term>
1005     <listitem>
1006       <para>
1007 Specifies which components in the GC are to be (Vm.
1008 This argument is the bitwise inclusive OR of zero or more of the valid
1009 GC component mask bits.
1010       </para>
1011     </listitem>
1012   </varlistentry>
1013   <varlistentry>
1014     <term>
1015       <emphasis remap='I'>values</emphasis>
1016     </term>
1017     <listitem>
1018       <para>
1019 Specifies any values as specified by the valuemask.
1020     </para>
1021   </listitem>
1022   </varlistentry>
1023 </variablelist>
1024 <para>
1025 <!-- .LP -->
1026 <!-- .eM -->
1027 The
1028 <xref linkend='XCreateGC' xrefstyle='select: title'/>
1029 function creates a graphics context and returns a GC.
1030 The GC can be used with any destination drawable having the same root
1031 and depth as the specified drawable.
1032 Use with other drawables results in a
1033 <errorname>BadMatch</errorname>
1034 error.
1035 </para>
1036 <para>
1037 <!-- .LP -->
1038 <xref linkend='XCreateGC' xrefstyle='select: title'/>
1039 can generate
1040 <errorname>BadAlloc</errorname>,
1041 <errorname>BadDrawable</errorname>,
1042 <errorname>BadFont</errorname>,
1043 <errorname>BadMatch</errorname>,
1044 <errorname>BadPixmap</errorname>,
1045 and
1046 <errorname>BadValue</errorname>
1047 errors.
1048 </para>
1049 <para>
1050 <!-- .LP -->
1051 <!-- .sp -->
1052 To copy components from a source GC to a destination GC, use
1053 <xref linkend='XCopyGC' xrefstyle='select: title'/>.
1054 </para>
1055 <indexterm significance="preferred"><primary>XCopyGC</primary></indexterm>
1056 <!-- .sM -->
1057 <funcsynopsis id='XCopyGC'>
1058 <funcprototype>
1059   <funcdef><function>XCopyGC</function></funcdef>
1060   <paramdef>Display<parameter> *display</parameter></paramdef>
1061   <paramdef>GCsrc,<parameter> dest</parameter></paramdef>
1062   <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>
1063 </funcprototype>
1064 </funcsynopsis>
1065 <!-- .FN -->
1066 <variablelist>
1067   <varlistentry>
1068     <term>
1069       <emphasis remap='I'>display</emphasis>
1070     </term>
1071     <listitem>
1072       <para>
1073 Specifies the connection to the X server.
1074       </para>
1075     </listitem>
1076   </varlistentry>
1077   <varlistentry>
1078     <term>
1079       <emphasis remap='I'>src</emphasis>
1080     </term>
1081     <listitem>
1082       <para>
1083 Specifies the components of the source GC.
1084 <!-- .ds Vm copied to the destination GC -->
1085       </para>
1086     </listitem>
1087   </varlistentry>
1088   <varlistentry>
1089     <term>
1090       <emphasis remap='I'>valuemask</emphasis>
1091     </term>
1092     <listitem>
1093       <para>
1094 Specifies which components in the GC are to be (Vm.
1095 This argument is the bitwise inclusive OR of zero or more of the valid
1096 GC component mask bits.
1097       </para>
1098     </listitem>
1099   </varlistentry>
1100   <varlistentry>
1101     <term>
1102       <emphasis remap='I'>dest</emphasis>
1103     </term>
1104     <listitem>
1105       <para>
1106 Specifies the destination GC.
1107     </para>
1108   </listitem>
1109   </varlistentry>
1110 </variablelist>
1111 <para>
1112 <!-- .LP -->
1113 <!-- .eM  -->
1114 The
1115 <xref linkend='XCopyGC' xrefstyle='select: title'/>
1116 function copies the specified components from the source GC
1117 to the destination GC.
1118 The source and destination GCs must have the same root and depth,
1119 or a
1120 <errorname>BadMatch</errorname>
1121 error results.
1122 The valuemask specifies which component to copy, as for
1123 <xref linkend='XCreateGC' xrefstyle='select: title'/>.
1124 </para>
1125 <para>
1126 <!-- .LP -->
1127 <xref linkend='XCopyGC' xrefstyle='select: title'/>
1128 can generate
1129 <errorname>BadAlloc</errorname>,
1130 <errorname>BadGC</errorname>,
1131 and
1132 <errorname>BadMatch</errorname>
1133 errors.
1134 </para>
1135 <para>
1136 <!-- .LP -->
1137 <!-- .sp -->
1138 To change the components in a given GC, use
1139 <xref linkend='XChangeGC' xrefstyle='select: title'/>.
1140 </para>
1141 <indexterm significance="preferred"><primary>XChangeGC</primary></indexterm>
1142 <!-- .sM -->
1143 <funcsynopsis id='XChangeGC'>
1144 <funcprototype>
1145   <funcdef><function>XChangeGC</function></funcdef>
1146   <paramdef>Display<parameter> *display</parameter></paramdef>
1147   <paramdef>GC<parameter> gc</parameter></paramdef>
1148   <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>
1149   <paramdef>XGCValues<parameter> *values</parameter></paramdef>
1150 </funcprototype>
1151 </funcsynopsis>
1152 <!-- .FN -->
1153 <variablelist>
1154   <varlistentry>
1155     <term>
1156       <emphasis remap='I'>display</emphasis>
1157     </term>
1158     <listitem>
1159       <para>
1160 Specifies the connection to the X server.
1161       </para>
1162     </listitem>
1163   </varlistentry>
1164   <varlistentry>
1165     <term>
1166       <emphasis remap='I'>gc</emphasis>
1167     </term>
1168     <listitem>
1169       <para>
1170 Specifies the GC.
1171 <!-- .ds Vm changed using information in the specified values structure -->
1172       </para>
1173     </listitem>
1174   </varlistentry>
1175   <varlistentry>
1176     <term>
1177       <emphasis remap='I'>valuemask</emphasis>
1178     </term>
1179     <listitem>
1180       <para>
1181 Specifies which components in the GC are to be (Vm.
1182 This argument is the bitwise inclusive OR of zero or more of the valid
1183 GC component mask bits.
1184       </para>
1185     </listitem>
1186   </varlistentry>
1187   <varlistentry>
1188     <term>
1189       <emphasis remap='I'>values</emphasis>
1190     </term>
1191     <listitem>
1192       <para>
1193 Specifies any values as specified by the valuemask.
1194     </para>
1195   </listitem>
1196   </varlistentry>
1197 </variablelist>
1198 <para>
1199 <!-- .LP -->
1200 <!-- .eM -->
1201 The
1202 <xref linkend='XChangeGC' xrefstyle='select: title'/>
1203 function changes the components specified by valuemask for
1204 the specified GC.
1205 The values argument contains the values to be set.
1206 The values and restrictions are the same as for
1207 <xref linkend='XCreateGC' xrefstyle='select: title'/>.
1208 Changing the clip-mask overrides any previous
1209 <xref linkend='XSetClipRectangles' xrefstyle='select: title'/>
1210 request on the context.
1211 Changing the dash-offset or dash-list
1212 overrides any previous
1213 <xref linkend='XSetDashes' xrefstyle='select: title'/>
1214 request on the context.
1215 The order in which components are verified and altered is server dependent.
1216 If an error is generated, a subset of the components may have been altered.
1217 </para>
1218 <para>
1219 <!-- .LP -->
1220 <xref linkend='XChangeGC' xrefstyle='select: title'/>
1221 can generate
1222 <errorname>BadAlloc</errorname>,
1223 <errorname>BadFont</errorname>,
1224 <errorname>BadGC</errorname>,
1225 <errorname>BadMatch</errorname>,
1226 <errorname>BadPixmap</errorname>,
1227 and
1228 <errorname>BadValue</errorname>
1229 errors.
1230 </para>
1231 <para>
1232 <!-- .LP -->
1233 <!-- .sp -->
1234 To obtain components of a given GC, use
1235 <xref linkend='XGetGCValues' xrefstyle='select: title'/>.
1236 </para>
1237 <indexterm significance="preferred"><primary>XGetGCValues</primary></indexterm>
1238 <!-- .sM -->
1239 <funcsynopsis id='XGetGCValues'>
1240 <funcprototype>
1241   <funcdef>Status <function>XGetGCValues</function></funcdef>
1242   <paramdef>Display<parameter> *display</parameter></paramdef>
1243   <paramdef>GC<parameter> gc</parameter></paramdef>
1244   <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef>
1245   <paramdef>XGCValues<parameter> *values_return</parameter></paramdef>
1246 </funcprototype>
1247 </funcsynopsis>
1248 <!-- .FN -->
1249 <variablelist>
1250   <varlistentry>
1251     <term>
1252       <emphasis remap='I'>display</emphasis>
1253     </term>
1254     <listitem>
1255       <para>
1256 Specifies the connection to the X server.
1257       </para>
1258     </listitem>
1259   </varlistentry>
1260   <varlistentry>
1261     <term>
1262       <emphasis remap='I'>gc</emphasis>
1263     </term>
1264     <listitem>
1265       <para>
1266 Specifies the GC.
1267 <!-- .ds Vm returned in the values_return argument -->
1268       </para>
1269     </listitem>
1270   </varlistentry>
1271   <varlistentry>
1272     <term>
1273       <emphasis remap='I'>valuemask</emphasis>
1274     </term>
1275     <listitem>
1276       <para>
1277 Specifies which components in the GC are to be (Vm.
1278 This argument is the bitwise inclusive OR of zero or more of the valid
1279 GC component mask bits.
1280       </para>
1281     </listitem>
1282   </varlistentry>
1283   <varlistentry>
1284     <term>
1285       <emphasis remap='I'>values_return</emphasis>
1286     </term>
1287     <listitem>
1288       <para>
1289 Returns the GC values in the specified
1290 <structname>XGCValues</structname>
1291 structure.
1292     </para>
1293   </listitem>
1294   </varlistentry>
1295 </variablelist>
1296 <para>
1297 <!-- .LP -->
1298 <!-- .eM -->
1299 The
1300 <xref linkend='XGetGCValues' xrefstyle='select: title'/>
1301 function returns the components specified by valuemask for the specified GC.
1302 If the valuemask contains a valid set of GC mask bits
1303 (<symbol>GCFunction</symbol>,
1304 <symbol>GCPlaneMask</symbol>,
1305 <symbol>GCForeground</symbol>,
1306 <symbol>GCBackground</symbol>,
1307 <symbol>GCLineWidth</symbol>,
1308 <symbol>GCLineStyle</symbol>,
1309 <symbol>GCCapStyle</symbol>,
1310 <symbol>GCJoinStyle</symbol>,
1311 <symbol>GCFillStyle</symbol>,
1312 <symbol>GCFillRule</symbol>,
1313 <symbol>GCTile</symbol>,
1314 <symbol>GCStipple</symbol>,
1315 <symbol>GCTileStipXOrigin</symbol>,
1316 <symbol>GCTileStipYOrigin</symbol>,
1317 <symbol>GCFont</symbol>,
1318 <symbol>GCSubwindowMode</symbol>,
1319 <symbol>GCGraphicsExposures</symbol>,
1320 <symbol>GCClipXOrigin</symbol>,
1321 <symbol>GCClipYOrigin</symbol>,
1322 <symbol>GCDashOffset</symbol>,
1323 or
1324 <symbol>GCArcMode</symbol>)
1325 and no error occurs,
1326 <xref linkend='XGetGCValues' xrefstyle='select: title'/>
1327 sets the requested components in values_return and returns a nonzero status.
1328 Otherwise, it returns a zero status.
1329 Note that the clip-mask and dash-list (represented by the
1330 <symbol>GCClipMask</symbol>
1331 and
1332 <symbol>GCDashList</symbol>
1333 bits, respectively, in the valuemask)
1334 cannot be requested.
1335 Also note that an invalid resource ID (with one or more of the three
1336 most significant bits set to 1) will be returned for
1337 <symbol>GCFont</symbol>,
1338 <symbol>GCTile</symbol>,
1339 and
1340 <symbol>GCStipple</symbol>
1341 if the component has never been explicitly set by the client.
1342 </para>
1343 <para>
1344 <!-- .LP -->
1345 <!-- .sp -->
1346 To free a given GC, use
1347 <xref linkend='XFreeGC' xrefstyle='select: title'/>.
1348 </para>
1349 <indexterm significance="preferred"><primary>XFreeGC</primary></indexterm>
1350 <!-- .sM -->
1351 <funcsynopsis id='XFreeGC'>
1352 <funcprototype>
1353   <funcdef><function>XFreeGC</function></funcdef>
1354   <paramdef>Display<parameter> *display</parameter></paramdef>
1355   <paramdef>GC<parameter> gc</parameter></paramdef>
1356 </funcprototype>
1357 </funcsynopsis>
1358 <!-- .FN -->
1359 <variablelist>
1360   <varlistentry>
1361     <term>
1362       <emphasis remap='I'>display</emphasis>
1363     </term>
1364     <listitem>
1365       <para>
1366 Specifies the connection to the X server.
1367       </para>
1368     </listitem>
1369   </varlistentry>
1370   <varlistentry>
1371     <term>
1372       <emphasis remap='I'>gc</emphasis>
1373     </term>
1374     <listitem>
1375       <para>
1376 Specifies the GC.
1377     </para>
1378   </listitem>
1379   </varlistentry>
1380 </variablelist>
1381 <para>
1382 <!-- .LP -->
1383 <!-- .eM -->
1384 The
1385 <xref linkend='XFreeGC' xrefstyle='select: title'/>
1386 function destroys the specified GC as well as all the associated storage.
1387 </para>
1388 <para>
1389 <!-- .LP -->
1390 <xref linkend='XFreeGC' xrefstyle='select: title'/>
1391 can generate a
1392 <errorname>BadGC</errorname>
1393 error.
1394 </para>
1395 <para>
1396 <!-- .LP -->
1397 <!-- .sp -->
1398 To obtain the
1399 <type>GContext</type>
1400 resource ID for a given GC, use
1401 <xref linkend='XGContextFromGC' xrefstyle='select: title'/>.
1402 </para>
1403 <indexterm significance="preferred"><primary>XGContextFromGC</primary></indexterm>
1404 <!-- .sM -->
1405 <funcsynopsis id='XGContextFromGC'>
1406 <funcprototype>
1407   <funcdef>GContext <function>XGContextFromGC</function></funcdef>
1408   <paramdef>GC<parameter> gc</parameter></paramdef>
1409 </funcprototype>
1410 </funcsynopsis>
1411 <!-- .FN -->
1412 <!-- .ds Gc for which you want the resource ID -->
1413 <variablelist>
1414   <varlistentry>
1415     <term>
1416       <emphasis remap='I'>gc</emphasis>
1417     </term>
1418     <listitem>
1419       <para>
1420 Specifies the GC (Gc.
1421     </para>
1422   </listitem>
1423   </varlistentry>
1424 </variablelist>
1425 <para>
1426 <!-- .LP -->
1427 <!-- .eM -->
1428 <!-- .sp -->
1429 Xlib usually defers sending changes to the components of a GC to the server
1430 until a graphics function is actually called with that GC.
1431 This permits batching of component changes into a single server request.
1432 In some circumstances, however, it may be necessary for the client
1433 to explicitly force sending the changes to the server.
1434 An example might be when a protocol extension uses the GC indirectly,
1435 in such a way that the extension interface cannot know what GC will be used.
1436 To force sending GC component changes, use
1437 <xref linkend='XFlushGC' xrefstyle='select: title'/>.
1438 </para>
1439 <indexterm significance="preferred"><primary>XFlushGC</primary></indexterm>
1440 <!-- .sM -->
1441 <funcsynopsis id='XFlushGC'>
1442 <funcprototype>
1443   <funcdef>void <function>XFlushGC</function></funcdef>
1444   <paramdef>Display<parameter> *display</parameter></paramdef>
1445   <paramdef>GC<parameter> gc</parameter></paramdef>
1446 </funcprototype>
1447 </funcsynopsis>
1448 <!-- .FN -->
1449 <variablelist>
1450   <varlistentry>
1451     <term>
1452       <emphasis remap='I'>display</emphasis>
1453     </term>
1454     <listitem>
1455       <para>
1456 Specifies the connection to the X server.
1457       </para>
1458     </listitem>
1459   </varlistentry>
1460   <varlistentry>
1461     <term>
1462       <emphasis remap='I'>gc</emphasis>
1463     </term>
1464     <listitem>
1465       <para>
1466 Specifies the GC.
1467     </para>
1468   </listitem>
1469   </varlistentry>
1470 </variablelist>
1471 <para>
1472 <!-- .LP -->
1473 <!-- .eM -->
1474 </para>
1475 </sect1>
1476 <sect1 id="Using_Graphics_Context_Convenience_Routines">
1477 <title>Using Graphics Context Convenience Routines</title>
1478 <!-- .XS -->
1479 <!-- (SN Using Graphics Context Convenience Routines  -->
1480 <!-- .XE -->
1481 <para>
1482 <!-- .LP -->
1483 This section discusses how to set the:
1484 </para>
1485 <itemizedlist>
1486   <listitem>
1487     <para>
1488 Foreground, background, plane mask, or function components
1489     </para>
1490   </listitem>
1491   <listitem>
1492     <para>
1493 Line attributes and dashes components
1494     </para>
1495   </listitem>
1496   <listitem>
1497     <para>
1498 Fill style and fill rule components
1499     </para>
1500   </listitem>
1501   <listitem>
1502     <para>
1503 Fill tile and stipple components
1504     </para>
1505   </listitem>
1506   <listitem>
1507     <para>
1508 Font component
1509     </para>
1510   </listitem>
1511   <listitem>
1512     <para>
1513 Clip region component
1514     </para>
1515   </listitem>
1516   <listitem>
1517     <para>
1518 Arc mode, subwindow mode, and graphics exposure components
1519     </para>
1520   </listitem>
1521 </itemizedlist>
1522 <sect2 id="Setting_the_Foreground_Background_Function_or_Plane_Mask">
1523 <title>Setting the Foreground, Background, Function, or Plane Mask</title>
1524 <!-- .XS -->
1525 <!-- (SN Setting the Foreground, Background, Function, or Plane Mask -->
1526 <!-- .XE -->
1527 <para>
1528 <!-- .LP -->
1529 To set the foreground, background, plane mask, and function components
1530 for a given GC, use
1531 <xref linkend='XSetState' xrefstyle='select: title'/>.
1532 </para>
1533 <indexterm significance="preferred"><primary>XSetState</primary></indexterm>
1534 <!-- .sM -->
1535 <funcsynopsis id='XSetState'>
1536 <funcprototype>
1537   <funcdef><function>XSetState</function></funcdef>
1538   <paramdef>Display<parameter> *display</parameter></paramdef>
1539   <paramdef>GC<parameter> gc</parameter></paramdef>
1540   <paramdef>unsignedlongforeground,<parameter> background</parameter></paramdef>
1541   <paramdef>int<parameter> function</parameter></paramdef>
1542   <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>
1543 </funcprototype>
1544 </funcsynopsis>
1545 <!-- .FN -->
1546 <variablelist>
1547   <varlistentry>
1548     <term>
1549       <emphasis remap='I'>display</emphasis>
1550     </term>
1551     <listitem>
1552       <para>
1553 Specifies the connection to the X server.
1554       </para>
1555     </listitem>
1556   </varlistentry>
1557   <varlistentry>
1558     <term>
1559       <emphasis remap='I'>gc</emphasis>
1560     </term>
1561     <listitem>
1562       <para>
1563 Specifies the GC.
1564       </para>
1565     </listitem>
1566   </varlistentry>
1567   <varlistentry>
1568     <term>
1569       <emphasis remap='I'>foreground</emphasis>
1570     </term>
1571     <listitem>
1572       <para>
1573 Specifies the foreground you want to set for the specified GC.
1574       </para>
1575     </listitem>
1576   </varlistentry>
1577   <varlistentry>
1578     <term>
1579       <emphasis remap='I'>background</emphasis>
1580     </term>
1581     <listitem>
1582       <para>
1583 Specifies the background you want to set for the specified GC.
1584       </para>
1585     </listitem>
1586   </varlistentry>
1587   <varlistentry>
1588     <term>
1589       <emphasis remap='I'>function</emphasis>
1590     </term>
1591     <listitem>
1592       <para>
1593 Specifies the function you want to set for the specified GC.
1594       </para>
1595     </listitem>
1596   </varlistentry>
1597   <varlistentry>
1598     <term>
1599       <emphasis remap='I'>plane_mask</emphasis>
1600     </term>
1601     <listitem>
1602       <para>
1603 Specifies the plane mask.
1604 <!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->
1605     </para>
1606   </listitem>
1607   </varlistentry>
1608 </variablelist>
1609 <para>
1610 <!-- .LP -->
1611 <!-- .eM -->
1612 <xref linkend='XSetState' xrefstyle='select: title'/>
1613 can generate
1614 <errorname>BadAlloc</errorname>,
1615 <errorname>BadGC</errorname>,
1616 and
1617 <errorname>BadValue</errorname>
1618 errors.
1619 </para>
1620 <para>
1621 <!-- .LP -->
1622 <!-- .sp -->
1623 To set the foreground of a given GC, use
1624 <xref linkend='XSetForeground' xrefstyle='select: title'/>.
1625 </para>
1626 <indexterm significance="preferred"><primary>XSetForeground</primary></indexterm>
1627 <!-- .sM -->
1628 <funcsynopsis id='XSetForeground'>
1629 <funcprototype>
1630   <funcdef><function>XSetForeground</function></funcdef>
1631   <paramdef>Display<parameter> *display</parameter></paramdef>
1632   <paramdef>GC<parameter> gc</parameter></paramdef>
1633   <paramdef>unsignedlong<parameter> foreground</parameter></paramdef>
1634 </funcprototype>
1635 </funcsynopsis>
1636 <!-- .FN -->
1637 <variablelist>
1638   <varlistentry>
1639     <term>
1640       <emphasis remap='I'>display</emphasis>
1641     </term>
1642     <listitem>
1643       <para>
1644 Specifies the connection to the X server.
1645       </para>
1646     </listitem>
1647   </varlistentry>
1648   <varlistentry>
1649     <term>
1650       <emphasis remap='I'>gc</emphasis>
1651     </term>
1652     <listitem>
1653       <para>
1654 Specifies the GC.
1655       </para>
1656     </listitem>
1657   </varlistentry>
1658   <varlistentry>
1659     <term>
1660       <emphasis remap='I'>foreground</emphasis>
1661     </term>
1662     <listitem>
1663       <para>
1664 Specifies the foreground you want to set for the specified GC.
1665     </para>
1666   </listitem>
1667   </varlistentry>
1668 </variablelist>
1669 <para>
1670 <!-- .LP -->
1671 <!-- .eM -->
1672 <xref linkend='XSetForeground' xrefstyle='select: title'/>
1673 can generate
1674 <errorname>BadAlloc</errorname>
1675 and
1676 <errorname>BadGC</errorname>
1677 errors.
1678 </para>
1679 <para>
1680 <!-- .LP -->
1681 <!-- .sp -->
1682 To set the background of a given GC, use
1683 <xref linkend='XSetBackground' xrefstyle='select: title'/>.
1684 </para>
1685 <indexterm significance="preferred"><primary>XSetBackground</primary></indexterm>
1686 <!-- .sM -->
1687 <funcsynopsis id='XSetBackground'>
1688 <funcprototype>
1689   <funcdef><function>XSetBackground</function></funcdef>
1690   <paramdef>Display<parameter> *display</parameter></paramdef>
1691   <paramdef>GC<parameter> gc</parameter></paramdef>
1692   <paramdef>unsignedlong<parameter> background</parameter></paramdef>
1693 </funcprototype>
1694 </funcsynopsis>
1695 <!-- .FN -->
1696 <variablelist>
1697   <varlistentry>
1698     <term>
1699       <emphasis remap='I'>display</emphasis>
1700     </term>
1701     <listitem>
1702       <para>
1703 Specifies the connection to the X server.
1704       </para>
1705     </listitem>
1706   </varlistentry>
1707   <varlistentry>
1708     <term>
1709       <emphasis remap='I'>gc</emphasis>
1710     </term>
1711     <listitem>
1712       <para>
1713 Specifies the GC.
1714       </para>
1715     </listitem>
1716   </varlistentry>
1717   <varlistentry>
1718     <term>
1719       <emphasis remap='I'>background</emphasis>
1720     </term>
1721     <listitem>
1722       <para>
1723 Specifies the background you want to set for the specified GC.
1724     </para>
1725   </listitem>
1726   </varlistentry>
1727 </variablelist>
1728 <para>
1729 <!-- .LP -->
1730 <!-- .eM -->
1731 <xref linkend='XSetBackground' xrefstyle='select: title'/>
1732 can generate
1733 <errorname>BadAlloc</errorname>
1734 and
1735 <errorname>BadGC</errorname>
1736 errors.
1737 </para>
1738 <para>
1739 <!-- .LP -->
1740 <!-- .sp -->
1741 To set the display function in a given GC, use
1742 <xref linkend='XSetFunction' xrefstyle='select: title'/>.
1743 </para>
1744 <indexterm significance="preferred"><primary>XSetFunction</primary></indexterm>
1745 <!-- .sM -->
1746 <funcsynopsis id='XSetFunction'>
1747 <funcprototype>
1748   <funcdef><function>XSetFunction</function></funcdef>
1749   <paramdef>Display<parameter> *display</parameter></paramdef>
1750   <paramdef>GC<parameter> gc</parameter></paramdef>
1751   <paramdef>int<parameter> function</parameter></paramdef>
1752 </funcprototype>
1753 </funcsynopsis>
1754 <!-- .FN -->
1755 <variablelist>
1756   <varlistentry>
1757     <term>
1758       <emphasis remap='I'>display</emphasis>
1759     </term>
1760     <listitem>
1761       <para>
1762 Specifies the connection to the X server.
1763       </para>
1764     </listitem>
1765   </varlistentry>
1766   <varlistentry>
1767     <term>
1768       <emphasis remap='I'>gc</emphasis>
1769     </term>
1770     <listitem>
1771       <para>
1772 Specifies the GC.
1773       </para>
1774     </listitem>
1775   </varlistentry>
1776   <varlistentry>
1777     <term>
1778       <emphasis remap='I'>function</emphasis>
1779     </term>
1780     <listitem>
1781       <para>
1782 Specifies the function you want to set for the specified GC.
1783     </para>
1784   </listitem>
1785   </varlistentry>
1786 </variablelist>
1787 <para>
1788 <!-- .LP -->
1789 <!-- .eM -->
1790 <xref linkend='XSetFunction' xrefstyle='select: title'/>
1791 can generate
1792 <errorname>BadAlloc</errorname>,
1793 <errorname>BadGC</errorname>,
1794 and
1795 <errorname>BadValue</errorname>
1796 errors.
1797 </para>
1798 <para>
1799 <!-- .LP -->
1800 <!-- .sp -->
1801 To set the plane mask of a given GC, use
1802 <xref linkend='XSetPlaneMask' xrefstyle='select: title'/>.
1803 </para>
1804 <indexterm significance="preferred"><primary>XSetPlaneMask</primary></indexterm>
1805 <!-- .sM -->
1806 <funcsynopsis id='XSetPlaneMask'>
1807 <funcprototype>
1808   <funcdef><function>XSetPlaneMask</function></funcdef>
1809   <paramdef>Display<parameter> *display</parameter></paramdef>
1810   <paramdef>GC<parameter> gc</parameter></paramdef>
1811   <paramdef>unsignedlong<parameter> plane_mask</parameter></paramdef>
1812 </funcprototype>
1813 </funcsynopsis>
1814 <!-- .FN -->
1815 <variablelist>
1816   <varlistentry>
1817     <term>
1818       <emphasis remap='I'>display</emphasis>
1819     </term>
1820     <listitem>
1821       <para>
1822 Specifies the connection to the X server.
1823       </para>
1824     </listitem>
1825   </varlistentry>
1826   <varlistentry>
1827     <term>
1828       <emphasis remap='I'>gc</emphasis>
1829     </term>
1830     <listitem>
1831       <para>
1832 Specifies the GC.
1833       </para>
1834     </listitem>
1835   </varlistentry>
1836   <varlistentry>
1837     <term>
1838       <emphasis remap='I'>plane_mask</emphasis>
1839     </term>
1840     <listitem>
1841       <para>
1842 Specifies the plane mask.
1843 <!-- .\" *** JIM: NEED MORE INFO FOR THIS. *** -->
1844     </para>
1845   </listitem>
1846   </varlistentry>
1847 </variablelist>
1848 <para>
1849 <!-- .LP -->
1850 <!-- .eM -->
1851 <xref linkend='XSetPlaneMask' xrefstyle='select: title'/>
1852 can generate
1853 <errorname>BadAlloc</errorname>
1854 and
1855 <errorname>BadGC</errorname>
1856 errors.
1857 </para>
1858 </sect2>
1859 <sect2 id="Setting_the_Line_Attributes_and_Dashes">
1860 <title>Setting the Line Attributes and Dashes</title>
1861 <!-- .XS -->
1862 <!-- (SN Setting the Line Attributes and Dashes  -->
1863 <!-- .XE -->
1864 <para>
1865 <!-- .LP -->
1866 To set the line drawing components of a given GC, use
1867 <xref linkend='XSetLineAttributes' xrefstyle='select: title'/>.
1868 </para>
1869 <indexterm significance="preferred"><primary>XSetLineAttributes</primary></indexterm>
1870 <!-- .sM -->
1871 <funcsynopsis id='XSetLineAttributes'>
1872 <funcprototype>
1873   <funcdef><function>XSetLineAttributes</function></funcdef>
1874   <paramdef>Display<parameter> *display</parameter></paramdef>
1875   <paramdef>GC<parameter> gc</parameter></paramdef>
1876   <paramdef>unsignedint<parameter> line_width</parameter></paramdef>
1877   <paramdef>int<parameter> line_style</parameter></paramdef>
1878   <paramdef>int<parameter> cap_style</parameter></paramdef>
1879   <paramdef>int<parameter> join_style</parameter></paramdef>
1880 </funcprototype>
1881 </funcsynopsis>
1882 <!-- .FN -->
1883 <variablelist>
1884   <varlistentry>
1885     <term>
1886       <emphasis remap='I'>display</emphasis>
1887     </term>
1888     <listitem>
1889       <para>
1890 Specifies the connection to the X server.
1891       </para>
1892     </listitem>
1893   </varlistentry>
1894   <varlistentry>
1895     <term>
1896       <emphasis remap='I'>gc</emphasis>
1897     </term>
1898     <listitem>
1899       <para>
1900 Specifies the GC.
1901       </para>
1902     </listitem>
1903   </varlistentry>
1904   <varlistentry>
1905     <term>
1906       <emphasis remap='I'>line_width</emphasis>
1907     </term>
1908     <listitem>
1909       <para>
1910 Specifies the line-width you want to set for the specified GC.
1911       </para>
1912     </listitem>
1913   </varlistentry>
1914   <varlistentry>
1915     <term>
1916       <emphasis remap='I'>line_style</emphasis>
1917     </term>
1918     <listitem>
1919       <para>
1920 Specifies the line-style you want to set for the specified GC.
1921 You can pass
1922 <symbol>LineSolid</symbol>,
1923 <symbol>LineOnOffDash</symbol>,
1924 or
1925 <symbol>LineDoubleDash</symbol>.
1926       </para>
1927     </listitem>
1928   </varlistentry>
1929   <varlistentry>
1930     <term>
1931       <emphasis remap='I'>cap_style</emphasis>
1932     </term>
1933     <listitem>
1934       <para>
1935 Specifies the line-style and cap-style you want to set for the specified GC.
1936 You can pass
1937 <symbol>CapNotLast</symbol>,
1938 <symbol>CapButt</symbol>,
1939 <symbol>CapRound</symbol>,
1940 or
1941 <symbol>CapProjecting</symbol>.
1942       </para>
1943     </listitem>
1944   </varlistentry>
1945   <varlistentry>
1946     <term>
1947       <emphasis remap='I'>join_style</emphasis>
1948     </term>
1949     <listitem>
1950       <para>
1951 Specifies the line join-style you want to set for the specified GC.
1952 You can pass
1953 <symbol>JoinMiter</symbol>,
1954 <symbol>JoinRound</symbol>,
1955 or
1956 <symbol>JoinBevel</symbol>.
1957     </para>
1958   </listitem>
1959   </varlistentry>
1960 </variablelist>
1961 <para>
1962 <!-- .LP -->
1963 <!-- .eM -->
1964 <xref linkend='XSetLineAttributes' xrefstyle='select: title'/>
1965 can generate
1966 <errorname>BadAlloc</errorname>,
1967 <errorname>BadGC</errorname>,
1968 and
1969 <errorname>BadValue</errorname>
1970 errors.
1971 </para>
1972 <para>
1973 <!-- .LP -->
1974 <!-- .sp -->
1975 To set the dash-offset and dash-list for dashed line styles of a given GC, use
1976 <xref linkend='XSetDashes' xrefstyle='select: title'/>.
1977 </para>
1978 <indexterm significance="preferred"><primary>XSetDashes</primary></indexterm>
1979 <!-- .sM -->
1980 <funcsynopsis id='XSetDashes'>
1981 <funcprototype>
1982   <funcdef><function>XSetDashes</function></funcdef>
1983   <paramdef>Display<parameter> *display</parameter></paramdef>
1984   <paramdef>GC<parameter> gc</parameter></paramdef>
1985   <paramdef>int<parameter> dash_offset</parameter></paramdef>
1986   <paramdef>char<parameter> dash_list[]</parameter></paramdef>
1987   <paramdef>int<parameter> n</parameter></paramdef>
1988 </funcprototype>
1989 </funcsynopsis>
1990 <!-- .FN -->
1991 <variablelist>
1992   <varlistentry>
1993     <term>
1994       <emphasis remap='I'>display</emphasis>
1995     </term>
1996     <listitem>
1997       <para>
1998 Specifies the connection to the X server.
1999       </para>
2000     </listitem>
2001   </varlistentry>
2002   <varlistentry>
2003     <term>
2004       <emphasis remap='I'>gc</emphasis>
2005     </term>
2006     <listitem>
2007       <para>
2008 Specifies the GC.
2009       </para>
2010     </listitem>
2011   </varlistentry>
2012   <varlistentry>
2013     <term>
2014       <emphasis remap='I'>dash_offset</emphasis>
2015     </term>
2016     <listitem>
2017       <para>
2018 Specifies the phase of the pattern for the dashed line-style you want to set
2019 for the specified GC.
2020       </para>
2021     </listitem>
2022   </varlistentry>
2023   <varlistentry>
2024     <term>
2025       <emphasis remap='I'>dash_list</emphasis>
2026     </term>
2027     <listitem>
2028       <para>
2029 Specifies the dash-list for the dashed line-style
2030 you want to set for the specified GC.
2031       </para>
2032     </listitem>
2033   </varlistentry>
2034   <varlistentry>
2035     <term>
2036       <emphasis remap='I'>n</emphasis>
2037     </term>
2038     <listitem>
2039       <para>
2040 Specifies the number of elements in dash_list.
2041     </para>
2042   </listitem>
2043   </varlistentry>
2044 </variablelist>
2045 <para>
2046 <!-- .LP -->
2047 <!-- .eM  -->
2048 The
2049 <xref linkend='XSetDashes' xrefstyle='select: title'/>
2050 function sets the dash-offset and dash-list attributes for dashed line styles
2051 in the specified GC.
2052 There must be at least one element in the specified dash_list,
2053 or a
2054 <errorname>BadValue</errorname>
2055 error results.
2056 The initial and alternating elements (second, fourth, and so on)
2057 of the dash_list are the even dashes, and
2058 the others are the odd dashes.
2059 Each element specifies a dash length in pixels.
2060 All of the elements must be nonzero,
2061 or a
2062 <errorname>BadValue</errorname>
2063 error results.
2064 Specifying an odd-length list is equivalent to specifying the same list
2065 concatenated with itself to produce an even-length list.
2066 </para>
2067 <para>
2068 <!-- .LP -->
2069 The dash-offset defines the phase of the pattern,
2070 specifying how many pixels into the dash-list the pattern
2071 should actually begin in any single graphics request.
2072 Dashing is continuous through path elements combined with a join-style
2073 but is reset to the dash-offset between each sequence of joined lines.
2074 </para>
2075 <para>
2076 <!-- .LP -->
2077 The unit of measure for dashes is the same for the ordinary coordinate system.
2078 Ideally, a dash length is measured along the slope of the line, but implementations
2079 are only required to match this ideal for horizontal and vertical lines.
2080 Failing the ideal semantics, it is suggested that the length be measured along the
2081 major axis of the line.
2082 The major axis is defined as the x axis for lines drawn at an angle of between
2083 &minus;45 and +45 degrees or between 135 and 225 degrees from the x axis.
2084 For all other lines, the major axis is the y axis.
2085 </para>
2086 <para>
2087 <!-- .LP -->
2088 <xref linkend='XSetDashes' xrefstyle='select: title'/>
2089 can generate
2090 <errorname>BadAlloc</errorname>,
2091 <errorname>BadGC</errorname>,
2092 and
2093 <errorname>BadValue</errorname>
2094 errors.
2095 </para>
2096 </sect2>
2097 <sect2 id='Setting_the_Fill_Style_and_Fill_Rule'>
2098 <title>Setting the Fill Style and Fill Rule</title>
2099 <!-- .XS -->
2100 <!-- (SN Setting the Fill Style and Fill Rule  -->
2101 <!-- .XE -->
2102 <para>
2103 <!-- .LP -->
2104 To set the fill-style of a given GC, use
2105 <xref linkend='XSetFillStyle' xrefstyle='select: title'/>.
2106 </para>
2107 <indexterm significance="preferred"><primary>XSetFillStyle</primary></indexterm>
2108 <!-- .sM -->
2109 <funcsynopsis id='XSetFillStyle'>
2110 <funcprototype>
2111   <funcdef><function>XSetFillStyle</function></funcdef>
2112   <paramdef>Display<parameter> *display</parameter></paramdef>
2113   <paramdef>GC<parameter> gc</parameter></paramdef>
2114   <paramdef>int<parameter> fill_style</parameter></paramdef>
2115 </funcprototype>
2116 </funcsynopsis>
2117 <!-- .FN -->
2118 <variablelist>
2119   <varlistentry>
2120     <term>
2121       <emphasis remap='I'>display</emphasis>
2122     </term>
2123     <listitem>
2124       <para>
2125 Specifies the connection to the X server.
2126       </para>
2127     </listitem>
2128   </varlistentry>
2129   <varlistentry>
2130     <term>
2131       <emphasis remap='I'>gc</emphasis>
2132     </term>
2133     <listitem>
2134       <para>
2135 Specifies the GC.
2136       </para>
2137     </listitem>
2138   </varlistentry>
2139   <varlistentry>
2140     <term>
2141       <emphasis remap='I'>fill_style</emphasis>
2142     </term>
2143     <listitem>
2144       <para>
2145 Specifies the fill-style you want to set for the specified GC.
2146 You can pass
2147 <symbol>FillSolid</symbol>,
2148 <symbol>FillTiled</symbol>,
2149 <symbol>FillStippled</symbol>,
2150 or
2151 <symbol>FillOpaqueStippled</symbol>.
2152     </para>
2153   </listitem>
2154   </varlistentry>
2155 </variablelist>
2156 <para>
2157 <!-- .LP -->
2158 <!-- .eM -->
2159 <xref linkend='XSetFillStyle' xrefstyle='select: title'/>
2160 can generate
2161 <errorname>BadAlloc</errorname>,
2162 <errorname>BadGC</errorname>,
2163 and
2164 <errorname>BadValue</errorname>
2165 errors.
2166 </para>
2167 <para>
2168 <!-- .LP -->
2169 <!-- .sp -->
2170 To set the fill-rule of a given GC, use
2171 <xref linkend='XSetFillRule' xrefstyle='select: title'/>.
2172 </para>
2173 <indexterm significance="preferred"><primary>XSetFillRule</primary></indexterm>
2174 <!-- .sM -->
2175 <funcsynopsis id='XSetFillRule'>
2176 <funcprototype>
2177   <funcdef><function>XSetFillRule</function></funcdef>
2178   <paramdef>Display<parameter> *display</parameter></paramdef>
2179   <paramdef>GC<parameter> gc</parameter></paramdef>
2180   <paramdef>int<parameter> fill_rule</parameter></paramdef>
2181 </funcprototype>
2182 </funcsynopsis>
2183 <!-- .FN -->
2184 <variablelist>
2185   <varlistentry>
2186     <term>
2187       <emphasis remap='I'>display</emphasis>
2188     </term>
2189     <listitem>
2190       <para>
2191 Specifies the connection to the X server.
2192       </para>
2193     </listitem>
2194   </varlistentry>
2195   <varlistentry>
2196     <term>
2197       <emphasis remap='I'>gc</emphasis>
2198     </term>
2199     <listitem>
2200       <para>
2201 Specifies the GC.
2202       </para>
2203     </listitem>
2204   </varlistentry>
2205   <varlistentry>
2206     <term>
2207       <emphasis remap='I'>fill_rule</emphasis>
2208     </term>
2209     <listitem>
2210       <para>
2211 Specifies the fill-rule you want to set for the specified GC.
2212 You can pass
2213 <symbol>EvenOddRule</symbol>
2214 or
2215 <symbol>WindingRule</symbol>.
2216     </para>
2217   </listitem>
2218   </varlistentry>
2219 </variablelist>
2220 <para>
2221 <!-- .LP -->
2222 <!-- .eM -->
2223 <xref linkend='XSetFillRule' xrefstyle='select: title'/>
2224 can generate
2225 <errorname>BadAlloc</errorname>,
2226 <errorname>BadGC</errorname>,
2227 and
2228 <errorname>BadValue</errorname>
2229 errors.
2230 </para>
2231 </sect2>
2232 <sect2 id='Setting_the_Fill_Tile_and_Stipple'>
2233 <title>Setting the Fill Tile and Stipple</title>
2234 <!-- .XS -->
2235 <!-- (SN Setting the Fill Tile and Stipple  -->
2236 <!-- .XE -->
2237 <para>
2238 <!-- .LP -->
2239 Some displays have hardware support for tiling or
2240 stippling with patterns of specific sizes.
2241 Tiling and stippling operations that restrict themselves to those specific
2242 sizes run much faster than such operations with arbitrary size patterns.
2243 Xlib provides functions that you can use to determine the best size,
2244 tile, or stipple for the display
2245 as well as to set the tile or stipple shape and the tile or stipple origin.
2246 </para>
2247 <para>
2248 <!-- .LP -->
2249 <!-- .sp -->
2250 To obtain the best size of a tile, stipple, or cursor, use
2251 <xref linkend='XQueryBestSize' xrefstyle='select: title'/>.
2252 </para>
2253 <indexterm significance="preferred"><primary>XQueryBestSize</primary></indexterm>
2254 <!-- .sM -->
2255 <funcsynopsis id='XQueryBestSize'>
2256 <funcprototype>
2257   <funcdef>Status <function>XQueryBestSize</function></funcdef>
2258   <paramdef>Display<parameter> *display</parameter></paramdef>
2259   <paramdef>int<parameter> class</parameter></paramdef>
2260   <paramdef>Drawable<parameter> which_screen</parameter></paramdef>
2261   <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
2262   <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
2263 </funcprototype>
2264 </funcsynopsis>
2265 <!-- .FN -->
2266 <variablelist>
2267   <varlistentry>
2268     <term>
2269       <emphasis remap='I'>display</emphasis>
2270     </term>
2271     <listitem>
2272       <para>
2273 Specifies the connection to the X server.
2274       </para>
2275     </listitem>
2276   </varlistentry>
2277   <varlistentry>
2278     <term>
2279       <emphasis remap='I'>class</emphasis>
2280     </term>
2281     <listitem>
2282       <para>
2283 Specifies the class that you are interested in.
2284 You can pass
2285 <symbol>TileShape</symbol>,
2286 <symbol>CursorShape</symbol>,
2287 or
2288 <symbol>StippleShape</symbol>.
2289       </para>
2290     </listitem>
2291   </varlistentry>
2292   <varlistentry>
2293     <term>
2294       <emphasis remap='I'>which_screen</emphasis>
2295     </term>
2296     <listitem>
2297       <para>
2298 Specifies any drawable on the screen.
2299       </para>
2300     </listitem>
2301   </varlistentry>
2302   <varlistentry>
2303     <term>
2304       <emphasis remap='I'>width</emphasis>
2305     </term>
2306     <listitem>
2307       <para>
2308 <!-- .br -->
2309 <!-- .ns -->
2310       </para>
2311     </listitem>
2312   </varlistentry>
2313   <varlistentry>
2314     <term>
2315       <emphasis remap='I'>height</emphasis>
2316     </term>
2317     <listitem>
2318       <para>
2319 Specify the width and height.
2320       </para>
2321     </listitem>
2322   </varlistentry>
2323   <varlistentry>
2324     <term>
2325       <emphasis remap='I'>width_return</emphasis>
2326     </term>
2327     <listitem>
2328       <para>
2329 <!-- .br -->
2330 <!-- .ns -->
2331       </para>
2332     </listitem>
2333   </varlistentry>
2334   <varlistentry>
2335     <term>
2336       <emphasis remap='I'>height_return</emphasis>
2337     </term>
2338     <listitem>
2339       <para>
2340 Return the width and height of the object best supported
2341 by the display hardware.
2342     </para>
2343   </listitem>
2344   </varlistentry>
2345 </variablelist>
2346 <para>
2347 <!-- .LP -->
2348 <!-- .eM -->
2349 The
2350 <xref linkend='XQueryBestSize' xrefstyle='select: title'/>
2351 function returns the best or closest size to the specified size.
2352 For
2353 <symbol>CursorShape</symbol>,
2354 this is the largest size that can be fully displayed on the screen specified by
2355 which_screen.
2356 For
2357 <symbol>TileShape</symbol>,
2358 this is the size that can be tiled fastest.
2359 For
2360 <symbol>StippleShape</symbol>,
2361 this is the size that can be stippled fastest.
2362 For
2363 <symbol>CursorShape</symbol>,
2364 the drawable indicates the desired screen.
2365 For
2366 <symbol>TileShape</symbol>
2367 and
2368 <symbol>StippleShape</symbol>,
2369 the drawable indicates the screen and possibly the window class and depth.
2370 An
2371 <symbol>InputOnly</symbol>
2372 window cannot be used as the drawable for
2373 <symbol>TileShape</symbol>
2374 or
2375 <symbol>StippleShape</symbol>,
2376 or a
2377 <errorname>BadMatch</errorname>
2378 error results.
2379 </para>
2380 <para>
2381 <!-- .LP -->
2382 <xref linkend='XQueryBestSize' xrefstyle='select: title'/>
2383 can generate
2384 <errorname>BadDrawable</errorname>,
2385 <errorname>BadMatch</errorname>,
2386 and
2387 <errorname>BadValue</errorname>
2388 errors.
2389 </para>
2390 <para>
2391 <!-- .LP -->
2392 <!-- .sp -->
2393 To obtain the best fill tile shape, use
2394 <xref linkend='XQueryBestTile' xrefstyle='select: title'/>.
2395 </para>
2396 <indexterm significance="preferred"><primary>XQueryBestTile</primary></indexterm>
2397 <!-- .sM -->
2398 <funcsynopsis id='XQueryBestTile'>
2399 <funcprototype>
2400   <funcdef>Status <function>XQueryBestTile</function></funcdef>
2401   <paramdef>Display<parameter> *display</parameter></paramdef>
2402   <paramdef>Drawable<parameter> which_screen</parameter></paramdef>
2403   <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
2404   <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
2405 </funcprototype>
2406 </funcsynopsis>
2407 <!-- .FN -->
2408 <variablelist>
2409   <varlistentry>
2410     <term>
2411       <emphasis remap='I'>display</emphasis>
2412     </term>
2413     <listitem>
2414       <para>
2415 Specifies the connection to the X server.
2416       </para>
2417     </listitem>
2418   </varlistentry>
2419   <varlistentry>
2420     <term>
2421       <emphasis remap='I'>which_screen</emphasis>
2422     </term>
2423     <listitem>
2424       <para>
2425 Specifies any drawable on the screen.
2426       </para>
2427     </listitem>
2428   </varlistentry>
2429   <varlistentry>
2430     <term>
2431       <emphasis remap='I'>width</emphasis>
2432     </term>
2433     <listitem>
2434       <para>
2435 <!-- .br -->
2436 <!-- .ns -->
2437       </para>
2438     </listitem>
2439   </varlistentry>
2440   <varlistentry>
2441     <term>
2442       <emphasis remap='I'>height</emphasis>
2443     </term>
2444     <listitem>
2445       <para>
2446 Specify the width and height.
2447       </para>
2448     </listitem>
2449   </varlistentry>
2450   <varlistentry>
2451     <term>
2452       <emphasis remap='I'>width_return</emphasis>
2453     </term>
2454     <listitem>
2455       <para>
2456 <!-- .br -->
2457 <!-- .ns -->
2458       </para>
2459     </listitem>
2460   </varlistentry>
2461   <varlistentry>
2462     <term>
2463       <emphasis remap='I'>height_return</emphasis>
2464     </term>
2465     <listitem>
2466       <para>
2467 Return the width and height of the object best supported
2468 by the display hardware.
2469     </para>
2470   </listitem>
2471   </varlistentry>
2472 </variablelist>
2473 <para>
2474 <!-- .LP -->
2475 <!-- .eM -->
2476 The
2477 <xref linkend='XQueryBestTile' xrefstyle='select: title'/>
2478 function returns the best or closest size, that is, the size that can be
2479 tiled fastest on the screen specified by which_screen.
2480 The drawable indicates the screen and possibly the window class and depth.
2481 If an
2482 <symbol>InputOnly</symbol>
2483 window is used as the drawable, a
2484 <errorname>BadMatch</errorname>
2485 error results.
2486 </para>
2487 <para>
2488 <!-- .LP -->
2489 <xref linkend='XQueryBestTile' xrefstyle='select: title'/>
2490 can generate
2491 <errorname>BadDrawable</errorname>
2492 and
2493 <errorname>BadMatch</errorname>
2494 errors.
2495 </para>
2496 <para>
2497 <!-- .LP -->
2498 <!-- .sp -->
2499 To obtain the best stipple shape, use
2500 <xref linkend='XQueryBestStipple' xrefstyle='select: title'/>.
2501 </para>
2502 <indexterm significance="preferred"><primary>XQueryBestStipple</primary></indexterm>
2503 <!-- .sM -->
2504 <funcsynopsis id='XQueryBestStipple'>
2505 <funcprototype>
2506   <funcdef>Status <function>XQueryBestStipple</function></funcdef>
2507   <paramdef>Display<parameter> *display</parameter></paramdef>
2508   <paramdef>Drawable<parameter> which_screen</parameter></paramdef>
2509   <paramdef>unsignedintwidth,<parameter> height</parameter></paramdef>
2510   <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
2511 </funcprototype>
2512 </funcsynopsis>
2513 <!-- .FN -->
2514 <variablelist>
2515   <varlistentry>
2516     <term>
2517       <emphasis remap='I'>display</emphasis>
2518     </term>
2519     <listitem>
2520       <para>
2521 Specifies the connection to the X server.
2522       </para>
2523     </listitem>
2524   </varlistentry>
2525   <varlistentry>
2526     <term>
2527       <emphasis remap='I'>which_screen</emphasis>
2528     </term>
2529     <listitem>
2530       <para>
2531 Specifies any drawable on the screen.
2532       </para>
2533     </listitem>
2534   </varlistentry>
2535   <varlistentry>
2536     <term>
2537       <emphasis remap='I'>width</emphasis>
2538     </term>
2539     <listitem>
2540       <para>
2541 <!-- .br -->
2542 <!-- .ns -->
2543       </para>
2544     </listitem>
2545   </varlistentry>
2546   <varlistentry>
2547     <term>
2548       <emphasis remap='I'>height</emphasis>
2549     </term>
2550     <listitem>
2551       <para>
2552 Specify the width and height.
2553       </para>
2554     </listitem>
2555   </varlistentry>
2556   <varlistentry>
2557     <term>
2558       <emphasis remap='I'>width_return</emphasis>
2559     </term>
2560     <listitem>
2561       <para>
2562 <!-- .br -->
2563 <!-- .ns -->
2564       </para>
2565     </listitem>
2566   </varlistentry>
2567   <varlistentry>
2568     <term>
2569       <emphasis remap='I'>height_return</emphasis>
2570     </term>
2571     <listitem>
2572       <para>
2573 Return the width and height of the object best supported
2574 by the display hardware.
2575     </para>
2576   </listitem>
2577   </varlistentry>
2578 </variablelist>
2579 <para>
2580 <!-- .LP -->
2581 <!-- .eM -->
2582 The
2583 <xref linkend='XQueryBestStipple' xrefstyle='select: title'/>
2584 function returns the best or closest size, that is, the size that can be
2585 stippled fastest on the screen specified by which_screen.
2586 The drawable indicates the screen and possibly the window class and depth.
2587 If an
2588 <symbol>InputOnly</symbol>
2589 window is used as the drawable, a
2590 <errorname>BadMatch</errorname>
2591 error results.
2592 </para>
2593 <para>
2594 <!-- .LP -->
2595 <xref linkend='XQueryBestStipple' xrefstyle='select: title'/>
2596 can generate
2597 <errorname>BadDrawable</errorname>
2598 and
2599 <errorname>BadMatch</errorname>
2600 errors.
2601 </para>
2602 <para>
2603 <!-- .LP -->
2604 <!-- .sp -->
2605 To set the fill tile of a given GC, use
2606 <xref linkend='XSetTile' xrefstyle='select: title'/>.
2607 </para>
2608 <indexterm significance="preferred"><primary>XSetTile</primary></indexterm>
2609 <!-- .sM -->
2610 <funcsynopsis id='XSetTile'>
2611 <funcprototype>
2612   <funcdef><function>XSetTile</function></funcdef>
2613   <paramdef>Display<parameter> *display</parameter></paramdef>
2614   <paramdef>GC<parameter> gc</parameter></paramdef>
2615   <paramdef>Pixmap<parameter> tile</parameter></paramdef>
2616 </funcprototype>
2617 </funcsynopsis>
2618 <!-- .FN -->
2619 <variablelist>
2620   <varlistentry>
2621     <term>
2622       <emphasis remap='I'>display</emphasis>
2623     </term>
2624     <listitem>
2625       <para>
2626 Specifies the connection to the X server.
2627       </para>
2628     </listitem>
2629   </varlistentry>
2630   <varlistentry>
2631     <term>
2632       <emphasis remap='I'>gc</emphasis>
2633     </term>
2634     <listitem>
2635       <para>
2636 Specifies the GC.
2637       </para>
2638     </listitem>
2639   </varlistentry>
2640   <varlistentry>
2641     <term>
2642       <emphasis remap='I'>tile</emphasis>
2643     </term>
2644     <listitem>
2645       <para>
2646 Specifies the fill tile you want to set for the specified GC.
2647     </para>
2648   </listitem>
2649   </varlistentry>
2650 </variablelist>
2651 <para>
2652 <!-- .LP -->
2653 <!-- .eM -->
2654 The tile and GC must have the same depth,
2655 or a
2656 <errorname>BadMatch</errorname>
2657 error results.
2658 </para>
2659 <para>
2660 <!-- .LP -->
2661 <xref linkend='XSetTile' xrefstyle='select: title'/>
2662 can generate
2663 <errorname>BadAlloc</errorname>,
2664 <errorname>BadGC</errorname>,
2665 <errorname>BadMatch</errorname>,
2666 and
2667 <errorname>BadPixmap</errorname>
2668 errors.
2669 </para>
2670 <para>
2671 <!-- .LP -->
2672 <!-- .sp -->
2673 To set the stipple of a given GC, use
2674 <xref linkend='XSetStipple' xrefstyle='select: title'/>.
2675 </para>
2676 <indexterm significance="preferred"><primary>XSetStipple</primary></indexterm>
2677 <!-- .sM -->
2678 <funcsynopsis id='XSetStipple'>
2679 <funcprototype>
2680   <funcdef><function>XSetStipple</function></funcdef>
2681   <paramdef>Display<parameter> *display</parameter></paramdef>
2682   <paramdef>GC<parameter> gc</parameter></paramdef>
2683   <paramdef>Pixmap<parameter> stipple</parameter></paramdef>
2684 </funcprototype>
2685 </funcsynopsis>
2686 <!-- .FN -->
2687 <variablelist>
2688   <varlistentry>
2689     <term>
2690       <emphasis remap='I'>display</emphasis>
2691     </term>
2692     <listitem>
2693       <para>
2694 Specifies the connection to the X server.
2695       </para>
2696     </listitem>
2697   </varlistentry>
2698   <varlistentry>
2699     <term>
2700       <emphasis remap='I'>gc</emphasis>
2701     </term>
2702     <listitem>
2703       <para>
2704 Specifies the GC.
2705       </para>
2706     </listitem>
2707   </varlistentry>
2708   <varlistentry>
2709     <term>
2710       <emphasis remap='I'>stipple</emphasis>
2711     </term>
2712     <listitem>
2713       <para>
2714 Specifies the stipple you want to set for the specified GC.
2715     </para>
2716   </listitem>
2717   </varlistentry>
2718 </variablelist>
2719 <para>
2720 <!-- .LP -->
2721 <!-- .eM -->
2722 The stipple must have a depth of one,
2723 or a
2724 <errorname>BadMatch</errorname>
2725 error results.
2726 </para>
2727 <para>
2728 <!-- .LP -->
2729 <xref linkend='XSetStipple' xrefstyle='select: title'/>
2730 can generate
2731 <errorname>BadAlloc</errorname>,
2732 <errorname>BadGC</errorname>,
2733 <errorname>BadMatch</errorname>,
2734 and
2735 <errorname>BadPixmap</errorname>
2736 errors.
2737 </para>
2738 <para>
2739 <!-- .LP -->
2740 <!-- .sp -->
2741 To set the tile or stipple origin of a given GC, use
2742 <xref linkend='XSetTSOrigin' xrefstyle='select: title'/>.
2743 </para>
2744 <indexterm significance="preferred"><primary>XSetTSOrigin</primary></indexterm>
2745 <!-- .sM -->
2746 <funcsynopsis id='XSetTSOrigin'>
2747 <funcprototype>
2748   <funcdef><function>XSetTSOrigin</function></funcdef>
2749   <paramdef>Display<parameter> *display</parameter></paramdef>
2750   <paramdef>GC<parameter> gc</parameter></paramdef>
2751   <paramdef>intts_x_origin,<parameter> ts_y_origin</parameter></paramdef>
2752 </funcprototype>
2753 </funcsynopsis>
2754 <!-- .FN -->
2755 <variablelist>
2756   <varlistentry>
2757     <term>
2758       <emphasis remap='I'>display</emphasis>
2759     </term>
2760     <listitem>
2761       <para>
2762 Specifies the connection to the X server.
2763       </para>
2764     </listitem>
2765   </varlistentry>
2766   <varlistentry>
2767     <term>
2768       <emphasis remap='I'>gc</emphasis>
2769     </term>
2770     <listitem>
2771       <para>
2772 Specifies the GC.
2773       </para>
2774     </listitem>
2775   </varlistentry>
2776   <varlistentry>
2777     <term>
2778       <emphasis remap='I'>ts_x_origin</emphasis>
2779     </term>
2780     <listitem>
2781       <para>
2782 <!-- .br -->
2783 <!-- .ns -->
2784       </para>
2785     </listitem>
2786   </varlistentry>
2787   <varlistentry>
2788     <term>
2789       <emphasis remap='I'>ts_y_origin</emphasis>
2790     </term>
2791     <listitem>
2792       <para>
2793 Specify the x and y coordinates of the tile and stipple origin.
2794     </para>
2795   </listitem>
2796   </varlistentry>
2797 </variablelist>
2798 <para>
2799 <!-- .LP -->
2800 <!-- .eM -->
2801 When graphics requests call for tiling or stippling,
2802 the parent's origin will be interpreted relative to whatever destination
2803 drawable is specified in the graphics request.
2804 </para>
2805 <para>
2806 <!-- .LP -->
2807 <xref linkend='XSetTSOrigin' xrefstyle='select: title'/>
2808 can generate
2809 <errorname>BadAlloc</errorname>
2810 and
2811 <errorname>BadGC</errorname>
2812 errors.
2813 </para>
2814 </sect2>
2815 <sect2 id='Setting_the_Current_Font'>
2816 <title>Setting the Current Font</title>
2817 <!-- .XS -->
2818 <!-- (SN Setting the Current Font  -->
2819 <!-- .XE -->
2820 <para>
2821 <!-- .LP -->
2822 To set the current font of a given GC, use
2823 <xref linkend='XSetFont' xrefstyle='select: title'/>.
2824 </para>
2825 <indexterm significance="preferred"><primary>XSetFont</primary></indexterm>
2826 <!-- .sM -->
2827 <funcsynopsis id='XSetFont'>
2828 <funcprototype>
2829   <funcdef><function>XSetFont</function></funcdef>
2830   <paramdef>Display<parameter> *display</parameter></paramdef>
2831   <paramdef>GC<parameter> gc</parameter></paramdef>
2832   <paramdef>Font<parameter> font</parameter></paramdef>
2833 </funcprototype>
2834 </funcsynopsis>
2835 <!-- .FN -->
2836 <variablelist>
2837   <varlistentry>
2838     <term>
2839       <emphasis remap='I'>display</emphasis>
2840     </term>
2841     <listitem>
2842       <para>
2843 Specifies the connection to the X server.
2844       </para>
2845     </listitem>
2846   </varlistentry>
2847   <varlistentry>
2848     <term>
2849       <emphasis remap='I'>gc</emphasis>
2850     </term>
2851     <listitem>
2852       <para>
2853 Specifies the GC.
2854       </para>
2855     </listitem>
2856   </varlistentry>
2857   <varlistentry>
2858     <term>
2859       <emphasis remap='I'>font</emphasis>
2860     </term>
2861     <listitem>
2862       <para>
2863 Specifies the font.
2864     </para>
2865   </listitem>
2866   </varlistentry>
2867 </variablelist>
2868 <para>
2869 <!-- .LP -->
2870 <!-- .eM -->
2871 <xref linkend='XSetFont' xrefstyle='select: title'/>
2872 can generate
2873 <errorname>BadAlloc</errorname>,
2874 <errorname>BadFont</errorname>,
2875 and
2876 <errorname>BadGC</errorname>
2877 errors.
2878 </para>
2879 </sect2>
2880 <sect2 id="Setting_the_Clip_Region">
2881 <title>Setting the Clip Region</title>
2882 <!-- .XS -->
2883 <!-- (SN Setting the Clip Region  -->
2884 <!-- .XE -->
2885 <para>
2886 <!-- .LP -->
2887 Xlib provides functions that you can use to set the clip-origin
2888 and the clip-mask or set the clip-mask to a list of rectangles.
2889 </para>
2890 <para>
2891 <!-- .LP -->
2892 <!-- .sp -->
2893 To set the clip-origin of a given GC, use
2894 <xref linkend='XSetClipOrigin' xrefstyle='select: title'/>.
2895 </para>
2896 <indexterm significance="preferred"><primary>XSetClipOrigin</primary></indexterm>
2897 <!-- .sM -->
2898 <funcsynopsis id='XSetClipOrigin'>
2899 <funcprototype>
2900   <funcdef><function>XSetClipOrigin</function></funcdef>
2901   <paramdef>Display<parameter> *display</parameter></paramdef>
2902   <paramdef>GC<parameter> gc</parameter></paramdef>
2903   <paramdef>intclip_x_origin,<parameter> clip_y_origin</parameter></paramdef>
2904 </funcprototype>
2905 </funcsynopsis>
2906 <!-- .FN -->
2907 <variablelist>
2908   <varlistentry>
2909     <term>
2910       <emphasis remap='I'>display</emphasis>
2911     </term>
2912     <listitem>
2913       <para>
2914 Specifies the connection to the X server.
2915       </para>
2916     </listitem>
2917   </varlistentry>
2918   <varlistentry>
2919     <term>
2920       <emphasis remap='I'>gc</emphasis>
2921     </term>
2922     <listitem>
2923       <para>
2924 Specifies the GC.
2925       </para>
2926     </listitem>
2927   </varlistentry>
2928   <varlistentry>
2929     <term>
2930       <emphasis remap='I'>clip_x_origin</emphasis>
2931     </term>
2932     <listitem>
2933       <para>
2934 <!-- .br -->
2935 <!-- .ns -->
2936       </para>
2937     </listitem>
2938   </varlistentry>
2939   <varlistentry>
2940     <term>
2941       <emphasis remap='I'>clip_y_origin</emphasis>
2942     </term>
2943     <listitem>
2944       <para>
2945 Specify the x and y coordinates of the clip-mask origin.
2946     </para>
2947   </listitem>
2948   </varlistentry>
2949 </variablelist>
2950 <para>
2951 <!-- .LP -->
2952 <!-- .eM -->
2953 The clip-mask origin is interpreted relative to the origin of whatever
2954 destination drawable is specified in the graphics request.
2955 </para>
2956 <para>
2957 <!-- .LP -->
2958 <xref linkend='XSetClipOrigin' xrefstyle='select: title'/>
2959 can generate
2960 <errorname>BadAlloc</errorname>
2961 and
2962 <errorname>BadGC</errorname>
2963 errors.
2964 </para>
2965 <para>
2966 <!-- .LP -->
2967 <!-- .sp -->
2968 To set the clip-mask of a given GC to the specified pixmap, use
2969 <xref linkend='XSetClipMask' xrefstyle='select: title'/>.
2970 </para>
2971 <indexterm significance="preferred"><primary>XSetClipMask</primary></indexterm>
2972 <!-- .sM -->
2973 <funcsynopsis id='XSetClipMask'>
2974 <funcprototype>
2975   <funcdef><function>XSetClipMask</function></funcdef>
2976   <paramdef>Display<parameter> *display</parameter></paramdef>
2977   <paramdef>GC<parameter> gc</parameter></paramdef>
2978   <paramdef>Pixmap<parameter> pixmap</parameter></paramdef>
2979 </funcprototype>
2980 </funcsynopsis>
2981 <!-- .FN -->
2982 <variablelist>
2983   <varlistentry>
2984     <term>
2985       <emphasis remap='I'>display</emphasis>
2986     </term>
2987     <listitem>
2988       <para>
2989 Specifies the connection to the X server.
2990       </para>
2991     </listitem>
2992   </varlistentry>
2993   <varlistentry>
2994     <term>
2995       <emphasis remap='I'>gc</emphasis>
2996     </term>
2997     <listitem>
2998       <para>
2999 Specifies the GC.
3000       </para>
3001     </listitem>
3002   </varlistentry>
3003   <varlistentry>
3004     <term>
3005       <emphasis remap='I'>pixmap</emphasis>
3006     </term>
3007     <listitem>
3008       <para>
3009 Specifies the pixmap or
3010 <symbol>None</symbol>.
3011     </para>
3012   </listitem>
3013   </varlistentry>
3014 </variablelist>
3015 <para>
3016 <!-- .LP -->
3017 <!-- .eM -->
3018 If the clip-mask is set to
3019 <symbol>None</symbol>,
3020 the pixels are always drawn (regardless of the clip-origin).
3021 </para>
3022 <para>
3023 <!-- .LP -->
3024 <xref linkend='XSetClipMask' xrefstyle='select: title'/>
3025 can generate
3026 <errorname>BadAlloc</errorname>,
3027 <errorname>BadGC</errorname>,
3028 <errorname>BadMatch</errorname>,
3029 and
3030 <errorname>BadPixmap</errorname>
3031 errors.
3032 </para>
3033 <para>
3034 <!-- .LP -->
3035 <!-- .sp -->
3036 To set the clip-mask of a given GC to the specified list of rectangles, use
3037 <xref linkend='XSetClipRectangles' xrefstyle='select: title'/>.
3038 </para>
3039 <indexterm significance="preferred"><primary>XSetClipRectangles</primary></indexterm>
3040 <!-- .sM -->
3041 <funcsynopsis id='XSetClipRectangles'>
3042 <funcprototype>
3043   <funcdef><function>XSetClipRectangles</function></funcdef>
3044   <paramdef>Display<parameter> *display</parameter></paramdef>
3045   <paramdef>GC<parameter> gc</parameter></paramdef>
3046   <paramdef>intclip_x_origin,<parameter> clip_y_origin</parameter></paramdef>
3047   <paramdef>XRectangle<parameter> rectangles[]</parameter></paramdef>
3048   <paramdef>int<parameter> n</parameter></paramdef>
3049   <paramdef>int<parameter> ordering</parameter></paramdef>
3050 </funcprototype>
3051 </funcsynopsis>
3052 <!-- .FN -->
3053 <variablelist>
3054   <varlistentry>
3055     <term>
3056       <emphasis remap='I'>display</emphasis>
3057     </term>
3058     <listitem>
3059       <para>
3060 Specifies the connection to the X server.
3061       </para>
3062     </listitem>
3063   </varlistentry>
3064   <varlistentry>
3065     <term>
3066       <emphasis remap='I'>gc</emphasis>
3067     </term>
3068     <listitem>
3069       <para>
3070 Specifies the GC.
3071       </para>
3072     </listitem>
3073   </varlistentry>
3074   <varlistentry>
3075     <term>
3076       <emphasis remap='I'>clip_x_origin</emphasis>
3077     </term>
3078     <listitem>
3079       <para>
3080 <!-- .br -->
3081 <!-- .ns -->
3082       </para>
3083     </listitem>
3084   </varlistentry>
3085   <varlistentry>
3086     <term>
3087       <emphasis remap='I'>clip_y_origin</emphasis>
3088     </term>
3089     <listitem>
3090       <para>
3091 Specify the x and y coordinates of the clip-mask origin.
3092       </para>
3093     </listitem>
3094   </varlistentry>
3095   <varlistentry>
3096     <term>
3097       <emphasis remap='I'>rectangles</emphasis>
3098     </term>
3099     <listitem>
3100       <para>
3101 Specifies an array of rectangles that define the clip-mask.
3102       </para>
3103     </listitem>
3104   </varlistentry>
3105   <varlistentry>
3106     <term>
3107       <emphasis remap='I'>n</emphasis>
3108     </term>
3109     <listitem>
3110       <para>
3111 Specifies the number of rectangles.
3112       </para>
3113     </listitem>
3114   </varlistentry>
3115   <varlistentry>
3116     <term>
3117       <emphasis remap='I'>ordering</emphasis>
3118     </term>
3119     <listitem>
3120       <para>
3121 Specifies the ordering relations on the rectangles.
3122 You can pass
3123 <symbol>Unsorted</symbol>,
3124 <symbol>YSorted</symbol>,
3125 <symbol>YXSorted</symbol>,
3126 or
3127 <symbol>YXBanded</symbol>.
3128     </para>
3129   </listitem>
3130   </varlistentry>
3131 </variablelist>
3132 <para>
3133 <!-- .LP -->
3134 <!-- .eM -->
3135 The
3136 <xref linkend='XSetClipRectangles' xrefstyle='select: title'/>
3137 function changes the clip-mask in the specified GC
3138 to the specified list of rectangles and sets the clip origin.
3139 The output is clipped to remain contained within the
3140 rectangles.
3141 The clip-origin is interpreted relative to the origin of
3142 whatever destination drawable is specified in a graphics request.
3143 The rectangle coordinates are interpreted relative to the clip-origin.
3144 The rectangles should be nonintersecting, or the graphics results will be
3145 undefined.
3146 Note that the list of rectangles can be empty,
3147 which effectively disables output.
3148 This is the opposite of passing
3149 <symbol>None</symbol>
3150 as the clip-mask in
3151 <xref linkend='XCreateGC' xrefstyle='select: title'/>,
3152 <xref linkend='XChangeGC' xrefstyle='select: title'/>,
3153 and
3154 <xref linkend='XSetClipMask' xrefstyle='select: title'/>.
3155 </para>
3156 <para>
3157 <!-- .LP -->
3158 If known by the client, ordering relations on the rectangles can be
3159 specified with the ordering argument.
3160 This may provide faster operation
3161 by the server.
3162 If an incorrect ordering is specified, the X server may generate a
3163 <errorname>BadMatch</errorname>
3164 error, but it is not required to do so.
3165 If no error is generated, the graphics
3166 results are undefined.
3167 <symbol>Unsorted</symbol>
3168 means the rectangles are in arbitrary order.
3169 <symbol>YSorted</symbol>
3170 means that the rectangles are nondecreasing in their Y origin.
3171 <symbol>YXSorted</symbol>
3172 additionally constrains
3173 <symbol>YSorted</symbol>
3174 order in that all
3175 rectangles with an equal Y origin are nondecreasing in their X
3176 origin.
3177 <symbol>YXBanded</symbol>
3178 additionally constrains
3179 <symbol>YXSorted</symbol>
3180 by requiring that,
3181 for every possible Y scanline, all rectangles that include that
3182 scanline have an identical Y origins and Y extents.
3183 </para>
3184 <para>
3185 <!-- .LP -->
3186 <xref linkend='XSetClipRectangles' xrefstyle='select: title'/>
3187 can generate
3188 <errorname>BadAlloc</errorname>,
3189 <errorname>BadGC</errorname>,
3190 <errorname>BadMatch</errorname>,
3191 and
3192 <errorname>BadValue</errorname>
3193 errors.
3194 </para>
3195 <para>
3196 <!-- .LP -->
3197 Xlib provides a set of basic functions for performing
3198 region arithmetic.
3199 For information about these functions,
3200 see <link linkend="Manipulating_Regions">section 16.5</link>.
3201 </para>
3202 </sect2>
3203 <sect2 id='Setting_the_Arc_Mode_Subwindow_Mode_and_Graphics_Exposure'>
3204 <title>Setting the Arc Mode, Subwindow Mode, and Graphics Exposure</title>
3205 <!-- .XS -->
3206 <!-- (SN Setting the Arc Mode, Subwindow Mode, and Graphics Exposure  -->
3207 <!-- .XE -->
3208 <para>
3209 <!-- .LP -->
3210 To set the arc mode of a given GC, use
3211 <xref linkend='XSetArcMode' xrefstyle='select: title'/>.
3212 </para>
3213 <indexterm significance="preferred"><primary>XSetArcMode</primary></indexterm>
3214 <!-- .sM -->
3215 <funcsynopsis id='XSetArcMode'>
3216 <funcprototype>
3217   <funcdef><function>XSetArcMode</function></funcdef>
3218   <paramdef>Display<parameter> *display</parameter></paramdef>
3219   <paramdef>GC<parameter> gc</parameter></paramdef>
3220   <paramdef>int<parameter> arc_mode</parameter></paramdef>
3221 </funcprototype>
3222 </funcsynopsis>
3223 <!-- .FN -->
3224 <variablelist>
3225   <varlistentry>
3226     <term>
3227       <emphasis remap='I'>display</emphasis>
3228     </term>
3229     <listitem>
3230       <para>
3231 Specifies the connection to the X server.
3232       </para>
3233     </listitem>
3234   </varlistentry>
3235   <varlistentry>
3236     <term>
3237       <emphasis remap='I'>gc</emphasis>
3238     </term>
3239     <listitem>
3240       <para>
3241 Specifies the GC.
3242       </para>
3243     </listitem>
3244   </varlistentry>
3245   <varlistentry>
3246     <term>
3247       <emphasis remap='I'>arc_mode</emphasis>
3248     </term>
3249     <listitem>
3250       <para>
3251 Specifies the arc mode.
3252 You can pass
3253 <symbol>ArcChord</symbol>
3254 or
3255 <symbol>ArcPieSlice</symbol>.
3256     </para>
3257   </listitem>
3258   </varlistentry>
3259 </variablelist>
3260 <para>
3261 <!-- .LP -->
3262 <!-- .eM -->
3263 <xref linkend='XSetArcMode' xrefstyle='select: title'/>
3264 can generate
3265 <errorname>BadAlloc</errorname>,
3266 <errorname>BadGC</errorname>,
3267 and
3268 <errorname>BadValue</errorname>
3269 errors.
3270 </para>
3271 <para>
3272 <!-- .LP -->
3273 <!-- .sp -->
3274 To set the subwindow mode of a given GC, use
3275 <xref linkend='XSetSubwindowMode' xrefstyle='select: title'/>.
3276 </para>
3277 <indexterm significance="preferred"><primary>XSetSubwindowMode</primary></indexterm>
3278 <!-- .sM -->
3279 <funcsynopsis id='XSetSubwindowMode'>
3280 <funcprototype>
3281   <funcdef><function>XSetSubwindowMode</function></funcdef>
3282   <paramdef>Display<parameter> *display</parameter></paramdef>
3283   <paramdef>GC<parameter> gc</parameter></paramdef>
3284   <paramdef>int<parameter> subwindow_mode</parameter></paramdef>
3285 </funcprototype>
3286 </funcsynopsis>
3287 <!-- .FN -->
3288 <variablelist>
3289   <varlistentry>
3290     <term>
3291       <emphasis remap='I'>display</emphasis>
3292     </term>
3293     <listitem>
3294       <para>
3295 Specifies the connection to the X server.
3296       </para>
3297     </listitem>
3298   </varlistentry>
3299   <varlistentry>
3300     <term>
3301       <emphasis remap='I'>gc</emphasis>
3302     </term>
3303     <listitem>
3304       <para>
3305 Specifies the GC.
3306       </para>
3307     </listitem>
3308   </varlistentry>
3309   <varlistentry>
3310     <term>
3311       <emphasis remap='I'>subwindow_mode</emphasis>
3312     </term>
3313     <listitem>
3314       <para>
3315 Specifies the subwindow mode.
3316 You can pass
3317 <symbol>ClipByChildren</symbol>
3318 or
3319 <symbol>IncludeInferiors</symbol>.
3320     </para>
3321   </listitem>
3322   </varlistentry>
3323 </variablelist>
3324 <para>
3325 <!-- .LP -->
3326 <!-- .eM -->
3327 <xref linkend='XSetSubwindowMode' xrefstyle='select: title'/>
3328 can generate
3329 <errorname>BadAlloc</errorname>,
3330 <errorname>BadGC</errorname>,
3331 and
3332 <errorname>BadValue</errorname>
3333 errors.
3334 </para>
3335 <para>
3336 <!-- .LP -->
3337 <!-- .sp -->
3338 To set the graphics-exposures flag of a given GC, use
3339 <xref linkend='XSetGraphicsExposures' xrefstyle='select: title'/>.
3340 </para>
3341 <indexterm significance="preferred"><primary>XSetGraphicsExposures</primary></indexterm>
3342 <!-- .sM -->
3343 <funcsynopsis id='XSetGraphicsExposures'>
3344 <funcprototype>
3345   <funcdef><function>XSetGraphicsExposures</function></funcdef>
3346   <paramdef>Display<parameter> *display</parameter></paramdef>
3347   <paramdef>GC<parameter> gc</parameter></paramdef>
3348   <paramdef>Bool<parameter> graphics_exposures</parameter></paramdef>
3349 </funcprototype>
3350 </funcsynopsis>
3351 <!-- .FN -->
3352 <variablelist>
3353   <varlistentry>
3354     <term>
3355       <emphasis remap='I'>display</emphasis>
3356     </term>
3357     <listitem>
3358       <para>
3359 Specifies the connection to the X server.
3360       </para>
3361     </listitem>
3362   </varlistentry>
3363   <varlistentry>
3364     <term>
3365       <emphasis remap='I'>gc</emphasis>
3366     </term>
3367     <listitem>
3368       <para>
3369 Specifies the GC.
3370       </para>
3371     </listitem>
3372   </varlistentry>
3373   <varlistentry>
3374     <term>
3375       <emphasis remap='I'>graphics_exposures</emphasis>
3376     </term>
3377     <listitem>
3378       <para>
3379 Specifies a Boolean value that indicates whether you want
3380 <symbol>GraphicsExpose</symbol>
3381 and
3382 <symbol>NoExpose</symbol>
3383 events to be reported when calling
3384 <xref linkend='XCopyArea' xrefstyle='select: title'/>
3385 and
3386 <xref linkend='XCopyPlane' xrefstyle='select: title'/>
3387 with this GC.
3388     </para>
3389   </listitem>
3390   </varlistentry>
3391 </variablelist>
3392 <para>
3393 <!-- .LP -->
3394 <!-- .eM -->
3395 <xref linkend='XSetGraphicsExposures' xrefstyle='select: title'/>
3396 can generate
3397 <errorname>BadAlloc</errorname>,
3398 <errorname>BadGC</errorname>,
3399 and
3400 <errorname>BadValue</errorname>
3401 errors.
3402 <!-- .bp -->
3403
3404 </para>
3405 </sect2>
3406 </sect1>
3407 </chapter>