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