added API docs for the less obvious functions. Gracefully handle attempts

2003-11-11  Sven Neumann  <sven@gimp.org>

	* app/display/gimpcanvas.c: added API docs for the less obvious
	functions. Gracefully handle attempts to draw on the unrealized
	widget.

	* app/display/gimpdisplayshell-selection.c (selection_draw):
	removed the redundant check for a realized canvas widget.

Also updated API docs.

ChangeLog

@@ -1,15 +1,22 @@
-2003-11-11  Maurits Rijk  <lpeek.mrijk@consunet.nl
+2003-11-11  Sven Neumann  <sven@gimp.org>
+
+	* app/display/gimpcanvas.c: added API docs for the less obvious
+	functions. Gracefully handle attempts to draw on the unrealized
+	widget.
+
+	* app/display/gimpdisplayshell-selection.c (selection_draw):
+	removed the redundant check for a realized canvas widget.
+
+2003-11-11  Maurits Rijk  <lpeek.mrijk@consunet.nl>
 
 	* plug-ins/gfig/gfig-preview.[ch]
 	* plug-ins/gfig/gfig-grid.[ch]: new files.
 	
 	* plug-ins/gfig/Makefile.am: changed accordingly.
-	* po-plug-ins/POTFILES.in: added new files for translation.
 
 	* plug-ins/gfig/gfig.[ch]: moved preview and grid code to their own
 	file.
 
-
 2003-11-11  Michael Natterer  <mitch@gimp.org>
 
 	* libgimpwidgets/gimpcolornotebook.c

app/display/gimpcanvas.c

@@ -218,13 +218,15 @@ static GdkGC *
 gimp_canvas_gc_new (GimpCanvas      *canvas,
                     GimpCanvasStyle  style)
 {
-  GtkWidget       *widget = GTK_WIDGET (canvas);
   GdkGC           *gc;
   GdkGCValues      values;
   GdkGCValuesMask  mask = 0;
   GdkColor         fg;
   GdkColor         bg;
 
+  if (! GTK_WIDGET_REALIZED (canvas))
+    return NULL;
+
   switch (style)
     {
     case GIMP_CANVAS_STYLE_BLACK:
@@ -262,11 +264,10 @@ gimp_canvas_gc_new (GimpCanvas      *canvas,
 
     case GIMP_CANVAS_STYLE_CUSTOM:
     default:
-      g_assert_not_reached ();
+      return NULL;
-      break;
     }
 
-  gc = gdk_gc_new_with_values (widget->window, &values, mask);
+  gc = gdk_gc_new_with_values (GTK_WIDGET (canvas)->window, &values, mask);
 
   switch (style)
     {
@@ -341,9 +342,34 @@ gimp_canvas_gc_new (GimpCanvas      *canvas,
   return gc;
 }
 
+static inline gboolean
+gimp_canvas_ensure_style (GimpCanvas      *canvas,
+                          GimpCanvasStyle  style)
+{
+  return (canvas->gc[style] != NULL ||
+          (canvas->gc[style] = gimp_canvas_gc_new (canvas, style)) != NULL);
+}
+
 
 /*  public functions  */
 
+/**
+ * gimp_canvas_new:
+ *
+ * Creates a new #GimpCanvas widget and sets it's widget name to
+ * "gimp-canvas".
+ *
+ * The #GimpCanvas widget is a #GdkDrawingArea abstraction. It manages
+ * a set of graphic contexts for drawing on a GIMP display. If you
+ * draw using a #GimpCanvasStyle, #GimpCanvas makes sure that the
+ * associated #GdkGC is created. All drawing on the canvas needs to
+ * happen by means of the #GimpCanvas drawing functions. Besides from
+ * not needing a #GdkGC pointer, the #GimpCanvas drawing functions
+ * look and work like their #GdkDrawable counterparts. #GimpCanvas
+ * gracefully handles attempts to draw on the unrealized widget.
+ *
+ * Return value: a new #GimpCanvas widget
+ **/
 GtkWidget *
 gimp_canvas_new (void)
 {
@@ -358,15 +384,10 @@ gimp_canvas_draw_cursor (GimpCanvas *canvas,
                          gint        y)
 {
   GtkWidget *widget = GTK_WIDGET (canvas);
-  GimpCanvasStyle  style;
 
-  for (style  = GIMP_CANVAS_STYLE_BLACK;
+  if (! (gimp_canvas_ensure_style (canvas, GIMP_CANVAS_STYLE_BLACK) &&
-       style <= GIMP_CANVAS_STYLE_WHITE;
+         gimp_canvas_ensure_style (canvas, GIMP_CANVAS_STYLE_WHITE)) )
-       style++)
+    return;
-    {
-      if (! canvas->gc[style])
-        canvas->gc[style] = gimp_canvas_gc_new (canvas, style);
-    }
 
   gdk_draw_line (widget->window, canvas->gc[GIMP_CANVAS_STYLE_WHITE],
                  x - 7, y - 1, x + 7, y - 1);
@@ -388,12 +409,11 @@ gimp_canvas_draw_point (GimpCanvas      *canvas,
                         gint             x,
                         gint             y)
 {
-  GtkWidget *widget = GTK_WIDGET (canvas);
+  if (! gimp_canvas_ensure_style (canvas, style))
+    return;
 
-  if (! canvas->gc[style])
+  gdk_draw_point (GTK_WIDGET (canvas)->window, canvas->gc[style],
-    canvas->gc[style] = gimp_canvas_gc_new (canvas, style);
+                  x, y);
-
-  gdk_draw_point (widget->window, canvas->gc[style], x, y);
 }
 
 void
@@ -402,12 +422,11 @@ gimp_canvas_draw_points (GimpCanvas      *canvas,
                          GdkPoint        *points,
                          gint             num_points)
 {
-  GtkWidget *widget = GTK_WIDGET (canvas);
+  if (! gimp_canvas_ensure_style (canvas, style))
+    return;
 
-  if (! canvas->gc[style])
+  gdk_draw_points (GTK_WIDGET (canvas)->window, canvas->gc[style],
-    canvas->gc[style] = gimp_canvas_gc_new (canvas, style);
+                   points, num_points);
-
-  gdk_draw_points (widget->window, canvas->gc[style], points, num_points);
 }
 
 void
@@ -418,12 +437,11 @@ gimp_canvas_draw_line (GimpCanvas      *canvas,
                        gint             x2,
                        gint             y2)
 {
-  GtkWidget *widget = GTK_WIDGET (canvas);
+  if (! gimp_canvas_ensure_style (canvas, style))
+    return;
 
-  if (! canvas->gc[style])
+  gdk_draw_line (GTK_WIDGET (canvas)->window, canvas->gc[style],
-    canvas->gc[style] = gimp_canvas_gc_new (canvas, style);
+                 x1, y1, x2, y2);
-
-  gdk_draw_line (widget->window, canvas->gc[style], x1, y1, x2, y2);
 }
 
 void
@@ -432,12 +450,11 @@ gimp_canvas_draw_lines (GimpCanvas      *canvas,
                         GdkPoint        *points,
                         gint             num_points)
 {
-  GtkWidget *widget = GTK_WIDGET (canvas);
+  if (! gimp_canvas_ensure_style (canvas, style))
+    return;
 
-  if (! canvas->gc[style])
+  gdk_draw_lines (GTK_WIDGET (canvas)->window, canvas->gc[style],
-    canvas->gc[style] = gimp_canvas_gc_new (canvas, style);
+                  points, num_points);
-
-  gdk_draw_lines (widget->window, canvas->gc[style], points, num_points);
 }
 
 void
@@ -449,12 +466,10 @@ gimp_canvas_draw_rectangle (GimpCanvas      *canvas,
                             gint             width,
                             gint             height)
 {
-  GtkWidget *widget = GTK_WIDGET (canvas);
+  if (! gimp_canvas_ensure_style (canvas, style))
+    return;
 
-  if (! canvas->gc[style])
+  gdk_draw_rectangle (GTK_WIDGET (canvas)->window, canvas->gc[style],
-    canvas->gc[style] = gimp_canvas_gc_new (canvas, style);
-
-  gdk_draw_rectangle (widget->window, canvas->gc[style],
                       filled, x, y, width, height);
 }
 
@@ -469,12 +484,10 @@ gimp_canvas_draw_arc (GimpCanvas      *canvas,
                       gint             angle1,
                       gint             angle2)
 {
-  GtkWidget *widget = GTK_WIDGET (canvas);
+  if (! gimp_canvas_ensure_style (canvas, style))
+    return;
 
-  if (! canvas->gc[style])
+  gdk_draw_arc (GTK_WIDGET (canvas)->window, canvas->gc[style],
-    canvas->gc[style] = gimp_canvas_gc_new (canvas, style);
-
-  gdk_draw_arc (widget->window, canvas->gc[style],
                 filled, x, y, width, height, angle1, angle2);
 }
 
@@ -485,12 +498,10 @@ gimp_canvas_draw_polygon (GimpCanvas      *canvas,
                           GdkPoint        *points,
                           gint             num_points)
 {
-  GtkWidget *widget = GTK_WIDGET (canvas);
+  if (! gimp_canvas_ensure_style (canvas, style))
+    return;
 
-  if (! canvas->gc[style])
+  gdk_draw_polygon (GTK_WIDGET (canvas)->window, canvas->gc[style],
-    canvas->gc[style] = gimp_canvas_gc_new (canvas, style);
-
-  gdk_draw_polygon (widget->window, canvas->gc[style],
                     filled, points, num_points);
 }
 
@@ -500,12 +511,10 @@ gimp_canvas_draw_segments (GimpCanvas      *canvas,
                            GdkSegment      *segments,
                            gint             num_segments)
 {
-  GtkWidget *widget = GTK_WIDGET (canvas);
+  if (! gimp_canvas_ensure_style (canvas, style))
+    return;
 
-  if (! canvas->gc[style])
+  gdk_draw_segments (GTK_WIDGET (canvas)->window, canvas->gc[style],
-    canvas->gc[style] = gimp_canvas_gc_new (canvas, style);
-
-  gdk_draw_segments (widget->window, canvas->gc[style],
                      segments, num_segments);
 }
 
@@ -521,12 +530,10 @@ gimp_canvas_draw_rgb (GimpCanvas      *canvas,
                       gint             xdith,
                       gint             ydith)
 {
-  GtkWidget *widget = GTK_WIDGET (canvas);
+  if (! gimp_canvas_ensure_style (canvas, style))
+    return;
 
-  if (! canvas->gc[style])
+  gdk_draw_rgb_image_dithalign (GTK_WIDGET (canvas)->window, canvas->gc[style],
-    canvas->gc[style] = gimp_canvas_gc_new (canvas, style);
-
-  gdk_draw_rgb_image_dithalign (widget->window, canvas->gc[style],
                                 x, y, width, height,
                                 GDK_RGB_DITHER_MAX,
                                 rgb_buf, rowstride, xdith, ydith);
@@ -564,28 +571,53 @@ gimp_canvas_set_clip_region (GimpCanvas      *canvas,
   gdk_gc_set_clip_region (canvas->gc[style], region);
 }
 
+/**
+ * gimp_canvas_set_stipple_index:
+ * @canvas: a #GimpCanvas widget
+ * @style:  the #GimpCanvasStyle to alter
+ * @index:  the new stipple index
+ *
+ * Some styles of the #GimpCanvas do a stipple fill. #GimpCanvas has a
+ * set of %GIMP_CANVAS_NUM_STIPPLES stipple bitmaps. This functions
+ * allows you to change the bitmap being used. This can be used to
+ * implement a marching ants effect. An older implementation used to
+ * use this feature and so it is included since it might be useful in
+ * the future. All stipple bitmaps but the default one are created on
+ * the fly.
+ */
 void
 gimp_canvas_set_stipple_index (GimpCanvas      *canvas,
                                GimpCanvasStyle  style,
                                guint            index)
 {
-  if (! canvas->gc[style])
+  if (! gimp_canvas_ensure_style (canvas, style))
-    canvas->gc[style] = gimp_canvas_gc_new (canvas, style);
+    return;
 
   index = index % GIMP_CANVAS_NUM_STIPPLES;
 
   if (! canvas->stipple[index])
     {
-      GtkWidget *widget = GTK_WIDGET (canvas);
-
       canvas->stipple[index] =
-        gdk_bitmap_create_from_data (widget->window,
+        gdk_bitmap_create_from_data (GTK_WIDGET (canvas)->window,
                                      (const gchar *) stipples[index], 8, 8);
     }
 
   gdk_gc_set_stipple (canvas->gc[style], canvas->stipple[index]);
 }
 
+/**
+ * gimp_canvas_set_custom_gc:
+ * @canvas: a #GimpCanvas widget
+ * @gc:     a #GdkGC;
+ *
+ * The #GimpCanvas widget has an extra style for a custom #GdkGC. This
+ * function allows you to set the @gc for the %GIMP_CANVAS_STYLE_CUSTOM.
+ * Drawing with the custom style only works if you set a #GdkGC
+ * earlier.  Since the custom #GdkGC can under certain circumstances
+ * be destroyed by #GimpCanvas, you should always set the custom gc
+ * before calling a #GimpCanvas drawing function with
+ * %GIMP_CANVAS_STYLE_CUSTOM.
+ **/
 void
 gimp_canvas_set_custom_gc (GimpCanvas *canvas,
                            GdkGC      *gc)

app/display/gimpdisplayshell-selection.c

@@ -392,9 +392,6 @@ selection_draw (Selection *select)
   if (select->hidden)
     return;
 
-  if (! GTK_WIDGET_REALIZED (canvas))
-    return;
-
 #ifdef USE_DRAWPOINTS
 
 #ifdef VERBOSE

devel-docs/ChangeLog

@@ -1,3 +1,16 @@
+2003-11-11  Sven Neumann  <sven@gimp.org>
+
+	* app/Makefile.am (IGNORE_HFILES): removed
+	gimpdisplayshell-marching-ants.h.
+	
+	* app/app-sections.txt
+	* libgimp/libgimp-sections.txt
+	* libgimp/tmpl/gimpgimprc.sgml
+	* libgimpwidgets/libgimpwidgets-sections.txt
+	* libgimpwidgets/tmpl/gimpcolorbutton.sgml
+	* libgimpwidgets/tmpl/gimpdialog.sgml
+	* libgimpwidgets/tmpl/gimpstock.sgml: updated.
+
 2003-11-11  Sven Neumann  <sven@gimp.org>
 
 	* app/app-docs.sgml

devel-docs/app/Makefile.am

@@ -40,7 +40,6 @@ IGNORE_HFILES = \
 	gimpimage-convert-fsdither.h	\
 	gimphelp-ids.h			\
 	gimprc-blurbs.h			\
-	gimpdisplayshell-marching-ants.h	\
 	paint-funcs-generic.h
 
 # Images to copy into HTML directory

devel-docs/app/app-sections.txt

@@ -1356,9 +1356,11 @@ GIMP_VIEWABLE_GET_CLASS
 <TITLE>GimpCanvas</TITLE>
 GimpCanvas
 GimpCanvasStyle
+GIMP_CANVAS_NUM_STIPPLES
 gimp_canvas_new
 gimp_canvas_draw_cursor
 gimp_canvas_draw_point
+gimp_canvas_draw_points
 gimp_canvas_draw_line
 gimp_canvas_draw_lines
 gimp_canvas_draw_rectangle
@@ -1367,8 +1369,10 @@ gimp_canvas_draw_polygon
 gimp_canvas_draw_segments
 gimp_canvas_draw_rgb
 gimp_canvas_set_clip_rect
-gimp_canvas_set_bg_color
+gimp_canvas_set_clip_region
 gimp_canvas_set_custom_gc
+gimp_canvas_set_stipple_index
+gimp_canvas_set_bg_color
 <SUBSECTION Standard>
 GimpCanvasClass
 GIMP_CANVAS
@@ -1641,7 +1645,7 @@ gimp_display_shell_scroll_clamp_offsets
 <FILE>gimpdisplayshell-selection</FILE>
 <TITLE>GimpDisplayShell-selection</TITLE>
 Selection
-gimp_display_shell_selection_create
+gimp_display_shell_selection_new
 gimp_display_shell_selection_free
 gimp_display_shell_selection_pause
 gimp_display_shell_selection_resume

devel-docs/libgimp/libgimp-sections.txt

@@ -267,7 +267,9 @@ gimp_fonts_set_popup
 gimp_gimprc_query
 gimp_gimprc_set
 gimp_get_default_comment
+gimp_get_module_load_inhibit
 gimp_get_monitor_resolution
+gimp_get_theme_dir
 </SECTION>
 
 <SECTION>

devel-docs/libgimp/tmpl/gimpgimprc.sgml

@@ -42,6 +42,14 @@ Interactions with settings from .gimprc.
 @Returns: 
 
 
+<!-- ##### FUNCTION gimp_get_module_load_inhibit ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
 <!-- ##### FUNCTION gimp_get_monitor_resolution ##### -->
 <para>
 
@@ -52,3 +60,11 @@ Interactions with settings from .gimprc.
 @Returns: 
 
 
+<!-- ##### FUNCTION gimp_get_theme_dir ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+

devel-docs/libgimpwidgets/libgimpwidgets-sections.txt

@@ -46,6 +46,8 @@ GimpColorButton
 gimp_color_button_new
 gimp_color_button_set_color
 gimp_color_button_get_color
+gimp_color_button_set_update
+gimp_color_button_get_update
 gimp_color_button_has_alpha
 gimp_color_button_set_type
 <SUBSECTION Standard>
@@ -268,6 +270,7 @@ GimpDialog
 gimp_dialog_new
 gimp_dialog_new_valist
 gimp_dialog_add_buttons_valist
+gimp_dialog_run
 <SUBSECTION Standard>
 GIMP_TYPE_DIALOG
 GIMP_DIALOG
@@ -319,6 +322,7 @@ GIMP_STOCK_RESET
 GIMP_STOCK_CLOSE
 GIMP_STOCK_MENU_LEFT
 GIMP_STOCK_MENU_RIGHT
+GIMP_STOCK_MOVE_TO_SCREEN
 GIMP_STOCK_INVERT
 GIMP_STOCK_LAYER_TO_IMAGESIZE
 GIMP_STOCK_MERGE_DOWN

devel-docs/libgimpwidgets/tmpl/gimpcolorbutton.sgml

@@ -64,6 +64,24 @@ color, the "color_changed" signal is emitted.
 @gcb: 
 
 
+<!-- ##### FUNCTION gimp_color_button_set_update ##### -->
+<para>
+
+</para>
+
+@button: 
+@continuous: 
+
+
+<!-- ##### FUNCTION gimp_color_button_get_update ##### -->
+<para>
+
+</para>
+
+@button: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gimp_color_button_has_alpha ##### -->
 <para>
 

devel-docs/libgimpwidgets/tmpl/gimpdialog.sgml

@@ -67,3 +67,12 @@ dialog-related stuff.
 @args: 
 
 
+<!-- ##### FUNCTION gimp_dialog_run ##### -->
+<para>
+
+</para>
+
+@dialog: 
+@Returns: 
+
+

devel-docs/libgimpwidgets/tmpl/gimpstock.sgml

@@ -73,6 +73,14 @@ the ones in dialog size).
 
 
 
+<!-- ##### MACRO GIMP_STOCK_MOVE_TO_SCREEN ##### -->
+<para>
+<inlinegraphic fileref="stock-move-to-screen-24.png" format="png"></inlinegraphic>
+<inlinegraphic fileref="stock-move-to-screen-16.png" format="png"></inlinegraphic>
+</para>
+
+
+
 <!-- ##### MACRO GIMP_STOCK_INVERT ##### -->
 <para>
 <inlinegraphic fileref="stock-invert-16.png" format="png"></inlinegraphic>