AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

ran make templates.

Browse Source 
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.
This commit is contained in:
Damon Chaplin 2000-02-01 04:27:56 +00:00 committed by Damon Chaplin
parent d201447174
commit 50ab749f4b
17 changed files with 1620 additions and 1081 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
docs/reference/ChangeLog
View File

@ -1,3 +1,32 @@
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.

12
docs/reference/gdk/gdk-decl.txt
View File

@ -929,7 +929,7 @@ GdkColor *color
</FUNCTION>
<FUNCTION>
<NAME>gdk_color_parse</NAME>
<RETURNS>gint </RETURNS>
<RETURNS>gboolean </RETURNS>
const gchar *spec,GdkColor *color
</FUNCTION>
<FUNCTION>
@ -949,7 +949,7 @@ GdkColormap *colormap,GdkColor *colors,gint ncolors
</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>
@ -959,22 +959,22 @@ GdkColormap *colormap,gulong *pixels,gint npixels,gulong planes
</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>

51
docs/reference/gdk/gdk-docs.sgml
View File

@ -32,28 +32,41 @@
<chapter id="gdk">
<title>GDK</title>
&gdk-General;
&gdk-Bitmaps-and-Pixmaps;
&gdk-Images;
&gdk-GdkRGB;
&gdk-Colormaps-and-Colors;
&gdk-Fonts;
&gdk-Drawing-Primitives;
&gdk-Graphics-Contexts;
&gdk-Visuals;
&gdk-Windows;
&gdk-Selections;
&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-Graphics-Contexts;
&gdk-Drawing-Primitives;
&gdk-Bitmaps-and-Pixmaps;
&gdk-GdkRGB;
&gdk-Images;
&gdk-Colormaps-and-Colors;
&gdk-Color-Contexts;
&gdk-Visuals;
&gdk-Fonts;
&gdk-Cursors;
&gdk-Windows;
&gdk-Events;
&gdk-Event-Structures;
&gdk-Cursors;
&gdk-Input;
&gdk-Selections;
&gdk-Drag-and-Drop;
&gdk-Properties-and-Atoms;
&gdk-Threads;
&gdk-Input;
&gdk-Input-Devices;
&gdk-Key-Values;
&gdk-Input-Methods;
&gdk-Input-Contexts;
</chapter>
</book>

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

@ -7,35 +7,47 @@
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
@ -65,13 +77,14 @@ gdk_bitmap_unref
<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>
@ -162,16 +175,16 @@ gdk_char_measure
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
@ -189,8 +202,10 @@ gdk_draw_text_wc
<SUBSECTION>
gdk_draw_pixmap
gdk_draw_bitmap
gdk_draw_image
<SUBSECTION Private>
gdk_draw_bitmap
</SECTION>
<SECTION>
@ -213,6 +228,7 @@ gdk_gc_set_background
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
@ -224,6 +240,9 @@ gdk_gc_set_subwindow
GdkSubwindowMode
gdk_gc_set_exposures
gdk_gc_set_line_attributes
GdkLineStyle
GdkCapStyle
GdkJoinStyle
gdk_gc_set_dashes
gdk_gc_copy
</SECTION>
@ -347,6 +366,7 @@ gdk_selection_send_notify
<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
@ -363,29 +383,29 @@ gdk_property_delete
<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_style
gdk_ic_set_attr
gdk_ic_get_attr
gdk_ic_get_events
gdk_ic_get_style
gdk_ic_get_attr
gdk_ic_set_attr
<SUBSECTION>
GdkICAttr
GdkICAttributesType
gdk_ic_attr_new
gdk_ic_attr_destroy
</SECTION>
@ -502,7 +522,10 @@ gdk_input_exit
<FILE>events</FILE>
GdkEventType
GdkEventMask
GDK_CURRENT_TIME
GDK_PRIORITY_EVENTS
<SUBSECTION>
gdk_events_pending
gdk_event_peek
gdk_event_get
@ -511,12 +534,19 @@ gdk_event_put
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>

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

@ -25,76 +25,6 @@ more information.
</para>
<!-- ##### ENUM GdkFill ##### -->
<para>
Used to specify the way in which drawing operations are performed.
See gdk_gc_set_fill().
</para>
@GDK_SOLID: graphics are drawn in a solid color, usually the foreground color
of the #GdkGC.
@GDK_TILED: graphics are drawn using a tile pixmap. See gdk_gc_set_tile().
@GDK_STIPPLED: graphics are drawn with a stipple (a pixmap with a depth of 1).
Bits set in the stipple are drawn in the foreground color. Bits not set in the
stipple are left as they are. See gdk_gc_set_stipple().
@GDK_OPAQUE_STIPPLED: graphics are drawn with a stipple, as in @GDK_STIPPLED,
except that the bits not set in the stipple are drawn in the background color
instead of being left as they are. See gdk_gc_set_stipple().
<!-- ##### ENUM GdkFillRule ##### -->
<para>
The method for determining which pixels are included in a region, when
creating a #GdkRegion from a polygon.
The fill rule is only relevant for polygons which overlap themselves.
</para>
@GDK_EVEN_ODD_RULE: areas which are overlapped an odd number of times are
included in the region, while areas overlapped an even number of times are not.
@GDK_WINDING_RULE: overlapping areas are always included.
<!-- ##### ENUM GdkLineStyle ##### -->
<para>
Used to specify how lines are drawn. See gdk_gc_set_line_attributes().
</para>
@GDK_LINE_SOLID: lines are drawn in a solid color, the foreground color.
@GDK_LINE_ON_OFF_DASH: dashed lines are drawn, with the pixels between the
dashes left as they are. The #GdkCapStyle is applied to each end of the dashes.
@GDK_LINE_DOUBLE_DASH: dashed lines are drawn, alternating between the
foreground and background colors. The %GDK_CAP_BUTT style is used where
dashes and gaps meet.
<!-- ##### 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 ##### -->
<para>
Used to specify how the the joins between lines are drawn.
See gdk_gc_set_line_attributes().
</para>
@GDK_JOIN_MITER: the ends of the lines are extended to meet at a point.
If the angle between the lines is less than 11 degrees, %GDK_JOIN_BEVEL is
used instead.
@GDK_JOIN_ROUND: the ends of the lines are rounded with a circular arc
centered on the joinpoint, with a diameter equal to the line width.
@GDK_JOIN_BEVEL: the lines have %GDK_CAP_BUTT cap styles, with the triangular
notch filled.
<!-- ##### FUNCTION gdk_draw_point ##### -->
<para>
Draws a point, using the foreground color and other attributes of the #GdkGC.
@ -106,6 +36,18 @@ Draws a point, using the foreground color and other attributes of the #GdkGC.
@y: the y coordinate of the point.
<!-- ##### 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_line ##### -->
<para>
Draws a line, using the foreground color and other attributes of the #GdkGC.
@ -119,6 +61,44 @@ Draws a line, using the foreground color and other attributes of the #GdkGC.
@y2: the y coordinate of the end point.
<!-- ##### FUNCTION gdk_draw_lines ##### -->
<para>
Draws a series of lines connecting the given points.
The way in which joins between lines are draw is determined by the
#GdkCapStyle value in the #GdkGC. This can be set with
gdk_gc_set_line_attributes().
</para>
@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
@gc: a #GdkGC.
@points: an array of #GdkPoint structures specifying the endpoints of the
lines.
@npoints: the size of the @points array.
<!-- ##### FUNCTION gdk_draw_segments ##### -->
<para>
Draws a number of unconnected lines.
</para>
@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
@gc: a #GdkGC.
@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.
<!-- ##### STRUCT GdkSegment ##### -->
<para>
Specifies the start and end point of a line for use by the gdk_draw_segments()
function.
</para>
@x1: the x coordinate of the start point.
@y1: the y coordinate of the start point.
@x2: the x coordinate of the end point.
@y2: the y coordinate of the end point.
<!-- ##### FUNCTION gdk_draw_rectangle ##### -->
<para>
Draws a rectangular outline or filled rectangle, using the foreground color
@ -238,83 +218,22 @@ the right edge of the source pixmap.
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.
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.
@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().
</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.

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

@ -232,6 +232,14 @@ as graphics tablets. It defaults to 0.5.
@time:
@state:
<!-- ##### ENUM GdkPropertyState ##### -->
<para>
</para>
@GDK_PROPERTY_NEW_VALUE:
@GDK_PROPERTY_DELETE:
<!-- ##### STRUCT GdkEventSelection ##### -->
<para>

268
docs/reference/gdk/tmpl/events.sgml
View File

@ -2,59 +2,102 @@
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:
@ -77,109 +120,186 @@ Events
@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.
<!-- ##### 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>
@func:
@data:
@notify:
<!-- ##### FUNCTION gdk_event_send_client_message ##### -->
<para>
Note that GTK+ uses this to install its own event handler, so it is probably
not useful for GTK+ applications.
</para>
@event:
@xid:
@Returns:
@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>
@event:
@data:
@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: the #GdkEvent to send, which should be a #GdkEventClient.
@xid: the window to send the X ClientMessage event to.
@Returns: non-zero on success.
<!-- ##### 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:
@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>
@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_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>
@show_events: TRUE to output event debugging information.

62
docs/reference/gdk/tmpl/fonts.sgml
View File

@ -579,3 +579,65 @@ relation to the baseline. See gdk_text_extents().
@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.

296
docs/reference/gdk/tmpl/gcs.sgml
View File

@ -185,48 +185,6 @@ A set of bit flags used to indicate which fields
@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
@ -253,111 +211,6 @@ useful. For bitmaps, %GDK_AND and %GDK_OR are also useful.
@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.
@ -468,6 +321,48 @@ Set the fill mode for a graphics context.
@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.
@ -611,6 +506,111 @@ explanations of the arguments.
@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
@ -635,3 +635,5 @@ onto another graphics context.
@dst_gc: the destination graphics context.
@src_gc: the source graphics context.

421
docs/reference/gdk/tmpl/general.sgml
View File

@ -2,11 +2,12 @@
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 ##### -->
@ -16,250 +17,330 @@ General
<!-- ##### 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>
<para>
Any arguments used by GDK are removed from the array and @argc and @argv are
updated accordingly.
</para>
<para>
GTK+ initializes GDK in gtk_init() and so this function is not usually needed
by GTK+ applications.
</para>
@argc:
@argv:
@argc: the number of command line arguments.
@argv: the array of command line arguments.
<!-- ##### FUNCTION gdk_init_check ##### -->
<para>
Initializes the GDK library and connects to the X server, returning TRUE on
success.
</para>
<para>
Any arguments used by GDK are removed from the array and @argc and @argv are
updated accordingly.
</para>
<para>
GTK+ initializes GDK in gtk_init() and so this function is not usually needed
by GTK+ applications.
</para>
@argc:
@argv:
@Returns:
@argc: the number of command line arguments.
@argv: the array of command line arguments.
@Returns: TRUE if initialization succeeded.
<!-- ##### FUNCTION gdk_exit ##### -->
<para>
Exits the application using the exit() system call.
</para>
@error_code:
<!-- ##### ENUM GdkStatus ##### -->
<para>
</para>
@GDK_OK:
@GDK_ERROR:
@GDK_ERROR_PARAM:
@GDK_ERROR_FILE:
@GDK_ERROR_MEM:
<!-- ##### MACRO GDK_NONE ##### -->
<para>
</para>
<!-- ##### MACRO GDK_CURRENT_TIME ##### -->
<para>
</para>
<!-- ##### MACRO GDK_PRIORITY_EVENTS ##### -->
<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>
@error_code: the error code to pass to the exit() call.
<!-- ##### 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_get_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>
@Returns:
<!-- ##### FUNCTION gdk_set_show_events ##### -->
<para>
If the locale is not supported by X then it is reset to the standard "C"
locale.
</para>
@show_events:
<!-- ##### FUNCTION gdk_add_client_message_filter ##### -->
<para>
</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>
@Returns:
<!-- ##### FUNCTION gdk_set_use_xshm ##### -->
<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>
@use_xshm:
@sm_client_id: the client id assigned by the session manager when the
connection was opened, or NULL to remove the property.
<!-- ##### 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>
@Returns:
<!-- ##### FUNCTION gdk_screen_width ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION gdk_screen_height ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION gdk_screen_width_mm ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION gdk_screen_height_mm ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION gdk_pointer_grab ##### -->
<para>
</para>
@window:
@owner_events:
@event_mask:
@confine_to:
@cursor:
@time:
@Returns:
<!-- ##### FUNCTION gdk_pointer_ungrab ##### -->
<para>
</para>
@time:
<!-- ##### FUNCTION gdk_keyboard_grab ##### -->
<para>
</para>
@window:
@owner_events:
@time:
@Returns:
<!-- ##### FUNCTION gdk_keyboard_ungrab ##### -->
<para>
</para>
@time:
<!-- ##### FUNCTION gdk_pointer_is_grabbed ##### -->
<para>
</para>
@Returns:
@Returns: the name of the 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>
<!-- ##### FUNCTION gdk_beep ##### -->
<!-- ##### FUNCTION gdk_screen_width ##### -->
<para>
Returns the width of the screen in pixels.
</para>
@Returns: the width of the screen in pixels.
<!-- ##### FUNCTION gdk_screen_height ##### -->
<para>
Returns the height of the screen in pixels.
</para>
@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: 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: 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>
@time: a timestamp from a #GdkEvent, or #GDK_CURRENT_TIME if no timestamp is
available.
<!-- ##### 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>
@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: 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: a timestamp from a #GdkEvent, or #GDK_CURRENT_TIME if no timestamp is
available.
<!-- ##### 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>
<!-- ##### 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_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_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.

189
docs/reference/gdk/tmpl/images.sgml
View File

@ -2,106 +2,155 @@
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:
<!-- ##### ENUM GdkImageType ##### -->
<para>
</para>
@GDK_IMAGE_NORMAL:
@GDK_IMAGE_SHARED:
@GDK_IMAGE_FASTEST:
<!-- ##### FUNCTION gdk_image_new_bitmap ##### -->
<para>
</para>
@visual:
@data:
@width:
@height:
@Returns:
@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.
<!-- ##### FUNCTION gdk_image_new ##### -->
<para>
Creates a new #GdkImage.
</para>
@type:
@visual:
@width:
@height:
@Returns:
@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.
<!-- ##### ENUM GdkImageType ##### -->
<para>
Specifies the type of a #GdkImage.
</para>
@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_bitmap ##### -->
<para>
Creates a new #GdkImage with a depth of 1 from the given data.
</para>
@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:
<!-- ##### FUNCTION gdk_image_put_pixel ##### -->
<para>
</para>
@image:
@x:
@y:
@pixel:
<!-- ##### FUNCTION gdk_image_get_pixel ##### -->
<para>
</para>
@image:
@x:
@y:
@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_destroy ##### -->
<para>
Destroys a #GdkImage, freeing any resources allocated for it.
</para>
@image:
@image: a #GdkImage.
<!-- ##### FUNCTION gdk_image_put_pixel ##### -->
<para>
Sets a pixel in a #GdkImage to a given pixel value.
</para>
@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_get_pixel ##### -->
<para>
Gets a pixel value at a specified position in a #GdkImage.
</para>
@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.

263
docs/reference/gdk/tmpl/input_contexts.sgml
View File

@ -2,11 +2,14 @@
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 ##### -->
@ -16,40 +19,182 @@ Input Contexts
<!-- ##### 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>
<!-- ##### FUNCTION gdk_ic_new ##### -->
<para>
Creates a new #GdkIC using the given attributes.
</para>
@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.
<!-- ##### FUNCTION gdk_ic_destroy ##### -->
<para>
Destroys the input context.
</para>
@ic: a #GdkIC.
<!-- ##### 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>
@ic: a #GdkIC.
@Returns: the mask of events that the input method needs to function
properly.
<!-- ##### FUNCTION gdk_ic_get_style ##### -->
<para>
Returns the pre-edit and status style of the #GdkIC.
</para>
@ic: a #GdkIC.
@Returns: the pre-edit and status style of the #GdkIC.
<!-- ##### FUNCTION gdk_ic_get_attr ##### -->
<para>
Gets attributes of a #GdkIC.
</para>
@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: 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.
<!-- ##### 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>
@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:
@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.
<!-- ##### 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>
@GDK_IC_STYLE:
@ -78,77 +223,21 @@ Input Contexts
@GDK_IC_PREEDIT_POSITION_REQ:
@GDK_IC_STATUS_AREA_REQ:
<!-- ##### FUNCTION gdk_ic_new ##### -->
<para>
</para>
@attr:
@mask:
@Returns:
<!-- ##### FUNCTION gdk_ic_destroy ##### -->
<para>
</para>
@ic:
<!-- ##### FUNCTION gdk_ic_get_style ##### -->
<para>
</para>
@ic:
@Returns:
<!-- ##### FUNCTION gdk_ic_set_attr ##### -->
<para>
</para>
@ic:
@attr:
@mask:
@Returns:
<!-- ##### FUNCTION gdk_ic_get_attr ##### -->
<para>
</para>
@ic:
@attr:
@mask:
@Returns:
<!-- ##### FUNCTION gdk_ic_get_events ##### -->
<para>
</para>
@ic:
@Returns:
<!-- ##### 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.

