2001-11-28 Matthias Clasen <matthiasc@poet.de>
+
+ gdk/tmpl/windows.sgml, gdk/tmpl/general.sgml,
+ gdk/tmpl/pixmaps.sgml, gdk/tmpl/drawing.sgml,
+ gdk/tmpl/gcs.sgml: Updates.
* gdk/tmpl/cursors.sgml: Document GdkCursor and standard cursors.
<!-- ##### STRUCT GdkDrawable ##### -->
<para>
-
+An opaque structure representing an object that can be
+drawn onto. This can be a #GdkPixmap, a #GdkBitmap,
+or a #GdkWindow.
</para>
@user_data:
<para>
The #GdkGCValues structure holds a set of values used
to create or modify a graphics context.
+</para>
-<informaltable pgwide=1 frame="none" role="struct">
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
-<tbody>
-
-<row>
-<entry>#GdkColor foreground;</entry>
-<entry>the foreground color.</entry>
-</row>
-
-<row>
-<entry>#GdkColor background;</entry>
-<entry>the background color.</entry>
-</row>
-
-<row>
-<entry>#GdkFont *font;</entry>
-<entry>the default font..</entry>
-</row>
-
-<row>
-<entry>#GdkFunction function;</entry>
-<entry>the bitwise operation used when drawing.</entry>
-</row>
-
-<row>
-<entry>#GdkFill fill;</entry>
-<entry>the fill style.</entry>
-</row>
-
-<row>
-<entry>#GdkPixmap *tile;</entry>
-<entry>the tile pixmap.</entry>
-</row>
-
-<row>
-<entry>#GdkPixmap *stipple;</entry>
-<entry>the stipple bitmap.</entry>
-</row>
-
-<row>
-<entry>#GdkPixmap *clip_mask;</entry>
-<entry>the clip mask bitmap.</entry>
-</row>
-
-<row>
-<entry>#GdkSubwindowMode subwindow_mode;</entry>
-<entry>the subwindow mode.</entry>
-</row>
-
-<row>
-<entry>#gint ts_x_origin;</entry>
-<entry>the x origin of the tile or stipple.</entry>
-</row>
-
-<row>
-<entry>#gint ts_y_origin;</entry>
-<entry>the y origin of the tile or stipple.</entry>
-</row>
-
-<row>
-<entry>#gint clip_x_origin;</entry>
-<entry>the x origin of the clip mask.</entry>
-</row>
-
-<row>
-<entry>#gint clip_y_origin;</entry>
-<entry>the y origin of the clip mask.</entry>
-</row>
-
-<row>
-<entry>#gint graphics_exposures;</entry>
-<entry>whether graphics exposures are enabled.</entry>
-</row>
-
-<row>
-<entry>#gint line_width;</entry>
-<entry>the line width</entry>
-</row>
-
-<row>
-<entry>#GdkLineStyle line_style;</entry>
-<entry>the way dashed lines are drawn</entry>
-</row>
-
-<row>
-<entry>#GdkCapStyle cap_style;</entry>
-<entry>the way the ends of lines are drawn</entry>
-</row>
-
-<row>
-<entry>#GdkJoinStyle join_style;</entry>
-<entry>the way joins between lines are drawn</entry>
-</row>
-
-</tbody></tgroup></informaltable>
-</para>
-
-@foreground:
-@background:
-@font:
-@function:
-@fill:
-@tile:
-@stipple:
-@clip_mask:
-@subwindow_mode:
-@ts_x_origin:
-@ts_y_origin:
-@clip_x_origin:
-@clip_y_origin:
-@graphics_exposures:
-@line_width:
-@line_style:
-@cap_style:
-@join_style:
+@foreground: the foreground color.
+@background: the background color.
+@font: the default font.
+@function: the bitwise operation used when drawing.
+@fill: the fill style.
+@tile: the tile pixmap.
+@stipple: the stipple bitmap.
+@clip_mask: the clip mask bitmap.
+@subwindow_mode: the subwindow mode.
+@ts_x_origin: the x origin of the tile or stipple.
+@ts_y_origin: the y origin of the tile or stipple.
+@clip_x_origin: the x origin of the clip mask.
+@clip_y_origin: the y origin of the clip mask.
+@graphics_exposures: whether graphics exposures are enabled.
+@line_width: the line width.
+@line_style: the way dashed lines are drawn.
+@cap_style: the way the ends of lines are drawn.
+@join_style: the way joins between lines are drawn.
<!-- ##### ENUM GdkGCValuesMask ##### -->
<para>
#GdkGCValues structure are set.
</para>
-@GDK_GC_FOREGROUND:
-@GDK_GC_BACKGROUND:
-@GDK_GC_FONT:
-@GDK_GC_FUNCTION:
-@GDK_GC_FILL:
-@GDK_GC_TILE:
-@GDK_GC_STIPPLE:
-@GDK_GC_CLIP_MASK:
-@GDK_GC_SUBWINDOW:
-@GDK_GC_TS_X_ORIGIN:
-@GDK_GC_TS_Y_ORIGIN:
-@GDK_GC_CLIP_X_ORIGIN:
-@GDK_GC_CLIP_Y_ORIGIN:
-@GDK_GC_EXPOSURES:
-@GDK_GC_LINE_WIDTH:
-@GDK_GC_LINE_STYLE:
-@GDK_GC_CAP_STYLE:
-@GDK_GC_JOIN_STYLE:
+@GDK_GC_FOREGROUND: the @foreground is set.
+@GDK_GC_BACKGROUND: the @background is set.
+@GDK_GC_FONT: the @font is set.
+@GDK_GC_FUNCTION: the @function is set.
+@GDK_GC_FILL: the @fill is set.
+@GDK_GC_TILE: the @tile is set.
+@GDK_GC_STIPPLE: the @stipple is set.
+@GDK_GC_CLIP_MASK: the @clip_mask is set.
+@GDK_GC_SUBWINDOW: the @subwindow_mode is set.
+@GDK_GC_TS_X_ORIGIN: the @ts_x_origin is set.
+@GDK_GC_TS_Y_ORIGIN: the @ts_y_origin is set.
+@GDK_GC_CLIP_X_ORIGIN: the @clip_x_origin is set.
+@GDK_GC_CLIP_Y_ORIGIN: the @clip_y_origin is set.
+@GDK_GC_EXPOSURES: the @graphics_exposures is set.
+@GDK_GC_LINE_WIDTH: the @line_width is set.
+@GDK_GC_LINE_STYLE: the @line_style is set.
+@GDK_GC_CAP_STYLE: the @cap_style is set.
+@GDK_GC_JOIN_STYLE: the @join_style is set.
<!-- ##### ENUM GdkFunction ##### -->
<para>
Create a new graphics context with default values.
</para>
-@drawable:
-@Returns: the new graphics context.
-<!-- # Unused Parameters # -->
-@window: a #GdkDrawable. The created GC must always be used
+@drawable: a #GdkDrawable. The created GC must always be used
with drawables of the same depth as this one.
+@Returns: the new graphics context.
<!-- ##### FUNCTION gdk_gc_new_with_values ##### -->
Create a new GC with the given initial values.
</para>
-@drawable:
+@drawable: a #GdkDrawable. The created GC must always be used
+ with drawables of the same depth as this one.
@values: a structure containing initial values for the GC.
@values_mask: a bit mask indicating which fields in @values
are set.
@Returns: the new graphics context.
-<!-- # Unused Parameters # -->
-@window: a #GdkDrawable. The created GC must always be used
- with drawables of the same depth as this one.
<!-- ##### FUNCTION gdk_gc_ref ##### -->
and should not be used.
</para>
-<!-- # Unused Parameters # -->
@gc: a #GdkGC.
<!-- ##### 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:
+@GDK_SOLID: draw with the foreground color.
+@GDK_TILED: draw with a tiled pixmap.
+@GDK_STIPPLED: 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.
+@GDK_OPAQUE_STIPPLED: 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.
<!-- ##### FUNCTION gdk_gc_set_tile ##### -->
<para>
<!-- ##### ENUM GdkSubwindowMode ##### -->
<para>
-
Determines how drawing onto a window will affect child
windows of that window.
-
-<informaltable pgwide=1 frame="none" role="enum">
-<tgroup cols="2"><colspec colwidth="3*"><colspec colwidth="7*">
-<tbody>
-
-<row>
-<entry>GDK_CLIP_BY_CHILDREN</entry>
-<entry>only draw onto the window itself.</entry>
-</row>
-
-<row>
-<entry>GDK_INCLUDE_INFERIORS</entry>
-<entry>Draw onto the window and child windows.</entry>
-</row>
-
-</tbody></tgroup></informaltable>
</para>
-@GDK_CLIP_BY_CHILDREN:
-@GDK_INCLUDE_INFERIORS:
+@GDK_CLIP_BY_CHILDREN: only draw onto the window itself.
+@GDK_INCLUDE_INFERIORS: draw onto the window and child windows.
<!-- ##### FUNCTION gdk_gc_set_exposures ##### -->
<para>
<!-- ##### FUNCTION gdk_gc_set_line_attributes ##### -->
<para>
Sets various attributes of how lines are drawn. See
-the corresponding members of GdkGCValues for full
+the corresponding members of #GdkGCValues for full
explanations of the arguments.
</para>
<!-- ##### 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:
+@GDK_LINE_SOLID: lines are drawn solid.
+@GDK_LINE_ON_OFF_DASH: even segments are drawn; odd segments are not drawn.
+@GDK_LINE_DOUBLE_DASH: 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.
+
<!-- ##### ENUM GdkCapStyle ##### -->
<para>
Determines how the end of lines are drawn.
+</para>
-<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:
+@GDK_CAP_BUTT: the ends of the lines are drawn squared off and extending
+ to the coordinates of the end point.
+@GDK_CAP_NOT_LAST: 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.
+@GDK_CAP_ROUND: the ends of the lines are drawn as semicircles with the
+ diameter equal to the line width and centered at the end point.
+@GDK_CAP_PROJECTING: the ends of the lines are drawn squared off and extending
+ half the width of the line beyond the end point.
<!-- ##### 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:
+@GDK_JOIN_MITER: the sides of each line are extended to meet at an angle.
+@GDK_JOIN_ROUND: the sides of the two lines are joined by a circular arc.
+@GDK_JOIN_BEVEL: the sides of the two lines are joined by a straight line which
+ makes an equal angle with each line.
+
<!-- ##### FUNCTION gdk_gc_set_dashes ##### -->
<para>
lengths specified in @dash_list. The manner in
which the on and off segments are drawn is determined
by the @line_style value of the GC. (This can
-be changed with gdk_gc_set_line_attributes)
+be changed with gdk_gc_set_line_attributes())
</para>
@gc: a #GdkGC.
-@dash_offset: the
+@dash_offset: the
@dash_list: an array of dash lengths.
@n: the number of elements in @dash_list.
<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).
+terminates with a call to <literal>exit(1)</literal>.
</para>
<para>
Any arguments used by GDK are removed from the array and @argc and @argv are
<!-- ##### FUNCTION gdk_init_check ##### -->
<para>
-Initializes the GDK library and connects to the X server, returning TRUE on
+Initializes the GDK library and connects to the X server, returning %TRUE on
success.
</para>
<para>
@argc: the number of command line arguments.
@argv: the array of command line arguments.
-@Returns: TRUE if initialization succeeded.
+@Returns: %TRUE if initialization succeeded.
<!-- ##### FUNCTION gdk_set_locale ##### -->
<para>
-Initializes the support for internationalization by calling the setlocale()
+Initializes the support for internationalization by calling the <function>setlocale()</function>
system call. This function is called by gtk_set_locale() and so GTK+
applications should use that instead.
</para>
<para>
-The locale to use is determined by the LANG environment variable,
+The locale to use is determined by the <envvar>LANG</envvar> environment variable,
so to run an application in a certain locale you can do something like this:
<informalexample>
<programlisting>
<!-- ##### FUNCTION gdk_set_sm_client_id ##### -->
<para>
-Sets the SM_CLIENT_ID property on the application's leader window so that
+Sets the <literal>SM_CLIENT_ID</literal> 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>
<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
+use is for session management. The <literal>WM_CLIENT_LEADER</literal> 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
+(ICCCM) for information on the <literal>WM_CLIENT_LEADER property</literal>. (Both documents are
part of the X Windows distribution.)
</para>
@sm_client_id: the client id assigned by the session manager when the
-connection was opened, or NULL to remove the property.
+connection was opened, or %NULL to remove the property.
<!-- ##### FUNCTION gdk_exit ##### -->
<para>
-Exits the application using the exit() system call.
+Exits the application using the <function>exit()</function> system call.
</para>
<para>
This routine is provided mainly for backwards compatability, since it used to
of g_atexit()).
</para>
-@error_code: the error code to pass to the exit() call.
+@error_code: the error code to pass to the <function>exit()</function> call.
<!-- ##### FUNCTION gdk_get_program_class ##### -->
<!-- ##### 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.
+Gets the name of the display, which usually comes from the <envvar>DISPLAY</envvar>
+environment variable or the <option>--display</option> command line option.
</para>
@Returns: the name of the display.
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.
+%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
+@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.
window during the grab. If the pointer is outside @confine_to, it will
automatically be moved to the closest edge of @confine_to 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
+@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
+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.
+@Returns: %GDK_GRAB_SUCCESS if the grab was successful.
<!-- ##### ENUM GdkGrabStatus ##### -->
<para>
-
+Returned by gdk_pointer_grab() and gdk_keyboard_grab() to indicate
+success or the reason for the failure of the grab attempt.
</para>
-@GDK_GRAB_SUCCESS:
-@GDK_GRAB_ALREADY_GRABBED:
-@GDK_GRAB_INVALID_TIME:
-@GDK_GRAB_NOT_VIEWABLE:
-@GDK_GRAB_FROZEN:
+@GDK_GRAB_SUCCESS: the resource was successfully grabbed.
+@GDK_GRAB_ALREADY_GRABBED: the resource is actively grabbed by another client.
+@GDK_GRAB_INVALID_TIME: the resource was grabbed more recently than the
+ specified time.
+@GDK_GRAB_NOT_VIEWABLE: the grab window or the @confine_to window are not
+ viewable.
+@GDK_GRAB_FROZEN: the resource is frozen by an active grab of another client.
<!-- ##### 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
+@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.
+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
into account.
</para>
-@Returns: TRUE if the pointer is currently grabbed by this application.
+@Returns: %TRUE if the pointer is currently grabbed by this application.
Though this value is not always correct.
</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
+@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 always reported,
independant of the event mask set by the application.
-@time: a timestamp from a #GdkEvent, or #GDK_CURRENT_TIME if no timestamp is
+@time: a timestamp from a #GdkEvent, or %GDK_CURRENT_TIME if no timestamp is
available.
-@Returns: 0 if the grab was successful.
+@Returns: %GDK_GRAB_SUCCESS if the grab was successful.
<!-- ##### FUNCTION gdk_keyboard_ungrab ##### -->
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
+@time: a timestamp from a #GdkEvent, or %GDK_CURRENT_TIME if no timestamp is
available.
<!-- ##### FUNCTION gdk_get_use_xshm ##### -->
<para>
-Returns TRUE if GDK will attempt to use the MIT-SHM shared memory extension.
+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
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.
+@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
+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.
+@use_xshm: %TRUE if use of the MIT shared memory extension should be attempted.
<!-- ##### FUNCTION gdk_error_trap_push ##### -->
@depth: The depth (number of bits per pixel) of the new pixmap.
If -1, and @window is not %NULL, the depth of the new
pixmap will be equal to that of @window.
-@Returns: the #GdkBitmap
+@Returns: the #GdkPixmap
<!-- ##### FUNCTION gdk_bitmap_create_from_data ##### -->
Increase the reference count of a pixmap.
</para>
-@Returns: @pixmap
-<!-- # Unused Parameters # -->
@pixmap: a #GdkPixmap
+@Returns: @pixmap
<!-- ##### MACRO gdk_pixmap_unref ##### -->
reference count is zero, destroy the pixmap.
</para>
-<!-- # Unused Parameters # -->
@pixmap: a #GdkPixmap
<!-- ##### STRUCT GdkBitmap ##### -->
<para>
An opaque structure representing an offscreen drawable of depth
-1. Pointers to structures of type GdkPixmap, #GdkBitmap, and
+1. Pointers to structures of type #GdkPixmap, #GdkBitmap, and
#GdkWindow, can often be used interchangeably. The type #GdkDrawable
refers generically to any of these types.
</para>
for gdk_pixmap_ref().
</para>
-@Returns:
-<!-- # Unused Parameters # -->
-@pixmap:
+@Returns: @pixmap
+@pixmap: a #GdkBitmap
<!-- ##### MACRO gdk_bitmap_unref ##### -->
for gdk_pixmap_unref().
</para>
-<!-- # Unused Parameters # -->
-@pixmap:
+@pixmap: a #GdkBitmap
<!-- ##### STRUCT GdkWindow ##### -->
<para>
-
+An opaque structure representing an onscreen drawable.
+Pointers to structures of type #GdkPixmap, #GdkBitmap,
+and #GdkWindow, can often be used interchangeably.
+The type #GdkDrawable refers generically to any of
+these types.
</para>
@user_data: used to store the #GtkWidget associated with this window
<!-- ##### ENUM GdkGravity ##### -->
<para>
-
+Defines the reference point of a window and the meaning of coordinates
+passed to gtk_window_move(). See gtk_window_move() and the "implementation
+notes" section of the
+<ulink url="http://www.freedesktop.org/standards/wm-spec.html">extended
+window manager hints</ulink> specification for more details.
</para>
-@GDK_GRAVITY_NORTH_WEST:
-@GDK_GRAVITY_NORTH:
-@GDK_GRAVITY_NORTH_EAST:
-@GDK_GRAVITY_WEST:
-@GDK_GRAVITY_CENTER:
-@GDK_GRAVITY_EAST:
-@GDK_GRAVITY_SOUTH_WEST:
-@GDK_GRAVITY_SOUTH:
-@GDK_GRAVITY_SOUTH_EAST:
-@GDK_GRAVITY_STATIC:
+@GDK_GRAVITY_NORTH_WEST: the reference point is at the top left corner.
+@GDK_GRAVITY_NORTH: the reference point is in the middle of the top edge.
+@GDK_GRAVITY_NORTH_EAST: the reference point is at the top right corner.
+@GDK_GRAVITY_WEST: the reference point is at the middle of the left edge.
+@GDK_GRAVITY_CENTER: the reference point is at the center of the window.
+@GDK_GRAVITY_EAST: the reference point is at the middle of the right edge.
+@GDK_GRAVITY_SOUTH_WEST: the reference point is at the lower left corner.
+@GDK_GRAVITY_SOUTH: the reference point is at the middle of the lower edge.
+@GDK_GRAVITY_SOUTH_EAST: the reference point is at the lower right corner.
+@GDK_GRAVITY_STATIC: the reference point is at the top left corner of the
+ window itself, ignoring window manager decorations.
+
<!-- ##### ENUM GdkWindowEdge ##### -->
<para>
-
+Determines a window edge or corner.
</para>
-@GDK_WINDOW_EDGE_NORTH_WEST:
-@GDK_WINDOW_EDGE_NORTH:
-@GDK_WINDOW_EDGE_NORTH_EAST:
-@GDK_WINDOW_EDGE_WEST:
-@GDK_WINDOW_EDGE_EAST:
-@GDK_WINDOW_EDGE_SOUTH_WEST:
-@GDK_WINDOW_EDGE_SOUTH:
-@GDK_WINDOW_EDGE_SOUTH_EAST:
+@GDK_WINDOW_EDGE_NORTH_WEST: the top left corner.
+@GDK_WINDOW_EDGE_NORTH: the top edge.
+@GDK_WINDOW_EDGE_NORTH_EAST: the top right corner.
+@GDK_WINDOW_EDGE_WEST: the left edge.
+@GDK_WINDOW_EDGE_EAST: the right edge.
+@GDK_WINDOW_EDGE_SOUTH_WEST: the lower left corner.
+@GDK_WINDOW_EDGE_SOUTH: the lower edge.
+@GDK_WINDOW_EDGE_SOUTH_EAST: the lower right corner.
+
<!-- ##### ENUM GdkWindowTypeHint ##### -->
<para>
-
+These are hints for the window manager that indicate what type of function
+the window has. The window manager can use this when determining decoration
+and behaviour of the window. The hint must be set before mapping the window.
</para>
-@GDK_WINDOW_TYPE_HINT_NORMAL:
-@GDK_WINDOW_TYPE_HINT_DIALOG:
-@GDK_WINDOW_TYPE_HINT_MENU:
-@GDK_WINDOW_TYPE_HINT_TOOLBAR:
+@GDK_WINDOW_TYPE_HINT_NORMAL: Normal toplevel window.
+@GDK_WINDOW_TYPE_HINT_DIALOG: Dialog window.
+@GDK_WINDOW_TYPE_HINT_MENU: Window used to implement a menu.
+@GDK_WINDOW_TYPE_HINT_TOOLBAR: Window used to implement toolbars.
<!-- ##### STRUCT GdkWindowAttr ##### -->
<para>
@mask:
@x:
@y:
-<!-- # Unused Parameters # -->
-@shape_mask:
-@offset_x:
-@offset_y:
<!-- ##### FUNCTION gdk_window_shape_combine_region ##### -->
@window:
@geometry:
@geom_mask:
-<!-- # Unused Parameters # -->
-@flags:
<!-- ##### FUNCTION gdk_window_set_icon_list ##### -->
@window:
@pixbufs:
-<!-- # Unused Parameters # -->
-@Returns:
<!-- ##### FUNCTION gdk_window_set_modal_hint ##### -->
@window:
@parent:
-<!-- # Unused Parameters # -->
-@leader:
<!-- ##### FUNCTION gdk_window_set_role ##### -->
<!-- ##### ENUM GdkWMDecoration ##### -->
<para>
-
+These are hints originally defined by the Motif toolkit.
+The window manager can use them when determining how to decorate
+the window. The hint must be set before mapping the window.
</para>
-@GDK_DECOR_ALL:
-@GDK_DECOR_BORDER:
-@GDK_DECOR_RESIZEH:
-@GDK_DECOR_TITLE:
-@GDK_DECOR_MENU:
-@GDK_DECOR_MINIMIZE:
-@GDK_DECOR_MAXIMIZE:
+@GDK_DECOR_ALL: all decorations should be applied.
+@GDK_DECOR_BORDER: a frame should be drawn around the window.
+@GDK_DECOR_RESIZEH: the frame should have resize handles.
+@GDK_DECOR_TITLE: a titlebar should be placed above the window.
+@GDK_DECOR_MENU: a button for opening a menu should be included.
+@GDK_DECOR_MINIMIZE: a minimize button should be included.
+@GDK_DECOR_MAXIMIZE: a maximize button should be included.
<!-- ##### FUNCTION gdk_window_set_functions ##### -->
<para>
<!-- ##### ENUM GdkWMFunction ##### -->
<para>
-
+These are hints originally defined by the Motif toolkit.
+The window manager can use them when determining the functions
+to offer for the window.
+The hint must be set before mapping the window.
</para>
-@GDK_FUNC_ALL:
-@GDK_FUNC_RESIZE:
-@GDK_FUNC_MOVE:
-@GDK_FUNC_MINIMIZE:
-@GDK_FUNC_MAXIMIZE:
-@GDK_FUNC_CLOSE:
+@GDK_FUNC_ALL: all functions should be offered.
+@GDK_FUNC_RESIZE: the window should be resizable.
+@GDK_FUNC_MOVE: the window should be movable.
+@GDK_FUNC_MINIMIZE: the window should be minimizable.
+@GDK_FUNC_MAXIMIZE: the window should be maximizable.
+@GDK_FUNC_CLOSE: the window should be closable.
<!-- ##### FUNCTION gdk_window_get_toplevels ##### -->
<para>
<!-- ##### STRUCT GdkPointerHooks ##### -->
<para>
-
+A table of pointers to functions for getting quantities related to
+the current pointer position. GDK has one global table of this type,
+which can be set using gdk_set_pointer_hooks().
+</para>
+<para>
+This is only useful for such low-level tools as an event recorder.
+Applications should never have any reason to use this facility
</para>
-@get_pointer:
-@window_at_pointer:
+@get_pointer: Obtains the current pointer position and modifier state.
+ The position is given in coordinates relative to the window containing
+ the pointer, which is returned in @window.
+@window_at_pointer: Obtains the window underneath the mouse pointer,
+ returning the location of that window in @win_x, @win_y. Returns %NULL
+ if the window under the mouse pointer is not known to GDK (for example,
+ belongs to another application).
+
<!-- ##### FUNCTION gdk_set_pointer_hooks ##### -->
<para>
projects / ~andy / gtk / commitdiff