Pileus Git - ~andy/gtk/blob - docs/reference/gdk/tmpl/gcs.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Graphics Contexts
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Objects to encapsulate drawing properties
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 All drawing operations in GDK take a
  10 <firstterm>graphics context</firstterm> (GC) argument.
  11 A graphics context encapsulates information about
  12 the way things are drawn, such as the foreground
  13 color or line width. By using graphics contexts,
  14 the number of arguments to each drawing call is
  15 greatly reduced, and communication overhead is
  16 minimized, since identical arguments do not need
  17 to be passed repeatedly.
  18 </para>
  19 <para>
  20 Most values of a graphics context can be set at
  21 creation time by using gdk_gc_new_with_values(),
  22 or can be set one-by-one using functions such
  23 as gdk_gc_set_foreground(). A few of the values
  24 in the GC, such as the dash pattern, can only
  25 be set by the latter method.
  26 </para>
  27
  28 <!-- ##### SECTION See_Also ##### -->
  29 <para>
  30
  31 </para>
  32
  33 <!-- ##### SECTION Stability_Level ##### -->
  34
  35
  36 <!-- ##### SECTION Image ##### -->
  37
  38
  39 <!-- ##### STRUCT GdkGC ##### -->
  40 <para>
  41 The #GdkGC structure represents a graphics context.
  42 It is an opaque structure with no user-visible
  43 elements.
  44 </para>
  45
  46
  47 <!-- ##### STRUCT GdkGCValues ##### -->
  48 <para>
  49 The #GdkGCValues structure holds a set of values used
  50 to create or modify a graphics context.
  51 </para>
  52
  53 @foreground: the foreground color. Note that gdk_gc_get_values()
  54   only sets the pixel value.
  55 @background: the background color. Note that gdk_gc_get_values()
  56   only sets the pixel value.
  57 @font: the default font.
  58 @function: the bitwise operation used when drawing.
  59 @fill: the fill style.
  60 @tile: the tile pixmap.
  61 @stipple: the stipple bitmap.
  62 @clip_mask: the clip mask bitmap.
  63 @subwindow_mode: the subwindow mode.
  64 @ts_x_origin: the x origin of the tile or stipple.
  65 @ts_y_origin: the y origin of the tile or stipple.
  66 @clip_x_origin: the x origin of the clip mask.
  67 @clip_y_origin: the y origin of the clip mask.
  68 @graphics_exposures: whether graphics exposures are enabled.
  69 @line_width: the line width.
  70 @line_style: the way dashed lines are drawn.
  71 @cap_style: the way the ends of lines are drawn.
  72 @join_style: the way joins between lines are drawn.
  73
  74 <!-- ##### ENUM GdkGCValuesMask ##### -->
  75 <para>
  76 A set of bit flags used to indicate which fields
  77 #GdkGCValues structure are set.
  78 </para>
  79
  80 @GDK_GC_FOREGROUND: the @foreground is set.
  81 @GDK_GC_BACKGROUND: the @background is set.
  82 @GDK_GC_FONT: the @font is set.
  83 @GDK_GC_FUNCTION: the @function is set.
  84 @GDK_GC_FILL: the @fill is set.
  85 @GDK_GC_TILE: the @tile is set.
  86 @GDK_GC_STIPPLE: the @stipple is set.
  87 @GDK_GC_CLIP_MASK: the @clip_mask is set.
  88 @GDK_GC_SUBWINDOW: the @subwindow_mode is set.
  89 @GDK_GC_TS_X_ORIGIN: the @ts_x_origin is set.
  90 @GDK_GC_TS_Y_ORIGIN: the @ts_y_origin is set.
  91 @GDK_GC_CLIP_X_ORIGIN: the @clip_x_origin is set.
  92 @GDK_GC_CLIP_Y_ORIGIN: the @clip_y_origin is set.
  93 @GDK_GC_EXPOSURES: the @graphics_exposures is set.
  94 @GDK_GC_LINE_WIDTH: the @line_width is set.
  95 @GDK_GC_LINE_STYLE: the @line_style is set.
  96 @GDK_GC_CAP_STYLE: the @cap_style is set.
  97 @GDK_GC_JOIN_STYLE: the @join_style is set.
  98
  99 <!-- ##### ENUM GdkFunction ##### -->
 100 <para>
 101 Determines how the bit values for the source pixels are combined with
 102 the bit values for destination pixels to produce the final result. The
 103 sixteen values here correspond to the 16 different possible 2x2 truth
 104 tables.  Only a couple of these values are usually useful; for colored
 105 images, only %GDK_COPY, %GDK_XOR and %GDK_INVERT are generally
 106 useful. For bitmaps, %GDK_AND and %GDK_OR are also useful.
 107 </para>
 108
 109 @GDK_COPY: <literal>dst = src</literal>
 110 @GDK_INVERT: <literal>dst = NOT dst</literal>
 111 @GDK_XOR: <literal>dst = src XOR dst</literal>
 112 @GDK_CLEAR: <literal>dst = 0</literal>
 113 @GDK_AND: <literal>dst = dst AND src</literal>
 114 @GDK_AND_REVERSE: <literal>dst = src AND (NOT dst)</literal>
 115 @GDK_AND_INVERT: <literal>dst = (NOT src) AND dst</literal>
 116 @GDK_NOOP: <literal>dst = dst</literal>
 117 @GDK_OR: <literal>dst = src OR dst</literal>
 118 @GDK_EQUIV: <literal>dst = (NOT src) XOR dst</literal>
 119 @GDK_OR_REVERSE: <literal>dst = src OR (NOT dst)</literal>
 120 @GDK_COPY_INVERT: <literal>dst = NOT src</literal>
 121 @GDK_OR_INVERT: <literal>dst = (NOT src) OR dst</literal>
 122 @GDK_NAND: <literal>dst = (NOT src) OR (NOT dst)</literal>
 123 @GDK_NOR: <literal>dst = (NOT src) AND (NOT dst)</literal>
 124 @GDK_SET: <literal>dst = 1</literal>
 125
 126 <!-- ##### FUNCTION gdk_gc_new ##### -->
 127 <para>
 128 </para>
 129
 130 @drawable:
 131 @Returns:
 132
 133
 134 <!-- ##### FUNCTION gdk_gc_new_with_values ##### -->
 135 <para>
 136
 137 </para>
 138
 139 @drawable:
 140 @values:
 141 @values_mask:
 142 @Returns:
 143
 144
 145 <!-- ##### FUNCTION gdk_gc_get_screen ##### -->
 146 <para>
 147
 148 </para>
 149
 150 @gc:
 151 @Returns:
 152
 153
 154 <!-- ##### FUNCTION gdk_gc_set_values ##### -->
 155 <para>
 156
 157 </para>
 158
 159 @gc:
 160 @values:
 161 @values_mask:
 162
 163
 164 <!-- ##### FUNCTION gdk_gc_get_values ##### -->
 165 <para>
 166
 167 </para>
 168
 169 @gc:
 170 @values:
 171
 172
 173 <!-- ##### FUNCTION gdk_gc_set_foreground ##### -->
 174 <para>
 175
 176 </para>
 177
 178 @gc:
 179 @color:
 180
 181
 182 <!-- ##### FUNCTION gdk_gc_set_background ##### -->
 183 <para>
 184
 185 </para>
 186
 187 @gc:
 188 @color:
 189
 190
 191 <!-- ##### FUNCTION gdk_gc_set_rgb_fg_color ##### -->
 192 <para>
 193
 194 </para>
 195
 196 @gc:
 197 @color:
 198
 199
 200 <!-- ##### FUNCTION gdk_gc_set_rgb_bg_color ##### -->
 201 <para>
 202
 203 </para>
 204
 205 @gc:
 206 @color:
 207
 208
 209 <!-- ##### FUNCTION gdk_gc_set_function ##### -->
 210 <para>
 211
 212 </para>
 213
 214 @gc:
 215 @function:
 216
 217
 218 <!-- ##### FUNCTION gdk_gc_set_fill ##### -->
 219 <para>
 220
 221 </para>
 222
 223 @gc:
 224 @fill:
 225
 226
 227 <!-- ##### ENUM GdkFill ##### -->
 228 <para>
 229 Determines how primitives are drawn.
 230 </para>
 231
 232 @GDK_SOLID: draw with the foreground color.
 233 @GDK_TILED: draw with a tiled pixmap.
 234 @GDK_STIPPLED: draw using the stipple bitmap. Pixels corresponding
 235   to bits in the stipple bitmap that are set will be drawn in the
 236   foreground color; pixels corresponding to bits that are
 237   not set will be left untouched.
 238 @GDK_OPAQUE_STIPPLED: draw using the stipple bitmap. Pixels corresponding
 239   to bits in the stipple bitmap that are set will be drawn in the
 240   foreground color; pixels corresponding to bits that are
 241   not set will be drawn with the background color.
 242
 243 <!-- ##### FUNCTION gdk_gc_set_tile ##### -->
 244 <para>
 245
 246 </para>
 247
 248 @gc:
 249 @tile:
 250
 251
 252 <!-- ##### FUNCTION gdk_gc_set_stipple ##### -->
 253 <para>
 254
 255 </para>
 256
 257 @gc:
 258 @stipple:
 259
 260
 261 <!-- ##### FUNCTION gdk_gc_set_ts_origin ##### -->
 262 <para>
 263
 264 </para>
 265
 266 @gc:
 267 @x:
 268 @y:
 269
 270
 271 <!-- ##### FUNCTION gdk_gc_set_clip_origin ##### -->
 272 <para>
 273
 274 </para>
 275
 276 @gc:
 277 @x:
 278 @y:
 279
 280
 281 <!-- ##### FUNCTION gdk_gc_set_clip_mask ##### -->
 282 <para>
 283
 284 </para>
 285
 286 @gc:
 287 @mask:
 288
 289
 290 <!-- ##### FUNCTION gdk_gc_set_clip_rectangle ##### -->
 291 <para>
 292 </para>
 293
 294 @gc:
 295 @rectangle:
 296
 297
 298 <!-- ##### FUNCTION gdk_gc_set_clip_region ##### -->
 299 <para>
 300
 301 </para>
 302
 303 @gc:
 304 @region:
 305
 306
 307 <!-- ##### FUNCTION gdk_gc_set_subwindow ##### -->
 308 <para>
 309
 310 </para>
 311
 312 @gc:
 313 @mode:
 314
 315
 316 <!-- ##### ENUM GdkSubwindowMode ##### -->
 317 <para>
 318 Determines how drawing onto a window will affect child
 319 windows of that window.
 320 </para>
 321
 322 @GDK_CLIP_BY_CHILDREN: only draw onto the window itself.
 323 @GDK_INCLUDE_INFERIORS: draw onto the window and child windows.
 324
 325 <!-- ##### FUNCTION gdk_gc_set_exposures ##### -->
 326 <para>
 327
 328 </para>
 329
 330 @gc:
 331 @exposures:
 332
 333
 334 <!-- ##### FUNCTION gdk_gc_set_line_attributes ##### -->
 335 <para>
 336
 337 </para>
 338
 339 @gc:
 340 @line_width:
 341 @line_style:
 342 @cap_style:
 343 @join_style:
 344
 345
 346 <!-- ##### ENUM GdkLineStyle ##### -->
 347 <para>
 348 Determines how lines are drawn.
 349 </para>
 350
 351 @GDK_LINE_SOLID: lines are drawn solid.
 352 @GDK_LINE_ON_OFF_DASH: even segments are drawn; odd segments are not drawn.
 353 @GDK_LINE_DOUBLE_DASH: even segments are normally. Odd segments are drawn
 354   in the background color if the fill style is %GDK_SOLID, or in the background
 355   color masked by the stipple if the fill style is %GDK_STIPPLED.
 356
 357 <!-- ##### ENUM GdkCapStyle ##### -->
 358 <para>
 359 Determines how the end of lines are drawn.
 360 </para>
 361
 362 @GDK_CAP_NOT_LAST: the same as %GDK_CAP_BUTT for lines of non-zero width.
 363        for zero width lines, the final point on the line will not be drawn.
 364 @GDK_CAP_BUTT: the ends of the lines are drawn squared off and extending
 365        to the coordinates of the end point.
 366 @GDK_CAP_ROUND: the ends of the lines are drawn as semicircles with the
 367        diameter equal to the line width and centered at the end point.
 368 @GDK_CAP_PROJECTING: the ends of the lines are drawn squared off and extending
 369        half the width of the line beyond the end point.
 370
 371 <!-- ##### ENUM GdkJoinStyle ##### -->
 372 <para>
 373 Determines how the joins between segments of a polygon are drawn.
 374 </para>
 375
 376 @GDK_JOIN_MITER: the sides of each line are extended to meet at an angle.
 377 @GDK_JOIN_ROUND: the sides of the two lines are joined by a circular arc.
 378 @GDK_JOIN_BEVEL: the sides of the two lines are joined by a straight line which
 379        makes an equal angle with each line.
 380
 381 <!-- ##### FUNCTION gdk_gc_set_dashes ##### -->
 382 <para>
 383
 384 </para>
 385
 386 @gc:
 387 @dash_offset:
 388 @dash_list:
 389 @n:
 390
 391
 392 <!-- ##### FUNCTION gdk_gc_copy ##### -->
 393 <para>
 394
 395 </para>
 396
 397 @dst_gc:
 398 @src_gc:
 399
 400
 401 <!-- ##### FUNCTION gdk_gc_set_colormap ##### -->
 402 <para>
 403
 404 </para>
 405
 406 @gc:
 407 @colormap:
 408
 409
 410 <!-- ##### FUNCTION gdk_gc_get_colormap ##### -->
 411 <para>
 412
 413 </para>
 414
 415 @gc:
 416 @Returns:
 417
 418
 419 <!-- ##### FUNCTION gdk_gc_offset ##### -->
 420 <para>
 421
 422 </para>
 423
 424 @gc:
 425 @x_offset:
 426 @y_offset:
 427
 428