Skip to content

GitLab

gtk
gtk
Commit af4bb73f authored by Matthias Clasen's avatar Matthias Clasen
Browse files
Options

gdk/tmpl/windows.sgml, gdk/tmpl/general.sgml, 

        gdk/tmpl/pixmaps.sgml, gdk/tmpl/drawing.sgml,
        gdk/tmpl/gcs.sgml: Updates.
parent 0b0b2b64
Hide whitespace changes
Inline Side-by-side
Showing with 203 additions and 390 deletions
docs/reference/ChangeLog
View file @ af4bb73f
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.
......
docs/reference/gdk/tmpl/drawing.sgml
View file @ af4bb73f
......@@ -27,7 +27,9 @@ more information.
<!-- ##### 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:
......
docs/reference/gdk/tmpl/gcs.sgml
View file @ af4bb73f
......@@ -54,122 +54,26 @@ elements.
<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>
......@@ -177,24 +81,24 @@ A set of bit flags used to indicate which fields
#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>
......@@ -228,11 +132,9 @@ useful. For bitmaps, %GDK_AND and %GDK_OR are also useful.
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 ##### -->
......@@ -240,14 +142,12 @@ Create a new graphics context with default 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 ##### -->
......@@ -275,7 +175,6 @@ Identical to gdk_gc_unref(). This function is obsolete
and should not be used.
</para>
<!-- # Unused Parameters # -->
@gc: a #GdkGC.
......@@ -369,44 +268,18 @@ Set the fill mode for a graphics context.
<!-- ##### 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>
......@@ -501,29 +374,12 @@ windows of that window.
<!-- ##### 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>
......@@ -540,7 +396,7 @@ drawable. (See gdk_draw_pixmap()).
<!-- ##### 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>
......@@ -554,107 +410,39 @@ explanations of the arguments.
<!-- ##### 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>
......@@ -663,11 +451,11 @@ drawn with alternating on and off segments of the
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.
......
docs/reference/gdk/tmpl/general.sgml
View file @ af4bb73f
......@@ -19,7 +19,7 @@ utility functions.
<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
......@@ -36,7 +36,7 @@ by GTK+ applications.
<!-- ##### 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>
......@@ -50,17 +50,17 @@ by GTK+ applications.
@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>
......@@ -79,29 +79,29 @@ locale.
<!-- ##### 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
......@@ -110,7 +110,7 @@ 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.
@error_code: the error code to pass to the <function>exit()</function> call.
<!-- ##### FUNCTION gdk_get_program_class ##### -->
......@@ -134,8 +134,8 @@ Sets the 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.
......@@ -207,12 +207,12 @@ 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.
%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.
......@@ -222,38 +222,41 @@ this application are reported with respect to @window and only if selected by
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
......@@ -262,7 +265,7 @@ 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.
@Returns: %TRUE if the pointer is currently grabbed by this application.
Though this value is not always correct.
......@@ -282,14 +285,14 @@ 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
@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 ##### -->
......@@ -297,7 +300,7 @@ available.
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.
......@@ -310,7 +313,7 @@ Emits a short beep.
<!-- ##### FUNCTION gdk_get_use_xshm ##### -->
<para>