224
docs/reference/gdk/tmpl/input_methods.sgml
View File

@ -2,100 +2,212 @@
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>
<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>
<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.
<!-- ##### FUNCTION gdk_im_ready ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION gdk_im_begin ##### -->
<para>
</para>
@ic:
@window:
<!-- ##### FUNCTION gdk_im_end ##### -->
<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>
@best_allowed_style:
@Returns:
<!-- ##### FUNCTION gdk_wcstombs ##### -->
<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>
@src:
@Returns:
<!-- ##### FUNCTION gdk_mbstowcs ##### -->
<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: 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_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>
@ic: a #GdkInputContext.
@window: the #GdkWindow which will be receiving the key press events.
<!-- ##### 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:

7
docs/reference/gdk/tmpl/properties.sgml
View File

@ -49,6 +49,13 @@ of strings on the X server.
</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

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

@ -88,6 +88,30 @@ Creates a new empty #GdkRegion.
@Returns: a new empty #GdkRegion.
<!-- ##### FUNCTION gdk_region_polygon ##### -->
<para>
Creates a new #GdkRegion using the polygon defined by a number of points.
</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.
<!-- ##### ENUM GdkFillRule ##### -->
<para>
The method for determining which pixels are included in a region, when
creating a #GdkRegion from a polygon.
The fill rule is only relevant for polygons which overlap themselves.
</para>
@GDK_EVEN_ODD_RULE: areas which are overlapped an odd number of times are
included in the region, while areas overlapped an even number of times are not.
@GDK_WINDING_RULE: overlapping areas are always included.
<!-- ##### FUNCTION gdk_region_destroy ##### -->
<para>
Destroys a #GdkRegion.
@ -96,13 +120,81 @@ Destroys a #GdkRegion.
@region: a #GdkRegion.
<!-- ##### FUNCTION gdk_region_get_clipbox ##### -->
<!-- ##### FUNCTION gdk_regions_intersect ##### -->
<para>
Returns the smallest rectangle which includes the entire #GdkRegion.
Returns the intersection of two regions.
</para>
@source1: a #GdkRegion.
@source2: a #GdkRegion.
@Returns: the intersection of @source1 and @source2.
<!-- ##### FUNCTION gdk_regions_union ##### -->
<para>
Returns the union of two regions.
This is all pixels in either of @source1 or @source2.
</para>
@source1: a #GdkRegion.
@source2: a #GdkRegion.
@Returns: the union of @source1 and @source2.
<!-- ##### FUNCTION gdk_regions_subtract ##### -->
<para>
Subtracts one region from another.
The result is a region containing all the pixels which are in @source1, but
which are not in @source2.
</para>
@source1: a #GdkRegion.
@source2: a #GdkRegion to subtract from @source1.
@Returns: @source1 - @source2.
<!-- ##### FUNCTION gdk_regions_xor ##### -->
<para>
Returns the difference between the union and the intersection of two regions.
This is a region containing the pixels that are in one of the source regions,
but which are not in both.
</para>
@source1: a #GdkRegion.
@source2: a #GdkRegion.
@Returns: the difference between the union and the intersection of @source1
and @source2.
<!-- ##### FUNCTION gdk_region_union_with_rect ##### -->
<para>
Returns the union of a region and a rectangle.
</para>
@region: a #GdkRegion.
@rectangle: returns the smallest rectangle which includes all of @region.
@rect: a #GdkRectangle.
@Returns: the union of @region and @rect.
<!-- ##### FUNCTION gdk_region_offset ##### -->
<para>
Moves a region the specified distance.
</para>
@region: a #GdkRegion.
@dx: the distance to move the region horizontally.
@dy: the distance to move the region vertically.
<!-- ##### FUNCTION gdk_region_shrink ##### -->
<para>
Resizes a region by the specified amount.
Positive values shrink the region. Negative values expand it.
</para>
@region: a #GdkRegion.
@dx: the number of pixels to shrink the region horizontally.
@dy: the number of pixels to shrink the region vertically.
<!-- ##### FUNCTION gdk_region_empty ##### -->
@ -156,92 +248,12 @@ Specifies the possible values returned by gdk_region_rect_in().
@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_polygon ##### -->
<!-- ##### FUNCTION gdk_region_get_clipbox ##### -->
<para>
Creates a new #GdkRegion using the polygon defined by a number of points.
</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.
<!-- ##### FUNCTION gdk_region_offset ##### -->
<para>
Moves a region.
Returns the smallest rectangle which includes the entire #GdkRegion.
</para>
@region: a #GdkRegion.
@dx: the distance to move the region horizontally.
@dy: the distance to move the region vertically.
<!-- ##### FUNCTION gdk_region_shrink ##### -->
<para>
Resizes a region.
</para>
@region: a #GdkRegion.
@dx:
@dy:
<!-- ##### FUNCTION gdk_region_union_with_rect ##### -->
<para>
Returns the union of a region and a rectangle.
</para>
@region: a #GdkRegion.
@rect: a #GdkRectangle.
@Returns: the union of @region and @rect.
<!-- ##### FUNCTION gdk_regions_intersect ##### -->
<para>
Returns the intersection of two regions.
</para>
@source1: a #GdkRegion.
@source2: a #GdkRegion.
@Returns: the intersection of @source1 and @source2.
<!-- ##### FUNCTION gdk_regions_union ##### -->
<para>
Returns the union of two regions.
This is all pixels in either of @source1 or @source2.
</para>
@source1: a #GdkRegion.
@source2: a #GdkRegion.
@Returns: the union of @source1 and @source2.
<!-- ##### FUNCTION gdk_regions_subtract ##### -->
<para>
Subtracts one region from another.
The result is a region containing all the pixels which are in @source1, but
which are not in @source2.
</para>
@source1: a #GdkRegion.
@source2: a #GdkRegion to subtract from @source1.
@Returns: @source1 - @source2.
<!-- ##### FUNCTION gdk_regions_xor ##### -->
<para>
Returns the difference between the union and the intersection of two regions.
This is a region containing the pixels that are in one of the source regions,
but which are not in both.
</para>
@source1: a #GdkRegion.
@source2: a #GdkRegion.
@Returns: the difference between the union and the intersection of @source1
and @source2.
@rectangle: returns the smallest rectangle which includes all of @region.

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

@ -125,7 +125,6 @@ on_darea_expose (GtkWidget *widget,
</programlisting>
</example>
<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
@ -140,49 +139,6 @@ colors.</para></listitem>
</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
@ -199,46 +155,6 @@ the chosen visual and colormap, respectively.
</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>
@ -276,6 +192,39 @@ contents are ignored).
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
@ -301,7 +250,6 @@ Draws a grayscale image in the drawable.
</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.
@ -340,37 +288,93 @@ memory bandwidth.
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>
%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>
Setting the dither alignment correctly allows updating of small parts
of the screen while avoiding visible "seams" between the different
dither textures.
Since GdkRgb currently only handles images with 8 bits per component,
dithering on 24 bit per pixel displays is a moot point.
</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.
@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.
<!-- ##### 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_rgb_xpixel_from_rgb ##### -->
@ -384,25 +388,6 @@ a #GdkColor struct.
@Returns: The X pixel value.
<!-- ##### 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.
<!-- ##### 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_install ##### -->
<para>
If @install is TRUE, directs GdkRgb to always install a new "private"
@ -436,7 +421,7 @@ Gets the visual chosen by GdkRgb. This visual and the corresponding
colormap should be used when creating windows that will be drawn in by GdkRgb.
</para>
@Returns: The @GdkVisual chosen by GdkRgb.
@Returns: The #GdkVisual chosen by GdkRgb.
<!-- ##### FUNCTION gdk_rgb_get_cmap ##### -->
@ -445,6 +430,25 @@ Gets the colormap set by GdkRgb. This colormap and the corresponding
visual should be used when creating windows that will be drawn in by GdkRgb.
</para>
@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.

6
docs/reference/gdk/tmpl/selections.sgml
View File

@ -25,8 +25,9 @@ can be retrieved by requesting the special target
<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
@ -148,6 +149,7 @@ form.
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