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

   1 <!-- ##### SECTION Title ##### -->
   2 Drawing Primitives
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 functions for drawing points, lines, arcs, and text.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 These functions provide support for drawing points, lines, arcs and text
  10 onto what are called 'drawables'. Drawables, as the name suggests, are things
  11 which support drawing onto them, and are either #GdkWindow or #GdkPixmap
  12 objects.
  13 </para>
  14 <para>
  15 Many of the drawing operations take a #GdkGC argument, which represents a
  16 graphics context. This #GdkGC contains a number of drawing attributes such
  17 as foreground color, background color and line width, and is used to reduce
  18 the number of arguments needed for each drawing operation. See the
  19 <link linkend="gdk-Graphics-Contexts">Graphics Contexts</link> section for
  20 more information.
  21 </para>
  22
  23 <!-- ##### SECTION See_Also ##### -->
  24 <para>
  25
  26 </para>
  27
  28 <!-- ##### STRUCT GdkDrawable ##### -->
  29 <para>
  30 An opaque structure representing an object that can be
  31 drawn onto. This can be a #GdkPixmap, a #GdkBitmap,
  32 or a #GdkWindow.
  33 </para>
  34
  35 @user_data:
  36
  37 <!-- ##### FUNCTION gdk_drawable_ref ##### -->
  38 <para>
  39
  40 </para>
  41
  42 @drawable:
  43 @Returns:
  44
  45
  46 <!-- ##### FUNCTION gdk_drawable_unref ##### -->
  47 <para>
  48
  49 </para>
  50
  51 @drawable:
  52
  53
  54 <!-- ##### FUNCTION gdk_drawable_set_data ##### -->
  55 <para>
  56
  57 </para>
  58
  59 @drawable:
  60 @key:
  61 @data:
  62 @destroy_func:
  63
  64
  65 <!-- ##### FUNCTION gdk_drawable_get_data ##### -->
  66 <para>
  67
  68 </para>
  69
  70 @drawable:
  71 @key:
  72 @Returns:
  73
  74
  75 <!-- ##### FUNCTION gdk_drawable_get_visual ##### -->
  76 <para>
  77
  78 </para>
  79
  80 @drawable:
  81 @Returns:
  82
  83
  84 <!-- ##### FUNCTION gdk_drawable_set_colormap ##### -->
  85 <para>
  86
  87 </para>
  88
  89 @drawable:
  90 @colormap:
  91
  92
  93 <!-- ##### FUNCTION gdk_drawable_get_colormap ##### -->
  94 <para>
  95
  96 </para>
  97
  98 @drawable:
  99 @Returns:
 100
 101
 102 <!-- ##### FUNCTION gdk_drawable_get_depth ##### -->
 103 <para>
 104
 105 </para>
 106
 107 @drawable:
 108 @Returns:
 109
 110
 111 <!-- ##### FUNCTION gdk_drawable_get_size ##### -->
 112 <para>
 113
 114 </para>
 115
 116 @drawable:
 117 @width:
 118 @height:
 119
 120
 121 <!-- ##### FUNCTION gdk_drawable_get_clip_region ##### -->
 122 <para>
 123
 124 </para>
 125
 126 @drawable:
 127 @Returns:
 128
 129
 130 <!-- ##### FUNCTION gdk_drawable_get_visible_region ##### -->
 131 <para>
 132
 133 </para>
 134
 135 @drawable:
 136 @Returns:
 137
 138
 139 <!-- ##### FUNCTION gdk_draw_point ##### -->
 140 <para>
 141 Draws a point, using the foreground color and other attributes of the #GdkGC.
 142 </para>
 143
 144 @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 145 @gc: a #GdkGC.
 146 @x: the x coordinate of the point.
 147 @y: the y coordinate of the point.
 148
 149
 150 <!-- ##### FUNCTION gdk_draw_points ##### -->
 151 <para>
 152 Draws a number of points, using the foreground color and other attributes of
 153 the #GdkGC.
 154 </para>
 155
 156 @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 157 @gc: a #GdkGC.
 158 @points: an array of #GdkPoint structures.
 159 @npoints: the number of points to be drawn.
 160
 161
 162 <!-- ##### FUNCTION gdk_draw_line ##### -->
 163 <para>
 164 Draws a line, using the foreground color and other attributes of the #GdkGC.
 165 </para>
 166
 167 @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 168 @gc: a #GdkGC.
 169 @x1: the x coordinate of the start point.
 170 @y1: the y coordinate of the start point.
 171 @x2: the x coordinate of the end point.
 172 @y2: the y coordinate of the end point.
 173
 174
 175 <!-- ##### FUNCTION gdk_draw_lines ##### -->
 176 <para>
 177 Draws a series of lines connecting the given points.
 178 The way in which joins between lines are draw is determined by the
 179 #GdkCapStyle value in the #GdkGC. This can be set with
 180 gdk_gc_set_line_attributes().
 181 </para>
 182
 183 @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 184 @gc: a #GdkGC.
 185 @points: an array of #GdkPoint structures specifying the endpoints of the
 186 lines.
 187 @npoints: the size of the @points array.
 188
 189
 190 <!-- ##### FUNCTION gdk_draw_segments ##### -->
 191 <para>
 192 Draws a number of unconnected lines.
 193 </para>
 194
 195 @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 196 @gc: a #GdkGC.
 197 @segs: an array of #GdkSegment structures specifying the start and end points
 198 of the lines to be drawn,
 199 @nsegs: the number of line segments to draw, i.e. the size of the @segs array.
 200
 201
 202 <!-- ##### STRUCT GdkSegment ##### -->
 203 <para>
 204 Specifies the start and end point of a line for use by the gdk_draw_segments()
 205 function.
 206 </para>
 207
 208 @x1: the x coordinate of the start point.
 209 @y1: the y coordinate of the start point.
 210 @x2: the x coordinate of the end point.
 211 @y2: the y coordinate of the end point.
 212
 213 <!-- ##### FUNCTION gdk_draw_rectangle ##### -->
 214 <para>
 215 Draws a rectangular outline or filled rectangle, using the foreground color
 216 and other attributes of the #GdkGC.
 217 </para>
 218 <note>
 219 <para>
 220 A rectangle drawn filled is 1 pixel smaller in both dimensions than a rectangle
 221 outlined. Calling <literal>gdk_draw_rectangle (window, gc, TRUE, 0, 0, 20, 20)</literal> results
 222 in a filled rectangle 20 pixels wide and 20 pixels high. Calling
 223 <literal>gdk_draw_rectangle (window, gc, FALSE, 0, 0, 20, 20)</literal> results in an outlined
 224 rectangle with corners at (0, 0), (0, 20), (20, 20), and (20, 0), which
 225 makes it 21 pixels wide and 21 pixels high.
 226 </para>
 227 </note>
 228
 229 @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 230 @gc: a #GdkGC.
 231 @filled: %TRUE if the rectangle should be filled.
 232 @x: the x coordinate of the left edge of the rectangle.
 233 @y: the y coordinate of the top edge of the rectangle.
 234 @width: the width of the rectangle.
 235 @height: the height of the rectangle.
 236
 237
 238 <!-- ##### FUNCTION gdk_draw_arc ##### -->
 239 <para>
 240 Draws an arc or a filled 'pie slice'. The arc is defined by the bounding
 241 rectangle of the entire ellipse, and the start and end angles of the part of
 242 the ellipse to be drawn.
 243 </para>
 244
 245 @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 246 @gc: a #GdkGC.
 247 @filled: %TRUE if the arc should be filled, producing a 'pie slice'.
 248 @x: the x coordinate of the left edge of the bounding rectangle.
 249 @y: the y coordinate of the top edge of the bounding rectangle.
 250 @width: the width of the bounding rectangle.
 251 @height: the height of the bounding rectangle.
 252 @angle1: the start angle of the arc, relative to the 3 o'clock position,
 253 counter-clockwise, in 1/64ths of a degree.
 254 @angle2: the end angle of the arc, relative to @angle1, in 1/64ths of a degree.
 255
 256
 257 <!-- ##### FUNCTION gdk_draw_polygon ##### -->
 258 <para>
 259 Draws an outlined or filled polygon.
 260 </para>
 261
 262 @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 263 @gc: a #GdkGC.
 264 @filled: %TRUE if the polygon should be filled. The polygon is closed
 265 automatically, connecting the last point to the first point if necessary.
 266 @points: an array of #GdkPoint structures specifying the points making up the
 267 polygon.
 268 @npoints: the number of points.
 269
 270
 271 <!-- ##### FUNCTION gdk_draw_glyphs ##### -->
 272 <para>
 273
 274 </para>
 275
 276 @drawable:
 277 @gc:
 278 @font:
 279 @x:
 280 @y:
 281 @glyphs:
 282
 283
 284 <!-- ##### FUNCTION gdk_draw_layout_line ##### -->
 285 <para>
 286
 287 </para>
 288
 289 @drawable:
 290 @gc:
 291 @x:
 292 @y:
 293 @line:
 294
 295
 296 <!-- ##### FUNCTION gdk_draw_layout_line_with_colors ##### -->
 297 <para>
 298
 299 </para>
 300
 301 @drawable:
 302 @gc:
 303 @x:
 304 @y:
 305 @line:
 306 @foreground:
 307 @background:
 308
 309
 310 <!-- ##### FUNCTION gdk_draw_layout ##### -->
 311 <para>
 312
 313 </para>
 314
 315 @drawable:
 316 @gc:
 317 @x:
 318 @y:
 319 @layout:
 320
 321
 322 <!-- ##### FUNCTION gdk_draw_layout_with_colors ##### -->
 323 <para>
 324
 325 </para>
 326
 327 @drawable:
 328 @gc:
 329 @x:
 330 @y:
 331 @layout:
 332 @foreground:
 333 @background:
 334
 335
 336 <!-- ##### FUNCTION gdk_draw_string ##### -->
 337 <para>
 338 Draws a string of characters in the given font or fontset.
 339 </para>
 340
 341 @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 342 @font: a #GdkFont.
 343 @gc: a #GdkGC.
 344 @x: the x coordinate of the left edge of the text.
 345 @y: the y coordinate of the baseline of the text.
 346 @string: the string of characters to draw.
 347
 348
 349 <!-- ##### FUNCTION gdk_draw_text ##### -->
 350 <para>
 351 Draws a number of characters in the given font or fontset.
 352 </para>
 353
 354 @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 355 @font: a #GdkFont.
 356 @gc: a #GdkGC.
 357 @x: the x coordinate of the left edge of the text.
 358 @y: the y coordinate of the baseline of the text.
 359 @text: the characters to draw.
 360 @text_length: the number of characters of @text to draw.
 361
 362
 363 <!-- ##### FUNCTION gdk_draw_text_wc ##### -->
 364 <para>
 365 Draws a number of wide characters using the given font of fontset.
 366 If the font is a 1-byte font, the string is converted into 1-byte characters
 367 (discarding the high bytes) before output.
 368 </para>
 369
 370 @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 371 @font: a #GdkFont.
 372 @gc: a #GdkGC.
 373 @x: the x coordinate of the left edge of the text.
 374 @y: the y coordinate of the baseline of the text.
 375 @text: the wide characters to draw.
 376 @text_length: the number of characters to draw.
 377
 378
 379 <!-- ##### MACRO gdk_draw_pixmap ##### -->
 380 <para>
 381 Draws a pixmap, or a part of a pixmap, onto another drawable.
 382 </para>
 383
 384 <!-- # Unused Parameters # -->
 385 @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 386 @gc: a #GdkGC.
 387 @src: the source #GdkPixmap to draw.
 388 @xsrc: the left edge of the source rectangle within @src.
 389 @ysrc: the top of the source rectangle within @src.
 390 @xdest: the x coordinate of the destination within @drawable.
 391 @ydest: the y coordinate of the destination within @drawable.
 392 @width: the width of the area to be copied, or -1 to make the area extend to
 393 the right edge of the source pixmap.
 394 @height: the height of the area to be copied, or -1 to make the area extend
 395 to the bottom edge of the source pixmap.
 396
 397
 398 <!-- ##### FUNCTION gdk_draw_drawable ##### -->
 399 <para>
 400
 401 </para>
 402
 403 @drawable:
 404 @gc:
 405 @src:
 406 @xsrc:
 407 @ysrc:
 408 @xdest:
 409 @ydest:
 410 @width:
 411 @height:
 412
 413
 414 <!-- ##### FUNCTION gdk_draw_image ##### -->
 415 <para>
 416 Draws a #GdkImage onto a drawable.
 417 The depth of the #GdkImage must match the depth of the #GdkDrawable.
 418 </para>
 419
 420 @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 421 @gc: a #GdkGC.
 422 @image: the #GdkImage to draw.
 423 @xsrc: the left edge of the source rectangle within @image.
 424 @ysrc: the top of the source rectangle within @image.
 425 @xdest: the x coordinate of the destination within @drawable.
 426 @ydest: the y coordinate of the destination within @drawable.
 427 @width: the width of the area to be copied, or -1 to make the area extend to
 428 the right edge of @image.
 429 @height: the height of the area to be copied, or -1 to make the area extend
 430 to the bottom edge of @image.
 431
 432
 433 <!-- ##### FUNCTION gdk_drawable_get_image ##### -->
 434 <para>
 435
 436 </para>
 437
 438 @drawable:
 439 @x:
 440 @y:
 441 @width:
 442 @height:
 443 @Returns:
 444
 445