diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 0ff9ed7cd1..5aa1e3c8c2 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,17 @@ +1999-08-28 Damon Chaplin + + * 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 * gtk/tmpl/gtktypeutils.sgml: Fix corrupted end tag. diff --git a/docs/reference/gdk/gdk-sections.txt b/docs/reference/gdk/gdk-sections.txt index 033341a53e..661ef50317 100644 --- a/docs/reference/gdk/gdk-sections.txt +++ b/docs/reference/gdk/gdk-sections.txt @@ -77,29 +77,33 @@ gdk_image_destroy
GdkRGB rgb -GdkRgbCmap -GdkRgbDither - gdk_rgb_init -gdk_rgb_cmap_new -gdk_rgb_cmap_free - -gdk_rgb_gc_set_foreground -gdk_rgb_gc_set_background + gdk_draw_rgb_image +gdk_draw_rgb_image_dithalign gdk_draw_indexed_image gdk_draw_gray_image gdk_draw_rgb_32_image -gdk_draw_rgb_image_dithalign +GdkRgbDither + + +gdk_rgb_cmap_new +gdk_rgb_cmap_free +GdkRgbCmap + + +gdk_rgb_gc_set_foreground +gdk_rgb_gc_set_background gdk_rgb_xpixel_from_rgb -gdk_rgb_set_verbose -gdk_rgb_ditherable + gdk_rgb_set_install gdk_rgb_set_min_colors gdk_rgb_get_visual gdk_rgb_get_cmap +gdk_rgb_ditherable +gdk_rgb_set_verbose
@@ -164,26 +168,29 @@ gdk_char_height Drawing Primitives drawing GdkFill -GdkFillRule GdkLineStyle GdkCapStyle GdkJoinStyle gdk_draw_point +gdk_draw_points gdk_draw_line +gdk_draw_lines +gdk_draw_segments +GdkSegment gdk_draw_rectangle gdk_draw_arc gdk_draw_polygon + + gdk_draw_string gdk_draw_text gdk_draw_text_wc + + gdk_draw_pixmap gdk_draw_bitmap gdk_draw_image -gdk_draw_points -gdk_draw_segments -GdkSegment -gdk_draw_lines
@@ -410,27 +417,34 @@ gdk_color_context_get_index_from_palette regions GdkPoint + GdkRectangle gdk_rectangle_intersect gdk_rectangle_union + GdkRegion gdk_region_new +gdk_region_polygon +GdkFillRule gdk_region_destroy -gdk_region_get_clipbox + + +gdk_regions_intersect +gdk_regions_union +gdk_regions_subtract +gdk_regions_xor +gdk_region_union_with_rect +gdk_region_offset +gdk_region_shrink + + gdk_region_empty gdk_region_equal gdk_region_point_in gdk_region_rect_in GdkOverlapType -gdk_region_polygon -gdk_region_offset -gdk_region_shrink -gdk_region_union_with_rect -gdk_regions_intersect -gdk_regions_union -gdk_regions_subtract -gdk_regions_xor +gdk_region_get_clipbox
diff --git a/docs/reference/gdk/tmpl/cursors.sgml b/docs/reference/gdk/tmpl/cursors.sgml index 3757f955c9..5b33090b9a 100644 --- a/docs/reference/gdk/tmpl/cursors.sgml +++ b/docs/reference/gdk/tmpl/cursors.sgml @@ -2,7 +2,7 @@ Cursors - +standard and pixmap cursors. @@ -40,6 +40,7 @@ Creates a new standard cursor. 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). +The standard cursor size is 16 by 16 pixels. Creating a custom cursor. diff --git a/docs/reference/gdk/tmpl/drawing.sgml b/docs/reference/gdk/tmpl/drawing.sgml index 159690bace..d57db7b25a 100644 --- a/docs/reference/gdk/tmpl/drawing.sgml +++ b/docs/reference/gdk/tmpl/drawing.sgml @@ -2,11 +2,22 @@ Drawing Primitives - +functions for drawing points, lines, arcs, and text. - +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. + + +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 +Graphics Contexts section for +more information. @@ -16,171 +27,215 @@ Drawing Primitives - +Used to specify the way in which drawing operations are performed. +See gdk_gc_set_fill(). -@GDK_SOLID: -@GDK_TILED: -@GDK_STIPPLED: -@GDK_OPAQUE_STIPPLED: +@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(). - +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. -@GDK_EVEN_ODD_RULE: -@GDK_WINDING_RULE: +@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. + - +Used to specify how lines are drawn. See gdk_gc_set_line_attributes(). -@GDK_LINE_SOLID: -@GDK_LINE_ON_OFF_DASH: -@GDK_LINE_DOUBLE_DASH: +@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. - +Used to specify how the ends of lines and dashes are drawn. +See gdk_gc_set_line_attributes(). -@GDK_CAP_NOT_LAST: -@GDK_CAP_BUTT: -@GDK_CAP_ROUND: -@GDK_CAP_PROJECTING: +@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. - +Used to specify how the the joins between lines are drawn. +See gdk_gc_set_line_attributes(). -@GDK_JOIN_MITER: -@GDK_JOIN_ROUND: -@GDK_JOIN_BEVEL: +@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. - +Draws a point, using the foreground color and other attributes of the #GdkGC. -@drawable: -@gc: -@x: -@y: +@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. - +Draws a line, using the foreground color and other attributes of the #GdkGC. -@drawable: -@gc: -@x1: -@y1: -@x2: -@y2: +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). +@gc: a #GdkGC. +@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. - +Draws a rectangular outline or filled rectangle, using the foreground color +and other attributes of the #GdkGC. + + +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. + + -@drawable: -@gc: -@filled: -@x: -@y: -@width: -@height: +@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. - +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. -@drawable: -@gc: -@filled: -@x: -@y: -@width: -@height: -@angle1: -@angle2: +@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. - +Draws an outlined or filled polygon. -@drawable: -@gc: -@filled: -@points: -@npoints: +@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. - +Draws a string of characters in the given font or fontset. -@drawable: -@font: -@gc: -@x: -@y: -@string: +@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. - +Draws a number of characters in the given font or fontset. -@drawable: -@font: -@gc: -@x: -@y: -@text: -@text_length: +@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. - +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. -@drawable: -@font: -@gc: -@x: -@y: -@text: -@text_length: +@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. - +Draws a pixmap, or a part of a pixmap, onto another drawable. -@drawable: -@gc: -@src: -@xsrc: -@ysrc: -@xdest: -@ydest: -@width: -@height: +@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. @@ -188,7 +243,7 @@ Drawing Primitives -@drawable: +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). @gc: @src: @xsrc: @@ -204,7 +259,7 @@ Drawing Primitives -@drawable: +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). @gc: @image: @xsrc: @@ -217,13 +272,14 @@ Drawing Primitives - +Draws a number of points, using the foreground color and other attributes of +the #GdkGC. -@drawable: -@gc: -@points: -@npoints: +@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. @@ -231,7 +287,7 @@ Drawing Primitives -@drawable: +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). @gc: @segs: @nsegs: @@ -249,12 +305,16 @@ Drawing Primitives - +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(). -@drawable: -@gc: -@points: -@npoints: +@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. diff --git a/docs/reference/gdk/tmpl/event_structs.sgml b/docs/reference/gdk/tmpl/event_structs.sgml index 417d599c11..5a4370bc1e 100644 --- a/docs/reference/gdk/tmpl/event_structs.sgml +++ b/docs/reference/gdk/tmpl/event_structs.sgml @@ -8,6 +8,12 @@ Event Structures + + +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(). + + @@ -16,12 +22,13 @@ Event Structures - +Contains the fields which are common to all event structs. +Any event can safely be cast to a #GdkEventAny to access these fields. -@type: -@window: -@send_event: +@type: the type of the event. +@window: the window which received the event. +@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent). @@ -85,24 +92,55 @@ Event Structures - +Used for button press and button release events. The +type field will be one of %GDK_BUTTON_PRESS, +%GDK_2BUTTON_PRESS, GDK_3BUTTON_PRESS, and GDK_BUTTON_RELEASE. + + +Double and treble-clicks result in a sequence of events being received. +For double-clicks the order of events will be: + +%GDK_BUTTON_PRESS +%GDK_BUTTON_RELEASE +%GDK_BUTTON_PRESS +%GDK_2BUTTON_PRESS +%GDK_BUTTON_RELEASE + +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. + + +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: + +%GDK_BUTTON_PRESS +%GDK_BUTTON_RELEASE +%GDK_BUTTON_PRESS +%GDK_2BUTTON_PRESS +%GDK_BUTTON_RELEASE +%GDK_BUTTON_PRESS +%GDK_3BUTTON_PRESS +%GDK_BUTTON_RELEASE + -@type: -@window: -@send_event: -@time: -@x: -@y: -@pressure: +@type: the type of the event. +@window: the window which received the event. +@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent). +@time: the time of the event in milliseconds. This wraps around every 50 days. +@x: the x coordinate of the mouse relative to the window. +@y: the y coordinate of the mouse relative to the window. +@pressure: the pressure of the button press, intended for input devices such +as graphics tablets. It defaults to 0.5. @xtilt: @ytilt: @state: @button: @source: @deviceid: -@x_root: -@y_root: +@x_root: the x coordinate of the mouse relative to the root of the screen. +@y_root: the y coordinate of the mouse relative to the root of the screen. @@ -193,14 +231,6 @@ Event Structures @time: @state: - - - - - -@GDK_PROPERTY_NEW_VALUE: -@GDK_PROPERTY_DELETE: - diff --git a/docs/reference/gdk/tmpl/regions.sgml b/docs/reference/gdk/tmpl/regions.sgml index 5f4f228d2b..dcb3b89682 100644 --- a/docs/reference/gdk/tmpl/regions.sgml +++ b/docs/reference/gdk/tmpl/regions.sgml @@ -2,11 +2,25 @@ Points, Rectangles and Regions - +simple graphical data types. - +GDK provides the #GdkPoint, #GdkRectangle and #GdkRegion data types for +representing pixels and sets of pixels on the screen. + + +#GdkPoint is a simple structure containing an x and y coordinate of a point. + + +#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(). + + +#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()). @@ -16,202 +30,218 @@ Points, Rectangles and Regions - +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. -@x: -@y: +@x: the x coordinate of the point. +@y: the y coordinate of the point. - +Defines the position and size of a rectangle. -@x: -@y: -@width: -@height: +@x: the x coordinate of the left edge of the rectangle. +@y: the y coordinate of the top of the rectangle. +@width: the width of the rectangle. +@height: the height of the rectangle. - +Calculates the intersection of two rectangles. -@src1: -@src2: -@dest: -@Returns: +@src1: a #GdkRectangle. +@src2: a #GdkRectangle. +@dest: the intersection of @src1 and @src2. +@Returns: TRUE if the rectangles intersect. - +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. -@src1: -@src2: -@dest: +@src1: a #GdkRectangle. +@src2: a #GdkRectangle. +@dest: the union of @src1 and @src2. - +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. -@user_data: +@user_data: arbitrary data attached to the #GdkRegion. - +Creates a new empty #GdkRegion. -@Returns: +@Returns: a new empty #GdkRegion. - +Destroys a #GdkRegion. -@region: +@region: a #GdkRegion. - +Returns the smallest rectangle which includes the entire #GdkRegion. -@region: -@rectangle: +@region: a #GdkRegion. +@rectangle: returns the smallest rectangle which includes all of @region. - +Returns TRUE if the #GdkRegion is empty. -@region: -@Returns: +@region: a #GdkRegion. +@Returns: TRUE if @region is empty. - +Returns TRUE if the two regions are the same. -@region1: -@region2: -@Returns: +@region1: a #GdkRegion. +@region2: a #GdkRegion. +@Returns: TRUE if @region1 and @region2 are equal. - +Returns TRUE if a point is in a region. -@region: -@x: -@y: -@Returns: +@region: a #GdkRegion. +@x: the x coordinate of a point. +@y: the y coordinate of a point. +@Returns: TRUE if the point is in @region. - +Tests whether a rectangle is within a region. -@region: -@rect: -@Returns: +@region: a #GdkRegion. +@rect: a #GdkRectangle. +@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. - +Specifies the possible values returned by gdk_region_rect_in(). -@GDK_OVERLAP_RECTANGLE_IN: -@GDK_OVERLAP_RECTANGLE_OUT: -@GDK_OVERLAP_RECTANGLE_PART: +@GDK_OVERLAP_RECTANGLE_IN: if the rectangle is inside the #GdkRegion. +@GDK_OVERLAP_RECTANGLE_OUT: if the rectangle is outside the #GdkRegion. +@GDK_OVERLAP_RECTANGLE_PART: if the rectangle is partly inside the #GdkRegion. +Creates a new #GdkRegion using the polygon defined by a number of points. -@points: -@npoints: -@fill_rule: -@Returns: +@points: an array of #GdkPoint structs. +@npoints: the number of elements in the @points array. +@fill_rule: specifies which pixels are included in the region when the polygon +overlaps itself. +@Returns: a new #GdkRegion based on the given polygon. - +Moves a region. -@region: -@dx: -@dy: +@region: a #GdkRegion. +@dx: the distance to move the region horizontally. +@dy: the distance to move the region vertically. - +Resizes a region. -@region: +@region: a #GdkRegion. @dx: @dy: - +Returns the union of a region and a rectangle. -@region: -@rect: -@Returns: +@region: a #GdkRegion. +@rect: a #GdkRectangle. +@Returns: the union of @region and @rect. - +Returns the intersection of two regions. -@source1: -@source2: -@Returns: +@source1: a #GdkRegion. +@source2: a #GdkRegion. +@Returns: the intersection of @source1 and @source2. - +Returns the union of two regions. +This is all pixels in either of @source1 or @source2. -@source1: -@source2: -@Returns: +@source1: a #GdkRegion. +@source2: a #GdkRegion. +@Returns: the union of @source1 and @source2. - +Subtracts one region from another. +The result is a region containing all the pixels which are in @source1, but +which are not in @source2. -@source1: -@source2: -@Returns: +@source1: a #GdkRegion. +@source2: a #GdkRegion to subtract from @source1. +@Returns: @source1 - @source2. - +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. -@source1: -@source2: -@Returns: +@source1: a #GdkRegion. +@source2: a #GdkRegion. +@Returns: the difference between the union and the intersection of @source1 +and @source2. diff --git a/docs/reference/gdk/tmpl/rgb.sgml b/docs/reference/gdk/tmpl/rgb.sgml index 12b8f72d87..928753dc61 100644 --- a/docs/reference/gdk/tmpl/rgb.sgml +++ b/docs/reference/gdk/tmpl/rgb.sgml @@ -2,215 +2,449 @@ GdkRGB - +displays RGB images (as well as grayscale and colormapped) to +the native window. +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. + + +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. + + + +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: + + + + + gdk_rgb_init (); + + gtk_widget_set_default_colormap (gdk_rgb_get_cmap ()); + gtk_widget_set_default_visual (gdk_rgb_get_visual ()); + + + + +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. + + + +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. + + + +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. + + + +A simple example program using GdkRGB. + +#include <gtk/gtk.h> + +#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 (&argc, &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); +} + + + + + + + +#GdkColor +The underlying Gdk mechanism for allocating +colors. + + + - +A private data structure which maps color indices to actual RGB +colors. This is used only for gdk_draw_indexed_image(). -@colors: -@lut: +Selects whether or not GdkRgb applies dithering +to the image on display. There are three values: + + + + + + +%GDK_RGB_DITHER_NONE: Never use dithering. + + + + + +%GDK_RGB_DITHER_NORMAL: Use dithering in 8 bits per pixel (and below) +only. + + + + + +%GDK_RGB_DITHER_MAX: Use dithering in 16 bits per pixel and below. + + + + + + +Since GdkRgb currently only handles images with 8 bits per component, +dithering on 24 bit per pixel displays is a moot point. -@GDK_RGB_DITHER_NONE: -@GDK_RGB_DITHER_NORMAL: -@GDK_RGB_DITHER_MAX: - +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. + +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. + - +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. -@colors: -@n_colors: -@Returns: +@colors: The colors, represented as 0xRRGGBB integer values. +@n_colors: The number of colors in the cmap. +@Returns: The newly created #GdkRgbCmap - +Frees the memory associated with a #GdkRgbCmap created by gdk_rgb_cmap_new(). -@cmap: +@cmap: The #GdkRgbCmap to free. - +Sets the foreground color in @gc to the specified color (or the +closest approximation, in the case of limited visuals). -@gc: -@rgb: +@gc: The @GdkGC to modify. +@rgb: The color, represented as a 0xRRGGBB integer value. - +Sets the background color in @gc to the specified color (or the +closest approximation, in the case of limited visuals). -@gc: -@rgb: +@gc: The @GdkGC to modify. +@rgb: The color, represented as a 0xRRGGBB integer value. - +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. -@drawable: -@gc: -@x: -@y: -@width: -@height: -@dith: -@rgb_buf: -@rowstride: + +The @rowstride parameter allows for lines to be aligned more flexibly. +For example, lines may be allocated to begin on 32-bit boundaries, +even if the width of the rectangle is odd. Rowstride is also useful +when drawing a subrectangle of a larger image in memory. Finally, to +replicate the same line a number of times, the trick of setting +@rowstride to 0 is allowed. + + + +In general, for 0 <= i < @width and 0 <= j < 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]. + + +@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. - +Draws an indexed image in the drawable, using a #GdkRgbCmap to assign +actual colors to the color indices. -@drawable: -@gc: -@x: -@y: -@width: -@height: -@dith: -@buf: -@rowstride: -@cmap: +@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. +@buf: The pixel data, represented as 8-bit color indices. +@rowstride: The number of bytes from the start of one row in @buf to the +start of the next. +@cmap: The #GdkRgbCmap used to assign colors to the color indices. +Draws a grayscale image in the drawable. -@drawable: -@gc: -@x: -@y: -@width: -@height: -@dith: -@buf: -@rowstride: + +@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. +@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. - +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. -@drawable: -@gc: -@x: -@y: -@width: -@height: -@dith: -@buf: -@rowstride: + +It's unlikely that this function will give significant performance +gains in practice. In my experience, the performance gain from having +pixels aligned to 32-bit boundaries is cancelled out by the increased +memory bandwidth. + + +@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. +@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. - +Draws an RGB image in the drawable, with an adjustment for dither alignment. -@drawable: -@gc: -@x: -@y: -@width: -@height: -@dith: -@rgb_buf: -@rowstride: -@xdith: -@ydith: + +This function is useful when drawing dithered images into a window +that may be scrolled. Pixel (x, y) will be drawn dithered as if its +actual location is (x + @xdith, y + @ydith). Thus, if you draw an +image into a window using zero dither alignment, then scroll up one +pixel, subsequent draws to the window should have @ydith = 1. + + + +Setting the dither alignment correctly allows updating of small parts +of the screen while avoiding visible "seams" between the different +dither textures. + + +@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. - +Finds the X pixel closest in color to the @rgb color specified. This +value may be used to set the pixel field of +a #GdkColor struct. -@rgb: -@Returns: +@rgb: The color, represented as a 0xRRGGBB integer value. +@Returns: The X pixel value. - +Sets the "verbose" flag. This is generally only useful for debugging. -@verbose: +@verbose: TRUE if verbose messages are desired. - +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. -@Returns: +@Returns: TRUE if the visual is ditherable. - +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. -@install: + +A private colormap has more colors, leading to better quality display, +but also leads to the dreaded "colormap flashing" effect. + + +@install: TRUE to set install mode. - +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. -@min_colors: +@min_colors: The minimum number of colors accepted. - +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. -@Returns: +@Returns: The @GdkVisual chosen by GdkRgb. - +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. -@Returns: +@Returns: The @GdkColormap set by GdkRgb. diff --git a/docs/reference/gtk/tmpl/gtkbbox.sgml b/docs/reference/gtk/tmpl/gtkbbox.sgml index 834df6912f..4d77c5b258 100644 --- a/docs/reference/gtk/tmpl/gtkbbox.sgml +++ b/docs/reference/gtk/tmpl/gtkbbox.sgml @@ -1,159 +1,195 @@ - -GtkButtonBox - - - - - - - - - - - - - - - - - - - -@box: -@spacing: -@child_min_width: -@child_min_height: -@child_ipad_x: -@child_ipad_y: -@layout_style: - - - - - - - - - - - - - -@min_width: -@min_height: - - - - - - - -@ipad_x: -@ipad_y: - - - - - - - -@min_width: -@min_height: - - - - - - - -@ipad_x: -@ipad_y: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@min_width: -@min_height: - - - - - - - -@widget: -@ipad_x: -@ipad_y: - - - - - - - -@widget: -@spacing: - - - - - - - -@widget: -@layout_style: - - - - - - - -@widget: -@min_width: -@min_height: - - - - - - - -@widget: -@ipad_x: -@ipad_y: - - - - - - - -@widget: -@nvis_children: -@width: -@height: - - + +GtkButtonBox + + +Base class for #GtkHButtonBox and #GtkVButtonBox + + + +The primary purpose of this class is to keep track of the various properties +of #GtkHButtonBox and #GtkVButtonBox widgets. + + +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. + + +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. + + +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. + + +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. + + +gtk_button_box_get_spacing() and gtk_button_box_set_spacing() retrieve and +change default number of pixels between buttons, respectively. + + +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. + + + + + + + + + + +#GtkVButtonBox +Vertical sub-class of #GtkButtonBox. + + +#GtkHButtonBox +Horizontal sub-class of #GtkButtonBox. + + + + + + +This is a read-only struct; no members should be modified directly. + + + + + +Used internally only. + + + + + + +Retrieves the default minimum width and height for all button boxes, and +places the values in @min_width and @min_height, respectively. + + +@min_width: the default minimum width of a child widget. +@min_height: the default minimum height of a child widget. + + + + +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. + + +@ipad_x: the default horizontal internal button padding. +@ipad_y: the default vertical internal button padding. + + + + +Sets the default size of child buttons. + + +@min_width: minimum default width for child buttons. +@min_height: minimum default height for child buttons. + + + + +Sets the default number of pixels that pad each button in every button box. + + +@ipad_x: new default horizontal padding. +@ipad_y: new default vertical padding. + + + + +Retrieves how much space a button box is placing between each child button. + + +@widget: a #GtkButtonBox. +@Returns: the current spacing applied to the buttons in @widget. + + + + +Retrieves the method being used to arrange the buttons in a button box. + + +@widget: a #GtkButtonBox. +@Returns: the method used to layout buttons in @widget. + + + + +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. + + +@widget: a #GtkButtonBox. +@min_width: the width of the buttons contained by @widget. +@min_height: the height of the buttons contained by @widget. + + + + +Gets the default number of pixels that pad the buttons in a given button box. + + +@widget: a #GtkButtonBox. +@ipad_x: the horizontal padding used by buttons in @widget. +@ipad_y: the vertical padding used by buttons in @widget. + + + + +Sets the amount of spacing between buttons in a given button box. + + +@widget: a #GtkButtonBox. +@spacing: the number of pixels of spacing. + + + + +Changes the way buttons are arranged in their container. + + +@widget: a #GtkButtonBox. +@layout_style: the new layout style. + + + + +Sets a new default size for the children of a given button box. + + +@widget: a #GtkButtonBox. +@min_width: a default width for buttons in @widget. +@min_height: a default height for buttons in @widget. + + + + +Changes the amount of internal padding used by all buttons in a given button +box. + + +@widget: a #GtkButtonBox. +@ipad_x: the horizontal padding that should be used by each button in @widget. +@ipad_y: the vertical padding that should be used by each button in @widget. + + + + +This is an internally used function and should never be called from an +application. +