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 <!-- ##### STRUCT GdkGC ##### -->
  34 <para>
  35 The #GdkGC structure represents a graphics context.
  36 It is an opaque structure with no user-visible
  37 elements.
  38 </para>
  39
  40
  41 <!-- ##### STRUCT GdkGCValues ##### -->
  42 <para>
  43 The #GdkGCValues structure holds a set of values used
  44 to create or modify a graphics context.
  45 </para>
  46
  47 @foreground: the foreground color.
  48 @background: the background color.
  49 @font: the default font.
  50 @function: the bitwise operation used when drawing.
  51 @fill: the fill style.
  52 @tile: the tile pixmap.
  53 @stipple: the stipple bitmap.
  54 @clip_mask: the clip mask bitmap.
  55 @subwindow_mode: the subwindow mode.
  56 @ts_x_origin: the x origin of the tile or stipple.
  57 @ts_y_origin: the y origin of the tile or stipple.
  58 @clip_x_origin: the x origin of the clip mask.
  59 @clip_y_origin: the y origin of the clip mask.
  60 @graphics_exposures: whether graphics exposures are enabled.
  61 @line_width: the line width.
  62 @line_style: the way dashed lines are drawn.
  63 @cap_style: the way the ends of lines are drawn.
  64 @join_style: the way joins between lines are drawn.
  65
  66 <!-- ##### ENUM GdkGCValuesMask ##### -->
  67 <para>
  68 A set of bit flags used to indicate which fields
  69 #GdkGCValues structure are set.
  70 </para>
  71
  72 @GDK_GC_FOREGROUND: the @foreground is set.
  73 @GDK_GC_BACKGROUND: the @background is set.
  74 @GDK_GC_FONT: the @font is set.
  75 @GDK_GC_FUNCTION: the @function is set.
  76 @GDK_GC_FILL: the @fill is set.
  77 @GDK_GC_TILE: the @tile is set.
  78 @GDK_GC_STIPPLE: the @stipple is set.
  79 @GDK_GC_CLIP_MASK: the @clip_mask is set.
  80 @GDK_GC_SUBWINDOW: the @subwindow_mode is set.
  81 @GDK_GC_TS_X_ORIGIN: the @ts_x_origin is set.
  82 @GDK_GC_TS_Y_ORIGIN: the @ts_y_origin is set.
  83 @GDK_GC_CLIP_X_ORIGIN: the @clip_x_origin is set.
  84 @GDK_GC_CLIP_Y_ORIGIN: the @clip_y_origin is set.
  85 @GDK_GC_EXPOSURES: the @graphics_exposures is set.
  86 @GDK_GC_LINE_WIDTH: the @line_width is set.
  87 @GDK_GC_LINE_STYLE: the @line_style is set.
  88 @GDK_GC_CAP_STYLE: the @cap_style is set.
  89 @GDK_GC_JOIN_STYLE: the @join_style is set.
  90
  91 <!-- ##### ENUM GdkFunction ##### -->
  92 <para>
  93 Determines how the bit values for the source pixels are combined with
  94 the bit values for destination pixels to produce the final result. The
  95 sixteen values here correspond to the 16 different possible 2x2 truth
  96 tables.  Only a couple of these values are usually useful; for colored
  97 images, only %GDK_COPY, %GDK_XOR and %GDK_INVERT are generally
  98 useful. For bitmaps, %GDK_AND and %GDK_OR are also useful.
  99 </para>
 100
 101 @GDK_COPY:
 102 @GDK_INVERT:
 103 @GDK_XOR:
 104 @GDK_CLEAR:
 105 @GDK_AND:
 106 @GDK_AND_REVERSE:
 107 @GDK_AND_INVERT:
 108 @GDK_NOOP:
 109 @GDK_OR:
 110 @GDK_EQUIV:
 111 @GDK_OR_REVERSE:
 112 @GDK_COPY_INVERT:
 113 @GDK_OR_INVERT:
 114 @GDK_NAND:
 115 @GDK_NOR:
 116 @GDK_SET:
 117
 118 <!-- ##### FUNCTION gdk_gc_new ##### -->
 119 <para>
 120 Create a new graphics context with default values.
 121 </para>
 122
 123 @drawable: a #GdkDrawable. The created GC must always be used
 124  with drawables of the same depth as this one.
 125 @Returns: the new graphics context.
 126
 127
 128 <!-- ##### FUNCTION gdk_gc_new_with_values ##### -->
 129 <para>
 130 Create a new GC with the given initial values.
 131 </para>
 132
 133 @drawable: a #GdkDrawable. The created GC must always be used
 134  with drawables of the same depth as this one.
 135 @values: a structure containing initial values for the GC.
 136 @values_mask: a bit mask indicating which fields in @values
 137    are set.
 138 @Returns: the new graphics context.
 139
 140
 141 <!-- ##### FUNCTION gdk_gc_get_screen ##### -->
 142 <para>
 143
 144 </para>
 145
 146 @gc:
 147 @Returns:
 148
 149
 150 <!-- ##### FUNCTION gdk_gc_ref ##### -->
 151 <para>
 152
 153 </para>
 154
 155 @gc:
 156 @Returns:
 157
 158
 159 <!-- ##### FUNCTION gdk_gc_unref ##### -->
 160 <para>
 161
 162 </para>
 163
 164 @gc:
 165
 166
 167 <!-- ##### MACRO gdk_gc_destroy ##### -->
 168 <para>
 169 Identical to gdk_gc_unref(). This function is obsolete
 170 and should not be used.
 171 </para>
 172
 173 <!-- # Unused Parameters # -->
 174 @gc: a #GdkGC.
 175
 176
 177 <!-- ##### FUNCTION gdk_gc_set_values ##### -->
 178 <para>
 179
 180 </para>
 181
 182 @gc:
 183 @values:
 184 @values_mask:
 185
 186
 187 <!-- ##### FUNCTION gdk_gc_get_values ##### -->
 188 <para>
 189 Retrieves the current values from a graphics context.
 190 </para>
 191
 192 @gc: a #GdkGC.
 193 @values: the #GdkGCValues structure in which to store the results.
 194
 195
 196 <!-- ##### FUNCTION gdk_gc_set_foreground ##### -->
 197 <para>
 198 Sets the foreground color for a graphics context.
 199 </para>
 200
 201 @gc: a #GdkGC.
 202 @color: the new foreground color.
 203
 204
 205 <!-- ##### FUNCTION gdk_gc_set_background ##### -->
 206 <para>
 207 Sets the background color for a graphics context.
 208 </para>
 209
 210 @gc: a #GdkGC.
 211 @color: the new background color.
 212
 213
 214 <!-- ##### FUNCTION gdk_gc_set_rgb_fg_color ##### -->
 215 <para>
 216
 217 </para>
 218
 219 @gc:
 220 @color:
 221
 222
 223 <!-- ##### FUNCTION gdk_gc_set_rgb_bg_color ##### -->
 224 <para>
 225
 226 </para>
 227
 228 @gc:
 229 @color:
 230
 231
 232 <!-- ##### FUNCTION gdk_gc_set_font ##### -->
 233 <para>
 234 Sets the font for a graphics context. (Note that
 235 all text-drawing functions in GDK take a @font
 236 argument; the value set here is used when that
 237 argument is %NULL.)
 238 </para>
 239
 240 @gc: a #GdkGC.
 241 @font: the new font.
 242
 243
 244 <!-- ##### FUNCTION gdk_gc_set_function ##### -->
 245 <para>
 246 Determines how the current pixel values and the
 247 pixel values being drawn are combined to produce
 248 the final pixel values.
 249 </para>
 250
 251 @gc: a #GdkGC.
 252 @function:
 253
 254
 255 <!-- ##### FUNCTION gdk_gc_set_fill ##### -->
 256 <para>
 257 Set the fill mode for a graphics context.
 258 </para>
 259
 260 @gc: a #GdkGC.
 261 @fill: the new fill mode.
 262
 263
 264 <!-- ##### ENUM GdkFill ##### -->
 265 <para>
 266 Determines how primitives are drawn.
 267 </para>
 268
 269 @GDK_SOLID: draw with the foreground color.
 270 @GDK_TILED: draw with a tiled pixmap.
 271 @GDK_STIPPLED: draw using the stipple bitmap. Pixels corresponding
 272   to bits in the stipple bitmap that are set will be drawn in the
 273   foreground color; pixels corresponding to bits that are
 274   not set will be left untouched.
 275 @GDK_OPAQUE_STIPPLED: draw using the stipple bitmap. Pixels corresponding
 276   to bits in the stipple bitmap that are set will be drawn in the
 277   foreground color; pixels corresponding to bits that are
 278   not set will be drawn with the background color.
 279
 280 <!-- ##### FUNCTION gdk_gc_set_tile ##### -->
 281 <para>
 282 Set a tile pixmap for a graphics context.
 283 This will only be used if the fill mode
 284 is %GDK_TILED.
 285 </para>
 286
 287 @gc: a #GdkGC.
 288 @tile: the new tile pixmap.
 289
 290
 291 <!-- ##### FUNCTION gdk_gc_set_stipple ##### -->
 292 <para>
 293 Set the stipple bitmap for a graphics context. The
 294 stipple will only be used if the fill mode is
 295 %GDK_STIPPLED or %GDK_OPAQUE_STIPPLED.
 296 </para>
 297
 298 @gc: a #GdkGC.
 299 @stipple: the new stipple bitmap.
 300
 301
 302 <!-- ##### FUNCTION gdk_gc_set_ts_origin ##### -->
 303 <para>
 304 Set the origin when using tiles or stipples with
 305 the GC. The tile or stipple will be aligned such
 306 that the upper left corner of the tile or stipple
 307 will coincide with this point.
 308 </para>
 309
 310 @gc: a #GdkGC.
 311 @x: the x-coordinate of the origin.
 312 @y: the y-coordinate of the origin.
 313
 314
 315 <!-- ##### FUNCTION gdk_gc_set_clip_origin ##### -->
 316 <para>
 317 Sets the origin of the clip mask. The coordinates are
 318 interpreted relative to the upper-left corner of
 319 the destination drawable of the current operation.
 320 </para>
 321
 322 @gc: a #GdkGC.
 323 @x: the x-coordinate of the origin.
 324 @y: the y-coordinate of the origin.
 325
 326
 327 <!-- ##### FUNCTION gdk_gc_set_clip_mask ##### -->
 328 <para>
 329 Sets the clip mask for a graphics context from a bitmap.
 330 The clip mask is interpreted relative to the clip
 331 origin. (See gdk_gc_set_clip_origin()).
 332 </para>
 333
 334 @gc: the #GdkGC.
 335 @mask: a bitmap.
 336
 337
 338 <!-- ##### FUNCTION gdk_gc_set_clip_rectangle ##### -->
 339 <para>
 340 Sets the clip mask for a graphics context from a
 341 rectangle. The clip mask is interpreted relative to the clip
 342 origin. (See gdk_gc_set_clip_origin()).
 343
 344 </para>
 345
 346 @gc: a #GdkGC.
 347 @rectangle: the rectangle to clip to.
 348
 349
 350 <!-- ##### FUNCTION gdk_gc_set_clip_region ##### -->
 351 <para>
 352 Sets the clip mask for a graphics context from a region structure.
 353 The clip mask is interpreted relative to the clip origin. (See
 354 gdk_gc_set_clip_origin()).
 355 </para>
 356
 357 @gc: a #GdkGC.
 358 @region: the #GdkRegion.
 359
 360
 361 <!-- ##### FUNCTION gdk_gc_set_subwindow ##### -->
 362 <para>
 363 Sets how drawing with this GC on a window will affect child
 364 windows of that window.
 365 </para>
 366
 367 @gc: a #GdkGC.
 368 @mode: the subwindow mode.
 369
 370
 371 <!-- ##### ENUM GdkSubwindowMode ##### -->
 372 <para>
 373 Determines how drawing onto a window will affect child
 374 windows of that window.
 375 </para>
 376
 377 @GDK_CLIP_BY_CHILDREN: only draw onto the window itself.
 378 @GDK_INCLUDE_INFERIORS: draw onto the window and child windows.
 379
 380 <!-- ##### FUNCTION gdk_gc_set_exposures ##### -->
 381 <para>
 382 Sets whether copying non-visible portions of a drawable
 383 using this graphics context generate exposure events
 384 for the corresponding regions of the destination
 385 drawable. (See gdk_draw_drawable()).
 386 </para>
 387
 388 @gc: a #GdkGC.
 389 @exposures: if %TRUE, exposure events will be generated.
 390
 391
 392 <!-- ##### FUNCTION gdk_gc_set_line_attributes ##### -->
 393 <para>
 394 Sets various attributes of how lines are drawn. See
 395 the corresponding members of #GdkGCValues for full
 396 explanations of the arguments.
 397 </para>
 398
 399 @gc: a #GdkGC.
 400 @line_width: the width of lines.
 401 @line_style: the dash-style for lines.
 402 @cap_style: the manner in which the ends of lines are drawn.
 403 @join_style: the in which lines are joined together.
 404
 405
 406 <!-- ##### ENUM GdkLineStyle ##### -->
 407 <para>
 408 Determines how lines are drawn.
 409 </para>
 410
 411 @GDK_LINE_SOLID: lines are drawn solid.
 412 @GDK_LINE_ON_OFF_DASH: even segments are drawn; odd segments are not drawn.
 413 @GDK_LINE_DOUBLE_DASH: even segments are normally. Odd segments are drawn
 414   in the background color if the fill style is %GDK_SOLID, or in the background
 415   color masked by the stipple if the fill style is %GDK_STIPPLED.
 416
 417 <!-- ##### ENUM GdkCapStyle ##### -->
 418 <para>
 419 Determines how the end of lines are drawn.
 420 </para>
 421
 422 @GDK_CAP_NOT_LAST: the same as %GDK_CAP_BUTT for lines of non-zero width.
 423        for zero width lines, the final point on the line will not be drawn.
 424 @GDK_CAP_BUTT: the ends of the lines are drawn squared off and extending
 425        to the coordinates of the end point.
 426 @GDK_CAP_ROUND: the ends of the lines are drawn as semicircles with the
 427        diameter equal to the line width and centered at the end point.
 428 @GDK_CAP_PROJECTING: the ends of the lines are drawn squared off and extending
 429        half the width of the line beyond the end point.
 430
 431 <!-- ##### ENUM GdkJoinStyle ##### -->
 432 <para>
 433 Determines how the joins between segments of a polygon are drawn.
 434 </para>
 435
 436 @GDK_JOIN_MITER: the sides of each line are extended to meet at an angle.
 437 @GDK_JOIN_ROUND: the sides of the two lines are joined by a circular arc.
 438 @GDK_JOIN_BEVEL: the sides of the two lines are joined by a straight line which
 439        makes an equal angle with each line.
 440
 441 <!-- ##### FUNCTION gdk_gc_set_dashes ##### -->
 442 <para>
 443 Sets the way dashed-lines are drawn. Lines will be
 444 drawn with alternating on and off segments of the
 445 lengths specified in @dash_list. The manner in
 446 which the on and off segments are drawn is determined
 447 by the @line_style value of the GC. (This can
 448 be changed with gdk_gc_set_line_attributes())
 449 </para>
 450
 451 @gc: a #GdkGC.
 452 @dash_offset: the
 453 @dash_list: an array of dash lengths.
 454 @n: the number of elements in @dash_list.
 455
 456
 457 <!-- ##### FUNCTION gdk_gc_copy ##### -->
 458 <para>
 459 Copy the set of values from one graphics context
 460 onto another graphics context.
 461 </para>
 462
 463 @dst_gc: the destination graphics context.
 464 @src_gc: the source graphics context.
 465
 466
 467 <!-- ##### FUNCTION gdk_gc_set_colormap ##### -->
 468 <para>
 469
 470 </para>
 471
 472 @gc:
 473 @colormap:
 474
 475
 476 <!-- ##### FUNCTION gdk_gc_get_colormap ##### -->
 477 <para>
 478
 479 </para>
 480
 481 @gc:
 482 @Returns:
 483
 484
 485 <!-- ##### FUNCTION gdk_gc_offset ##### -->
 486 <para>
 487
 488 </para>
 489
 490 @gc:
 491 @x_offset:
 492 @y_offset:
 493
 494