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