AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-11-06 00:30:08 +00:00
Code Issues Projects Releases Wiki Activity

new section from Lee Mallabone.

Browse Source 
1999-08-28  Damon Chaplin  <damon@karuna.freeserve.co.uk>

	* gtk/tmpl/gtkbbox.sgml: new section from Lee Mallabone.

	* gdk/gdk-sections.txt: rearranged rgb, regions, and drawing sections.

	* gdk/tmpl/rgb.sgml: new section from Raph Levien, with a few changes
	by me, including a little example app.

	* gdk/tmpl/regions.sgml:
	* gdk/tmpl/event_structs.sgml:
	* gdk/tmpl/drawing.sgml: my first attempt.
	* gdk/tmpl/cursors.sgml: tiny changes.
This commit is contained in:
Damon Chaplin 1999-08-28 20:47:33 +00:00 committed by Damon Chaplin
parent 411e9361c2
commit fc3cd85675
8 changed files with 896 additions and 477 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/reference/ChangeLog
View File

@ -1,3 +1,17 @@
1999-08-28 Damon Chaplin <damon@karuna.freeserve.co.uk>
* gtk/tmpl/gtkbbox.sgml: new section from Lee Mallabone.
* gdk/gdk-sections.txt: rearranged rgb, regions, and drawing sections.
* gdk/tmpl/rgb.sgml: new section from Raph Levien, with a few changes
by me, including a little example app.
* gdk/tmpl/regions.sgml:
* gdk/tmpl/event_structs.sgml:
* gdk/tmpl/drawing.sgml: my first attempt.
* gdk/tmpl/cursors.sgml: tiny changes.
Tue Aug 17 09:14:01 1999 Owen Taylor <otaylor@redhat.com> Tue Aug 17 09:14:01 1999 Owen Taylor <otaylor@redhat.com>
* gtk/tmpl/gtktypeutils.sgml: Fix corrupted end tag. * gtk/tmpl/gtktypeutils.sgml: Fix corrupted end tag.

64
docs/reference/gdk/gdk-sections.txt
View File

@ -77,29 +77,33 @@ gdk_image_destroy
<SECTION> <SECTION>
<TITLE>GdkRGB</TITLE> <TITLE>GdkRGB</TITLE>
<FILE>rgb</FILE> <FILE>rgb</FILE>
GdkRgbCmap
GdkRgbDither
gdk_rgb_init gdk_rgb_init
gdk_rgb_cmap_new
gdk_rgb_cmap_free
gdk_rgb_gc_set_foreground
gdk_rgb_gc_set_background
<SUBSECTION>
gdk_draw_rgb_image gdk_draw_rgb_image
gdk_draw_rgb_image_dithalign
gdk_draw_indexed_image gdk_draw_indexed_image
gdk_draw_gray_image gdk_draw_gray_image
gdk_draw_rgb_32_image gdk_draw_rgb_32_image
gdk_draw_rgb_image_dithalign GdkRgbDither
<SUBSECTION>
gdk_rgb_cmap_new
gdk_rgb_cmap_free
GdkRgbCmap
<SUBSECTION>
gdk_rgb_gc_set_foreground
gdk_rgb_gc_set_background
gdk_rgb_xpixel_from_rgb gdk_rgb_xpixel_from_rgb
gdk_rgb_set_verbose <SUBSECTION>
gdk_rgb_ditherable
gdk_rgb_set_install gdk_rgb_set_install
gdk_rgb_set_min_colors gdk_rgb_set_min_colors
gdk_rgb_get_visual gdk_rgb_get_visual
gdk_rgb_get_cmap gdk_rgb_get_cmap
gdk_rgb_ditherable
gdk_rgb_set_verbose
</SECTION> </SECTION>
<SECTION> <SECTION>
@ -164,26 +168,29 @@ gdk_char_height
<TITLE>Drawing Primitives</TITLE> <TITLE>Drawing Primitives</TITLE>
<FILE>drawing</FILE> <FILE>drawing</FILE>
GdkFill GdkFill
GdkFillRule
GdkLineStyle GdkLineStyle
GdkCapStyle GdkCapStyle
GdkJoinStyle GdkJoinStyle
gdk_draw_point gdk_draw_point
gdk_draw_points
gdk_draw_line gdk_draw_line
gdk_draw_lines
gdk_draw_segments
GdkSegment
gdk_draw_rectangle gdk_draw_rectangle
gdk_draw_arc gdk_draw_arc
gdk_draw_polygon gdk_draw_polygon
<SUBSECTION>
gdk_draw_string gdk_draw_string
gdk_draw_text gdk_draw_text
gdk_draw_text_wc gdk_draw_text_wc
<SUBSECTION>
gdk_draw_pixmap gdk_draw_pixmap
gdk_draw_bitmap gdk_draw_bitmap
gdk_draw_image gdk_draw_image
gdk_draw_points
gdk_draw_segments
GdkSegment
gdk_draw_lines
</SECTION> </SECTION>
<SECTION> <SECTION>
@ -410,27 +417,34 @@ gdk_color_context_get_index_from_palette
<FILE>regions</FILE> <FILE>regions</FILE>
GdkPoint GdkPoint
<SUBSECTION>
GdkRectangle GdkRectangle
gdk_rectangle_intersect gdk_rectangle_intersect
gdk_rectangle_union gdk_rectangle_union
<SUBSECTION>
GdkRegion GdkRegion
gdk_region_new gdk_region_new
gdk_region_polygon
GdkFillRule
gdk_region_destroy gdk_region_destroy
gdk_region_get_clipbox
<SUBSECTION>
gdk_regions_intersect
gdk_regions_union
gdk_regions_subtract
gdk_regions_xor
gdk_region_union_with_rect
gdk_region_offset
gdk_region_shrink
<SUBSECTION>
gdk_region_empty gdk_region_empty
gdk_region_equal gdk_region_equal
gdk_region_point_in gdk_region_point_in
gdk_region_rect_in gdk_region_rect_in
GdkOverlapType GdkOverlapType
gdk_region_polygon gdk_region_get_clipbox
gdk_region_offset
gdk_region_shrink
gdk_region_union_with_rect
gdk_regions_intersect
gdk_regions_union
gdk_regions_subtract
gdk_regions_xor
</SECTION> </SECTION>
<SECTION> <SECTION>

3
docs/reference/gdk/tmpl/cursors.sgml
View File

@ -2,7 +2,7 @@
Cursors Cursors
<!-- ##### SECTION Short_Description ##### --> <!-- ##### SECTION Short_Description ##### -->
standard and pixmap cursors.
<!-- ##### SECTION Long_Description ##### --> <!-- ##### SECTION Long_Description ##### -->
<para> <para>
@ -40,6 +40,7 @@ Creates a new standard cursor.
<para> <para>
Creates a new cursor from a given pixmap and mask. Both the pixmap and mask Creates a new cursor from a given pixmap and mask. Both the pixmap and mask
must have a depth of 1 (i.e. each pixel has only 2 values - on or off). must have a depth of 1 (i.e. each pixel has only 2 values - on or off).
The standard cursor size is 16 by 16 pixels.
</para> </para>
<example><title>Creating a custom cursor.</title> <example><title>Creating a custom cursor.</title>
<programlisting> <programlisting>

270
docs/reference/gdk/tmpl/drawing.sgml
View File

@ -2,11 +2,22 @@
Drawing Primitives Drawing Primitives
<!-- ##### SECTION Short_Description ##### --> <!-- ##### SECTION Short_Description ##### -->
functions for drawing points, lines, arcs, and text.
<!-- ##### SECTION Long_Description ##### --> <!-- ##### SECTION Long_Description ##### -->
<para> <para>
These functions provide support for drawing points, lines, arcs and text
onto what are called 'drawables'. Drawables, as the name suggests, are things
which support drawing onto them, and are either #GdkWindow or #GdkPixmap
objects.
</para>
<para>
Many of the drawing operations take a #GdkGC argument, which represents a
graphics context. This #GdkGC contains a number of drawing attributes such
as foreground color, background color and line width, and is used to reduce
the number of arguments needed for each drawing operation. See the
<link linkend="gdk-Graphics-Contexts">Graphics Contexts</link> section for
more information.
</para> </para>
<!-- ##### SECTION See_Also ##### --> <!-- ##### SECTION See_Also ##### -->
@ -16,171 +27,215 @@ Drawing Primitives
<!-- ##### ENUM GdkFill ##### --> <!-- ##### ENUM GdkFill ##### -->
<para> <para>
Used to specify the way in which drawing operations are performed.
See gdk_gc_set_fill().
</para> </para>
@GDK_SOLID: @GDK_SOLID: graphics are drawn in a solid color, usually the foreground color
@GDK_TILED: of the #GdkGC.
@GDK_STIPPLED: @GDK_TILED: graphics are drawn using a tile pixmap. See gdk_gc_set_tile().
@GDK_OPAQUE_STIPPLED: @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().
<!-- ##### ENUM GdkFillRule ##### --> <!-- ##### ENUM GdkFillRule ##### -->
<para> <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> </para>
@GDK_EVEN_ODD_RULE: @GDK_EVEN_ODD_RULE: areas which are overlapped an odd number of times are
@GDK_WINDING_RULE: included in the region, while areas overlapped an even number of times are not.
@GDK_WINDING_RULE: overlapping areas are always included.
<!-- ##### ENUM GdkLineStyle ##### --> <!-- ##### ENUM GdkLineStyle ##### -->
<para> <para>
Used to specify how lines are drawn. See gdk_gc_set_line_attributes().
</para> </para>
@GDK_LINE_SOLID: @GDK_LINE_SOLID: lines are drawn in a solid color, the foreground color.
@GDK_LINE_ON_OFF_DASH: @GDK_LINE_ON_OFF_DASH: dashed lines are drawn, with the pixels between the
@GDK_LINE_DOUBLE_DASH: 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.
<!-- ##### ENUM GdkCapStyle ##### --> <!-- ##### ENUM GdkCapStyle ##### -->
<para> <para>
Used to specify how the ends of lines and dashes are drawn.
See gdk_gc_set_line_attributes().
</para> </para>
@GDK_CAP_NOT_LAST: @GDK_CAP_NOT_LAST: this is equivalent to %GDK_CAP_BUTT, except that for a line
@GDK_CAP_BUTT: width of 0 the final endpoint is not drawn.
@GDK_CAP_ROUND: @GDK_CAP_BUTT: the ends of the line are square with no projection beyond the
@GDK_CAP_PROJECTING: 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.
<!-- ##### ENUM GdkJoinStyle ##### --> <!-- ##### ENUM GdkJoinStyle ##### -->
<para> <para>
Used to specify how the the joins between lines are drawn.
See gdk_gc_set_line_attributes().
</para> </para>
@GDK_JOIN_MITER: @GDK_JOIN_MITER: the ends of the lines are extended to meet at a point.
@GDK_JOIN_ROUND: If the angle between the lines is less than 11 degrees, %GDK_JOIN_BEVEL is
@GDK_JOIN_BEVEL: 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.
<!-- ##### FUNCTION gdk_draw_point ##### --> <!-- ##### FUNCTION gdk_draw_point ##### -->
<para> <para>
Draws a point, using the foreground color and other attributes of the #GdkGC.
</para> </para>
@drawable: @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
@gc: @gc: a #GdkGC.
@x: @x: the x coordinate of the point.
@y: @y: the y coordinate of the point.
<!-- ##### FUNCTION gdk_draw_line ##### --> <!-- ##### FUNCTION gdk_draw_line ##### -->
<para> <para>
Draws a line, using the foreground color and other attributes of the #GdkGC.
</para> </para>
@drawable: @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
@gc: @gc: a #GdkGC.
@x1: @x1: the x coordinate of the start point.
@y1: @y1: the y coordinate of the start point.
@x2: @x2: the x coordinate of the end point.
@y2: @y2: the y coordinate of the end point.
<!-- ##### FUNCTION gdk_draw_rectangle ##### --> <!-- ##### FUNCTION gdk_draw_rectangle ##### -->
<para> <para>
Draws a rectangular outline or filled rectangle, using the foreground color
and other attributes of the #GdkGC.
</para> </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: @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
@gc: @gc: a #GdkGC.
@filled: @filled: TRUE if the rectangle should be filled.
@x: @x: the x coordinate of the left edge of the rectangle.
@y: @y: the y coordinate of the top edge of the rectangle.
@width: @width: the width of the rectangle.
@height: @height: the height of the rectangle.
<!-- ##### FUNCTION gdk_draw_arc ##### --> <!-- ##### FUNCTION gdk_draw_arc ##### -->
<para> <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> </para>
@drawable: @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
@gc: @gc: a #GdkGC.
@filled: @filled: TRUE if the arc should be filled, producing a 'pie slice'.
@x: @x: the x coordinate of the left edge of the bounding rectangle.
@y: @y: the y coordinate of the top edge of the bounding rectangle.
@width: @width: the width of the bounding rectangle.
@height: @height: the height of the bounding rectangle.
@angle1: @angle1: the start angle of the arc, relative to the 3 o'clock position,
@angle2: counter-clockwise, in 1/64ths of a degree.
@angle2: the end angle of the arc, similar to @angle1.
<!-- ##### FUNCTION gdk_draw_polygon ##### --> <!-- ##### FUNCTION gdk_draw_polygon ##### -->
<para> <para>
Draws an outlined or filled polygon.
</para> </para>
@drawable: @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
@gc: @gc: a #GdkGC.
@filled: @filled: TRUE if the polygon should be filled. The polygon is closed
@points: automatically, connecting the last point to the first point if necessary.
@npoints: @points: an array of #GdkPoint structures specifying the points making up the
polygon.
@npoints: the number of points.
<!-- ##### FUNCTION gdk_draw_string ##### --> <!-- ##### FUNCTION gdk_draw_string ##### -->
<para> <para>
Draws a string of characters in the given font or fontset.
</para> </para>
@drawable: @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
@font: @font: a #GdkFont.
@gc: q@gc: a #GdkGC.
@x: @x: the x coordinate of the left edge of the text.
@y: @y: the y coordinate of the baseline of the text.
@string: @string: the string of characters to draw.
<!-- ##### FUNCTION gdk_draw_text ##### --> <!-- ##### FUNCTION gdk_draw_text ##### -->
<para> <para>
Draws a number of characters in the given font or fontset.
</para> </para>
@drawable: @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
@font: @font: a #GdkFont.
@gc: @gc: a #GdkGC.
@x: @x: the x coordinate of the left edge of the text.
@y: @y: the y coordinate of the baseline of the text.
@text: @text: the characters to draw.
@text_length: @text_length: the number of characters of @text to draw.
<!-- ##### FUNCTION gdk_draw_text_wc ##### --> <!-- ##### FUNCTION gdk_draw_text_wc ##### -->
<para> <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> </para>
@drawable: @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
@font: @font: a #GdkFont.
@gc: @gc: a #GdkGC.
@x: @x: the x coordinate of the left edge of the text.
@y: @y: the y coordinate of the baseline of the text.
@text: @text: the wide characters to draw.
@text_length: @text_length: the number of characters to draw.
<!-- ##### FUNCTION gdk_draw_pixmap ##### --> <!-- ##### FUNCTION gdk_draw_pixmap ##### -->
<para> <para>
Draws a pixmap, or a part of a pixmap, onto another drawable.
</para> </para>
@drawable: @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
@gc: @gc: a #GdkGC.
@src: @src: the source #GdkPixmap to draw.
@xsrc: @xsrc: the left edge of the source rectangle within @src.
@ysrc: @ysrc: the top of the source rectangle within @src.
@xdest: @xdest: the x coordinate of the destination within @drawable.
@ydest: @ydest: the y coordinate of the destination within @drawable.
@width: @width: the width of the area to be copied, or -1 to make the area extend to
@height: 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.
<!-- ##### FUNCTION gdk_draw_bitmap ##### --> <!-- ##### FUNCTION gdk_draw_bitmap ##### -->
@ -188,7 +243,7 @@ Drawing Primitives
</para> </para>
@drawable: @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
@gc: @gc:
@src: @src:
@xsrc: @xsrc:
@ -204,7 +259,7 @@ Drawing Primitives
</para> </para>
@drawable: @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
@gc: @gc:
@image: @image:
@xsrc: @xsrc:
@ -217,13 +272,14 @@ Drawing Primitives
<!-- ##### FUNCTION gdk_draw_points ##### --> <!-- ##### FUNCTION gdk_draw_points ##### -->
<para> <para>
Draws a number of points, using the foreground color and other attributes of
the #GdkGC.
</para> </para>
@drawable: @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
@gc: @gc: a #GdkGC.
@points: @points: an array of #GdkPoint structures.
@npoints: @npoints: the number of points to be drawn.
<!-- ##### FUNCTION gdk_draw_segments ##### --> <!-- ##### FUNCTION gdk_draw_segments ##### -->
@ -231,7 +287,7 @@ Drawing Primitives
</para> </para>
@drawable: @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
@gc: @gc:
@segs: @segs:
@nsegs: @nsegs:
@ -249,12 +305,16 @@ Drawing Primitives
<!-- ##### FUNCTION gdk_draw_lines ##### --> <!-- ##### FUNCTION gdk_draw_lines ##### -->
<para> <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> </para>
@drawable: @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
@gc: @gc: a #GdkGC.
@points: @points: an array of #GdkPoint structures specifying the endpoints of the
@npoints: lines.
@npoints: the number of endpoints.

74
docs/reference/gdk/tmpl/event_structs.sgml
View File

@ -8,6 +8,12 @@ Event Structures
<para> <para>
</para> </para>
<note>
<para>
A common mistake is to forget to set the event mask of a widget so that the
required events are received. See gtk_widget_set_events().
</para>
</note>
<!-- ##### SECTION See_Also ##### --> <!-- ##### SECTION See_Also ##### -->
<para> <para>
@ -16,12 +22,13 @@ Event Structures
<!-- ##### STRUCT GdkEventAny ##### --> <!-- ##### STRUCT GdkEventAny ##### -->
<para> <para>
Contains the fields which are common to all event structs.
Any event can safely be cast to a #GdkEventAny to access these fields.
</para> </para>
@type: @type: the type of the event.
@window: @window: the window which received the event.
@send_event: @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
<!-- ##### STRUCT GdkEventExpose ##### --> <!-- ##### STRUCT GdkEventExpose ##### -->
<para> <para>
@ -85,24 +92,55 @@ Event Structures
<!-- ##### STRUCT GdkEventButton ##### --> <!-- ##### STRUCT GdkEventButton ##### -->
<para> <para>
Used for button press and button release events. The
<structfield>type</structfield> field will be one of %GDK_BUTTON_PRESS,
%GDK_2BUTTON_PRESS, GDK_3BUTTON_PRESS, and GDK_BUTTON_RELEASE.
</para>
<para>
Double and treble-clicks result in a sequence of events being received.
For double-clicks the order of events will be:
<orderedlist>
<listitem><para>%GDK_BUTTON_PRESS</para></listitem>
<listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
<listitem><para>%GDK_BUTTON_PRESS</para></listitem>
<listitem><para>%GDK_2BUTTON_PRESS</para></listitem>
<listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
</orderedlist>
Note that the first click is received just like a normal
button press, while the second click results in a %GDK_2BUTTON_PRESS being
received just after the %GDK_BUTTON_PRESS.
</para>
<para>
Treble-clicks are very similar to double-clicks, except that %GDK_3BUTTON_PRESS
is inserted after the third click. The order of the events is:
<orderedlist>
<listitem><para>%GDK_BUTTON_PRESS</para></listitem>
<listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
<listitem><para>%GDK_BUTTON_PRESS</para></listitem>
<listitem><para>%GDK_2BUTTON_PRESS</para></listitem>
<listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
<listitem><para>%GDK_BUTTON_PRESS</para></listitem>
<listitem><para>%GDK_3BUTTON_PRESS</para></listitem>
<listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
</orderedlist>
</para> </para>
@type: @type: the type of the event.
@window: @window: the window which received the event.
@send_event: @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
@time: @time: the time of the event in milliseconds. This wraps around every 50 days.
@x: @x: the x coordinate of the mouse relative to the window.
@y: @y: the y coordinate of the mouse relative to the window.
@pressure: @pressure: the pressure of the button press, intended for input devices such
as graphics tablets. It defaults to 0.5.
@xtilt: @xtilt:
@ytilt: @ytilt:
@state: @state:
@button: @button:
@source: @source:
@deviceid: @deviceid:
@x_root: @x_root: the x coordinate of the mouse relative to the root of the screen.
@y_root: @y_root: the y coordinate of the mouse relative to the root of the screen.
<!-- ##### STRUCT GdkEventKey ##### --> <!-- ##### STRUCT GdkEventKey ##### -->
<para> <para>
@ -193,14 +231,6 @@ Event Structures
@time: @time:
@state: @state:
<!-- ##### ENUM GdkPropertyState ##### -->
<para>
</para>
@GDK_PROPERTY_NEW_VALUE:
@GDK_PROPERTY_DELETE:
<!-- ##### STRUCT GdkEventSelection ##### --> <!-- ##### STRUCT GdkEventSelection ##### -->
<para> <para>

186
docs/reference/gdk/tmpl/regions.sgml
View File

@ -2,11 +2,25 @@
Points, Rectangles and Regions Points, Rectangles and Regions
<!-- ##### SECTION Short_Description ##### --> <!-- ##### SECTION Short_Description ##### -->
simple graphical data types.
<!-- ##### SECTION Long_Description ##### --> <!-- ##### SECTION Long_Description ##### -->
<para> <para>
GDK provides the #GdkPoint, #GdkRectangle and #GdkRegion data types for
representing pixels and sets of pixels on the screen.
</para>
<para>
#GdkPoint is a simple structure containing an x and y coordinate of a point.
</para>
<para>
#GdkRectangle is a structure holding the position and size of a rectangle.
The intersection of two rectangles can be computed with
gdk_rectangle_intersect(). To find the union of two rectangles use
gdk_rectangle_union().
</para>
<para>
#GdkRegion is an opaque data type holding a set of arbitrary pixels, and is
usually used for clipping graphical operations (see gdk_gc_set_clip_region()).
</para> </para>
<!-- ##### SECTION See_Also ##### --> <!-- ##### SECTION See_Also ##### -->
@ -16,202 +30,218 @@ Points, Rectangles and Regions
<!-- ##### STRUCT GdkPoint ##### --> <!-- ##### STRUCT GdkPoint ##### -->
<para> <para>
Defines the x and y coordinates of a point.
Note that both are defined as #gint16 values, so the coordinates are limited
to between -32,768 and 32,767.
</para> </para>
@x: @x: the x coordinate of the point.
@y: @y: the y coordinate of the point.
<!-- ##### STRUCT GdkRectangle ##### --> <!-- ##### STRUCT GdkRectangle ##### -->
<para> <para>
Defines the position and size of a rectangle.
</para> </para>
@x: @x: the x coordinate of the left edge of the rectangle.
@y: @y: the y coordinate of the top of the rectangle.
@width: @width: the width of the rectangle.
@height: @height: the height of the rectangle.
<!-- ##### FUNCTION gdk_rectangle_intersect ##### --> <!-- ##### FUNCTION gdk_rectangle_intersect ##### -->
<para> <para>
Calculates the intersection of two rectangles.
</para> </para>
@src1: @src1: a #GdkRectangle.
@src2: @src2: a #GdkRectangle.
@dest: @dest: the intersection of @src1 and @src2.
@Returns: @Returns: TRUE if the rectangles intersect.
<!-- ##### FUNCTION gdk_rectangle_union ##### --> <!-- ##### FUNCTION gdk_rectangle_union ##### -->
<para> <para>
Calculates the union of two rectangles.
The union of rectangles @src1 and @src2 is the smallest rectangle which
includes both @src1 and @src2 within it.
</para> </para>
@src1: @src1: a #GdkRectangle.
@src2: @src2: a #GdkRectangle.
@dest: @dest: the union of @src1 and @src2.
<!-- ##### STRUCT GdkRegion ##### --> <!-- ##### STRUCT GdkRegion ##### -->
<para> <para>
A GdkRegion represents a set of pixels on the screen.
The only user-visible field of the structure is the user_data member, which
can be used to attach arbitrary data to the #GdkRegion.
</para> </para>
@user_data: @user_data: arbitrary data attached to the #GdkRegion.
<!-- ##### FUNCTION gdk_region_new ##### --> <!-- ##### FUNCTION gdk_region_new ##### -->
<para> <para>
Creates a new empty #GdkRegion.
</para> </para>
@Returns: @Returns: a new empty #GdkRegion.
<!-- ##### FUNCTION gdk_region_destroy ##### --> <!-- ##### FUNCTION gdk_region_destroy ##### -->
<para> <para>
Destroys a #GdkRegion.
</para> </para>
@region: @region: a #GdkRegion.
<!-- ##### FUNCTION gdk_region_get_clipbox ##### --> <!-- ##### FUNCTION gdk_region_get_clipbox ##### -->
<para> <para>
Returns the smallest rectangle which includes the entire #GdkRegion.
</para> </para>
@region: @region: a #GdkRegion.
@rectangle: @rectangle: returns the smallest rectangle which includes all of @region.
<!-- ##### FUNCTION gdk_region_empty ##### --> <!-- ##### FUNCTION gdk_region_empty ##### -->
<para> <para>
Returns TRUE if the #GdkRegion is empty.
</para> </para>
@region: @region: a #GdkRegion.
@Returns: @Returns: TRUE if @region is empty.
<!-- ##### FUNCTION gdk_region_equal ##### --> <!-- ##### FUNCTION gdk_region_equal ##### -->
<para> <para>
Returns TRUE if the two regions are the same.
</para> </para>
@region1: @region1: a #GdkRegion.
@region2: @region2: a #GdkRegion.
@Returns: @Returns: TRUE if @region1 and @region2 are equal.
<!-- ##### FUNCTION gdk_region_point_in ##### --> <!-- ##### FUNCTION gdk_region_point_in ##### -->
<para> <para>
Returns TRUE if a point is in a region.
</para> </para>
@region: @region: a #GdkRegion.
@x: @x: the x coordinate of a point.
@y: @y: the y coordinate of a point.
@Returns: @Returns: TRUE if the point is in @region.
<!-- ##### FUNCTION gdk_region_rect_in ##### --> <!-- ##### FUNCTION gdk_region_rect_in ##### -->
<para> <para>
Tests whether a rectangle is within a region.
</para> </para>
@region: @region: a #GdkRegion.
@rect: @rect: a #GdkRectangle.
@Returns: @Returns: GDK_OVERLAP_RECTANGLE_IN, GDK_OVERLAP_RECTANGLE_OUT, or
GDK_OVERLAP_RECTANGLE_PART, depending on whether the rectangle is inside,
outside, or partly inside the #GdkRegion, respectively.
<!-- ##### ENUM GdkOverlapType ##### --> <!-- ##### ENUM GdkOverlapType ##### -->
<para> <para>
Specifies the possible values returned by gdk_region_rect_in().
</para> </para>
@GDK_OVERLAP_RECTANGLE_IN: @GDK_OVERLAP_RECTANGLE_IN: if the rectangle is inside the #GdkRegion.
@GDK_OVERLAP_RECTANGLE_OUT: @GDK_OVERLAP_RECTANGLE_OUT: if the rectangle is outside the #GdkRegion.
@GDK_OVERLAP_RECTANGLE_PART: @GDK_OVERLAP_RECTANGLE_PART: if the rectangle is partly inside the #GdkRegion.
<!-- ##### FUNCTION gdk_region_polygon ##### --> <!-- ##### FUNCTION gdk_region_polygon ##### -->
<para> <para>
Creates a new #GdkRegion using the polygon defined by a number of points.
</para> </para>
@points: @points: an array of #GdkPoint structs.
@npoints: @npoints: the number of elements in the @points array.
@fill_rule: @fill_rule: specifies which pixels are included in the region when the polygon
@Returns: overlaps itself.
@Returns: a new #GdkRegion based on the given polygon.
<!-- ##### FUNCTION gdk_region_offset ##### --> <!-- ##### FUNCTION gdk_region_offset ##### -->
<para> <para>
Moves a region.
</para> </para>
@region: @region: a #GdkRegion.
@dx: @dx: the distance to move the region horizontally.
@dy: @dy: the distance to move the region vertically.
<!-- ##### FUNCTION gdk_region_shrink ##### --> <!-- ##### FUNCTION gdk_region_shrink ##### -->
<para> <para>
Resizes a region.
</para> </para>
@region: @region: a #GdkRegion.
@dx: @dx:
@dy: @dy:
<!-- ##### FUNCTION gdk_region_union_with_rect ##### --> <!-- ##### FUNCTION gdk_region_union_with_rect ##### -->
<para> <para>
Returns the union of a region and a rectangle.
</para> </para>
@region: @region: a #GdkRegion.
@rect: @rect: a #GdkRectangle.
@Returns: @Returns: the union of @region and @rect.
<!-- ##### FUNCTION gdk_regions_intersect ##### --> <!-- ##### FUNCTION gdk_regions_intersect ##### -->
<para> <para>
Returns the intersection of two regions.
</para> </para>
@source1: @source1: a #GdkRegion.
@source2: @source2: a #GdkRegion.
@Returns: @Returns: the intersection of @source1 and @source2.
<!-- ##### FUNCTION gdk_regions_union ##### --> <!-- ##### FUNCTION gdk_regions_union ##### -->
<para> <para>
Returns the union of two regions.
This is all pixels in either of @source1 or @source2.
</para> </para>
@source1: @source1: a #GdkRegion.
@source2: @source2: a #GdkRegion.
@Returns: @Returns: the union of @source1 and @source2.
<!-- ##### FUNCTION gdk_regions_subtract ##### --> <!-- ##### FUNCTION gdk_regions_subtract ##### -->
<para> <para>
Subtracts one region from another.
The result is a region containing all the pixels which are in @source1, but
which are not in @source2.
</para> </para>
@source1: @source1: a #GdkRegion.
@source2: @source2: a #GdkRegion to subtract from @source1.
@Returns: @Returns: @source1 - @source2.
<!-- ##### FUNCTION gdk_regions_xor ##### --> <!-- ##### FUNCTION gdk_regions_xor ##### -->
<para> <para>
Returns the difference between the union and the intersection of two regions.
This is a region containing the pixels that are in one of the source regions,
but which are not in both.
</para> </para>
@source1: @source1: a #GdkRegion.
@source2: @source2: a #GdkRegion.
@Returns: @Returns: the difference between the union and the intersection of @source1
and @source2.

408
docs/reference/gdk/tmpl/rgb.sgml
View File

@ -2,215 +2,449 @@
GdkRGB GdkRGB
<!-- ##### SECTION Short_Description ##### --> <!-- ##### SECTION Short_Description ##### -->
displays RGB images (as well as grayscale and colormapped) to
the native window.
<!-- ##### SECTION Long_Description ##### --> <!-- ##### SECTION Long_Description ##### -->
<para> <para>
GdkRgb converts RGB, grayscale, and colormapped images into the native
window pixel format and displays them. It takes care of colormaps,
visuals, dithering, and management of the temporary buffers.
</para> </para>
<para>
You must call gdk_rgb_init() before using any GdkRgb functionality. If
you fail to do so, expect coredumps. All Gtk+ widgets that use GdkRgb
(including #GtkPreview) call gdk_rgb_init() in their class_init method.
Thus, if you use GdkRgb only indirectly, you don't need to worry
about it.
</para>
<para>
GdkRgb tries to use the system default visual and colormap, but
doesn't always succeed. Thus, you have to be prepared to install the
visual and colormap generated by GdkRgb. The following code sequence
(before any widgets are created) should work in most applications:
</para>
<informalexample>
<programlisting>
gdk_rgb_init ();
gtk_widget_set_default_colormap (gdk_rgb_get_cmap ());
gtk_widget_set_default_visual (gdk_rgb_get_visual ());
</programlisting>
</informalexample>
<para>
You can also push the colormap and visual, but in general it doesn't
work unless the push wraps the window creation call. If you wrap the
push around a widget which is embedded in a window without the GdkRgb
colormap and visual, it probably won't work, and is likely to cause
colormap flashing, as well.
</para>
<para>
On 8-bit systems, the colormaps used by Imlib and GdkRgb may
conflict. There is no good general solution to this other than phasing
out the dependence on Imlib.
</para>
<para>
You can set the threshold for installing colormaps with
gdk_rgb_set_min_colors (). The default is 5x5x5 (125). If a colorcube
of this size or larger can be allocated in the default colormap, then
that's done. Otherwise, GdkRgb creates its own private colormap.
Setting it to 0 means that it always tries to use the default
colormap, and setting it to 256 means that it always creates a private
one. Note, however, that setting it to 0 doesn't let you get away with
ignoring the colormap and visual - a colormap is always created in
grayscale and direct color modes, and the visual is changed in cases
where a "better" visual than the default is available.
</para>
<example>
<title>A simple example program using GdkRGB.</title>
<programlisting>
#include &lt;gtk/gtk.h&gt;
#define IMAGE_WIDTH 256
#define IMAGE_HEIGHT 256
guchar rgbbuf[IMAGE_WIDTH * IMAGE_HEIGHT * 3];
gboolean on_darea_expose (GtkWidget *widget,
GdkEventExpose *event,
gpointer user_data);
int
main (int argc, char *argv[])
{
GtkWidget *window, *darea;
gint x, y;
guchar *pos;
gtk_init (&amp;argc, &amp;argv);
gdk_rgb_init ();
window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
darea = gtk_drawing_area_new ();
gtk_drawing_area_size (GTK_DRAWING_AREA (darea), IMAGE_WIDTH, IMAGE_HEIGHT);
gtk_container_add (GTK_CONTAINER (window), darea);
gtk_signal_connect (GTK_OBJECT (darea), "expose-event",
GTK_SIGNAL_FUNC (on_darea_expose), NULL);
gtk_widget_show_all (window);
/* Set up the RGB buffer. */
pos = rgbbuf;
for (y = 0; y < IMAGE_HEIGHT; y++)
{
for (x = 0; x < IMAGE_WIDTH; x++)
{
*pos++ = x - x % 32; /* Red. */
*pos++ = (x / 32) * 4 + y - y % 32; /* Green. */
*pos++ = y - y % 32; /* Blue. */
}
}
gtk_main ();
return 0;
}
gboolean
on_darea_expose (GtkWidget *widget,
GdkEventExpose *event,
gpointer user_data)
{
gdk_draw_rgb_image (widget->window, widget->style->fg_gc[GTK_STATE_NORMAL],
0, 0, IMAGE_WIDTH, IMAGE_HEIGHT,
GDK_RGB_DITHER_MAX, rgbbuf, IMAGE_WIDTH * 3);
}
</programlisting>
</example>
<!-- ##### SECTION See_Also ##### --> <!-- ##### SECTION See_Also ##### -->
<para> <para>
<variablelist>
<varlistentry>
<term>#GdkColor</term>
<listitem><para>The underlying Gdk mechanism for allocating
colors.</para></listitem>
</varlistentry>
</variablelist>
</para> </para>
<!-- ##### STRUCT GdkRgbCmap ##### --> <!-- ##### STRUCT GdkRgbCmap ##### -->
<para> <para>
A private data structure which maps color indices to actual RGB
colors. This is used only for gdk_draw_indexed_image().
</para> </para>
@colors:
@lut:
<!-- ##### ENUM GdkRgbDither ##### --> <!-- ##### ENUM GdkRgbDither ##### -->
<para> <para>
Selects whether or not GdkRgb applies dithering
to the image on display. There are three values:
</para>
<itemizedlist>
<listitem>
<para>
%GDK_RGB_DITHER_NONE: Never use dithering.
</para>
</listitem>
<listitem>
<para>
%GDK_RGB_DITHER_NORMAL: Use dithering in 8 bits per pixel (and below)
only.
</para>
</listitem>
<listitem>
<para>
%GDK_RGB_DITHER_MAX: Use dithering in 16 bits per pixel and below.
</para>
</listitem>
</itemizedlist>
<para>
Since GdkRgb currently only handles images with 8 bits per component,
dithering on 24 bit per pixel displays is a moot point.
</para> </para>
@GDK_RGB_DITHER_NONE:
@GDK_RGB_DITHER_NORMAL:
@GDK_RGB_DITHER_MAX:
<!-- ##### FUNCTION gdk_rgb_init ##### --> <!-- ##### FUNCTION gdk_rgb_init ##### -->
<para> <para>
Initializes GdkRgb statically. It may be called more than once with no
ill effects. It must, however, be called before any other GdkRgb
operations are performed.
</para> </para>
<para>
The GdkRgb "context" is allocated statically. Thus, GdkRgb may be used
to drive only one visual in any given application. GdkRgb
automatically selects a best visual and sets its own colormap, if
necessary. gdk_rgb_get_visual() and gdk_rgb_get_cmap () retrieve
the chosen visual and colormap, respectively.
</para>
<!-- ##### FUNCTION gdk_rgb_cmap_new ##### --> <!-- ##### FUNCTION gdk_rgb_cmap_new ##### -->
<para> <para>
Creates a new #GdkRgbCmap structure. The cmap maps color indexes to
RGB colors. If @n_colors is less than 256, then images containing
color values greater than or equal to @n_colors will produce undefined
results, including possibly segfaults.
</para> </para>
@colors: @colors: The colors, represented as 0xRRGGBB integer values.
@n_colors: @n_colors: The number of colors in the cmap.
@Returns: @Returns: The newly created #GdkRgbCmap
<!-- ##### FUNCTION gdk_rgb_cmap_free ##### --> <!-- ##### FUNCTION gdk_rgb_cmap_free ##### -->
<para> <para>
Frees the memory associated with a #GdkRgbCmap created by gdk_rgb_cmap_new().
</para> </para>
@cmap: @cmap: The #GdkRgbCmap to free.
<!-- ##### FUNCTION gdk_rgb_gc_set_foreground ##### --> <!-- ##### FUNCTION gdk_rgb_gc_set_foreground ##### -->
<para> <para>
Sets the foreground color in @gc to the specified color (or the
closest approximation, in the case of limited visuals).
</para> </para>
@gc: @gc: The @GdkGC to modify.
@rgb: @rgb: The color, represented as a 0xRRGGBB integer value.
<!-- ##### FUNCTION gdk_rgb_gc_set_background ##### --> <!-- ##### FUNCTION gdk_rgb_gc_set_background ##### -->
<para> <para>
Sets the background color in @gc to the specified color (or the
closest approximation, in the case of limited visuals).
</para> </para>
@gc: @gc: The @GdkGC to modify.
@rgb: @rgb: The color, represented as a 0xRRGGBB integer value.
<!-- ##### FUNCTION gdk_draw_rgb_image ##### --> <!-- ##### FUNCTION gdk_draw_rgb_image ##### -->
<para> <para>
Draws an RGB image in the drawable. This is the core GdkRgb
function, and likely the only one you will need to use other than the
initialization stuff.
</para> </para>
@drawable: <para>
@gc: The @rowstride parameter allows for lines to be aligned more flexibly.
@x: For example, lines may be allocated to begin on 32-bit boundaries,
@y: even if the width of the rectangle is odd. Rowstride is also useful
@width: when drawing a subrectangle of a larger image in memory. Finally, to
@height: replicate the same line a number of times, the trick of setting
@dith: @rowstride to 0 is allowed.
@rgb_buf: </para>
@rowstride:
<para>
In general, for 0 &lt;= i &lt; @width and 0 &lt;= j &lt; height,
the pixel (x + i, y + j) is colored with red value @rgb_buf[@j *
@rowstride + @i * 3], green value @rgb_buf[@j * @rowstride + @i * 3 +
1], and blue value @rgb_buf[@j * @rowstride + @i * 3 + 2].
</para>
@drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
@gc: The graphics context (all Gdk drawing operations require one; its
contents are ignored).
@x: The x coordinate of the top-left corner in the drawable.
@y: The y coordinate of the top-left corner in the drawable.
@width: The width of the rectangle to be drawn.
@height: The height of the rectangle to be drawn.
@dith: A #GdkRgbDither value, selecting the desired dither mode.
@rgb_buf: The pixel data, represented as packed 24-bit data.
@rowstride: The number of bytes from the start of one row in @rgb_buf to the
start of the next.
<!-- ##### FUNCTION gdk_draw_indexed_image ##### --> <!-- ##### FUNCTION gdk_draw_indexed_image ##### -->
<para> <para>
Draws an indexed image in the drawable, using a #GdkRgbCmap to assign
actual colors to the color indices.
</para> </para>
@drawable: @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
@gc: @gc: The graphics context.
@x: @x: The x coordinate of the top-left corner in the drawable.
@y: @y: The y coordinate of the top-left corner in the drawable.
@width: @width: The width of the rectangle to be drawn.
@height: @height: The height of the rectangle to be drawn.
@dith: @dith: A #GdkRgbDither value, selecting the desired dither mode.
@buf: @buf: The pixel data, represented as 8-bit color indices.
@rowstride: @rowstride: The number of bytes from the start of one row in @buf to the
@cmap: start of the next.
@cmap: The #GdkRgbCmap used to assign colors to the color indices.
<!-- ##### FUNCTION gdk_draw_gray_image ##### --> <!-- ##### FUNCTION gdk_draw_gray_image ##### -->
<para> <para>
Draws a grayscale image in the drawable.
</para> </para>
@drawable:
@gc: @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
@x: @gc: The graphics context.
@y: @x: The x coordinate of the top-left corner in the drawable.
@width: @y: The y coordinate of the top-left corner in the drawable.
@height: @width: The width of the rectangle to be drawn.
@dith: @height: The height of the rectangle to be drawn.
@buf: @dith: A #GdkRgbDither value, selecting the desired dither mode.
@rowstride: @buf: The pixel data, represented as 8-bit gray values.
@rowstride: The number of bytes from the start of one row in @buf to the
start of the next.
<!-- ##### FUNCTION gdk_draw_rgb_32_image ##### --> <!-- ##### FUNCTION gdk_draw_rgb_32_image ##### -->
<para> <para>
Draws a padded RGB image in the drawable. The image is stored as one
pixel per 32-bit word. It is laid out as a red byte, a green byte, a
blue byte, and a padding byte.
</para> </para>
@drawable: <para>
@gc: It's unlikely that this function will give significant performance
@x: gains in practice. In my experience, the performance gain from having
@y: pixels aligned to 32-bit boundaries is cancelled out by the increased
@width: memory bandwidth.
@height: </para>
@dith:
@buf: @drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
@rowstride: @gc: The graphics context.
@x: The x coordinate of the top-left corner in the drawable.
@y: The y coordinate of the top-left corner in the drawable.
@width: The width of the rectangle to be drawn.
@height: The height of the rectangle to be drawn.
@dith: A #GdkRgbDither value, selecting the desired dither mode.
@buf: The pixel data, represented as padded 32-bit data.
@rowstride: The number of bytes from the start of one row in @buf to the
start of the next.
<!-- ##### FUNCTION gdk_draw_rgb_image_dithalign ##### --> <!-- ##### FUNCTION gdk_draw_rgb_image_dithalign ##### -->
<para> <para>
Draws an RGB image in the drawable, with an adjustment for dither alignment.
</para> </para>
@drawable: <para>
@gc: This function is useful when drawing dithered images into a window
@x: that may be scrolled. Pixel (x, y) will be drawn dithered as if its
@y: actual location is (x + @xdith, y + @ydith). Thus, if you draw an
@width: image into a window using zero dither alignment, then scroll up one
@height: pixel, subsequent draws to the window should have @ydith = 1.
@dith: </para>
@rgb_buf:
@rowstride: <para>
@xdith: Setting the dither alignment correctly allows updating of small parts
@ydith: of the screen while avoiding visible "seams" between the different
dither textures.
</para>
@drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
@gc: The graphics context.
@x: The x coordinate of the top-left corner in the drawable.
@y: The y coordinate of the top-left corner in the drawable.
@width: The width of the rectangle to be drawn.
@height: The height of the rectangle to be drawn.
@dith: A #GdkRgbDither value, selecting the desired dither mode.
@rgb_buf: The pixel data, represented as packed 24-bit data.
@rowstride: The number of bytes from the start of one row in @rgb_buf to the
start of the next.
@xdith: An x offset for dither alignment.
@ydith: A y offset for dither alignment.
<!-- ##### FUNCTION gdk_rgb_xpixel_from_rgb ##### --> <!-- ##### FUNCTION gdk_rgb_xpixel_from_rgb ##### -->
<para> <para>
Finds the X pixel closest in color to the @rgb color specified. This
value may be used to set the <structfield>pixel</structfield> field of
a #GdkColor struct.
</para> </para>
@rgb: @rgb: The color, represented as a 0xRRGGBB integer value.
@Returns: @Returns: The X pixel value.
<!-- ##### FUNCTION gdk_rgb_set_verbose ##### --> <!-- ##### FUNCTION gdk_rgb_set_verbose ##### -->
<para> <para>
Sets the "verbose" flag. This is generally only useful for debugging.
</para> </para>
@verbose: @verbose: TRUE if verbose messages are desired.
<!-- ##### FUNCTION gdk_rgb_ditherable ##### --> <!-- ##### FUNCTION gdk_rgb_ditherable ##### -->
<para> <para>
Determine whether the visual is ditherable. This function may be
useful for presenting a user interface choice to the user about which
dither mode is desired; if the display is not ditherable, it may make
sense to gray out or hide the corresponding UI widget.
</para> </para>
@Returns: @Returns: TRUE if the visual is ditherable.
<!-- ##### FUNCTION gdk_rgb_set_install ##### --> <!-- ##### FUNCTION gdk_rgb_set_install ##### -->
<para> <para>
If @install is TRUE, directs GdkRgb to always install a new "private"
colormap rather than trying to find a best fit with the colors already
allocated. Ordinarily, GdkRgb will install a colormap only if a
sufficient cube cannot be allocated.
</para> </para>
@install: <para>
A private colormap has more colors, leading to better quality display,
but also leads to the dreaded "colormap flashing" effect.
</para>
@install: TRUE to set install mode.
<!-- ##### FUNCTION gdk_rgb_set_min_colors ##### --> <!-- ##### FUNCTION gdk_rgb_set_min_colors ##### -->
<para> <para>
Sets the minimum number of colors for the color cube. Generally,
GdkRgb tries to allocate the largest color cube it can. If it can't
allocate a color cube at least as large as @min_colors, it installs a
private colormap.
</para> </para>
@min_colors: @min_colors: The minimum number of colors accepted.
<!-- ##### FUNCTION gdk_rgb_get_visual ##### --> <!-- ##### FUNCTION gdk_rgb_get_visual ##### -->
<para> <para>
Gets the visual chosen by GdkRgb. This visual and the corresponding
colormap should be used when creating windows that will be drawn in by GdkRgb.
</para> </para>
@Returns: @Returns: The @GdkVisual chosen by GdkRgb.
<!-- ##### FUNCTION gdk_rgb_get_cmap ##### --> <!-- ##### FUNCTION gdk_rgb_get_cmap ##### -->
<para> <para>
Gets the colormap set by GdkRgb. This colormap and the corresponding
visual should be used when creating windows that will be drawn in by GdkRgb.
</para> </para>
@Returns: @Returns: The @GdkColormap set by GdkRgb.

154
docs/reference/gtk/tmpl/gtkbbox.sgml
View File

@ -2,158 +2,194 @@
GtkButtonBox GtkButtonBox
<!-- ##### SECTION Short_Description ##### --> <!-- ##### SECTION Short_Description ##### -->
Base class for #GtkHButtonBox and #GtkVButtonBox
<!-- ##### SECTION Long_Description ##### --> <!-- ##### SECTION Long_Description ##### -->
<para>
The primary purpose of this class is to keep track of the various properties
of #GtkHButtonBox and #GtkVButtonBox widgets.
</para>
<para>
gtk_button_box_get_child_size_default() retrieves the default minimum width and height
for widgets in any button box. gtk_button_box_set_child_size_default()
changes the default minimum child widget size.
</para>
<para>
gtk_button_box_get_child_size() retrieves the minimum width and height
for widgets in a given button box. gtk_button_box_set_child_size()
allows those properties to be changed.
</para>
<para>
gtk_button_box_get_child_ipadding_default() gets the default number of pixels of
horizontal and vertical padding that are applied to each button in every button box.
gtk_button_box_set_child_ipadding_default() allows these defaults to be
changed.
</para>
<para>
The internal padding of buttons can be retrieved and changed per button box using
gtk_button_box_get_child_ipadding() and gtk_button_box_set_child_ipadding()
respectively.
</para>
<para>
gtk_button_box_get_spacing() and gtk_button_box_set_spacing() retrieve and
change default number of pixels between buttons, respectively.
</para>
<para>
gtk_button_box_get_layout() and gtk_button_box_set_layout() retrieve and alter the method
used to spread the buttons in a button box across the container, respectively.
</para>
<para> <para>
</para> </para>
<!-- ##### SECTION See_Also ##### --> <!-- ##### SECTION See_Also ##### -->
<para> <para>
<variablelist>
<varlistentry>
<term>#GtkVButtonBox</term>
<listitem><para>Vertical sub-class of #GtkButtonBox.</para></listitem>
</varlistentry>
<varlistentry>
<term>#GtkHButtonBox</term>
<listitem><para>Horizontal sub-class of #GtkButtonBox.</para></listitem>
</varlistentry>
</variablelist>
</para> </para>
<!-- ##### STRUCT GtkButtonBox ##### --> <!-- ##### STRUCT GtkButtonBox ##### -->
<para> <para>
This is a read-only struct; no members should be modified directly.
</para> </para>
@box:
@spacing:
@child_min_width:
@child_min_height:
@child_ipad_x:
@child_ipad_y:
@layout_style:
<!-- ##### MACRO GTK_BUTTONBOX_DEFAULT ##### --> <!-- ##### MACRO GTK_BUTTONBOX_DEFAULT ##### -->
<para> <para>
Used internally only.
</para> </para>
<!-- ##### FUNCTION gtk_button_box_get_child_size_default ##### --> <!-- ##### FUNCTION gtk_button_box_get_child_size_default ##### -->
<para> <para>
Retrieves the default minimum width and height for all button boxes, and
places the values in @min_width and @min_height, respectively.
</para> </para>
@min_width: @min_width: the default minimum width of a child widget.
@min_height: @min_height: the default minimum height of a child widget.
<!-- ##### FUNCTION gtk_button_box_get_child_ipadding_default ##### --> <!-- ##### FUNCTION gtk_button_box_get_child_ipadding_default ##### -->
<para> <para>
The internal padding of a button is the amount of space between the outside
of the button and the widget it contains. This function gets the default
amount of horizontal and vertical padding, placing the results in @ipad_x
and @ipad_y, respectively.
</para> </para>
@ipad_x: @ipad_x: the default horizontal internal button padding.
@ipad_y: @ipad_y: the default vertical internal button padding.
<!-- ##### FUNCTION gtk_button_box_set_child_size_default ##### --> <!-- ##### FUNCTION gtk_button_box_set_child_size_default ##### -->
<para> <para>
Sets the default size of child buttons.
</para> </para>
@min_width: @min_width: minimum default width for child buttons.
@min_height: @min_height: minimum default height for child buttons.
<!-- ##### FUNCTION gtk_button_box_set_child_ipadding_default ##### --> <!-- ##### FUNCTION gtk_button_box_set_child_ipadding_default ##### -->
<para> <para>
Sets the default number of pixels that pad each button in every button box.
</para> </para>
@ipad_x: @ipad_x: new default horizontal padding.
@ipad_y: @ipad_y: new default vertical padding.
<!-- ##### FUNCTION gtk_button_box_get_spacing ##### --> <!-- ##### FUNCTION gtk_button_box_get_spacing ##### -->
<para> <para>
Retrieves how much space a button box is placing between each child button.
</para> </para>
@widget: @widget: a #GtkButtonBox.
@Returns: @Returns: the current spacing applied to the buttons in @widget.
<!-- ##### FUNCTION gtk_button_box_get_layout ##### --> <!-- ##### FUNCTION gtk_button_box_get_layout ##### -->
<para> <para>
Retrieves the method being used to arrange the buttons in a button box.
</para> </para>
@widget: @widget: a #GtkButtonBox.
@Returns: @Returns: the method used to layout buttons in @widget.
<!-- ##### FUNCTION gtk_button_box_get_child_size ##### --> <!-- ##### FUNCTION gtk_button_box_get_child_size ##### -->
<para> <para>
Retrieves the current width and height of all child widgets in a button box.
@min_width and @min_height are filled with those values, respectively.
</para> </para>
@widget: @widget: a #GtkButtonBox.
@min_width: @min_width: the width of the buttons contained by @widget.
@min_height: @min_height: the height of the buttons contained by @widget.
<!-- ##### FUNCTION gtk_button_box_get_child_ipadding ##### --> <!-- ##### FUNCTION gtk_button_box_get_child_ipadding ##### -->
<para> <para>
Gets the default number of pixels that pad the buttons in a given button box.
</para> </para>
@widget: @widget: a #GtkButtonBox.
@ipad_x: @ipad_x: the horizontal padding used by buttons in @widget.
@ipad_y: @ipad_y: the vertical padding used by buttons in @widget.
<!-- ##### FUNCTION gtk_button_box_set_spacing ##### --> <!-- ##### FUNCTION gtk_button_box_set_spacing ##### -->
<para> <para>
Sets the amount of spacing between buttons in a given button box.
</para> </para>
@widget: @widget: a #GtkButtonBox.
@spacing: @spacing: the number of pixels of spacing.
<!-- ##### FUNCTION gtk_button_box_set_layout ##### --> <!-- ##### FUNCTION gtk_button_box_set_layout ##### -->
<para> <para>
Changes the way buttons are arranged in their container.
</para> </para>
@widget: @widget: a #GtkButtonBox.
@layout_style: @layout_style: the new layout style.
<!-- ##### FUNCTION gtk_button_box_set_child_size ##### --> <!-- ##### FUNCTION gtk_button_box_set_child_size ##### -->
<para> <para>
Sets a new default size for the children of a given button box.
</para> </para>
@widget: @widget: a #GtkButtonBox.
@min_width: @min_width: a default width for buttons in @widget.
@min_height: @min_height: a default height for buttons in @widget.
<!-- ##### FUNCTION gtk_button_box_set_child_ipadding ##### --> <!-- ##### FUNCTION gtk_button_box_set_child_ipadding ##### -->
<para> <para>
Changes the amount of internal padding used by all buttons in a given button
box.
</para> </para>
@widget: @widget: a #GtkButtonBox.
@ipad_x: @ipad_x: the horizontal padding that should be used by each button in @widget.
@ipad_y: @ipad_y: the vertical padding that should be used by each button in @widget.
<!-- ##### FUNCTION gtk_button_box_child_requisition ##### --> <!-- ##### FUNCTION gtk_button_box_child_requisition ##### -->
<para> <para>
This is an internally used function and should never be called from an
application.
</para> </para>
@widget:
@nvis_children:
@width:
@height: