gcs.sgml 8.67 KB
Newer Older
Owen Taylor's avatar
Owen Taylor committed
1
2
3
4
<!-- ##### SECTION Title ##### -->
Graphics Contexts

<!-- ##### SECTION Short_Description ##### -->
Matthias Clasen's avatar
Matthias Clasen committed
5
Objects to encapsulate drawing properties
Owen Taylor's avatar
Owen Taylor committed
6
7
8

<!-- ##### SECTION Long_Description ##### -->
<para>
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
All drawing operations in GDK take a 
<firstterm>graphics context</firstterm> (GC) argument. 
A graphics context encapsulates information about
the way things are drawn, such as the foreground
color or line width. By using graphics contexts, 
the number of arguments to each drawing call is
greatly reduced, and communication overhead is
minimized, since identical arguments do not need
to be passed repeatedly.
</para>
<para>
Most values of a graphics context can be set at
creation time by using gdk_gc_new_with_values(),
or can be set one-by-one using functions such
as gdk_gc_set_foreground(). A few of the values
in the GC, such as the dash pattern, can only
be set by the latter method.
Owen Taylor's avatar
Owen Taylor committed
26
27
28
29
30
31
32
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

Matthias Clasen's avatar
2.7.0    
Matthias Clasen committed
33
34
35
<!-- ##### SECTION Stability_Level ##### -->


Owen Taylor's avatar
Owen Taylor committed
36
<!-- ##### STRUCT GdkGC ##### -->
37
<para>
38
39
40
The #GdkGC structure represents a graphics context.
It is an opaque structure with no user-visible
elements.
Owen Taylor's avatar
Owen Taylor committed
41
42
</para>

43

Owen Taylor's avatar
Owen Taylor committed
44
45
<!-- ##### STRUCT GdkGCValues ##### -->
<para>
46
47
The #GdkGCValues structure holds a set of values used
to create or modify a graphics context.
48
</para>
49

Matthias Clasen's avatar
Matthias Clasen committed
50
51
52
53
@foreground: the foreground color. Note that gdk_gc_get_values()
  only sets the pixel value.
@background: the background color. Note that gdk_gc_get_values()
  only sets the pixel value.
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
@font: the default font.
@function: the bitwise operation used when drawing.
@fill: the fill style.
@tile: the tile pixmap.
@stipple: the stipple bitmap.
@clip_mask: the clip mask bitmap.
@subwindow_mode: the subwindow mode.
@ts_x_origin: the x origin of the tile or stipple.
@ts_y_origin: the y origin of the tile or stipple.
@clip_x_origin: the x origin of the clip mask.
@clip_y_origin: the y origin of the clip mask.
@graphics_exposures: whether graphics exposures are enabled.
@line_width: the line width.
@line_style: the way dashed lines are drawn.
@cap_style: the way the ends of lines are drawn.
@join_style: the way joins between lines are drawn.
Owen Taylor's avatar
Owen Taylor committed
70
71
72

<!-- ##### ENUM GdkGCValuesMask ##### -->
<para>
73
74
A set of bit flags used to indicate which fields
#GdkGCValues structure are set.
Owen Taylor's avatar
Owen Taylor committed
75
76
</para>

Owen Taylor's avatar
Owen Taylor committed
77
@GDK_GC_FOREGROUND: the @foreground is set.
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
@GDK_GC_BACKGROUND: the @background is set.
@GDK_GC_FONT: the @font is set.
@GDK_GC_FUNCTION: the @function is set.
@GDK_GC_FILL: the @fill is set.
@GDK_GC_TILE: the @tile is set.
@GDK_GC_STIPPLE: the @stipple is set.
@GDK_GC_CLIP_MASK: the @clip_mask is set.
@GDK_GC_SUBWINDOW: the @subwindow_mode is set.
@GDK_GC_TS_X_ORIGIN: the @ts_x_origin is set.
@GDK_GC_TS_Y_ORIGIN: the @ts_y_origin is set.
@GDK_GC_CLIP_X_ORIGIN: the @clip_x_origin is set.
@GDK_GC_CLIP_Y_ORIGIN: the @clip_y_origin is set.
@GDK_GC_EXPOSURES: the @graphics_exposures is set.
@GDK_GC_LINE_WIDTH: the @line_width is set.
@GDK_GC_LINE_STYLE: the @line_style is set.
@GDK_GC_CAP_STYLE: the @cap_style is set.
@GDK_GC_JOIN_STYLE: the @join_style is set.
Owen Taylor's avatar
Owen Taylor committed
95

96
97
<!-- ##### ENUM GdkFunction ##### -->
<para>
98
99
100
101
102
103
Determines how the bit values for the source pixels are combined with
the bit values for destination pixels to produce the final result. The
sixteen values here correspond to the 16 different possible 2x2 truth
tables.  Only a couple of these values are usually useful; for colored
images, only %GDK_COPY, %GDK_XOR and %GDK_INVERT are generally
useful. For bitmaps, %GDK_AND and %GDK_OR are also useful.
Owen Taylor's avatar
Owen Taylor committed
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
</para>

@GDK_COPY: 
@GDK_INVERT: 
@GDK_XOR: 
@GDK_CLEAR: 
@GDK_AND: 
@GDK_AND_REVERSE: 
@GDK_AND_INVERT: 
@GDK_NOOP: 
@GDK_OR: 
@GDK_EQUIV: 
@GDK_OR_REVERSE: 
@GDK_COPY_INVERT: 
@GDK_OR_INVERT: 
@GDK_NAND: 
120
@GDK_NOR: 
Owen Taylor's avatar
Owen Taylor committed
121
122
@GDK_SET: 

123
<!-- ##### FUNCTION gdk_gc_new ##### -->
Owen Taylor's avatar
Owen Taylor committed
124
<para>
125
126
</para>

Matthias Clasen's avatar
Matthias Clasen committed
127
@drawable: 
128
@Returns: 
129

Owen Taylor's avatar
Owen Taylor committed
130

131
132
<!-- ##### FUNCTION gdk_gc_new_with_values ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
133

Owen Taylor's avatar
Owen Taylor committed
134
135
</para>

Matthias Clasen's avatar
Matthias Clasen committed
136
137
@drawable: 
@values: 
138
@values_mask: 
Matthias Clasen's avatar
Matthias Clasen committed
139
@Returns: 
Owen Taylor's avatar
Owen Taylor committed
140
141


Owen Taylor's avatar
Owen Taylor committed
142
143
144
145
146
147
148
149
150
<!-- ##### FUNCTION gdk_gc_get_screen ##### -->
<para>

</para>

@gc: 
@Returns: 


Owen Taylor's avatar
Owen Taylor committed
151
152
<!-- ##### FUNCTION gdk_gc_ref ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
153

Owen Taylor's avatar
Owen Taylor committed
154
155
</para>

Owen Taylor's avatar
Owen Taylor committed
156
157
@gc: 
@Returns: 
Owen Taylor's avatar
Owen Taylor committed
158
159
160
161


<!-- ##### FUNCTION gdk_gc_unref ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
162

Owen Taylor's avatar
Owen Taylor committed
163
164
</para>

Owen Taylor's avatar
Owen Taylor committed
165
@gc: 
Owen Taylor's avatar
Owen Taylor committed
166
167


168
<!-- ##### MACRO gdk_gc_destroy ##### -->
Owen Taylor's avatar
Owen Taylor committed
169
<para>
Matthias Clasen's avatar
Matthias Clasen committed
170
This function is obsolete and should not be used.
Owen Taylor's avatar
Owen Taylor committed
171
172
</para>

Matthias Clasen's avatar
Matthias Clasen committed
173
@Deprecated: Use g_object_unref() instead
Owen Taylor's avatar
Owen Taylor committed
174
<!-- # Unused Parameters # -->
175
@gc: a #GdkGC.
176

Owen Taylor's avatar
Owen Taylor committed
177

178
179
180
181
182
183
184
185
186
187
<!-- ##### FUNCTION gdk_gc_set_values ##### -->
<para>

</para>

@gc: 
@values: 
@values_mask: 


Owen Taylor's avatar
Owen Taylor committed
188
189
<!-- ##### FUNCTION gdk_gc_get_values ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
190

Owen Taylor's avatar
Owen Taylor committed
191
192
</para>

193
194
@gc: 
@values: 
Owen Taylor's avatar
Owen Taylor committed
195
196
197
198


<!-- ##### FUNCTION gdk_gc_set_foreground ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
199

Owen Taylor's avatar
Owen Taylor committed
200
201
</para>

Matthias Clasen's avatar
Matthias Clasen committed
202
203
@gc: 
@color: 
Owen Taylor's avatar
Owen Taylor committed
204
205
206
207


<!-- ##### FUNCTION gdk_gc_set_background ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
208

Owen Taylor's avatar
Owen Taylor committed
209
210
</para>

211
212
@gc: 
@color: 
Owen Taylor's avatar
Owen Taylor committed
213
214


215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
<!-- ##### FUNCTION gdk_gc_set_rgb_fg_color ##### -->
<para>

</para>

@gc: 
@color: 


<!-- ##### FUNCTION gdk_gc_set_rgb_bg_color ##### -->
<para>

</para>

@gc: 
@color: 


Owen Taylor's avatar
Owen Taylor committed
233
234
<!-- ##### FUNCTION gdk_gc_set_font ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
235

Owen Taylor's avatar
Owen Taylor committed
236
237
</para>

238
239
@gc: 
@font: 
Owen Taylor's avatar
Owen Taylor committed
240
241
242
243


<!-- ##### FUNCTION gdk_gc_set_function ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
244

Owen Taylor's avatar
Owen Taylor committed
245
246
</para>

247
@gc: 
Owen Taylor's avatar
Owen Taylor committed
248
249
250
251
252
@function: 


<!-- ##### FUNCTION gdk_gc_set_fill ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
253

Owen Taylor's avatar
Owen Taylor committed
254
255
</para>

256
257
@gc: 
@fill: 
Owen Taylor's avatar
Owen Taylor committed
258
259


Damon Chaplin's avatar
Damon Chaplin committed
260
261
<!-- ##### ENUM GdkFill ##### -->
<para>
262
Determines how primitives are drawn.
Damon Chaplin's avatar
Damon Chaplin committed
263
264
</para>

Owen Taylor's avatar
Owen Taylor committed
265
@GDK_SOLID: draw with the foreground color.
266
267
268
269
@GDK_TILED: draw with a tiled pixmap.
@GDK_STIPPLED: draw using the stipple bitmap. Pixels corresponding
  to bits in the stipple bitmap that are set will be drawn in the
  foreground color; pixels corresponding to bits that are
Owen Taylor's avatar
Owen Taylor committed
270
  not set will be left untouched.
271
272
273
@GDK_OPAQUE_STIPPLED: draw using the stipple bitmap. Pixels corresponding
  to bits in the stipple bitmap that are set will be drawn in the
  foreground color; pixels corresponding to bits that are
Owen Taylor's avatar
Owen Taylor committed
274
  not set will be drawn with the background color.
Damon Chaplin's avatar
Damon Chaplin committed
275

Owen Taylor's avatar
Owen Taylor committed
276
277
<!-- ##### FUNCTION gdk_gc_set_tile ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
278

Owen Taylor's avatar
Owen Taylor committed
279
280
</para>

281
282
@gc: 
@tile: 
Owen Taylor's avatar
Owen Taylor committed
283
284
285
286


<!-- ##### FUNCTION gdk_gc_set_stipple ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
287

Owen Taylor's avatar
Owen Taylor committed
288
289
</para>

Matthias Clasen's avatar
Matthias Clasen committed
290
291
@gc: 
@stipple: 
Owen Taylor's avatar
Owen Taylor committed
292
293
294
295


<!-- ##### FUNCTION gdk_gc_set_ts_origin ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
296

Owen Taylor's avatar
Owen Taylor committed
297
298
</para>

299
@gc: 
Matthias Clasen's avatar
Matthias Clasen committed
300
301
@x: 
@y: 
Owen Taylor's avatar
Owen Taylor committed
302
303
304
305


<!-- ##### FUNCTION gdk_gc_set_clip_origin ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
306

Owen Taylor's avatar
Owen Taylor committed
307
308
</para>

309
@gc: 
Matthias Clasen's avatar
Matthias Clasen committed
310
311
@x: 
@y: 
Owen Taylor's avatar
Owen Taylor committed
312
313
314
315


<!-- ##### FUNCTION gdk_gc_set_clip_mask ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
316

Owen Taylor's avatar
Owen Taylor committed
317
318
</para>

Matthias Clasen's avatar
Matthias Clasen committed
319
320
@gc: 
@mask: 
Owen Taylor's avatar
Owen Taylor committed
321
322
323
324
325
326


<!-- ##### FUNCTION gdk_gc_set_clip_rectangle ##### -->
<para>
</para>

Matthias Clasen's avatar
Matthias Clasen committed
327
328
@gc: 
@rectangle: 
Owen Taylor's avatar
Owen Taylor committed
329
330
331
332


<!-- ##### FUNCTION gdk_gc_set_clip_region ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
333

Owen Taylor's avatar
Owen Taylor committed
334
335
</para>

336
@gc: 
Matthias Clasen's avatar
Matthias Clasen committed
337
@region: 
Owen Taylor's avatar
Owen Taylor committed
338
339
340
341


<!-- ##### FUNCTION gdk_gc_set_subwindow ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
342

Owen Taylor's avatar
Owen Taylor committed
343
344
</para>

Matthias Clasen's avatar
Matthias Clasen committed
345
346
@gc: 
@mode: 
Owen Taylor's avatar
Owen Taylor committed
347
348
349
350


<!-- ##### ENUM GdkSubwindowMode ##### -->
<para>
351
352
Determines how drawing onto a window will affect child
windows of that window. 
Owen Taylor's avatar
Owen Taylor committed
353
354
</para>

355
356
@GDK_CLIP_BY_CHILDREN: only draw onto the window itself.
@GDK_INCLUDE_INFERIORS: draw onto the window and child windows.
Owen Taylor's avatar
Owen Taylor committed
357
358
359

<!-- ##### FUNCTION gdk_gc_set_exposures ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
360

Owen Taylor's avatar
Owen Taylor committed
361
362
</para>

Matthias Clasen's avatar
Matthias Clasen committed
363
364
@gc: 
@exposures: 
Owen Taylor's avatar
Owen Taylor committed
365
366
367
368


<!-- ##### FUNCTION gdk_gc_set_line_attributes ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
369

Owen Taylor's avatar
Owen Taylor committed
370
371
</para>

Matthias Clasen's avatar
Matthias Clasen committed
372
373
374
375
@gc: 
@line_width: 
@line_style: 
@cap_style: 
376
@join_style: 
Owen Taylor's avatar
Owen Taylor committed
377
378


Damon Chaplin's avatar
Damon Chaplin committed
379
380
<!-- ##### ENUM GdkLineStyle ##### -->
<para>
381
Determines how lines are drawn.
Damon Chaplin's avatar
Damon Chaplin committed
382
383
</para>

Owen Taylor's avatar
Owen Taylor committed
384
385
@GDK_LINE_SOLID: lines are drawn solid.
@GDK_LINE_ON_OFF_DASH: even segments are drawn; odd segments are not drawn.
386
387
388
389
@GDK_LINE_DOUBLE_DASH: even segments are normally. Odd segments are drawn
  in the background color if the fill style is %GDK_SOLID, or in the background
  color masked by the stipple if the fill style is %GDK_STIPPLED.

Damon Chaplin's avatar
Damon Chaplin committed
390
391
<!-- ##### ENUM GdkCapStyle ##### -->
<para>
392
Determines how the end of lines are drawn.
393
</para>
394

395
@GDK_CAP_NOT_LAST: the same as %GDK_CAP_BUTT for lines of non-zero width.
Owen Taylor's avatar
Owen Taylor committed
396
397
398
       for zero width lines, the final point on the line will not be drawn.
@GDK_CAP_BUTT: the ends of the lines are drawn squared off and extending
       to the coordinates of the end point.
399
@GDK_CAP_ROUND: the ends of the lines are drawn as semicircles with the
Owen Taylor's avatar
Owen Taylor committed
400
       diameter equal to the line width and centered at the end point.
401
@GDK_CAP_PROJECTING: the ends of the lines are drawn squared off and extending
Owen Taylor's avatar
Owen Taylor committed
402
       half the width of the line beyond the end point.
Damon Chaplin's avatar
Damon Chaplin committed
403
404
405

<!-- ##### ENUM GdkJoinStyle ##### -->
<para>
406
Determines how the joins between segments of a polygon are drawn.
Damon Chaplin's avatar
Damon Chaplin committed
407
408
</para>

Owen Taylor's avatar
Owen Taylor committed
409
410
@GDK_JOIN_MITER: the sides of each line are extended to meet at an angle.
@GDK_JOIN_ROUND: the sides of the two lines are joined by a circular arc.
411
@GDK_JOIN_BEVEL: the sides of the two lines are joined by a straight line which
Owen Taylor's avatar
Owen Taylor committed
412
       makes an equal angle with each line.
Damon Chaplin's avatar
Damon Chaplin committed
413

Owen Taylor's avatar
Owen Taylor committed
414
415
<!-- ##### FUNCTION gdk_gc_set_dashes ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
416

Owen Taylor's avatar
Owen Taylor committed
417
418
</para>

Matthias Clasen's avatar
Matthias Clasen committed
419
420
421
422
@gc: 
@dash_offset: 
@dash_list: 
@n: 
Owen Taylor's avatar
Owen Taylor committed
423
424
425
426


<!-- ##### FUNCTION gdk_gc_copy ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
427

Owen Taylor's avatar
Owen Taylor committed
428
429
</para>

430
@dst_gc: 
Matthias Clasen's avatar
Matthias Clasen committed
431
@src_gc: 
Damon Chaplin's avatar
Damon Chaplin committed
432
433


434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
<!-- ##### FUNCTION gdk_gc_set_colormap ##### -->
<para>

</para>

@gc: 
@colormap: 


<!-- ##### FUNCTION gdk_gc_get_colormap ##### -->
<para>

</para>

@gc: 
@Returns: 


Havoc Pennington's avatar
Havoc Pennington committed
452
453
454
455
456
457
458
459
460
461
<!-- ##### FUNCTION gdk_gc_offset ##### -->
<para>

</para>

@gc: 
@x_offset: 
@y_offset: