Drawing Primitives
<!-- ##### SECTION Short_Description ##### -->
-functions for drawing points, lines, arcs, and text.
+Functions for drawing points, lines, arcs, and text
<!-- ##### SECTION Long_Description ##### -->
<para>
<link linkend="gdk-Graphics-Contexts">Graphics Contexts</link> section for
more information.
</para>
+<para id="pango-data-structures">
+Some of the drawing operations take Pango data structures like #PangoContext,
+#PangoLayout or #PangoLayoutLine as arguments. If you're using GTK+, the ususal
+way to obtain these structures is via gtk_widget_create_pango_context() or
+gtk_widget_create_pango_layout().
+</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
-<!-- ##### ENUM GdkFill ##### -->
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
+<!-- ##### STRUCT GdkDrawable ##### -->
+<para>
+An opaque structure representing an object that can be
+drawn onto. This can be a #GdkPixmap, a #GdkBitmap,
+or a #GdkWindow.
+</para>
+
+
+<!-- ##### FUNCTION gdk_drawable_ref ##### -->
+<para>
+
+</para>
+
+@drawable:
+@Returns:
+
+
+<!-- ##### FUNCTION gdk_drawable_unref ##### -->
+<para>
+
+</para>
+
+@drawable:
+
+
+<!-- ##### FUNCTION gdk_drawable_set_data ##### -->
+<para>
+
+</para>
+
+@drawable:
+@key:
+@data:
+@destroy_func:
+
+
+<!-- ##### FUNCTION gdk_drawable_get_data ##### -->
+<para>
+
+</para>
+
+@drawable:
+@key:
+@Returns:
+
+
+<!-- ##### FUNCTION gdk_drawable_get_display ##### -->
+<para>
+
+</para>
+
+@drawable:
+@Returns:
+
+
+<!-- ##### FUNCTION gdk_drawable_get_screen ##### -->
+<para>
+
+</para>
+
+@drawable:
+@Returns:
+
+
+<!-- ##### FUNCTION gdk_drawable_get_visual ##### -->
+<para>
+
+</para>
+
+@drawable:
+@Returns:
+
+
+<!-- ##### FUNCTION gdk_drawable_set_colormap ##### -->
<para>
-Used to specify the way in which drawing operations are performed.
-See gdk_gc_set_fill().
+
</para>
-@GDK_SOLID: graphics are drawn in a solid color, usually the foreground color
-of the #GdkGC.
-@GDK_TILED: graphics are drawn using a tile pixmap. See gdk_gc_set_tile().
-@GDK_STIPPLED: graphics are drawn with a stipple (a pixmap with a depth of 1).
-Bits set in the stipple are drawn in the foreground color. Bits not set in the
-stipple are left as they are. See gdk_gc_set_stipple().
-@GDK_OPAQUE_STIPPLED: graphics are drawn with a stipple, as in @GDK_STIPPLED,
-except that the bits not set in the stipple are drawn in the background color
-instead of being left as they are. See gdk_gc_set_stipple().
+@drawable:
+@colormap:
+
-<!-- ##### ENUM GdkFillRule ##### -->
+<!-- ##### FUNCTION gdk_drawable_get_colormap ##### -->
<para>
-The method for determining which pixels are included in a region, when
-creating a #GdkRegion from a polygon.
-The fill rule is only relevant for polygons which overlap themselves.
+
</para>
-@GDK_EVEN_ODD_RULE: areas which are overlapped an odd number of times are
-included in the region, while areas overlapped an even number of times are not.
-@GDK_WINDING_RULE: overlapping areas are always included.
+@drawable:
+@Returns:
-<!-- ##### ENUM GdkLineStyle ##### -->
+<!-- ##### FUNCTION gdk_drawable_get_depth ##### -->
<para>
-Used to specify how lines are drawn. See gdk_gc_set_line_attributes().
+
</para>
-@GDK_LINE_SOLID: lines are drawn in a solid color, the foreground color.
-@GDK_LINE_ON_OFF_DASH: dashed lines are drawn, with the pixels between the
-dashes left as they are. The #GdkCapStyle is applied to each end of the dashes.
-@GDK_LINE_DOUBLE_DASH: dashed lines are drawn, alternating between the
-foreground and background colors. The %GDK_CAP_BUTT style is used where
-dashes and gaps meet.
+@drawable:
+@Returns:
+
-<!-- ##### ENUM GdkCapStyle ##### -->
+<!-- ##### FUNCTION gdk_drawable_get_size ##### -->
<para>
-Used to specify how the ends of lines and dashes are drawn.
-See gdk_gc_set_line_attributes().
+
</para>
-@GDK_CAP_NOT_LAST: this is equivalent to %GDK_CAP_BUTT, except that for a line
-width of 0 the final endpoint is not drawn.
-@GDK_CAP_BUTT: the ends of the line are square with no projection beyond the
-endpoint.
-@GDK_CAP_ROUND: the ends of the line are rounded using a circular arc centered
-on the endpoint. This is equivalent to %GDK_CAP_BUTT when the line width is 0.
-@GDK_CAP_PROJECTING: the ends of the line are square, but project beyond the
-endpoint to a distance of half the line width.
-This is equivalent to %GDK_CAP_BUTT when the line width is 0.
+@drawable:
+@width:
+@height:
+
-<!-- ##### ENUM GdkJoinStyle ##### -->
+<!-- ##### FUNCTION gdk_drawable_get_clip_region ##### -->
<para>
-Used to specify how the the joins between lines are drawn.
-See gdk_gc_set_line_attributes().
+
</para>
-@GDK_JOIN_MITER: the ends of the lines are extended to meet at a point.
-If the angle between the lines is less than 11 degrees, %GDK_JOIN_BEVEL is
-used instead.
-@GDK_JOIN_ROUND: the ends of the lines are rounded with a circular arc
-centered on the joinpoint, with a diameter equal to the line width.
-@GDK_JOIN_BEVEL: the lines have %GDK_CAP_BUTT cap styles, with the triangular
-notch filled.
+@drawable:
+@Returns:
+
+
+<!-- ##### FUNCTION gdk_drawable_get_visible_region ##### -->
+<para>
+
+</para>
+
+@drawable:
+@Returns:
+
<!-- ##### FUNCTION gdk_draw_point ##### -->
<para>
-Draws a point, using the foreground color and other attributes of the #GdkGC.
</para>
-@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
-@gc: a #GdkGC.
-@x: the x coordinate of the point.
-@y: the y coordinate of the point.
+@drawable:
+@gc:
+@x:
+@y:
+
+
+<!-- ##### FUNCTION gdk_draw_points ##### -->
+<para>
+</para>
+
+@drawable:
+@gc:
+@points:
+@n_points:
<!-- ##### FUNCTION gdk_draw_line ##### -->
<para>
-Draws a line, using the foreground color and other attributes of the #GdkGC.
</para>
-@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
-@gc: a #GdkGC.
+@drawable:
+@gc:
+@x1_:
+@y1_:
+@x2_:
+@y2_:
+
+
+<!-- ##### FUNCTION gdk_draw_lines ##### -->
+<para>
+</para>
+
+@drawable:
+@gc:
+@points:
+lines.
+@n_points:
+
+
+<!-- ##### FUNCTION gdk_draw_pixbuf ##### -->
+<para>
+
+</para>
+
+@drawable:
+@gc:
+@pixbuf:
+@src_x:
+@src_y:
+@dest_x:
+@dest_y:
+@width:
+@height:
+@dither:
+@x_dither:
+@y_dither:
+
+
+<!-- ##### FUNCTION gdk_draw_segments ##### -->
+<para>
+</para>
+
+@drawable:
+@gc:
+@segs:
+@n_segs:
+
+
+<!-- ##### STRUCT GdkSegment ##### -->
+<para>
+Specifies the start and end point of a line for use by the gdk_draw_segments()
+function.
+</para>
+
@x1: the x coordinate of the start point.
@y1: the y coordinate of the start point.
@x2: the x coordinate of the end point.
@y2: the y coordinate of the end point.
-
<!-- ##### FUNCTION gdk_draw_rectangle ##### -->
<para>
-Draws a rectangular outline or filled rectangle, using the foreground color
-and other attributes of the #GdkGC.
</para>
<note>
<para>
-A rectangle drawn filled is 1 pixel smaller in both dimensions than a rectangle
-outlined. Calling gdk_draw_rectangle (window, gc, TRUE, 0, 0, 20, 20) results
-in a filled rectangle 20 pixels wide and 20 pixels high. Calling
-gdk_draw_rectangle (window, gc, FALSE, 0, 0, 20, 20) results in an outlined
-rectangle with corners at (0, 0), (0, 20), (20, 20), and (20, 0), which
-makes it 21 pixels wide and 21 pixels high.
</para>
</note>
-@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
-@gc: a #GdkGC.
-@filled: TRUE if the rectangle should be filled.
-@x: the x coordinate of the left edge of the rectangle.
-@y: the y coordinate of the top edge of the rectangle.
-@width: the width of the rectangle.
-@height: the height of the rectangle.
+@drawable:
+@gc:
+@filled:
+@x:
+@y:
+@width:
+@height:
<!-- ##### FUNCTION gdk_draw_arc ##### -->
<para>
-Draws an arc or a filled 'pie slice'. The arc is defined by the bounding
-rectangle of the entire ellipse, and the start and end angles of the part of
-the ellipse to be drawn.
</para>
-@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
-@gc: a #GdkGC.
-@filled: TRUE if the arc should be filled, producing a 'pie slice'.
-@x: the x coordinate of the left edge of the bounding rectangle.
-@y: the y coordinate of the top edge of the bounding rectangle.
-@width: the width of the bounding rectangle.
-@height: the height of the bounding rectangle.
-@angle1: the start angle of the arc, relative to the 3 o'clock position,
-counter-clockwise, in 1/64ths of a degree.
-@angle2: the end angle of the arc, similar to @angle1.
+@drawable:
+@gc:
+@filled:
+@x:
+@y:
+@width:
+@height:
+@angle1:
+@angle2:
<!-- ##### FUNCTION gdk_draw_polygon ##### -->
<para>
-Draws an outlined or filled polygon.
</para>
-@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
-@gc: a #GdkGC.
-@filled: TRUE if the polygon should be filled. The polygon is closed
-automatically, connecting the last point to the first point if necessary.
-@points: an array of #GdkPoint structures specifying the points making up the
-polygon.
-@npoints: the number of points.
+@drawable:
+@gc:
+@filled:
+@points:
+@n_points:
+
+
+<!-- ##### FUNCTION gdk_draw_trapezoids ##### -->
+<para>
+
+</para>
+
+@drawable:
+@gc:
+@trapezoids:
+@n_trapezoids:
+
+
+<!-- ##### STRUCT GdkTrapezoid ##### -->
+<para>
+Specifies a trapezpoid for use by the gdk_draw_trapezoids().
+The trapezoids used here have parallel, horizontal top and
+bottom edges.
+</para>
+
+@y1: the y coordinate of the start point.
+@x11: the x coordinate of the top left corner
+@x21: the x coordinate of the top right corner
+@y2: the y coordinate of the end point.
+@x12: the x coordinate of the bottom left corner
+@x22: the x coordinate of the bottom right corner
+
+<!-- ##### FUNCTION gdk_draw_glyphs ##### -->
+<para>
+
+</para>
+
+@drawable:
+@gc:
+@font:
+@x:
+@y:
+@glyphs:
+
+
+<!-- ##### FUNCTION gdk_draw_glyphs_transformed ##### -->
+<para>
+
+</para>
+
+@drawable:
+@gc:
+@matrix:
+@font:
+@x:
+@y:
+@glyphs:
+
+
+<!-- ##### FUNCTION gdk_draw_layout_line ##### -->
+<para>
+
+</para>
+
+@drawable:
+@gc:
+@x:
+@y:
+@line:
+
+
+<!-- ##### FUNCTION gdk_draw_layout_line_with_colors ##### -->
+<para>
+
+</para>
+
+@drawable:
+@gc:
+@x:
+@y:
+@line:
+@foreground:
+@background:
+
+
+<!-- ##### FUNCTION gdk_draw_layout ##### -->
+<para>
+
+</para>
+
+@drawable:
+@gc:
+@x:
+@y:
+@layout:
+
+
+<!-- ##### FUNCTION gdk_draw_layout_with_colors ##### -->
+<para>
+
+</para>
+
+@drawable:
+@gc:
+@x:
+@y:
+@layout:
+@foreground:
+@background:
<!-- ##### FUNCTION gdk_draw_string ##### -->
<para>
-Draws a string of characters in the given font or fontset.
</para>
-@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
-@font: a #GdkFont.
-q@gc: a #GdkGC.
-@x: the x coordinate of the left edge of the text.
-@y: the y coordinate of the baseline of the text.
-@string: the string of characters to draw.
+@drawable:
+@font:
+@gc:
+@x:
+@y:
+@string:
<!-- ##### FUNCTION gdk_draw_text ##### -->
<para>
-Draws a number of characters in the given font or fontset.
</para>
-@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
-@font: a #GdkFont.
-@gc: a #GdkGC.
-@x: the x coordinate of the left edge of the text.
-@y: the y coordinate of the baseline of the text.
-@text: the characters to draw.
-@text_length: the number of characters of @text to draw.
+@drawable:
+@font:
+@gc:
+@x:
+@y:
+@text:
+@text_length:
<!-- ##### FUNCTION gdk_draw_text_wc ##### -->
<para>
-Draws a number of wide characters using the given font of fontset.
-If the font is a 1-byte font, the string is converted into 1-byte characters
-(discarding the high bytes) before output.
</para>
-@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
-@font: a #GdkFont.
-@gc: a #GdkGC.
-@x: the x coordinate of the left edge of the text.
-@y: the y coordinate of the baseline of the text.
-@text: the wide characters to draw.
-@text_length: the number of characters to draw.
+@drawable:
+@font:
+@gc:
+@x:
+@y:
+@text:
+@text_length:
-<!-- ##### FUNCTION gdk_draw_pixmap ##### -->
+<!-- ##### MACRO gdk_draw_pixmap ##### -->
<para>
Draws a pixmap, or a part of a pixmap, onto another drawable.
</para>
-@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
-@gc: a #GdkGC.
-@src: the source #GdkPixmap to draw.
-@xsrc: the left edge of the source rectangle within @src.
-@ysrc: the top of the source rectangle within @src.
-@xdest: the x coordinate of the destination within @drawable.
-@ydest: the y coordinate of the destination within @drawable.
-@width: the width of the area to be copied, or -1 to make the area extend to
-the right edge of the source pixmap.
-@height: the height of the area to be copied, or -1 to make the area extend
-to the bottom edge of the source pixmap.
+@Deprecated: Use gdk_draw_drawable() instead.
-<!-- ##### FUNCTION gdk_draw_bitmap ##### -->
+<!-- ##### FUNCTION gdk_draw_drawable ##### -->
<para>
</para>
-@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@drawable:
@gc:
@src:
@xsrc:
<!-- ##### FUNCTION gdk_draw_image ##### -->
<para>
-
</para>
-@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@drawable:
@gc:
@image:
@xsrc:
@height:
-<!-- ##### FUNCTION gdk_draw_points ##### -->
-<para>
-Draws a number of points, using the foreground color and other attributes of
-the #GdkGC.
-</para>
-
-@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
-@gc: a #GdkGC.
-@points: an array of #GdkPoint structures.
-@npoints: the number of points to be drawn.
-
-
-<!-- ##### FUNCTION gdk_draw_segments ##### -->
+<!-- ##### FUNCTION gdk_drawable_get_image ##### -->
<para>
</para>
-@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
-@gc:
-@segs:
-@nsegs:
+@drawable:
+@x:
+@y:
+@width:
+@height:
+@Returns:
-<!-- ##### STRUCT GdkSegment ##### -->
+<!-- ##### FUNCTION gdk_drawable_copy_to_image ##### -->
<para>
</para>
-@x1:
-@y1:
-@x2:
-@y2:
-
-<!-- ##### FUNCTION gdk_draw_lines ##### -->
-<para>
-Draws a series of lines connecting the given points.
-The way in which joins between lines are draw is determined by the
-#GdkCapStyle value in the #GdkGC. This can be set with
-gdk_gc_set_line_attributes().
-</para>
-
-@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
-@gc: a #GdkGC.
-@points: an array of #GdkPoint structures specifying the endpoints of the
-lines.
-@npoints: the number of endpoints.
+@drawable:
+@image:
+@src_x:
+@src_y:
+@dest_x:
+@dest_y:
+@width:
+@height:
+@Returns: