+2000-02-02 Damon Chaplin <damon@karuna.freeserve.co.uk>
+
+ * gdk/tmpl/*.sgml: ran make templates.
+
+ * gdk/gdk-docs.sgml: rearranged sections.
+
+ * gdk/tmpl/events.sgml: documented.
+
+ * gdk/tmpl/general.sgml: documented.
+
+ * gdk/tmpl/rgb.sgml: fixed a few '@' -> '#'.
+
+ * gdk/gdk-sections.txt: rearranged a few bits, including moving
+ GdkWChar and related functions from the input method section to the
+ font section, and GdkCapStyle etc. from Drawing Primitives to GCs.
+
+ * gdk/tmpl/images.sgml: documented.
+
+ * gdk/tmpl/drawing.sgml: updated.
+
+ * gdk/tmpl/regions.sgml: updated.
+
+ * gdk/tmpl/input_contexts.sgml: documented.
+
+ * gdk/tmpl/input_methods.sgml: documented.
+
+ * gdk/tmpl/selections.sgml: changed xref to a link since Jade says
+ a xref to a RefEntry is not supported.
+
2000-01-19 Damon Chaplin <damon@karuna.freeserve.co.uk>
* gtk/tmpl/gtkscrollbar.sgml: Started.
<FUNCTION>
<NAME>gdk_colormap_new</NAME>
<RETURNS>GdkColormap *</RETURNS>
-GdkVisual *visual,gint allocate
+GdkVisual *visual,gint allocate
</FUNCTION>
<FUNCTION>
<NAME>gdk_colormap_ref</NAME>
<RETURNS>GdkColormap *</RETURNS>
-GdkColormap *cmap
+GdkColormap *cmap
</FUNCTION>
<FUNCTION>
<NAME>gdk_colormap_unref</NAME>
<RETURNS>void </RETURNS>
-GdkColormap *cmap
+GdkColormap *cmap
</FUNCTION>
<FUNCTION>
<NAME>gdk_colormap_get_system</NAME>
<FUNCTION>
<NAME>gdk_colormap_change</NAME>
<RETURNS>void </RETURNS>
-GdkColormap *colormap,gint ncolors
+GdkColormap *colormap,gint ncolors
</FUNCTION>
<FUNCTION>
<NAME>gdk_colormap_alloc_colors</NAME>
<RETURNS>gint </RETURNS>
-GdkColormap *colormap,GdkColor *colors,gint ncolors,gboolean writeable,gboolean best_match,gboolean *success
+GdkColormap *colormap,GdkColor *colors,gint ncolors,gboolean writeable,gboolean best_match,gboolean *success
</FUNCTION>
<FUNCTION>
<NAME>gdk_colormap_alloc_color</NAME>
<RETURNS>gboolean </RETURNS>
-GdkColormap *colormap,GdkColor *color,gboolean writeable,gboolean best_match
+GdkColormap *colormap,GdkColor *color,gboolean writeable,gboolean best_match
</FUNCTION>
<FUNCTION>
<NAME>gdk_colormap_free_colors</NAME>
<RETURNS>void </RETURNS>
-GdkColormap *colormap,GdkColor *colors,gint ncolors
+GdkColormap *colormap,GdkColor *colors,gint ncolors
</FUNCTION>
<FUNCTION>
<NAME>gdk_colormap_get_visual</NAME>
-<RETURNS>GdkVisual *</RETURNS>
-GdkColormap *colormap
+<RETURNS>GdkVisual *</RETURNS>
+GdkColormap *colormap
</FUNCTION>
<FUNCTION>
<NAME>gdk_color_copy</NAME>
-<RETURNS>GdkColor *</RETURNS>
-GdkColor *color
+<RETURNS>GdkColor *</RETURNS>
+GdkColor *color
</FUNCTION>
<FUNCTION>
<NAME>gdk_color_free</NAME>
<RETURNS>void </RETURNS>
-GdkColor *color
+GdkColor *color
</FUNCTION>
<FUNCTION>
<NAME>gdk_color_parse</NAME>
-<RETURNS>gint </RETURNS>
-const gchar *spec,GdkColor *color
+<RETURNS>gboolean </RETURNS>
+const gchar *spec,GdkColor *color
</FUNCTION>
<FUNCTION>
<NAME>gdk_color_hash</NAME>
</FUNCTION>
<FUNCTION>
<NAME>gdk_colors_alloc</NAME>
-<RETURNS>gint </RETURNS>
+<RETURNS>gboolean </RETURNS>
GdkColormap *colormap,gint contiguous,gulong *planes,gint nplanes,gulong *pixels,gint npixels
</FUNCTION>
<FUNCTION>
</FUNCTION>
<FUNCTION>
<NAME>gdk_color_white</NAME>
-<RETURNS>gint </RETURNS>
+<RETURNS>gboolean </RETURNS>
GdkColormap *colormap,GdkColor *color
</FUNCTION>
<FUNCTION>
<NAME>gdk_color_black</NAME>
-<RETURNS>gint </RETURNS>
+<RETURNS>gboolean </RETURNS>
GdkColormap *colormap,GdkColor *color
</FUNCTION>
<FUNCTION>
<NAME>gdk_color_alloc</NAME>
-<RETURNS>gint </RETURNS>
+<RETURNS>gboolean </RETURNS>
GdkColormap *colormap,GdkColor *color
</FUNCTION>
<FUNCTION>
<NAME>gdk_color_change</NAME>
-<RETURNS>gint </RETURNS>
+<RETURNS>gboolean </RETURNS>
GdkColormap *colormap,GdkColor *color
</FUNCTION>
<FUNCTION>
<chapter id="gdk">
<title>GDK</title>
&gdk-General;
+
+ &gdk-Points-Rectangles-and-Regions;
+ &gdk-Graphics-Contexts;
+ &gdk-Drawing-Primitives;
+
&gdk-Bitmaps-and-Pixmaps;
- &gdk-Images;
&gdk-GdkRGB;
+ &gdk-Images;
+
&gdk-Colormaps-and-Colors;
- &gdk-Fonts;
- &gdk-Drawing-Primitives;
- &gdk-Graphics-Contexts;
+ &gdk-Color-Contexts;
&gdk-Visuals;
+
+ &gdk-Fonts;
+ &gdk-Cursors;
+
&gdk-Windows;
+
+ &gdk-Events;
+ &gdk-Event-Structures;
+
&gdk-Selections;
+ &gdk-Drag-and-Drop;
+
&gdk-Properties-and-Atoms;
- &gdk-Input-Methods;
- &gdk-Input-Contexts;
- &gdk-Color-Contexts;
- &gdk-Points-Rectangles-and-Regions;
+
&gdk-Threads;
- &gdk-Key-Values;
- &gdk-Input-Devices;
- &gdk-Events;
- &gdk-Event-Structures;
- &gdk-Cursors;
+
&gdk-Input;
- &gdk-Drag-and-Drop;
+
+ &gdk-Input-Devices;
+
+ &gdk-Key-Values;
+
+ &gdk-Input-Methods;
+ &gdk-Input-Contexts;
</chapter>
</book>
gdk_init
gdk_init_check
gdk_exit
-GdkStatus
-GDK_NONE
-GDK_CURRENT_TIME
-GDK_PRIORITY_EVENTS
gdk_set_locale
-gdk_get_show_events
-gdk_set_show_events
-gdk_add_client_message_filter
gdk_set_sm_client_id
-gdk_get_use_xshm
-gdk_set_use_xshm
+
+<SUBSECTION>
gdk_get_display
+
+<SUBSECTION>
+gdk_flush
+
+<SUBSECTION>
gdk_screen_width
gdk_screen_height
gdk_screen_width_mm
gdk_screen_height_mm
+
+<SUBSECTION>
gdk_pointer_grab
gdk_pointer_ungrab
+gdk_pointer_is_grabbed
+
+<SUBSECTION>
gdk_keyboard_grab
gdk_keyboard_ungrab
-gdk_pointer_is_grabbed
-gdk_flush
-gdk_beep
+
+<SUBSECTION>
gdk_key_repeat_disable
gdk_key_repeat_restore
+
+<SUBSECTION>
+gdk_beep
+
+<SUBSECTION>
+gdk_get_use_xshm
+gdk_set_use_xshm
+
+<SUBSECTION>
gdk_error_trap_push
gdk_error_trap_pop
<SUBSECTION Private>
+GdkStatus
gdk_time_get
gdk_timer_get
gdk_timer_set
<TITLE>Images</TITLE>
<FILE>images</FILE>
GdkImage
+gdk_image_new
GdkImageType
gdk_image_new_bitmap
-gdk_image_new
gdk_image_get
+gdk_image_destroy
+<SUBSECTION>
gdk_image_put_pixel
gdk_image_get_pixel
-gdk_image_destroy
</SECTION>
<SECTION>
gdk_string_height
gdk_text_height
gdk_char_height
+
+<SUBSECTION>
+GdkWChar
+gdk_wcstombs
+gdk_mbstowcs
</SECTION>
<SECTION>
<TITLE>Drawing Primitives</TITLE>
<FILE>drawing</FILE>
-GdkFill
-GdkLineStyle
-GdkCapStyle
-GdkJoinStyle
-
gdk_draw_point
gdk_draw_points
gdk_draw_line
<SUBSECTION>
gdk_draw_pixmap
-gdk_draw_bitmap
gdk_draw_image
+
+<SUBSECTION Private>
+gdk_draw_bitmap
</SECTION>
<SECTION>
gdk_gc_set_font
gdk_gc_set_function
gdk_gc_set_fill
+GdkFill
gdk_gc_set_tile
gdk_gc_set_stipple
gdk_gc_set_ts_origin
GdkSubwindowMode
gdk_gc_set_exposures
gdk_gc_set_line_attributes
+GdkLineStyle
+GdkCapStyle
+GdkJoinStyle
gdk_gc_set_dashes
gdk_gc_copy
</SECTION>
<TITLE>Properties and Atoms</TITLE>
<FILE>properties</FILE>
GdkAtom
+GDK_NONE
gdk_text_property_to_text_list
gdk_free_text_list
gdk_string_to_compound_text
<TITLE>Input Methods</TITLE>
<FILE>input_methods</FILE>
GdkIMStyle
-GdkWChar
gdk_im_ready
-gdk_im_begin
-gdk_im_end
gdk_im_decide_style
gdk_im_set_best_style
-gdk_wcstombs
-gdk_mbstowcs
+<SUBSECTION>
+gdk_im_begin
+gdk_im_end
</SECTION>
<SECTION>
<TITLE>Input Contexts</TITLE>
<FILE>input_contexts</FILE>
GdkIC
-GdkICAttr
-GdkICAttributesType
gdk_ic_new
gdk_ic_destroy
+gdk_ic_get_events
gdk_ic_get_style
-gdk_ic_set_attr
gdk_ic_get_attr
-gdk_ic_get_events
+gdk_ic_set_attr
+
+<SUBSECTION>
+GdkICAttr
+GdkICAttributesType
gdk_ic_attr_new
gdk_ic_attr_destroy
</SECTION>
<FILE>events</FILE>
GdkEventType
GdkEventMask
+GDK_CURRENT_TIME
+GDK_PRIORITY_EVENTS
+<SUBSECTION>
gdk_events_pending
gdk_event_peek
gdk_event_get
gdk_event_copy
gdk_event_free
gdk_event_get_time
-gdk_event_handler_set
-gdk_event_send_client_message
+<SUBSECTION>
+gdk_event_handler_set
GdkEventFunc
+<SUBSECTION>
+gdk_event_send_client_message
gdk_event_send_clientmessage_toall
+gdk_add_client_message_filter
+
+<SUBSECTION>
+gdk_get_show_events
+gdk_set_show_events
</SECTION>
<SECTION>
</para>
-<!-- ##### ENUM GdkFill ##### -->
+<!-- ##### FUNCTION gdk_draw_point ##### -->
<para>
-Used to specify the way in which drawing operations are performed.
-See gdk_gc_set_fill().
+Draws a point, using the foreground color and other attributes of the #GdkGC.
</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().
-
-<!-- ##### ENUM GdkFillRule ##### -->
+@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.
+
+
+<!-- ##### FUNCTION gdk_draw_points ##### -->
<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.
+Draws a number of points, using the foreground color and other attributes of
+the #GdkGC.
</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: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@points: an array of #GdkPoint structures.
+@npoints: the number of points to be drawn.
-<!-- ##### ENUM GdkLineStyle ##### -->
+<!-- ##### FUNCTION gdk_draw_line ##### -->
<para>
-Used to specify how lines are drawn. See gdk_gc_set_line_attributes().
+Draws a line, using the foreground color and other attributes of the #GdkGC.
</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: 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.
-<!-- ##### ENUM GdkCapStyle ##### -->
-<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.
-
-<!-- ##### ENUM GdkJoinStyle ##### -->
+<!-- ##### FUNCTION gdk_draw_lines ##### -->
<para>
-Used to specify how the the joins between lines are drawn.
-See gdk_gc_set_line_attributes().
+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>
-@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: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@points: an array of #GdkPoint structures specifying the endpoints of the
+lines.
+@npoints: the size of the @points array.
+
-<!-- ##### FUNCTION gdk_draw_point ##### -->
+<!-- ##### FUNCTION gdk_draw_segments ##### -->
<para>
-Draws a point, using the foreground color and other attributes of the #GdkGC.
+Draws a number of unconnected lines.
</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.
+@segs: an array of #GdkSegment structures specifying the start and end points
+of the lines to be drawn,
+@nsegs: the number of line segments to draw, i.e. the size of the @segs array.
-<!-- ##### FUNCTION gdk_draw_line ##### -->
+<!-- ##### STRUCT GdkSegment ##### -->
<para>
-Draws a line, using the foreground color and other attributes of the #GdkGC.
+Specifies the start and end point of a line for use by the gdk_draw_segments()
+function.
</para>
-@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.
-
<!-- ##### FUNCTION gdk_draw_rectangle ##### -->
<para>
Draws a rectangular outline or filled rectangle, using the foreground color
to the bottom edge of the source pixmap.
-<!-- ##### FUNCTION gdk_draw_bitmap ##### -->
-<para>
-
-</para>
-
-@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
-@gc:
-@src:
-@xsrc:
-@ysrc:
-@xdest:
-@ydest:
-@width:
-@height:
-
-
<!-- ##### FUNCTION gdk_draw_image ##### -->
<para>
-
-</para>
-
-@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
-@gc:
-@image:
-@xsrc:
-@ysrc:
-@xdest:
-@ydest:
-@width:
-@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 ##### -->
-<para>
-
-</para>
-
-@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
-@gc:
-@segs:
-@nsegs:
-
-
-<!-- ##### STRUCT GdkSegment ##### -->
-<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().
+Draws a #GdkImage onto a drawable.
+The depth of the #GdkImage must match the depth of the #GdkDrawable.
</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.
+@image: the #GdkImage to draw.
+@xsrc: the left edge of the source rectangle within @image.
+@ysrc: the top of the source rectangle within @image.
+@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 @image.
+@height: the height of the area to be copied, or -1 to make the area extend
+to the bottom edge of @image.
@time:
@state:
+<!-- ##### ENUM GdkPropertyState ##### -->
+<para>
+
+</para>
+
+@GDK_PROPERTY_NEW_VALUE:
+@GDK_PROPERTY_DELETE:
+
<!-- ##### STRUCT GdkEventSelection ##### -->
<para>
Events
<!-- ##### SECTION Short_Description ##### -->
-
+functions for handling events from the window system.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+This section describes functions dealing with events from the window system.
+</para>
+<para>
+In GTK+ applications the events are handled automatically in
+gtk_main_do_event() and passed on to the appropriate widgets, so these
+functions are rarely needed. Though some of the fields in the
+<link linkend="gdk-Event-Structures">Event Structures</link> are useful.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<variablelist>
+<varlistentry>
+<term><link linkend="gdk-Event-Structures">Event Structures</link></term>
+<listitem><para>
+The structs used for each type of event.
+</para></listitem>
+</varlistentry>
+</variablelist>
</para>
<!-- ##### ENUM GdkEventType ##### -->
<para>
-
+Specifies the type of the event.
+</para>
+<para>
+Do not confuse these events with the signals that GTK+ widgets emit.
+Although many of these events result in corresponding signals being emitted,
+the events are often transformed or filtered along the way.
</para>
-@GDK_NOTHING:
-@GDK_DELETE:
-@GDK_DESTROY:
-@GDK_EXPOSE:
-@GDK_MOTION_NOTIFY:
-@GDK_BUTTON_PRESS:
-@GDK_2BUTTON_PRESS:
-@GDK_3BUTTON_PRESS:
-@GDK_BUTTON_RELEASE:
-@GDK_KEY_PRESS:
-@GDK_KEY_RELEASE:
-@GDK_ENTER_NOTIFY:
-@GDK_LEAVE_NOTIFY:
-@GDK_FOCUS_CHANGE:
-@GDK_CONFIGURE:
-@GDK_MAP:
-@GDK_UNMAP:
-@GDK_PROPERTY_NOTIFY:
-@GDK_SELECTION_CLEAR:
-@GDK_SELECTION_REQUEST:
-@GDK_SELECTION_NOTIFY:
-@GDK_PROXIMITY_IN:
-@GDK_PROXIMITY_OUT:
-@GDK_DRAG_ENTER:
-@GDK_DRAG_LEAVE:
-@GDK_DRAG_MOTION:
-@GDK_DRAG_STATUS:
-@GDK_DROP_START:
-@GDK_DROP_FINISHED:
-@GDK_CLIENT_EVENT:
-@GDK_VISIBILITY_NOTIFY:
-@GDK_NO_EXPOSE:
+@GDK_NOTHING: a special code to indicate a null event.
+@GDK_DELETE: the window manager has requested that the toplevel window be
+hidden or destroyed, usually when the user clicks on a special icon in the
+title bar.
+@GDK_DESTROY: the window has been destroyed.
+@GDK_EXPOSE: all or part of the window has become visible and needs to be
+redrawn.
+@GDK_MOTION_NOTIFY: the pointer (usually a mouse) has moved.
+@GDK_BUTTON_PRESS: a mouse button has been pressed.
+@GDK_2BUTTON_PRESS: a mouse button has been double-clicked (clicked twice
+within a short period of time). Note that each click also generates a
+%GDK_BUTTON_PRESS event.
+@GDK_3BUTTON_PRESS: a mouse button has been clicked 3 times in a short period
+of time. Note that each click also generates a %GDK_BUTTON_PRESS event.
+@GDK_BUTTON_RELEASE: a mouse button has been released.
+@GDK_KEY_PRESS: a key has been pressed.
+@GDK_KEY_RELEASE: a key has been released.
+@GDK_ENTER_NOTIFY: the pointer has entered the window.
+@GDK_LEAVE_NOTIFY: the pointer has left the window.
+@GDK_FOCUS_CHANGE: the keyboard focus has entered or left the window. Note that
+in GTK+ keyboard focus is handled mostly within GTK+ itself, so it is usually
+only toplevel windows which receive these events.
+@GDK_CONFIGURE: the size, position or stacking order of the window has changed.
+Note that GTK+ discards these events for %GDK_WINDOW_CHILD windows.
+@GDK_MAP: the window has been mapped.
+@GDK_UNMAP: the window has been unmapped.
+@GDK_PROPERTY_NOTIFY: a property on the window has been changed or deleted.
+@GDK_SELECTION_CLEAR: the application has lost ownership of a selection.
+@GDK_SELECTION_REQUEST: another application has requested a selection.
+@GDK_SELECTION_NOTIFY: a selection has been received.
+@GDK_PROXIMITY_IN: an input device has moved into contact with a sensing
+surface (e.g. a touchscreen or graphics tablet).
+@GDK_PROXIMITY_OUT: an input device has moved out of contact with a sensing
+surface.
+@GDK_DRAG_ENTER: the mouse has entered the window while a drag is in progress.
+@GDK_DRAG_LEAVE: the mouse has left the window while a drag is in progress.
+@GDK_DRAG_MOTION: the mouse has moved in the window while a drag is in
+progress.
+@GDK_DRAG_STATUS: the status of the drag operation initiated by the window
+has changed.
+@GDK_DROP_START: a drop operation onto the window has started.
+@GDK_DROP_FINISHED: the drop operation initiated by the window has completed.
+@GDK_CLIENT_EVENT: a message has been received from another application.
+@GDK_VISIBILITY_NOTIFY: the window visibility status has changed.
+@GDK_NO_EXPOSE: indicates that the source region was completely available
+when parts of a drawable were copied. This is not very useful.
<!-- ##### ENUM GdkEventMask ##### -->
<para>
-
+A set of bit-flags to indicate which events a window is to receive.
+Most of these masks map onto one or more of the #GdkEventType event types
+above.
+</para>
+<para>
+%GDK_POINTER_MOTION_HINT_MASK is a special mask which is used to reduce the
+number of %GDK_MOTION_NOTIFY events received. Normally a %GDK_MOTION_NOTIFY
+event is received each time the mouse moves. However, if the application
+spends a lot of time processing the event (updating the display, for example),
+it can easily lag behind the position of the mouse. When using the
+%GDK_POINTER_MOTION_HINT_MASK the server will only send %GDK_MOTION_NOTIFY
+events when the application asks for them, by calling gdk_window_get_pointer().
</para>
@GDK_EXPOSURE_MASK:
@GDK_PROXIMITY_IN_MASK:
@GDK_PROXIMITY_OUT_MASK:
@GDK_SUBSTRUCTURE_MASK:
-@GDK_ALL_EVENTS_MASK:
+@GDK_ALL_EVENTS_MASK: the combination of all the above event masks.
-<!-- ##### FUNCTION gdk_events_pending ##### -->
+<!-- ##### MACRO GDK_CURRENT_TIME ##### -->
+<para>
+Represents the current time, and can be used anywhere a time is expected.
+</para>
+
+
+
+<!-- ##### MACRO GDK_PRIORITY_EVENTS ##### -->
<para>
+This is the priority that events from the X server are given in the
+<link linkend="glib-The-Main-Event-Loop">GLib Main Loop</link>.
+</para>
+
+
+<!-- ##### FUNCTION gdk_events_pending ##### -->
+<para>
+Checks if any events are waiting to be processed.
</para>
-@Returns:
+@Returns: TRUE if any events are pending.
<!-- ##### FUNCTION gdk_event_peek ##### -->
<para>
-
+Gets a copy of the first #GdkEvent in the event queue.
+(Note that this function will not get more events from the X server.
+It only checks the events that have already been moved to the GDK event queue.)
</para>
-@Returns:
+@Returns: a copy of the first #GdkEvent on the event queue, or NULL if no
+events are in the queue. The returned #GdkEvent should be freed with
+gdk_event_free().
<!-- ##### FUNCTION gdk_event_get ##### -->
<para>
-
+Gets the next #GdkEvent to be processed, fetching events from the X server if
+necessary.
</para>
-@Returns:
+@Returns: the next #GdkEvent to be processed, or NULL if no events are pending.
+The returned #GdkEvent should be freed with gdk_event_free().
<!-- ##### FUNCTION gdk_event_get_graphics_expose ##### -->
<para>
-
+Waits for a GraphicsExpose or NoExpose event from the X server.
+This is used in the #GtkText and #GtkCList widgets in GTK+ to make sure any
+GraphicsExpose events are handled before the widget is scrolled.
</para>
-@window:
-@Returns:
+@window: the #GdkWindow to wait for the events for.
+@Returns: a #GdkEventExpose if a GraphicsExpose was received, or NULL if a
+NoExpose event was received.
<!-- ##### FUNCTION gdk_event_put ##### -->
<para>
-
+Appends a copy of the given event onto the front of the event queue.
</para>
-@event:
+@event: a #GdkEvent.
<!-- ##### FUNCTION gdk_event_copy ##### -->
<para>
-
+Copies a #GdkEvent, copying or incrementing the reference count of the
+resources associated with it (e.g. #GdkWindow's and strings).
</para>
-@event:
-@Returns:
+@event: a #GdkEvent.
+@Returns: a copy of @event. The returned #GdkEvent should be freed with
+gdk_event_free().
<!-- ##### FUNCTION gdk_event_free ##### -->
<para>
-
+Frees a #GdkEvent, freeing or decrementing any resources associated with it.
+Note that this function should only be called with events returned from
+gdk_event_peek(), gdk_event_get(), gdk_event_get_graphics_expose() and
+gdk_event_copy().
</para>
-@event:
+@event: a #GdkEvent.
<!-- ##### FUNCTION gdk_event_get_time ##### -->
<para>
-
+Gets the timestamp from a #GdkEvent.
</para>
-@event:
-@Returns:
+@event: a #GdkEvent.
+@Returns: the timestamp from @event, or #GDK_CURRENT_TIME if the event has
+no timestamp.
<!-- ##### FUNCTION gdk_event_handler_set ##### -->
<para>
+Sets the function to call to handle all events from GDK.
+</para>
+<para>
+Note that GTK+ uses this to install its own event handler, so it is probably
+not useful for GTK+ applications.
+</para>
+
+@func: the function to call to handle events from GDK.
+@data: user data to pass to the function.
+@notify: the function to call when the handler function is removed, i.e. when
+gdk_event_handler_set() is called with another event handler.
+
+<!-- ##### USER_FUNCTION GdkEventFunc ##### -->
+<para>
+Specifies the type of function passed to gdk_event_handler_set() to handle
+all GDK events.
</para>
-@func:
-@data:
-@notify:
+@event: the #GdkEvent to process.
+@data: user data set when the event handler was installed with
+gdk_event_handler_set().
<!-- ##### FUNCTION gdk_event_send_client_message ##### -->
<para>
-
+Sends an X ClientMessage event to a given window.
+</para>
+<para>
+This could be used for communicating between different applications,
+though the amount of data is limited to 20 bytes.
</para>
-@event:
-@xid:
-@Returns:
+@event: the #GdkEvent to send, which should be a #GdkEventClient.
+@xid: the window to send the X ClientMessage event to.
+@Returns: non-zero on success.
-<!-- ##### USER_FUNCTION GdkEventFunc ##### -->
+<!-- ##### FUNCTION gdk_event_send_clientmessage_toall ##### -->
+<para>
+Sends an X ClientMessage event to all toplevel windows.
+</para>
<para>
+Toplevel windows are determined by checking for the WM_STATE property, as
+described in the Inter-Client Communication Conventions Manual (ICCCM).
+If no windows are found with the WM_STATE property set, the message is sent
+to all children of the root window.
+</para>
+
+@event: the #GdkEvent to send, which should be a #GdkEventClient.
+
+<!-- ##### FUNCTION gdk_add_client_message_filter ##### -->
+<para>
+Adds a filter to be called when X ClientMessage events are received.
</para>
-@event:
-@data:
+@message_type: the type of ClientMessage events to receive. This will be
+checked against the <structfield>message_type</structfield> field of the
+XClientMessage event struct.
+@func: the function to call to process the event.
+@data: user data to pass to @func.
-<!-- ##### FUNCTION gdk_event_send_clientmessage_toall ##### -->
+<!-- ##### FUNCTION gdk_get_show_events ##### -->
<para>
+Returns non-zero if event debugging output is enabled.
+</para>
+@Returns: non-zero if event debugging output is enabled.
+
+
+<!-- ##### FUNCTION gdk_set_show_events ##### -->
+<para>
+Sets whether event debugging information is output.
+Note that GTK+ must be compiled with debugging enabled, i.e. using the
+'--enable-debug' configure option.
</para>
-@event:
+@show_events: TRUE to output event debugging information.
@Returns: the height of the character in pixels.
+<!-- ##### TYPEDEF GdkWChar ##### -->
+<para>
+Specifies a wide character type, used to represent character codes.
+This is needed since some native languages have character sets which have
+more than 256 characters (Japanese and Chinese, for example).
+</para>
+<para>
+Wide character values between 0 and 127 are always identical in meaning to
+the ASCII character codes. The wide character value 0 is often used to
+terminate strings of wide characters in a similar way to normal strings
+using the char type.
+</para>
+<para>
+An alternative to wide characters is multi-byte characters, which extend
+normal char strings to cope with larger character sets. As the name suggests,
+multi-byte characters use a different number of bytes to store different
+character codes. For example codes 0-127 (i.e. the ASCII codes) often
+use just one byte of memory, while other codes may use 2, 3 or even 4 bytes.
+Multi-byte characters have the advantage that they can often be used in an
+application with little change, since strings are still represented as arrays
+of char values. However multi-byte strings are much easier to manipulate since
+the character are all of the same size.
+</para>
+<para>
+Applications typically use wide characters to represent character codes
+internally, and multi-byte strings when saving the characters to a file.
+The gdk_wcstombs() and gdk_mbstowcs() functions can be used to convert from
+one representation to the other.
+</para>
+<para>
+See the 'Extended Characters' section of the GNU C Library Reference Manual
+for more detailed information on wide and multi-byte characters.
+</para>
+
+
+<!-- ##### FUNCTION gdk_wcstombs ##### -->
+<para>
+Converts a wide character string to a multi-byte string.
+(The function name comes from an acronym of 'Wide Character String TO
+Multi-Byte String').
+</para>
+
+@src: a wide character string.
+@Returns: the multi-byte string corresponding to @src, or NULL if the
+conversion failed. The returned string should be freed with g_free() when no
+longer needed.
+
+
+<!-- ##### FUNCTION gdk_mbstowcs ##### -->
+<para>
+Converts a multi-byte string to a wide character string.
+(The function name comes from an acronym of 'Multi-Byte String TO Wide
+Character String').
+</para>
+
+@dest: the space to place the converted wide character string into.
+@src: the multi-byte string to convert, which must be null-terminated.
+@dest_max: the maximum number of wide characters to place in @dest.
+@Returns: the number of wide characters written into @dest, or -1 if the
+conversion failed.
+
+
@GDK_GC_CAP_STYLE:
@GDK_GC_JOIN_STYLE:
-<!-- ##### ENUM GdkFill ##### -->
-<para>
-Determines how primitives are drawn.
-
-<informaltable pgwide=1 frame="none" role="enum">
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
-<tbody>
-
-<row>
-<entry>GDK_SOLID</entry>
-<entry>draw with the foreground color.</entry>
-</row>
-
-<row>
-<entry>GDK_TILED</entry>
-<entry>draw with a tiled pixmap.</entry>
-</row>
-
-<row>
-<entry>GDK_STIPPLED</entry>
-<entry>draw using the stipple bitmap. Pixels corresponding
-to bits in the stipple bitmap that are set will be drawn in the
-foreground color; pixels corresponding to bits that are
-not set will be left untouched.</entry>
-</row>
-
-<row>
-<entry>GDK_OPAQUE_STIPPLED</entry>
-<entry>draw using the stipple bitmap. Pixels corresponding
-to bits in the stipple bitmap that are set will be drawn in the
-foreground color; pixels corresponding to bits that are
-not set will be drawn with the background color.</entry>
-</row>
-
-</tbody></tgroup></informaltable>
-</para>
-
-@GDK_SOLID:
-@GDK_TILED:
-@GDK_STIPPLED:
-@GDK_OPAQUE_STIPPLED:
-
<!-- ##### ENUM GdkFunction ##### -->
<para>
Determines how the bit values for the source pixels are combined with
@GDK_NAND:
@GDK_SET:
-<!-- ##### ENUM GdkLineStyle ##### -->
-<para>
-Determines how lines are drawn.
-
-<informaltable pgwide=1 frame="none" role="enum">
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
-<tbody>
-
-<row>
-<entry>GDK_LINE_SOLID</entry>
-<entry>lines are drawn solid.</entry>
-</row>
-
-<row>
-<entry>GDK_LINE_ON_OFF_DASH</entry>
-<entry>even segments are drawn; odd segments are not drawn.</entry>
-</row>
-
-<row>
-<entry>GDK_LINE_DOUBLE_DASH</entry>
-<entry>even segments are normally. Odd segments are drawn
-in the background color if the fill style is %GDK_SOLID,
-or in the background color masked by the stipple if the
-fill style is %GDK_STIPPLED.</entry>
-</row>
-
-</tbody></tgroup></informaltable>
-</para>
-
-@GDK_LINE_SOLID:
-@GDK_LINE_ON_OFF_DASH:
-@GDK_LINE_DOUBLE_DASH:
-
-<!-- ##### ENUM GdkCapStyle ##### -->
-<para>
-Determines how the end of lines are drawn.
-
-<informaltable pgwide=1 frame="none" role="struct">
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
-<tbody>
-
-<row>
-<entry>GDK_CAP_NOT_LAST</entry>
-<entry>the same as %GDK_CAP_BUTT for lines of non-zero width.
- for zero width lines, the final point on the line
- will not be drawn.</entry>
-</row>
-
-<row>
-<entry>GDK_CAP_BUTT</entry>
-<entry>the ends of the lines are drawn squared off and extending
- to the coordinates of the end point.</entry>
-</row>
-
-<row>
-<entry>GDK_CAP_ROUND</entry>
-<entry>the ends of the lines are drawn as semicircles with the
- diameter equal to the line width and centered at the
- end point.</entry>
-</row>
-
-<row>
-<entry>GDK_CAP_PROJECTING</entry>
-<entry>the ends of the lines are drawn squared off and extending
- half the width of the line beyond the end point.</entry>
-</row>
-</tbody></tgroup></informaltable>
-</para>
-
-@GDK_CAP_NOT_LAST:
-@GDK_CAP_BUTT:
-@GDK_CAP_ROUND:
-@GDK_CAP_PROJECTING:
-
-<!-- ##### ENUM GdkJoinStyle ##### -->
-<para>
-Determines how the joins between segments of a polygon are drawn.
-
-<informaltable pgwide=1 frame="none" role="struct">
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
-<tbody>
-
-<row>
-<entry>GDK_JOIN_MITER</entry>
-<entry>the sides of each line are extended to meet at an angle.</entry>
-</row>
-
-<row>
-<entry>GDK_JOIN_ROUND</entry>
-<entry>the sides of the two lines are joined by a circular arc.</entry>
-</row>
-
-<row>
-<entry>GDK_JOIN_BEVEL</entry>
-<entry>the sides of the two lines are joined by a straight line which
- makes an equal angle with each line.</entry>
-</row>
-
-</tbody></tgroup></informaltable>
-</para>
-
-@GDK_JOIN_MITER:
-@GDK_JOIN_ROUND:
-@GDK_JOIN_BEVEL:
-
<!-- ##### FUNCTION gdk_gc_new ##### -->
<para>
Create a new graphics context with default values.
@fill: the new fill mode.
+<!-- ##### ENUM GdkFill ##### -->
+<para>
+Determines how primitives are drawn.
+
+<informaltable pgwide=1 frame="none" role="enum">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>GDK_SOLID</entry>
+<entry>draw with the foreground color.</entry>
+</row>
+
+<row>
+<entry>GDK_TILED</entry>
+<entry>draw with a tiled pixmap.</entry>
+</row>
+
+<row>
+<entry>GDK_STIPPLED</entry>
+<entry>draw using the stipple bitmap. Pixels corresponding
+to bits in the stipple bitmap that are set will be drawn in the
+foreground color; pixels corresponding to bits that are
+not set will be left untouched.</entry>
+</row>
+
+<row>
+<entry>GDK_OPAQUE_STIPPLED</entry>
+<entry>draw using the stipple bitmap. Pixels corresponding
+to bits in the stipple bitmap that are set will be drawn in the
+foreground color; pixels corresponding to bits that are
+not set will be drawn with the background color.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
+
+@GDK_SOLID:
+@GDK_TILED:
+@GDK_STIPPLED:
+@GDK_OPAQUE_STIPPLED:
+
<!-- ##### FUNCTION gdk_gc_set_tile ##### -->
<para>
Set a tile pixmap for a graphics context.
@join_style: the in which lines are joined together.
+<!-- ##### ENUM GdkLineStyle ##### -->
+<para>
+Determines how lines are drawn.
+
+<informaltable pgwide=1 frame="none" role="enum">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>GDK_LINE_SOLID</entry>
+<entry>lines are drawn solid.</entry>
+</row>
+
+<row>
+<entry>GDK_LINE_ON_OFF_DASH</entry>
+<entry>even segments are drawn; odd segments are not drawn.</entry>
+</row>
+
+<row>
+<entry>GDK_LINE_DOUBLE_DASH</entry>
+<entry>even segments are normally. Odd segments are drawn
+in the background color if the fill style is %GDK_SOLID,
+or in the background color masked by the stipple if the
+fill style is %GDK_STIPPLED.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
+
+@GDK_LINE_SOLID:
+@GDK_LINE_ON_OFF_DASH:
+@GDK_LINE_DOUBLE_DASH:
+
+<!-- ##### ENUM GdkCapStyle ##### -->
+<para>
+Determines how the end of lines are drawn.
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>GDK_CAP_NOT_LAST</entry>
+<entry>the same as %GDK_CAP_BUTT for lines of non-zero width.
+ for zero width lines, the final point on the line
+ will not be drawn.</entry>
+</row>
+
+<row>
+<entry>GDK_CAP_BUTT</entry>
+<entry>the ends of the lines are drawn squared off and extending
+ to the coordinates of the end point.</entry>
+</row>
+
+<row>
+<entry>GDK_CAP_ROUND</entry>
+<entry>the ends of the lines are drawn as semicircles with the
+ diameter equal to the line width and centered at the
+ end point.</entry>
+</row>
+
+<row>
+<entry>GDK_CAP_PROJECTING</entry>
+<entry>the ends of the lines are drawn squared off and extending
+ half the width of the line beyond the end point.</entry>
+</row>
+</tbody></tgroup></informaltable>
+</para>
+
+@GDK_CAP_NOT_LAST:
+@GDK_CAP_BUTT:
+@GDK_CAP_ROUND:
+@GDK_CAP_PROJECTING:
+
+<!-- ##### ENUM GdkJoinStyle ##### -->
+<para>
+Determines how the joins between segments of a polygon are drawn.
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>GDK_JOIN_MITER</entry>
+<entry>the sides of each line are extended to meet at an angle.</entry>
+</row>
+
+<row>
+<entry>GDK_JOIN_ROUND</entry>
+<entry>the sides of the two lines are joined by a circular arc.</entry>
+</row>
+
+<row>
+<entry>GDK_JOIN_BEVEL</entry>
+<entry>the sides of the two lines are joined by a straight line which
+ makes an equal angle with each line.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
+
+@GDK_JOIN_MITER:
+@GDK_JOIN_ROUND:
+@GDK_JOIN_BEVEL:
+
<!-- ##### FUNCTION gdk_gc_set_dashes ##### -->
<para>
Sets the way dashed-lines are drawn. Lines will be
@dst_gc: the destination graphics context.
@src_gc: the source graphics context.
+
+
General
<!-- ##### SECTION Short_Description ##### -->
-
+library initialization and miscellaneous functions.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+This section describes the GDK initialization functions and miscellaneous
+utility functions.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### FUNCTION gdk_init ##### -->
<para>
-
+Initializes the GDK library and connects to the X server.
+If initialization fails, a warning message is output and the application
+terminates with a call to exit(1).
</para>
-
-@argc:
-@argv:
-
-
-<!-- ##### FUNCTION gdk_init_check ##### -->
<para>
-
+Any arguments used by GDK are removed from the array and @argc and @argv are
+updated accordingly.
</para>
-
-@argc:
-@argv:
-@Returns:
-
-
-<!-- ##### FUNCTION gdk_exit ##### -->
<para>
-
+GTK+ initializes GDK in gtk_init() and so this function is not usually needed
+by GTK+ applications.
</para>
-@error_code:
+@argc: the number of command line arguments.
+@argv: the array of command line arguments.
-<!-- ##### ENUM GdkStatus ##### -->
+<!-- ##### FUNCTION gdk_init_check ##### -->
<para>
-
+Initializes the GDK library and connects to the X server, returning TRUE on
+success.
</para>
-
-@GDK_OK:
-@GDK_ERROR:
-@GDK_ERROR_PARAM:
-@GDK_ERROR_FILE:
-@GDK_ERROR_MEM:
-
-<!-- ##### MACRO GDK_NONE ##### -->
<para>
-
+Any arguments used by GDK are removed from the array and @argc and @argv are
+updated accordingly.
</para>
-
-
-
-<!-- ##### MACRO GDK_CURRENT_TIME ##### -->
<para>
-
+GTK+ initializes GDK in gtk_init() and so this function is not usually needed
+by GTK+ applications.
</para>
+@argc: the number of command line arguments.
+@argv: the array of command line arguments.
+@Returns: TRUE if initialization succeeded.
-<!-- ##### MACRO GDK_PRIORITY_EVENTS ##### -->
+<!-- ##### FUNCTION gdk_exit ##### -->
<para>
-
+Exits the application using the exit() system call.
</para>
-
-
-
-<!-- ##### FUNCTION gdk_set_locale ##### -->
<para>
-
+This routine is provided mainly for backwards compatability, since it used to
+perform tasks necessary to exit the application cleanly. Those tasks are now
+performed in a function which is automatically called on exit (via the use
+of g_atexit()).
</para>
-@Returns:
+@error_code: the error code to pass to the exit() call.
-<!-- ##### FUNCTION gdk_get_show_events ##### -->
+<!-- ##### FUNCTION gdk_set_locale ##### -->
<para>
-
+Initializes the support for internationalization by calling the setlocale()
+system call. This function is called by gtk_set_locale() and so GTK+
+applications should use that instead.
</para>
-
-@Returns:
-
-
-<!-- ##### FUNCTION gdk_set_show_events ##### -->
<para>
-
+The locale to use is determined by the LANG environment variable,
+so to run an application in a certain locale you can do something like this:
+<informalexample>
+<programlisting>
+ export LANG="fr"
+ ... run application ...
+</programlisting>
+</informalexample>
</para>
-
-@show_events:
-
-
-<!-- ##### FUNCTION gdk_add_client_message_filter ##### -->
<para>
-
+If the locale is not supported by X then it is reset to the standard "C"
+locale.
</para>
-@message_type:
-@func:
-@data:
+@Returns: the resulting locale.
<!-- ##### FUNCTION gdk_set_sm_client_id ##### -->
<para>
-
+Sets the SM_CLIENT_ID property on the application's leader window so that
+the window manager can save the application's state using the X11R6 ICCCM
+session management protocol.
</para>
-
-@sm_client_id:
-
-
-<!-- ##### FUNCTION gdk_get_use_xshm ##### -->
<para>
-
+The leader window is automatically created by GDK and never shown. It's only
+use is for session management. The WM_CLIENT_LEADER property is automatically
+set on all X windows created by the application to point to the leader window.
+</para>
+<para>
+See the X Session Management Library documentation for more information on
+session management and the Inter-Client Communication Conventions Manual
+(ICCCM) for information on the WM_CLIENT_LEADER property. (Both documents are
+part of the X Windows distribution.)
</para>
-@Returns:
+@sm_client_id: the client id assigned by the session manager when the
+connection was opened, or NULL to remove the property.
-<!-- ##### FUNCTION gdk_set_use_xshm ##### -->
+<!-- ##### FUNCTION gdk_get_display ##### -->
<para>
-
+Gets the name of the display, which usually comes from the DISPLAY
+environment variable or the --display command line option.
</para>
-@use_xshm:
+@Returns: the name of the display.
-<!-- ##### FUNCTION gdk_get_display ##### -->
+<!-- ##### FUNCTION gdk_flush ##### -->
<para>
-
+Flushes the X output buffer and waits until all requests have been processed
+by the server. This is rarely needed by applications. It's main use is for
+trapping X errors with gdk_error_trap_push() and gdk_error_trap_pop().
</para>
-@Returns:
<!-- ##### FUNCTION gdk_screen_width ##### -->
<para>
-
+Returns the width of the screen in pixels.
</para>
-@Returns:
+@Returns: the width of the screen in pixels.
<!-- ##### FUNCTION gdk_screen_height ##### -->
<para>
-
+Returns the height of the screen in pixels.
</para>
-@Returns:
+@Returns: the height of the screen in pixels.
<!-- ##### FUNCTION gdk_screen_width_mm ##### -->
<para>
-
+Returns the width of the screen in millimeters.
+Note that on many X servers this value will not be correct.
</para>
-@Returns:
+@Returns: the width of the screen in millimeters, though it is not always
+correct.
<!-- ##### FUNCTION gdk_screen_height_mm ##### -->
<para>
-
+Returns the height of the screen in millimeters.
+Note that on many X servers this value will not be correct.
</para>
-@Returns:
+@Returns: the height of the screen in millimeters, though it is not always
+correct.
<!-- ##### FUNCTION gdk_pointer_grab ##### -->
<para>
+Grabs the pointer (usually a mouse) so that all events are passed to this
+application until the pointer is ungrabbed with gdk_pointer_ungrab(), or
+the grab window becomes unviewable.
+This overrides any previous pointer grab by this client.
+</para>
+<para>
+Pointer grabs are used for operations which need complete control over mouse
+events, even if the mouse leaves the application.
+For example in GTK+ it is used for Drag and Drop, for dragging the handle in
+the #GtkHPaned and #GtkVPaned widgets, and for resizing columns in #GtkCList
+widgets.
+</para>
+<para>
+Note that if the event mask of an X window has selected both button press and
+button release events, then a button press event will cause an automatic
+pointer grab until the button is released.
+X does this automatically since most applications expect to receive button
+press and release events in pairs.
+It is equivalent to a pointer grab on the window with @owner_events set to
+TRUE.
+</para>
+
+@window: the #GdkWindow which will own the grab (the grab window).
+@owner_events: if FALSE then all pointer events are reported with respect to
+@window and are only reported if selected by @event_mask. If TRUE then pointer
+events for this application are reported as normal, but pointer events outside
+this application are reported with respect to @window and only if selected by
+@event_mask. In either mode, unreported events are discarded.
+@event_mask: specifies the event mask, which is used in accordance with
+@owner_events.
+@confine_to: TRUE to confine the pointer to @window. If the pointer is outside
+@window, it will automatically be moved to the closest edge of @window and
+enter and leave events will be generated as necessary.
+@cursor: the cursor to display while the grab is active. If this is NULL then
+the normal cursors are used for @window and its descendants, and the cursor
+for @window is used for all other windows.
+@time: the timestamp of the event which led to this pointer grab. This usually
+comes from a #GdkEventButton struct, though #GDK_CURRENT_TIME can be used if
+the time isn't known.
+@Returns: 0 if the grab was successful.
+
+<!-- ##### FUNCTION gdk_pointer_ungrab ##### -->
+<para>
+Ungrabs the pointer, if it is grabbed by this application.
</para>
-@window:
-@owner_events:
-@event_mask:
-@confine_to:
-@cursor:
-@time:
-@Returns:
+@time: a timestamp from a #GdkEvent, or #GDK_CURRENT_TIME if no timestamp is
+available.
-<!-- ##### FUNCTION gdk_pointer_ungrab ##### -->
+<!-- ##### FUNCTION gdk_pointer_is_grabbed ##### -->
<para>
-
+Returns TRUE if the pointer is currently grabbed by this application.
+</para>
+<para>
+Note that the return value is not completely reliable since the X server may
+automatically ungrab the pointer, without informing the application, if the
+grab window becomes unviewable. It also does not take passive pointer grabs
+into account.
</para>
-@time:
+@Returns: TRUE if the pointer is currently grabbed by this application.
+Though this value is not always correct.
<!-- ##### FUNCTION gdk_keyboard_grab ##### -->
<para>
-
+Grabs the keyboard so that all events are passed to this
+application until the keyboard is ungrabbed with gdk_keyboard_ungrab().
+This overrides any previous keyboard grab by this client.
</para>
-@window:
-@owner_events:
-@time:
-@Returns:
+@window: the #GdkWindow which will own the grab (the grab window).
+@owner_events: if FALSE then all keyboard events are reported with respect to
+@window. If TRUE then keyboard events for this application are reported as
+normal, but keyboard events outside this application are reported with respect
+to @window. Both key press and key release events are alwasy reported,
+independant of the event mask set by the application.
+@time: a timestamp from a #GdkEvent, or #GDK_CURRENT_TIME if no timestamp is
+available.
+@Returns: 0 if the grab was successful.
<!-- ##### FUNCTION gdk_keyboard_ungrab ##### -->
<para>
-
+Ungrabs the keyboard, if it is grabbed by this application.
</para>
-@time:
+@time: a timestamp from a #GdkEvent, or #GDK_CURRENT_TIME if no timestamp is
+available.
-<!-- ##### FUNCTION gdk_pointer_is_grabbed ##### -->
+<!-- ##### FUNCTION gdk_key_repeat_disable ##### -->
<para>
-
+Disables the keyboard auto-repeat mode.
+This should be used with care as it may affect other applications.
</para>
-@Returns:
-<!-- ##### FUNCTION gdk_flush ##### -->
+<!-- ##### FUNCTION gdk_key_repeat_restore ##### -->
<para>
-
+Restores the keyboard auto-repeat mode to its state when the application was
+started.
</para>
<!-- ##### FUNCTION gdk_beep ##### -->
<para>
-
+Emits a short beep.
</para>
-<!-- ##### FUNCTION gdk_key_repeat_disable ##### -->
+<!-- ##### FUNCTION gdk_get_use_xshm ##### -->
<para>
-
+Returns TRUE if GDK will attempt to use the MIT-SHM shared memory extension.
+</para>
+<para>
+The shared memory extension is used for #GdkImage, and consequently for
+<link linkend="gdk-GdkRGB">GdkRGB</link>.
+It enables much faster drawing by communicating with the X server through
+SYSV shared memory calls. However, it can only be used if the X client and
+server are on the same machine and the server supports it.
</para>
+@Returns: TRUE if use of the MIT shared memory extension will be attempted.
-<!-- ##### FUNCTION gdk_key_repeat_restore ##### -->
+<!-- ##### FUNCTION gdk_set_use_xshm ##### -->
<para>
-
+Sets whether the use of the MIT shared memory extension should be attempted.
+This function is mainly for internal use. It is only safe for an application
+to set this to FALSE, since if it is set to TRUE and the server does not
+support the extension it may cause warning messages to be output.
</para>
+@use_xshm: TRUE if use of the MIT shared memory extension should be attempted.
<!-- ##### FUNCTION gdk_error_trap_push ##### -->
<para>
-
+This function allows X errors to be trapped instead of the normal behavior
+of exiting the application. It should only be used if it is not possible to
+avoid the X error in any other way.
</para>
+<example>
+<title>Trapping an X error.</title>
+<programlisting>
+ gdk_error_trap_push ();
+
+ /* ... Call the X function which may cause an error here ... */
+
+ /* Flush the X queue to catch errors now. */
+ gdk_flush ();
+
+ if (gdk_error_trap_pop ())
+ {
+ /* ... Handle the error here ... */
+ }
+</programlisting>
+</example>
<!-- ##### FUNCTION gdk_error_trap_pop ##### -->
<para>
-
+Removes the X error trap installed with gdk_error_trap_push().
</para>
-@Returns:
+@Returns: the X error code, or 0 if no error occurred.
Images
<!-- ##### SECTION Short_Description ##### -->
-
+an area for bit-mapped graphics stored on the X Windows client.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GdkImage type represents an area for drawing graphics.
+It has now been superceded to a large extent by the much more flexible
+<link linkend="gdk-GdkRGB">GdkRGB</link> functions.
+</para>
+<para>
+To create an empty #GdkImage use gdk_image_new().
+To create a #GdkImage from bitmap data use gdk_image_new_bitmap().
+To create an image from part of a #GdkWindow use gdk_image_get().
+</para>
+<para>
+The image can be manipulated with gdk_image_get_pixel() and
+gdk_image_put_pixel(), or alternatively by changing the actual pixel data.
+Though manipulating the pixel data requires complicated code to cope with
+the different formats that may be used.
+</para>
+<para>
+To draw a #GdkImage in a #GdkWindow or #GdkPixmap use gdk_draw_image().
+</para>
+<para>
+To destroy a #GdkImage use gdk_image_destroy().
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<variablelist>
+
+<varlistentry>
+<term><link linkend="gdk-Bitmaps-and-Pixmaps">Bitmaps and Pixmaps</link></term>
+<listitem><para>
+Graphics which are stored on the X Windows server.
+Since these are stored on the server they can be drawn very quickly, and all
+of the <link linkend="gdk-Drawing-Primitives">Drawing Primitives</link> can be
+used to draw on them. Their main disadvantage is that manipulating individual
+pixels can be very slow.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><link linkend="gdk-GdkRGB">GdkRGB</link></term>
+<listitem><para>
+Built on top of #GdkImage, this provides much more functionality,
+including the dithering of colors to produce better output on low-color
+displays.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
</para>
<!-- ##### STRUCT GdkImage ##### -->
<para>
-
+The #GdkImage struct contains information on the image and the pixel data.
</para>
-@type:
-@visual:
-@byte_order:
-@width:
-@height:
-@depth:
-@bpp:
-@bpl:
-@mem:
+@type: the type of the image.
+@visual: the visual.
+@byte_order: the byte order.
+@width: the width of the image in pixels.
+@height: the height of the image in pixels.
+@depth: the depth of the image, i.e. the number of bits per pixel.
+@bpp: the number of bytes per pixel.
+@bpl: the number of bytes per line of the image.
+@mem: the pixel data.
-<!-- ##### ENUM GdkImageType ##### -->
+<!-- ##### FUNCTION gdk_image_new ##### -->
<para>
-
+Creates a new #GdkImage.
</para>
-@GDK_IMAGE_NORMAL:
-@GDK_IMAGE_SHARED:
-@GDK_IMAGE_FASTEST:
+@type: the type of the #GdkImage, one of %GDK_IMAGE_NORMAL, %GDK_IMAGE_SHARED
+and %GDK_IMAGE_FASTEST. %GDK_IMAGE_FASTEST is probably the best choice, since
+it will try creating a %GDK_IMAGE_SHARED image first and if that fails it will
+then use %GDK_IMAGE_NORMAL.
+@visual: the #GdkVisual to use for the image.
+@width: the width of the image in pixels.
+@height: the height of the image in pixels.
+@Returns: a new #GdkImage, or NULL if the image could not be created.
-<!-- ##### FUNCTION gdk_image_new_bitmap ##### -->
-<para>
+<!-- ##### ENUM GdkImageType ##### -->
+<para>
+Specifies the type of a #GdkImage.
</para>
-@visual:
-@data:
-@width:
-@height:
-@Returns:
+@GDK_IMAGE_NORMAL: The original X image type, which is quite slow since the
+image has to be transferred from the client to the server to display it.
+@GDK_IMAGE_SHARED: A faster image type, which uses shared memory to transfer
+the image data between client and server. However this will only be available
+if client and server are on the same machine and the shared memory extension
+is supported by the server.
+@GDK_IMAGE_FASTEST: Specifies that %GDK_IMAGE_SHARED should be tried first,
+and if that fails then %GDK_IMAGE_NORMAL will be used.
-
-<!-- ##### FUNCTION gdk_image_new ##### -->
+<!-- ##### FUNCTION gdk_image_new_bitmap ##### -->
<para>
-
+Creates a new #GdkImage with a depth of 1 from the given data.
</para>
-@type:
-@visual:
-@width:
-@height:
-@Returns:
+@visual: the #GdkVisual to use for the image.
+@data: the pixel data.
+@width: the width of the image in pixels.
+@height: the height of the image in pixels.
+@Returns: a new #GdkImage.
<!-- ##### FUNCTION gdk_image_get ##### -->
<para>
-
+Gets part of a #GdkWindow and stores it in a new #GdkImage.
</para>
-@window:
-@x:
-@y:
-@width:
-@height:
-@Returns:
+@window: the #GdkWindow to copy from.
+@x: the left edge of the rectangle to copy from @window.
+@y: the top edge of the rectangle to copy from @window.
+@width: the width of the area to copy, in pixels.
+@height: the height of the area to copy, in pixels.
+@Returns: a new #GdkImage with a copy of the given area of @window.
-<!-- ##### FUNCTION gdk_image_put_pixel ##### -->
+<!-- ##### FUNCTION gdk_image_destroy ##### -->
<para>
-
+Destroys a #GdkImage, freeing any resources allocated for it.
</para>
-@image:
-@x:
-@y:
-@pixel:
+@image: a #GdkImage.
-<!-- ##### FUNCTION gdk_image_get_pixel ##### -->
+<!-- ##### FUNCTION gdk_image_put_pixel ##### -->
<para>
-
+Sets a pixel in a #GdkImage to a given pixel value.
</para>
-@image:
-@x:
-@y:
-@Returns:
+@image: a #GdkImage.
+@x: the x coordinate of the pixel to set.
+@y: the y coordinate of the pixel to set.
+@pixel: the pixel value to set.
-<!-- ##### FUNCTION gdk_image_destroy ##### -->
+<!-- ##### FUNCTION gdk_image_get_pixel ##### -->
<para>
-
+Gets a pixel value at a specified position in a #GdkImage.
</para>
-@image:
+@image: a #GdkImage.
+@x: the x coordinate of the pixel to get.
+@y: the y coordinate of the pixel to get.
+@Returns: the pixel value at the given position.
Input Contexts
<!-- ##### SECTION Short_Description ##### -->
-
+internationalized text input properties.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+A #GdkIC input context is used for each user interface element which supports
+internationalized text input. See the
+<link linkend="gdk-Input-Methods">Input Methods</link> section for an overview
+of how internationalized text input works in GTK+.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GdkIC ##### -->
<para>
-
+The #GdkIC struct is an opaque structure representing an input context
+for use with the global <link linkend="gdk-Input-Methods">Input Method</link>.
</para>
-<!-- ##### STRUCT GdkICAttr ##### -->
+<!-- ##### FUNCTION gdk_ic_new ##### -->
<para>
-
+Creates a new #GdkIC using the given attributes.
</para>
-@style:
-@client_window:
-@focus_window:
-@filter_events:
-@spot_location:
-@line_spacing:
-@cursor:
-@preedit_fontset:
-@preedit_area:
-@preedit_area_needed:
-@preedit_foreground:
-@preedit_background:
-@preedit_pixmap:
-@preedit_colormap:
-@status_fontset:
-@status_area:
-@status_area_needed:
-@status_foreground:
-@status_background:
-@status_pixmap:
-@status_colormap:
+@attr: a #GdkICAttr struct containing attributes to use for the input context.
+@mask: a #GdkICAttributesType mask specifying which of the attributes in @attr
+are set.
+@Returns: a new #GdkIC.
-<!-- ##### ENUM GdkICAttributesType ##### -->
-<para>
+<!-- ##### FUNCTION gdk_ic_destroy ##### -->
+<para>
+Destroys the input context.
</para>
-@GDK_IC_STYLE:
-@GDK_IC_CLIENT_WINDOW:
-@GDK_IC_FOCUS_WINDOW:
-@GDK_IC_FILTER_EVENTS:
-@GDK_IC_SPOT_LOCATION:
-@GDK_IC_LINE_SPACING:
-@GDK_IC_CURSOR:
-@GDK_IC_PREEDIT_FONTSET:
-@GDK_IC_PREEDIT_AREA:
-@GDK_IC_PREEDIT_AREA_NEEDED:
-@GDK_IC_PREEDIT_FOREGROUND:
-@GDK_IC_PREEDIT_BACKGROUND:
-@GDK_IC_PREEDIT_PIXMAP:
-@GDK_IC_PREEDIT_COLORMAP:
-@GDK_IC_STATUS_FONTSET:
-@GDK_IC_STATUS_AREA:
-@GDK_IC_STATUS_AREA_NEEDED:
-@GDK_IC_STATUS_FOREGROUND:
-@GDK_IC_STATUS_BACKGROUND:
-@GDK_IC_STATUS_PIXMAP:
-@GDK_IC_STATUS_COLORMAP:
-@GDK_IC_ALL_REQ:
-@GDK_IC_PREEDIT_AREA_REQ:
-@GDK_IC_PREEDIT_POSITION_REQ:
-@GDK_IC_STATUS_AREA_REQ:
+@ic: a #GdkIC.
-<!-- ##### FUNCTION gdk_ic_new ##### -->
-<para>
+<!-- ##### FUNCTION gdk_ic_get_events ##### -->
+<para>
+Returns the mask of events that the input method needs to function properly.
+This is typically called in a widget's realize method after creating the
+#GdkIC. The returned event mask is then combined with the widget's
+own event mask and applied using gdk_window_set_events().
</para>
-@attr:
-@mask:
-@Returns:
+@ic: a #GdkIC.
+@Returns: the mask of events that the input method needs to function
+properly.
-<!-- ##### FUNCTION gdk_ic_destroy ##### -->
+<!-- ##### FUNCTION gdk_ic_get_style ##### -->
<para>
-
+Returns the pre-edit and status style of the #GdkIC.
</para>
-@ic:
+@ic: a #GdkIC.
+@Returns: the pre-edit and status style of the #GdkIC.
-<!-- ##### FUNCTION gdk_ic_get_style ##### -->
+<!-- ##### FUNCTION gdk_ic_get_attr ##### -->
<para>
-
+Gets attributes of a #GdkIC.
</para>
-@ic:
-@Returns:
+@ic: a #GdkIC.
+@attr: a #GdkICAttr struct to contain the returned attributes.
+@mask: a #GdkICAttributesType mask specifying which attributes to get.
+@Returns: a #GdkICAttributesType mask specifying which of the attributes
+were not retrieved succesfully.
<!-- ##### FUNCTION gdk_ic_set_attr ##### -->
<para>
-
+Sets attributes of the #GdkIC.
+</para>
+<para>
+Note that the GDK_IC_STYLE and GDK_IC_CLIENT_WINDOW attributes can only be set
+when creating the #GdkIC, and the GDK_IC_FILTER_EVENTS attribute is read-only.
</para>
-@ic:
-@attr:
-@mask:
-@Returns:
+@ic: a #GdkIC.
+@attr: a #GdkICAttr struct containing attributes to use for the input context.
+@mask: a #GdkICAttributesType mask specifying which of the attributes in @attr
+are set.
+@Returns: a #GdkICAttributesType mask indicating which of the attributes
+were not set successfully.
-<!-- ##### FUNCTION gdk_ic_get_attr ##### -->
+<!-- ##### STRUCT GdkICAttr ##### -->
<para>
-
+The #GdkICAttr struct is used when getting and setting attributes of the
+input context. It is used together with a #GdkICAttributesType mask which
+specifies which of the fields are being set or returned.
</para>
-@ic:
-@attr:
-@mask:
-@Returns:
-
+@style: the pre-edit and status style. This attribute is required when
+creating the #GdkIC, and cannot be changed.
+@client_window: the #GdkWindow in which the input method will display its
+pre-edit and status areas or create subwindows.
+The preedit_area and status_area attributes are specified relative to this
+window. This attribute is required when creating the #GdkIC, and cannot be
+changed.
+@focus_window: the #GdkWindow which is to be used when editing text.
+gdk_im_begin() sets this attribute before starting the text input process,
+so it is normally not necessary to set it elsewhere.
+@filter_events: the mask of events that the input method requires.
+See the gdk_ic_get_events() function. This attribute is read-only and is
+never changed.
+@spot_location: the position of the insertion cursor, for use with the
+%GDK_IM_PREEDIT_POSITION style. The y coordinate specifies the baseline of
+the text.
+@line_spacing: the line spacing to be used in the pre-edit and status areas
+when displaying multi-line text.
+@cursor: the cursor to use in the input method's windows.
+If this attribute isn't set it is determined by the input method.
+@preedit_fontset: the font to use for the pre-edit area.
+If this attribute isn't set it is determined by the input method.
+@preedit_area: the area in which the input method will display pre-editing
+data, used for the %GDK_IM_PREEDIT_POSITION and %GDK_IM_PREEDIT_AREA styles.
+@preedit_area_needed: the area that the input method requests for displaying
+pre-editing data, used for the %GDK_IM_PREEDIT_POSITION and
+%GDK_IM_PREEDIT_AREA styles.
+@preedit_foreground: the foreground color to use for the pre-edit area.
+This color must already be allocated in the preedit_colormap.
+If this attribute isn't set it is determined by the input method.
+@preedit_background: the background color to use for the pre-edit area.
+This color must already be allocated in the preedit_colormap.
+If this attribute isn't set it is determined by the input method.
+@preedit_pixmap: the background pixmap to use for the pre-edit area.
+If this attribute isn't set it is determined by the input method.
+@preedit_colormap: the colormap the input method should use to allocate colors.
+The default value is the colormap of client_window.
+@status_fontset: the font to use for the status area.
+If this attribute isn't set it is determined by the input method.
+@status_area: the are that the input method will display status information in.
+This is used for the %GDK_IM_STATUS_AREA style.
+@status_area_needed: the size that the input method requests for displaying
+status information, for the %GDK_IM_STATUS_AREA style.
+@status_foreground: the foreground color to use for the status area.
+This color must already be allocated in the status_colormap.
+If this attribute isn't set it is determined by the input method.
+@status_background: the background color to use for the status area.
+This color must already be allocated in the status_colormap.
+If this attribute isn't set it is determined by the input method.
+@status_pixmap: the background pixmap to use for the status area.
+If this attribute isn't set it is determined by the input method.
+@status_colormap: the colormap the input method should use to allocate colors.
+The default value is the colormap of client_window.
-<!-- ##### FUNCTION gdk_ic_get_events ##### -->
+<!-- ##### ENUM GdkICAttributesType ##### -->
<para>
-
+The #GdkICAttributesType contains a set of bit-flags which are used to
+specify which of the attributes in a #GdkICAttr are being set or returned.
+</para>
+<para>
+It also contains several combinations of the flags which specify required
+attributes for the various styles:
+<variablelist>
+<varlistentry>
+<term>%GDK_IC_ALL_REQ:</term>
+<listitem><para>
+the set of attributes required for all styles.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>%GDK_IC_PREEDIT_AREA_REQ:</term>
+<listitem><para>
+the set of additional attributes required for the
+%GDK_IM_PREEDIT_AREA pre-edit style.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>%GDK_IC_PREEDIT_POSITION_REQ:</term>
+<listitem><para>
+the set of additional attributes required for the
+%GDK_IM_PREEDIT_POSITION pre-edit style.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>%GDK_IC_STATUS_AREA_REQ:</term>
+<listitem><para>
+the set of additional attributes required for the
+%GDK_IM_STATUS_AREA status style.
+</para></listitem>
+</varlistentry>
+</variablelist>
</para>
-@ic:
-@Returns:
-
+@GDK_IC_STYLE:
+@GDK_IC_CLIENT_WINDOW:
+@GDK_IC_FOCUS_WINDOW:
+@GDK_IC_FILTER_EVENTS:
+@GDK_IC_SPOT_LOCATION:
+@GDK_IC_LINE_SPACING:
+@GDK_IC_CURSOR:
+@GDK_IC_PREEDIT_FONTSET:
+@GDK_IC_PREEDIT_AREA:
+@GDK_IC_PREEDIT_AREA_NEEDED:
+@GDK_IC_PREEDIT_FOREGROUND:
+@GDK_IC_PREEDIT_BACKGROUND:
+@GDK_IC_PREEDIT_PIXMAP:
+@GDK_IC_PREEDIT_COLORMAP:
+@GDK_IC_STATUS_FONTSET:
+@GDK_IC_STATUS_AREA:
+@GDK_IC_STATUS_AREA_NEEDED:
+@GDK_IC_STATUS_FOREGROUND:
+@GDK_IC_STATUS_BACKGROUND:
+@GDK_IC_STATUS_PIXMAP:
+@GDK_IC_STATUS_COLORMAP:
+@GDK_IC_ALL_REQ:
+@GDK_IC_PREEDIT_AREA_REQ:
+@GDK_IC_PREEDIT_POSITION_REQ:
+@GDK_IC_STATUS_AREA_REQ:
<!-- ##### FUNCTION gdk_ic_attr_new ##### -->
<para>
-
+Creates a new #GdkICAttr struct, with all fields set to 0.
+The #GdkICAttr struct should be freed with gdk_ic_attr_destroy() when no
+longer needed.
</para>
-@Returns:
+@Returns: a new #GdkICAttr struct.
<!-- ##### FUNCTION gdk_ic_attr_destroy ##### -->
<para>
-
+Destroys the given #GdkICAttr struct, freeing the allocated memory.
</para>
-@attr:
+@attr: a #GdkICAttr struct.
Input Methods
<!-- ##### SECTION Short_Description ##### -->
-
+support for internationalized text input.
<!-- ##### SECTION Long_Description ##### -->
<para>
+Input Methods provide a way for complex character sets to be used in GTK+.
+Languages such as Chinese, Japanese, and Korean (often abbreviated to CJK)
+use a large number of ideographs, making it impossible to support all
+characters with a simple keyboard. Instead, text is usually
+<emphasis>pre-edited</emphasis> using a phonetic alphabet and then
+<emphasis>composed</emphasis> to form the ideographs.
+</para>
+<para>
+GTK+ makes use of the input method mechanism provided by the X Windows
+platform. When a GTK+ application is started, it opens a connection to the
+input method appropriate for the current locale (if any).
+</para>
+<para>
+Widgets which handle textual input, such as #GtkEntry, need to do a number of
+things to support internationalized text input:
+<variablelist>
+<varlistentry>
+<term>When the widget is realized:</term>
+<listitem><para>Check if an input method is being used with gdk_im_ready().
+If it is, create a new <link linkend="gdk-Input-Contexts">Input Context</link>
+using gdk_ic_new(). Find out which events the
+<link linkend="gdk-Input-Contexts">Input Context</link> needs to receive
+with gdk_ic_get_events(), and make sure that the widget's window receives
+these events using gdk_window_set_events().
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>When the widget's size, state or cursor position changes:</term>
+<listitem><para>
+Update the appropriate
+<link linkend="gdk-Input-Contexts">Input Context</link> attributes
+using gdk_ic_set_attr().
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>When the keyboard focus enters or leaves the widget:</term>
+<listitem><para>
+Call gdk_im_begin() or gdk_im_end() to start or finish editing the text.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>When the widget receives a key_press event:</term>
+<listitem><para>
+The <structfield>string</structfield> and <structfield>length</structfield>
+fields of the #GdkEventKey struct should be used to insert the composed text
+into the widget.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>When the widget is unrealized:</term>
+<listitem><para>
+Destroy the <link linkend="gdk-Input-Contexts">Input Context</link>.
+</para></listitem>
+</varlistentry>
+</variablelist>
+</para>
+<para>
+See the XLib reference manual for more detailed information on input methods,
+and the #GtkEntry and #GtkText widgets for some example code.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
+<variablelist>
+<varlistentry>
+<term><link linkend="gdk-Input-Contexts">Input Contexts</link></term>
+<listitem><para>
+Used for each widget that handles internationalized text input using the
+global input method.
+</para></listitem>
+</varlistentry>
+</variablelist>
</para>
<!-- ##### ENUM GdkIMStyle ##### -->
<para>
-
+A set of bit-flags used to specify the input method styles which are supported
+or which are currently in use. The flags can be divided into 2 groups, the
+pre-edit flags and the status flags.
</para>
-
-@GDK_IM_PREEDIT_AREA:
-@GDK_IM_PREEDIT_CALLBACKS:
-@GDK_IM_PREEDIT_POSITION:
-@GDK_IM_PREEDIT_NOTHING:
-@GDK_IM_PREEDIT_NONE:
-@GDK_IM_PREEDIT_MASK:
-@GDK_IM_STATUS_AREA:
-@GDK_IM_STATUS_CALLBACKS:
-@GDK_IM_STATUS_NOTHING:
-@GDK_IM_STATUS_NONE:
-@GDK_IM_STATUS_MASK:
-
-<!-- ##### TYPEDEF GdkWChar ##### -->
<para>
-
+The pre-edit flags specify how pre-editing data is displayed.
+For example, this could display the text being typed in in the phonetic
+alphabet before it is composed and inserted as an ideograph.
</para>
-
-
-<!-- ##### FUNCTION gdk_im_ready ##### -->
<para>
-
+The status flags specify how status information is displayed.
+The status information can be thought of as an extension of the
+standard keyboard mode indicators, such as the Caps Lock indicator.
</para>
-
-@Returns:
-
-
-<!-- ##### FUNCTION gdk_im_begin ##### -->
+<note>
<para>
-
+The %GDK_IM_PREEDIT_CALLBACKS and %GDK_IM_STATUS_CALLBACKS styles are not
+currently supported in GTK+.
</para>
+</note>
+
+@GDK_IM_PREEDIT_AREA: The application provides the input method with an area
+in which to perform <emphasis>off-the-spot</emphasis> pre-editing.
+@GDK_IM_PREEDIT_CALLBACKS: The application registers a number of callback
+functions which are used to display pre-editing data.
+@GDK_IM_PREEDIT_POSITION: The application provides the input method with the
+position of the insertion cursor, for <emphasis>over-the-spot</emphasis>
+pre-editing. The input method creates its own window over the widget to
+display the pre-editing data.
+@GDK_IM_PREEDIT_NOTHING: The input method uses the root X window to perform
+pre-editing, so the application does not need to do anything.
+@GDK_IM_PREEDIT_NONE: No pre-editing is done by the input method, or no
+pre-editing data needs to be displayed.
+@GDK_IM_PREEDIT_MASK: A bit-mask containing all the pre-edit flags.
+@GDK_IM_STATUS_AREA: The application provides the input method with an area
+in which to display status information.
+@GDK_IM_STATUS_CALLBACKS: The applications registers a number of callback
+functions which are used to display status information.
+@GDK_IM_STATUS_NOTHING: The input method uses the root X window to display
+status information, so the application does not need to do anything.
+@GDK_IM_STATUS_NONE: The input method does not display status information.
+@GDK_IM_STATUS_MASK: A bit-mask containing all the status flags.
-@ic:
-@window:
-
-
-<!-- ##### FUNCTION gdk_im_end ##### -->
+<!-- ##### FUNCTION gdk_im_ready ##### -->
<para>
-
+Checks if an input method is to be used for the current locale.
+If GTK+ has been compiled without support for input methods, or the current
+locale doesn't need an input method, then this will return FALSE.
</para>
+@Returns: TRUE if an input method is available and should be used.
<!-- ##### FUNCTION gdk_im_decide_style ##### -->
<para>
-
+Decides which input method style should be used, by comparing the styles given
+in @supported_style with those of the available input method.
</para>
-@supported_style:
-@Returns:
+@supported_style: styles which are supported by the widget.
+@Returns: the best style in @supported_style that is also supported by the
+available input method.
<!-- ##### FUNCTION gdk_im_set_best_style ##### -->
<para>
-
+Sets the best pre-edit and/or status style which should be used.
+This will affect the style chosen in gdk_im_decide_style().
+</para>
+<para>
+The order of the pre-edit styles is (from worst to best):
+%GDK_IM_PREEDIT_NONE, %GDK_IM_PREEDIT_NOTHING, %GDK_IM_PREEDIT_AREA,
+%GDK_IM_PREEDIT_POSITION, %GDK_IM_PREEDIT_CALLBACKS.
+The order of the status styles is:
+%GDK_IM_STATUS_NONE, %GDK_IM_STATUS_NOTHING, %GDK_IM_STATUS_AREA,
+%GDK_IM_STATUS_CALLBACKS.
+</para>
+<para>
+So, for example, to set the best allowed pre-edit style to %GDK_IM_PREEDIT_AREA
+you would do this:
+
+<informalexample>
+<programlisting>
+ gdk_im_set_best_style (GDK_IM_PREEDIT_AREA);
+</programlisting>
+</informalexample>
+
+Or to set the best allowed pre-edit style to %GDK_IM_PREEDIT_POSITION and the
+best allowed status style to %GDK_IM_STATUS_NOTHING you can do this:
+
+<informalexample>
+<programlisting>
+ gdk_im_set_best_style (GDK_IM_PREEDIT_POSITION | GDK_IM_STATUS_NOTHING);
+</programlisting>
+</informalexample>
</para>
-@best_allowed_style:
-@Returns:
+@best_allowed_style: a bit-mask with the best pre-edit style and/or the best
+status style to use. If 0 is used, then the current bit-mask of all allowed
+styles is returned.
+@Returns: a bit-mask of all the styles allowed.
-<!-- ##### FUNCTION gdk_wcstombs ##### -->
+<!-- ##### FUNCTION gdk_im_begin ##### -->
<para>
-
+Starts editing, using the given #GdkInputContext and #GdkWindow.
+This should be called when the widget receives the input focus, typically in
+the widget's focus_in_event method.
</para>
-@src:
-@Returns:
+@ic: a #GdkInputContext.
+@window: the #GdkWindow which will be receiving the key press events.
-<!-- ##### FUNCTION gdk_mbstowcs ##### -->
+<!-- ##### FUNCTION gdk_im_end ##### -->
<para>
-
+Stops editing using the input method.
+This should be called when the widget loses the input focus, typically in
+the widget's focus_out_event method.
</para>
-@dest:
-@src:
-@dest_max:
-@Returns:
</para>
+<!-- ##### MACRO GDK_NONE ##### -->
+<para>
+
+</para>
+
+
+
<!-- ##### FUNCTION gdk_text_property_to_text_list ##### -->
<para>
Convert a text string from the encoding as it is stored in
@Returns: a new empty #GdkRegion.
-<!-- ##### FUNCTION gdk_region_destroy ##### -->
+<!-- ##### FUNCTION gdk_region_polygon ##### -->
<para>
-Destroys a #GdkRegion.
+Creates a new #GdkRegion using the polygon defined by a number of points.
+
</para>
-@region: a #GdkRegion.
+@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.
-<!-- ##### FUNCTION gdk_region_get_clipbox ##### -->
+<!-- ##### ENUM GdkFillRule ##### -->
<para>
-Returns the smallest rectangle which includes the entire #GdkRegion.
+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>
-@region: a #GdkRegion.
-@rectangle: returns the smallest rectangle which includes all of @region.
+@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.
-
-<!-- ##### FUNCTION gdk_region_empty ##### -->
+<!-- ##### FUNCTION gdk_region_destroy ##### -->
<para>
-Returns TRUE if the #GdkRegion is empty.
+Destroys a #GdkRegion.
</para>
@region: a #GdkRegion.
-@Returns: TRUE if @region is empty.
-<!-- ##### FUNCTION gdk_region_equal ##### -->
+<!-- ##### FUNCTION gdk_regions_intersect ##### -->
<para>
-Returns TRUE if the two regions are the same.
+Returns the intersection of two regions.
</para>
-@region1: a #GdkRegion.
-@region2: a #GdkRegion.
-@Returns: TRUE if @region1 and @region2 are equal.
+@source1: a #GdkRegion.
+@source2: a #GdkRegion.
+@Returns: the intersection of @source1 and @source2.
-<!-- ##### FUNCTION gdk_region_point_in ##### -->
+<!-- ##### FUNCTION gdk_regions_union ##### -->
<para>
-Returns TRUE if a point is in a region.
+Returns the union of two regions.
+This is all pixels in either of @source1 or @source2.
</para>
-@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.
+@source1: a #GdkRegion.
+@source2: a #GdkRegion.
+@Returns: the union of @source1 and @source2.
-<!-- ##### FUNCTION gdk_region_rect_in ##### -->
+<!-- ##### FUNCTION gdk_regions_subtract ##### -->
<para>
-Tests whether a rectangle is within a region.
+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>
-@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.
+@source1: a #GdkRegion.
+@source2: a #GdkRegion to subtract from @source1.
+@Returns: @source1 - @source2.
-<!-- ##### ENUM GdkOverlapType ##### -->
+<!-- ##### FUNCTION gdk_regions_xor ##### -->
<para>
-Specifies the possible values returned by gdk_region_rect_in().
+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>
-@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.
+@source1: a #GdkRegion.
+@source2: a #GdkRegion.
+@Returns: the difference between the union and the intersection of @source1
+and @source2.
-<!-- ##### FUNCTION gdk_region_polygon ##### -->
-<para>
-Creates a new #GdkRegion using the polygon defined by a number of points.
+<!-- ##### FUNCTION gdk_region_union_with_rect ##### -->
+<para>
+Returns the union of a region and a rectangle.
</para>
-@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.
+@region: a #GdkRegion.
+@rect: a #GdkRectangle.
+@Returns: the union of @region and @rect.
<!-- ##### FUNCTION gdk_region_offset ##### -->
<para>
-Moves a region.
+Moves a region the specified distance.
</para>
@region: a #GdkRegion.
<!-- ##### FUNCTION gdk_region_shrink ##### -->
<para>
-Resizes a region.
+Resizes a region by the specified amount.
+Positive values shrink the region. Negative values expand it.
</para>
@region: a #GdkRegion.
-@dx:
-@dy:
+@dx: the number of pixels to shrink the region horizontally.
+@dy: the number of pixels to shrink the region vertically.
-<!-- ##### FUNCTION gdk_region_union_with_rect ##### -->
+<!-- ##### FUNCTION gdk_region_empty ##### -->
<para>
-Returns the union of a region and a rectangle.
+Returns TRUE if the #GdkRegion is empty.
</para>
@region: a #GdkRegion.
-@rect: a #GdkRectangle.
-@Returns: the union of @region and @rect.
+@Returns: TRUE if @region is empty.
-<!-- ##### FUNCTION gdk_regions_intersect ##### -->
+<!-- ##### FUNCTION gdk_region_equal ##### -->
<para>
-Returns the intersection of two regions.
+Returns TRUE if the two regions are the same.
</para>
-@source1: a #GdkRegion.
-@source2: a #GdkRegion.
-@Returns: the intersection of @source1 and @source2.
+@region1: a #GdkRegion.
+@region2: a #GdkRegion.
+@Returns: TRUE if @region1 and @region2 are equal.
-<!-- ##### FUNCTION gdk_regions_union ##### -->
+<!-- ##### FUNCTION gdk_region_point_in ##### -->
<para>
-Returns the union of two regions.
-This is all pixels in either of @source1 or @source2.
+Returns TRUE if a point is in a region.
</para>
-@source1: a #GdkRegion.
-@source2: a #GdkRegion.
-@Returns: the union of @source1 and @source2.
+@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.
-<!-- ##### FUNCTION gdk_regions_subtract ##### -->
+<!-- ##### FUNCTION gdk_region_rect_in ##### -->
<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.
+Tests whether a rectangle is within a region.
</para>
-@source1: a #GdkRegion.
-@source2: a #GdkRegion to subtract from @source1.
-@Returns: @source1 - @source2.
+@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.
-<!-- ##### FUNCTION gdk_regions_xor ##### -->
+<!-- ##### ENUM GdkOverlapType ##### -->
<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.
+Specifies the possible values returned by gdk_region_rect_in().
</para>
-@source1: a #GdkRegion.
-@source2: a #GdkRegion.
-@Returns: the difference between the union and the intersection of @source1
-and @source2.
+@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.
+
+<!-- ##### FUNCTION gdk_region_get_clipbox ##### -->
+<para>
+Returns the smallest rectangle which includes the entire #GdkRegion.
+</para>
+
+@region: a #GdkRegion.
+@rectangle: returns the smallest rectangle which includes all of @region.
</programlisting>
</example>
-
<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
</para>
-<!-- ##### STRUCT GdkRgbCmap ##### -->
-<para>
-A private data structure which maps color indices to actual RGB
-colors. This is used only for gdk_draw_indexed_image().
-</para>
-
-
-<!-- ##### ENUM GdkRgbDither ##### -->
-<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>
-
-
<!-- ##### FUNCTION gdk_rgb_init ##### -->
<para>
Initializes GdkRgb statically. It may be called more than once with no
</para>
-<!-- ##### FUNCTION gdk_rgb_cmap_new ##### -->
-<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>
-
-@colors: The colors, represented as 0xRRGGBB integer values.
-@n_colors: The number of colors in the cmap.
-@Returns: The newly created #GdkRgbCmap
-
-
-<!-- ##### FUNCTION gdk_rgb_cmap_free ##### -->
-<para>
-Frees the memory associated with a #GdkRgbCmap created by gdk_rgb_cmap_new().
-</para>
-
-@cmap: The #GdkRgbCmap to free.
-
-
-<!-- ##### FUNCTION gdk_rgb_gc_set_foreground ##### -->
-<para>
-Sets the foreground color in @gc to the specified color (or the
-closest approximation, in the case of limited visuals).
-</para>
-
-@gc: The @GdkGC to modify.
-@rgb: The color, represented as a 0xRRGGBB integer value.
-
-
-<!-- ##### FUNCTION gdk_rgb_gc_set_background ##### -->
-<para>
-Sets the background color in @gc to the specified color (or the
-closest approximation, in the case of limited visuals).
-</para>
-
-@gc: The @GdkGC to modify.
-@rgb: The color, represented as a 0xRRGGBB integer value.
-
<!-- ##### FUNCTION gdk_draw_rgb_image ##### -->
<para>
@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.
+@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_rgb_image_dithalign ##### -->
+<para>
+Draws an RGB image in the drawable, with an adjustment for dither alignment.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+Setting the dither alignment correctly allows updating of small parts
+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_draw_indexed_image ##### -->
<para>
Draws an indexed image in the drawable, using a #GdkRgbCmap to assign
@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.
+@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.
</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.
+@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.
@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.
+@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 ##### -->
+<!-- ##### ENUM GdkRgbDither ##### -->
<para>
-Draws an RGB image in the drawable, with an adjustment for dither alignment.
+
+Selects whether or not GdkRgb applies dithering
+to the image on display. There are three values:
</para>
+<itemizedlist>
+
+<listitem>
<para>
-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.
+%GDK_RGB_DITHER_NONE: Never use dithering.
</para>
+</listitem>
+<listitem>
<para>
-Setting the dither alignment correctly allows updating of small parts
-of the screen while avoiding visible "seams" between the different
-dither textures.
+%GDK_RGB_DITHER_NORMAL: Use dithering in 8 bits per pixel (and below)
+only.
</para>
+</listitem>
-@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.
+<listitem>
+<para>
+%GDK_RGB_DITHER_MAX: Use dithering in 16 bits per pixel and below.
+</para>
+</listitem>
+</itemizedlist>
-<!-- ##### FUNCTION gdk_rgb_xpixel_from_rgb ##### -->
<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.
+Since GdkRgb currently only handles images with 8 bits per component,
+dithering on 24 bit per pixel displays is a moot point.
</para>
+@GDK_RGB_DITHER_NONE:
+@GDK_RGB_DITHER_NORMAL:
+@GDK_RGB_DITHER_MAX:
+
+<!-- ##### FUNCTION gdk_rgb_cmap_new ##### -->
+<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>
+
+@colors: The colors, represented as 0xRRGGBB integer values.
+@n_colors: The number of colors in the cmap.
+@Returns: The newly created #GdkRgbCmap
+
+
+<!-- ##### FUNCTION gdk_rgb_cmap_free ##### -->
+<para>
+Frees the memory associated with a #GdkRgbCmap created by gdk_rgb_cmap_new().
+</para>
+
+@cmap: The #GdkRgbCmap to free.
+
+
+<!-- ##### STRUCT GdkRgbCmap ##### -->
+<para>
+A private data structure which maps color indices to actual RGB
+colors. This is used only for gdk_draw_indexed_image().
+</para>
+
+@colors:
+@lut:
+
+<!-- ##### FUNCTION gdk_rgb_gc_set_foreground ##### -->
+<para>
+Sets the foreground color in @gc to the specified color (or the
+closest approximation, in the case of limited visuals).
+</para>
+
+@gc: The #GdkGC to modify.
@rgb: The color, represented as a 0xRRGGBB integer value.
-@Returns: The X pixel value.
-<!-- ##### FUNCTION gdk_rgb_set_verbose ##### -->
+<!-- ##### FUNCTION gdk_rgb_gc_set_background ##### -->
<para>
-Sets the "verbose" flag. This is generally only useful for debugging.
+Sets the background color in @gc to the specified color (or the
+closest approximation, in the case of limited visuals).
</para>
-@verbose: TRUE if verbose messages are desired.
+@gc: The #GdkGC to modify.
+@rgb: The color, represented as a 0xRRGGBB integer value.
-<!-- ##### FUNCTION gdk_rgb_ditherable ##### -->
+<!-- ##### FUNCTION gdk_rgb_xpixel_from_rgb ##### -->
<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.
+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>
-@Returns: TRUE if the visual is ditherable.
+@rgb: The color, represented as a 0xRRGGBB integer value.
+@Returns: The X pixel value.
<!-- ##### FUNCTION gdk_rgb_set_install ##### -->
colormap should be used when creating windows that will be drawn in by GdkRgb.
</para>
-@Returns: The @GdkVisual chosen by GdkRgb.
+@Returns: The #GdkVisual chosen by GdkRgb.
<!-- ##### FUNCTION gdk_rgb_get_cmap ##### -->
visual should be used when creating windows that will be drawn in by GdkRgb.
</para>
-@Returns: The @GdkColormap set by GdkRgb.
+@Returns: The #GdkColormap set by GdkRgb.
+
+
+<!-- ##### FUNCTION gdk_rgb_ditherable ##### -->
+<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>
+
+@Returns: TRUE if the visual is ditherable.
+
+
+<!-- ##### FUNCTION gdk_rgb_set_verbose ##### -->
+<para>
+Sets the "verbose" flag. This is generally only useful for debugging.
+</para>
+
+@verbose: TRUE if verbose messages are desired.
<literal>TARGETS</literal>. When a selection is
retrieved, the data is accompanied by a type
(an atom), and a format (an integer, representing
-the number of bits per item). See <xref
-linkend="gdk-Properties-and-Atoms"> for more information.
+the number of bits per item).
+See <link linkend="gdk-Properties-and-Atoms">Properties and Atoms</link>
+for more information.
</para>
<para>
The functions in this section only contain the lowlevel
@GDK_TARGET_PIXMAP: A pixmap ID.
@GDK_TARGET_STRING: A string encoded in ISO Latin-1.
(With the additional of <symbol>TAB</symbol>
- and <symbol>NEWLINE</symbol>.)
+ and <symbol>NEWLINE</symbol>.)
<!-- ##### FUNCTION gdk_selection_owner_set ##### -->
<para>
request if it did not own the selection at
the time indicated by the timestamp.
+
<!-- ##### FUNCTION gdk_selection_property_get ##### -->
<para>
Retrieve selection data that was stored by the selection
projects / ~andy / gtk / commitdiff