Added section. (Written a while ago but fell through the cracks)

Thu Aug 19 14:43:08 1999  Owen Taylor  <otaylor@redhat.com>

	* gdk/tmpl/gcs.sgml gdk/gdk-sections.txt: Added section.
	  (Written a while ago but fell through the cracks)

	* gtk/gtk-docs.sgml: Add a &hash; entity here as a
	  temporary hack. (There is no standard entity
	  for '#', and no way of escaping '#' in gtk-doc)

	* gtk/tmpl/gtkrc.sgml: Use the above to fix up #rrggbb
	  string literals.

	* gtk/tmpl/gtkdrawingarea.sgml: Fixed a couple
	  of errors in the example. (pointed out by
	  Nick Lamb)

5 files changed, 428 insertions, 87 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index d30e9d31db..d638e36f4b 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,19 @@
+Thu Aug 19 14:43:08 1999  Owen Taylor  <otaylor@redhat.com>
+
+	* gdk/tmpl/gcs.sgml gdk/gdk-sections.txt: Added section. 
+	  (Written a while ago but fell through the cracks)
+
+	* gtk/gtk-docs.sgml: Add a &hash; entity here as a
+	  temporary hack. (There is no standard entity
+	  for '#', and no way of escaping '#' in gtk-doc)
+
+	* gtk/tmpl/gtkrc.sgml: Use the above to fix up #rrggbb
+	  string literals.
+
+	* gtk/tmpl/gtkdrawingarea.sgml: Fixed a couple
+	  of errors in the example. (pointed out by
+	  Nick Lamb)
+
 Mon Aug 16 6:60:53 1999  Owen Taylor  <otaylor@redhat.com>
 
 	* gdk/tmpl/properties.sgml
diff --git a/docs/reference/gdk/tmpl/gcs.sgml b/docs/reference/gdk/tmpl/gcs.sgml
index 101e3a3058..e8da61fbc0 100644
--- a/docs/reference/gdk/tmpl/gcs.sgml
+++ b/docs/reference/gdk/tmpl/gcs.sgml
@@ -2,11 +2,27 @@
 Graphics Contexts
 
 <!-- ##### SECTION Short_Description ##### -->
-
+objects to encapsulate drawing properties.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+All drawing operations in GDK take a 
+<firstterm>graphics context</firstterm> (GC) argument. 
+A graphics context encapsulates information about
+the way things are drawn, such as the foreground
+color or line width. By using graphics contexts, 
+the number of arguments to each drawing call is
+greatly reduced, and communication overhead is
+minimized, since identical arguments do not need
+to be passed repeatedly.
+</para>
+<para>
+Most values of a graphics context can be set at
+creation time by using gdk_gc_new_with_values(),
+or can be set one-by-one using functions such
+as gdk_gc_set_foreground(). A few of the values
+in the GC, such as the dash pattern, can only
+be set by the latter method.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -16,14 +32,113 @@ Graphics Contexts
 
 <!-- ##### STRUCT GdkGC ##### -->
 <para>
-
+The #GdkGC structure represents a graphics context.
+It is an opaque structure with no user-visible
+elements.
 </para>
 
 @dummy_var: 
 
 <!-- ##### STRUCT GdkGCValues ##### -->
 <para>
-
+The #GdkGCValues structure holds a set of values used
+to create or modify a graphics context.
+
+<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: 
@@ -47,7 +162,8 @@ Graphics Contexts
 
 <!-- ##### ENUM GdkGCValuesMask ##### -->
 <para>
-
+A set of bit flags used to indicate which fields
+#GdkGCValues structure are set.
 </para>
 
 @GDK_GC_FOREGROUND: 
@@ -69,9 +185,56 @@ Graphics Contexts
 @GDK_GC_CAP_STYLE: 
 @GDK_GC_JOIN_STYLE: 
 
-<!-- ##### ENUM GdkFunction ##### -->
+<!-- ##### 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
+the bit values for destination pixels to produce the final result. The
+sixteen values here correspond to the 16 different possible 2x2 truth
+tables.  Only a couple of these values are usually useful; for colored
+images, only %GDK_COPY, %GDK_XOR and %GDK_INVERT are generally
+useful. For bitmaps, %GDK_AND and %GDK_OR are also useful.
 </para>
 
 @GDK_COPY: 
@@ -90,182 +253,333 @@ Graphics Contexts
 @GDK_NAND: 
 @GDK_SET: 
 
-<!-- ##### FUNCTION gdk_gc_new ##### -->
+<!-- ##### 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>
 
-@window: 
-@Returns: 
+@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.
 
-<!-- ##### FUNCTION gdk_gc_new_with_values ##### -->
+<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. 
+</para>
+
+@window: 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 ##### -->
+<para>
+Create a new GC with the given initial values.
 </para>
 
-@window: 
-@values: 
-@values_mask: 
-@Returns: 
+@window: 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.
 
 
 <!-- ##### FUNCTION gdk_gc_ref ##### -->
 <para>
-
+Increase the reference count on a graphics context.
 </para>
 
-@gc: 
-@Returns: 
+@gc: a #GdkGC.
+@Returns: @gc.
 
 
 <!-- ##### FUNCTION gdk_gc_unref ##### -->
 <para>
-
+Decrease the reference count on a graphics context. If
+the resulting reference count is zero, the graphics
+context will be destroyed.
 </para>
 
-@gc: 
+@gc: a #GdkGC.
 
 
 <!-- ##### FUNCTION gdk_gc_destroy ##### -->
 <para>
-
+Identical to gdk_gc_unref(). This function is obsolete
+and should not be used.
 </para>
 
-@gc: 
+@gc: a #GdkGC.
 
 
 <!-- ##### FUNCTION gdk_gc_get_values ##### -->
 <para>
-
+Retrieves the current values from a graphics context.
 </para>
 
-@gc: 
-@values: 
+@gc: a #GdkGC.
+@values: the #GdkGCValues structure in which to store the results.
 
 
 <!-- ##### FUNCTION gdk_gc_set_foreground ##### -->
 <para>
-
+Sets the foreground color for a graphics context.
 </para>
 
-@gc: 
-@color: 
+@gc: a #GdkGC.
+@color: the new foreground color.
 
 
 <!-- ##### FUNCTION gdk_gc_set_background ##### -->
 <para>
-
+Sets the background color for a graphics context.
 </para>
 
-@gc: 
-@color: 
+@gc: a #GdkGC.
+@color: the new background color.
 
 
 <!-- ##### FUNCTION gdk_gc_set_font ##### -->
 <para>
-
+Sets the font for a graphics context. (Note that
+all text-drawing functions in GDK take a @font
+argument; the value set here is used when that
+argument is %NULL.)
 </para>
 
-@gc: 
-@font: 
+@gc: a #GdkGC.
+@font: the new font.
 
 
 <!-- ##### FUNCTION gdk_gc_set_function ##### -->
 <para>
-
+Determines how the current pixel values and the
+pixel values being drawn are combined to produce
+the final pixel values.
 </para>
 
-@gc: 
+@gc: a #GdkGC.
 @function: 
 
 
 <!-- ##### FUNCTION gdk_gc_set_fill ##### -->
 <para>
-
+Set the fill mode for a graphics context.
 </para>
 
-@gc: 
-@fill: 
+@gc: a #GdkGC.
+@fill: the new fill mode.
 
 
 <!-- ##### FUNCTION gdk_gc_set_tile ##### -->
 <para>
-
+Set a tile pixmap for a graphics context.
+This will only be used if the fill mode
+is %GDK_TILED.
 </para>
 
-@gc: 
-@tile: 
+@gc: a #GdkGC.
+@tile: the new tile pixmap.
 
 
 <!-- ##### FUNCTION gdk_gc_set_stipple ##### -->
 <para>
-
+Set the stipple bitmap for a graphics context. The
+stipple will only be used if the fill mode is
+%GDK_STIPPLED or %GDK_OPAQUE_STIPPLED.
 </para>
 
-@gc: 
-@stipple: 
+@gc: a #GdkGC.
+@stipple: the new stipple bitmap.
 
 
 <!-- ##### FUNCTION gdk_gc_set_ts_origin ##### -->
 <para>
-
+Set the origin when using tiles or stipples with
+the GC. The tile or stipple will be aligned such
+that the upper left corner of the tile or stipple
+will coincide with this point.
 </para>
 
-@gc: 
-@x: 
-@y: 
+@gc: a #GdkGC.
+@x: the x-coordinate of the origin.
+@y: the y-coordinate of the origin.
 
 
 <!-- ##### FUNCTION gdk_gc_set_clip_origin ##### -->
 <para>
-
+Sets the origin of the clip mask. The coordinates are
+interpreted relative to the upper-left corner of
+the destination drawable of the current operation.
 </para>
 
-@gc: 
-@x: 
-@y: 
+@gc: a #GdkGC.
+@x: the x-coordinate of the origin.
+@y: the y-coordinate of the origin.
 
 
 <!-- ##### FUNCTION gdk_gc_set_clip_mask ##### -->
 <para>
-
+Sets the clip mask for a graphics context from a bitmap.
+The clip mask is interpreted relative to the clip
+origin. (See gdk_gc_set_clip_origin()).
 </para>
 
-@gc: 
-@mask: 
+@gc: the #GdkGC.
+@mask: a bitmap.
 
 
 <!-- ##### FUNCTION gdk_gc_set_clip_rectangle ##### -->
 <para>
+Sets the clip mask for a graphics context from a
+rectangle. The clip mask is interpreted relative to the clip
+origin. (See gdk_gc_set_clip_origin()).
 
 </para>
 
-@gc: 
-@rectangle: 
+@gc: a #GdkGC.
+@rectangle: the rectangle to clip to.
 
 
 <!-- ##### FUNCTION gdk_gc_set_clip_region ##### -->
 <para>
-
+Sets the clip mask for a graphics context from a region structure.
+The clip mask is interpreted relative to the clip origin. (See
+gdk_gc_set_clip_origin()).
 </para>
 
-@gc: 
-@region: 
+@gc: a #GdkGC.
+@region: the #GdkRegion.
 
 
 <!-- ##### FUNCTION gdk_gc_set_subwindow ##### -->
 <para>
-
+Sets how drawing with this GC on a window will affect child
+windows of that window. 
 </para>
 
-@gc: 
-@mode: 
+@gc: a #GdkGC.
+@mode: the subwindow mode.
 
 
 <!-- ##### 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: 
@@ -273,42 +587,51 @@ Graphics Contexts
 
 <!-- ##### FUNCTION gdk_gc_set_exposures ##### -->
 <para>
-
+Sets whether copying non-visible portions of a drawable
+using this graphics context generate exposure events
+for the corresponding regions of the destination
+drawable. (See gdk_draw_pixmap()).
 </para>
 
-@gc: 
-@exposures: 
+@gc: a #GdkGC.
+@exposures: if %TRUE, exposure events will be generated.
 
 
 <!-- ##### FUNCTION gdk_gc_set_line_attributes ##### -->
 <para>
-
+Sets various attributes of how lines are drawn. See
+the corresponding members of GdkGCValues for full
+explanations of the arguments.
 </para>
 
-@gc: 
-@line_width: 
-@line_style: 
-@cap_style: 
-@join_style: 
+@gc: a #GdkGC.
+@line_width: the width of lines.
+@line_style: the dash-style for lines.
+@cap_style: the manner in which the ends of lines are drawn.
+@join_style: the in which lines are joined together.
 
 
 <!-- ##### FUNCTION gdk_gc_set_dashes ##### -->
 <para>
-
+Sets the way dashed-lines are drawn. Lines will be
+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)
 </para>
 
-@gc: 
-@dash_offset: 
-@dash_list: 
-@n: 
+@gc: a #GdkGC.
+@dash_offset: the
+@dash_list: an array of dash lengths.
+@n: the number of elements in @dash_list.
 
 
 <!-- ##### FUNCTION gdk_gc_copy ##### -->
 <para>
-
+Copy the set of values from one graphics context
+onto another graphics context.
 </para>
 
-@dst_gc: 
-@src_gc: 
-
-
+@dst_gc: the destination graphics context.
+@src_gc: the source graphics context.
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index b1586642c9..97afce3121 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -1,4 +1,5 @@
 <!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
+<!entity hash "#">
 <!entity GtkAccelLabel SYSTEM "sgml/gtkaccellabel.sgml">
 <!entity GtkAdjustment SYSTEM "sgml/gtkadjustment.sgml">
 <!entity GtkAlignment SYSTEM "sgml/gtkalignment.sgml">
diff --git a/docs/reference/gtk/tmpl/gtkdrawingarea.sgml b/docs/reference/gtk/tmpl/gtkdrawingarea.sgml
index b78eae267d..cc9800dec9 100644
--- a/docs/reference/gtk/tmpl/gtkdrawingarea.sgml
+++ b/docs/reference/gtk/tmpl/gtkdrawingarea.sgml
@@ -60,9 +60,10 @@ expose_event (GdkWidget *widget, GdkEventExpose *event, gpointer data)
   gdk_draw_arc (widget->window,
                 widget->style->fg_gc[widget->state],
                 TRUE,
-                0, 0, widget->allocation->width, widget->allocation.height,
+                0, 0, widget->allocation.width, widget->allocation.height,
                 0, 64 * 360);
-  gdk_gc_set_clip_rectangle (widget->style->fg_gc[widget->state]);
+  gdk_gc_set_clip_rectangle (widget->style->fg_gc[widget->state],
+                             NULL);
 
   return TRUE;
 }
diff --git a/docs/reference/gtk/tmpl/gtkrc.sgml b/docs/reference/gtk/tmpl/gtkrc.sgml
index 850384c402..381af1ba21 100644
--- a/docs/reference/gtk/tmpl/gtkrc.sgml
+++ b/docs/reference/gtk/tmpl/gtkrc.sgml
@@ -269,9 +269,9 @@ state of the widget. The states are:
 </para>
 
 <para>
-Colors can be specified as a string <literal>"#rrrrggggbbbb"</literal>,
-<literal>"#rrrgggbbb"</literal>, <literal>"#rrggbb"</literal>,
-or <literal>"#rgb"</literal>, where <literal>r</literal>
+Colors can be specified as a string <literal>"&hash;rrrrggggbbbb"</literal>,
+<literal>"&hash;rrrgggbbb"</literal>, <literal>"&hash;rrggbb"</literal>,
+or <literal>"&hash;rgb"</literal>, where <literal>r</literal>
 <literal>g</literal>, and <literal>b</literal> are
 hex digits, or they can be specified as a triplet of floats
 <literal>{ <replaceable>r</replaceable>, <replaceable>g</replaceable>,