[gtk+] Documentation and stylistic fixups



commit d1ee8e2d4b7b83b3fbbfe39b7985bfc4b39c8264
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Oct 14 13:25:23 2009 -0400

    Documentation and stylistic fixups

 docs/reference/gtk/gtk-docs.sgml |    6 ++
 docs/reference/gtk/gtk.types     |    2 +
 gtk/gtkaboutdialog.c             |   12 ++--
 gtk/gtkcellrendererspinner.c     |  109 +++++++++++++++++++++++---------------
 gtk/gtkspinner.c                 |   97 ++++++++++++++++++++--------------
 5 files changed, 138 insertions(+), 88 deletions(-)
---
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index e6e2fe4..830f94a 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -161,6 +161,7 @@ that is, GUI components such as #GtkButton or #GtkTextView.
       <xi:include href="xml/gtkstatusbar.xml" />
       <xi:include href="xml/gtkinfobar.xml" />
       <xi:include href="xml/gtkstatusicon.xml" />
+      <xi:include href="xml/gtkspinner.xml" />
     </chapter>
 
     <chapter id="ButtonWidgets">
@@ -219,6 +220,7 @@ that is, GUI components such as #GtkButton or #GtkTextView.
       <xi:include href="xml/gtkcellrendererspin.xml" />
       <xi:include href="xml/gtkcellrenderertext.xml" />
       <xi:include href="xml/gtkcellrenderertoggle.xml" />
+      <xi:include href="xml/gtkcellrendererspinner.xml" />
       <xi:include href="xml/gtkliststore.xml" />
       <xi:include href="xml/gtktreestore.xml" />
     </chapter>
@@ -491,4 +493,8 @@ that is, GUI components such as #GtkButton or #GtkTextView.
     <title>Index of new symbols in 2.18</title>
     <xi:include href="xml/api-index-2.18.xml"><xi:fallback /></xi:include>
   </index>
+  <index id="api-index-2-20" role="2.20">
+    <title>Index of new symbols in 2.20</title>
+    <xi:include href="xml/api-index-2.20.xml"><xi:fallback /></xi:include>
+  </index>
 </book>
diff --git a/docs/reference/gtk/gtk.types b/docs/reference/gtk/gtk.types
index d743aa1..5ed938e 100644
--- a/docs/reference/gtk/gtk.types
+++ b/docs/reference/gtk/gtk.types
@@ -29,6 +29,7 @@ gtk_cell_renderer_get_type
 gtk_cell_renderer_pixbuf_get_type
 gtk_cell_renderer_progress_get_type
 gtk_cell_renderer_spin_get_type
+gtk_cell_renderer_spinner_get_type
 gtk_cell_renderer_text_get_type
 gtk_cell_renderer_toggle_get_type
 gtk_cell_view_get_type
@@ -146,6 +147,7 @@ gtk_settings_get_type
 gtk_size_group_get_type
 gtk_socket_get_type
 gtk_spin_button_get_type
+gtk_spinner_get_type
 gtk_statusbar_get_type
 gtk_status_icon_get_type
 gtk_style_get_type
diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c
index 0e5ca7e..9cb8422 100644
--- a/gtk/gtkaboutdialog.c
+++ b/gtk/gtkaboutdialog.c
@@ -81,12 +81,13 @@
  * <literal>url</literal> extending to the next space, tab or line break.
  *
  * <para id="gtk-about-dialog-hook-setup">
- * Since 2.18 #GtkAboutDialog provides default website and email hooks that use
- * gtk_show_uri().
- *
- * If you want provide your own hooks overriding the default ones, it is important
- * to do so before setting the website and email URL properties, like this:
+ * Since 2.18 #GtkAboutDialog provides default website and email hooks that
+ * use gtk_show_uri().
+ * </para>
  *
+ * If you want provide your own hooks overriding the default ones, it is
+ * important to do so before setting the website and email URL properties,
+ * like this:
  * <informalexample><programlisting>
  * gtk_about_dialog_set_url_hook (GTK_ABOUT_DIALOG (dialog), launch_url, NULL, NULL);
  * gtk_about_dialog_set_website (GTK_ABOUT_DIALOG (dialog), app_url);
@@ -104,7 +105,6 @@
  * application, but in order to ensure proper translation of the title,
  * applications should set the title property explicitly when constructing
  * a #GtkAboutDialog, as shown in the following example:
- *
  * <informalexample><programlisting>
  * gtk_show_about_dialog (NULL,
  *                        "program-name", "ExampleCode",
diff --git a/gtk/gtkcellrendererspinner.c b/gtk/gtkcellrendererspinner.c
index 6501b26..4eb6220 100644
--- a/gtk/gtkcellrendererspinner.c
+++ b/gtk/gtkcellrendererspinner.c
@@ -34,6 +34,26 @@
 #include "gtkcellrendererspinner.h"
 #include "gtkalias.h"
 
+
+/**
+ * SECTION:gtkcellrendererspinner
+ * @Short_description: Renders a spinning animation in a cell
+ * @Title: GtkCellRendererSpinner
+ * @See_also: #GtkSpinner, #GtkCellRendererProgress
+ *
+ * GtkCellRendererSpinner renders a spinning animation in a cell, very
+ * similar to #GtkSpinner. It can often be used as an alternative
+ * to a #GtkCellRendererProgress for displaying indefinite activity,
+ * instead of actual progress.
+ *
+ * To start the animation in a cell, set the #GtkCellRendererSpinner:active
+ * property to %TRUE and increment the #GtkCellRendererSpinner:pulse property
+ * at regular intervals. The usual way to set the cell renderer properties
+ * for each cell is to bind them to columns in your tree model using e.g.
+ * gtk_tree_view_column_add_attribute().
+ */
+
+
 enum {
   PROP_0,
   PROP_ACTIVE,
@@ -54,28 +74,28 @@ struct _GtkCellRendererSpinnerPrivate
                         GTK_TYPE_CELL_RENDERER_SPINNER, \
                         GtkCellRendererSpinnerPrivate))
 
-static void gtk_cell_renderer_spinner_get_property        (GObject                *object,
-                                                         guint                         param_id,
-                                                         GValue                        *value,
-                                                         GParamSpec                *pspec);
-static void gtk_cell_renderer_spinner_set_property        (GObject                *object,
-                                                         guint                         param_id,
-                                                         const GValue                *value,
-                                                         GParamSpec                *pspec);
-static void gtk_cell_renderer_spinner_get_size                (GtkCellRenderer        *cell,
-                                                         GtkWidget                *widget,
-                                                         GdkRectangle                *cell_area,
-                                                         gint                        *x_offset,
-                                                         gint                        *y_offset,
-                                                         gint                        *width,
-                                                         gint                        *height);
-static void gtk_cell_renderer_spinner_render                (GtkCellRenderer        *cell,
-                                                         GdkWindow                *window,
-                                                         GtkWidget                *widget,
-                                                         GdkRectangle                *background_area,
-                                                         GdkRectangle                *cell_area,
-                                                         GdkRectangle                *expose_area,
-                                                         guint                         flags);
+static void gtk_cell_renderer_spinner_get_property (GObject         *object,
+                                                    guint            param_id,
+                                                    GValue          *value,
+                                                    GParamSpec      *pspec);
+static void gtk_cell_renderer_spinner_set_property (GObject         *object,
+                                                    guint            param_id,
+                                                    const GValue    *value,
+                                                    GParamSpec      *pspec);
+static void gtk_cell_renderer_spinner_get_size     (GtkCellRenderer *cell,
+                                                    GtkWidget       *widget,
+                                                    GdkRectangle    *cell_area,
+                                                    gint            *x_offset,
+                                                    gint            *y_offset,
+                                                    gint            *width,
+                                                    gint            *height);
+static void gtk_cell_renderer_spinner_render       (GtkCellRenderer *cell,
+                                                    GdkWindow       *window,
+                                                    GtkWidget       *widget,
+                                                    GdkRectangle    *background_area,
+                                                    GdkRectangle    *cell_area,
+                                                    GdkRectangle    *expose_area,
+                                                    guint            flags);
 
 G_DEFINE_TYPE (GtkCellRendererSpinner, gtk_cell_renderer_spinner, GTK_TYPE_CELL_RENDERER)
 
@@ -91,7 +111,7 @@ gtk_cell_renderer_spinner_class_init (GtkCellRendererSpinnerClass *klass)
   cell_class->get_size = gtk_cell_renderer_spinner_get_size;
   cell_class->render = gtk_cell_renderer_spinner_render;
 
-  /* GtkCellRendererSpinner::active:
+  /* GtkCellRendererSpinner:active:
    *
    * Whether the spinner is active (ie. shown) in the cell
    *
@@ -104,11 +124,15 @@ gtk_cell_renderer_spinner_class_init (GtkCellRendererSpinnerClass *klass)
                                                          P_("Whether the spinner is active (ie. shown) in the cell"),
                                                          FALSE,
                                                          G_PARAM_READWRITE));
-  /* GtkCellRendererSpinner::pulse:
+  /**
+   * GtkCellRendererSpinner:pulse:
+   *
+   * Pulse of the spinner. Increment this value to draw the next frame of the
+   * spinner animation. Usually, you would update this value in a timeout.
    *
-   * Pulse of the spinner. Increment this value to draw the next frame of the spinner animation.
-   * Usually, you would update this value in a timeout, every 80 milliseconds to show a full
-   * animation within one second.
+   * The #GtkSpinner widget draws one full cycle of the animation per second.
+   * You can learn about the number of frames used by the theme
+   * by looking at the #GtkSpinner:num-steps style property
    *
    * Since 2.20
    */
@@ -119,7 +143,8 @@ gtk_cell_renderer_spinner_class_init (GtkCellRendererSpinnerClass *klass)
                                                       P_("Pulse of the spinner"),
                                                       0, G_MAXUINT, 0,
                                                       G_PARAM_READWRITE));
-  /* GtkCellRendererSpinner::size:
+  /**
+   * GtkCellRendererSpinner:size:
    *
    * The #GtkIconSize value that specifies the size of the rendered spinner.
    *
@@ -129,7 +154,7 @@ gtk_cell_renderer_spinner_class_init (GtkCellRendererSpinnerClass *klass)
                                    PROP_SIZE,
                                    g_param_spec_enum ("size",
                                                       P_("Size"),
-                                                      P_("The #GtkIconSize value that specifies the size of the rendered spinner"),
+                                                      P_("The GtkIconSize value that specifies the size of the rendered spinner"),
                                                       GTK_TYPE_ICON_SIZE, GTK_ICON_SIZE_MENU,
                                                       G_PARAM_READWRITE));
 
@@ -164,7 +189,7 @@ gtk_cell_renderer_spinner_new (void)
 
 static void
 gtk_cell_renderer_spinner_update_size (GtkCellRendererSpinner *cell,
-                                       GtkWidget *widget)
+                                       GtkWidget              *widget)
 {
   GtkCellRendererSpinnerPrivate *priv = cell->priv;
   GdkScreen *screen;
@@ -238,12 +263,12 @@ gtk_cell_renderer_spinner_set_property (GObject      *object,
 
 static void
 gtk_cell_renderer_spinner_get_size (GtkCellRenderer *cellr,
-                                    GtkWidget *widget,
-                                    GdkRectangle *cell_area,
-                                    gint *x_offset,
-                                    gint *y_offset,
-                                    gint *width,
-                                    gint *height)
+                                    GtkWidget       *widget,
+                                    GdkRectangle    *cell_area,
+                                    gint            *x_offset,
+                                    gint            *y_offset,
+                                    gint            *width,
+                                    gint            *height)
 {
   GtkCellRendererSpinner *cell = GTK_CELL_RENDERER_SPINNER (cellr);
   GtkCellRendererSpinnerPrivate *priv = cell->priv;
@@ -296,12 +321,12 @@ gtk_cell_renderer_spinner_get_size (GtkCellRenderer *cellr,
 
 static void
 gtk_cell_renderer_spinner_render (GtkCellRenderer *cellr,
-                                  GdkWindow *window,
-                                  GtkWidget *widget,
-                                  GdkRectangle *background_area,
-                                  GdkRectangle *cell_area,
-                                  GdkRectangle *expose_area,
-                                  guint flags)
+                                  GdkWindow       *window,
+                                  GtkWidget       *widget,
+                                  GdkRectangle    *background_area,
+                                  GdkRectangle    *cell_area,
+                                  GdkRectangle    *expose_area,
+                                  guint            flags)
 {
   GtkCellRendererSpinner *cell = GTK_CELL_RENDERER_SPINNER (cellr);
   GtkCellRendererSpinnerPrivate *priv = cell->priv;
diff --git a/gtk/gtkspinner.c b/gtk/gtkspinner.c
index 63a6477..db9307c 100644
--- a/gtk/gtkspinner.c
+++ b/gtk/gtkspinner.c
@@ -38,6 +38,22 @@
 #include "gtkstyle.h"
 #include "gtkalias.h"
 
+
+/**
+ * SECTION:gtkspinner
+ * @Short_description: Show a spinner animation
+ * @Title: GtkSpinner
+ * @See_also: #GtkCellRendererSpinner, #GtkProgressBar
+ *
+ * A GtkSpinner widget displays an icon-size spinning animation.
+ * It is often used as an alternative to a #GtkProgressBar for
+ * displaying indefinite activity, instead of actual progress.
+ *
+ * To start the animation, use gtk_spinner_start(), to stop it
+ * use gtk_spinner_stop().
+ */
+
+
 #define GTK_SPINNER_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), GTK_TYPE_SPINNER, GtkSpinnerPrivate))
 
 G_DEFINE_TYPE (GtkSpinner, gtk_spinner, GTK_TYPE_DRAWING_AREA);
@@ -54,22 +70,26 @@ struct _GtkSpinnerPrivate
   guint timeout;
 };
 
-static void gtk_spinner_class_init (GtkSpinnerClass *klass);
-static void gtk_spinner_init (GtkSpinner *spinner);
-static void gtk_spinner_dispose (GObject *gobject);
-static gboolean gtk_spinner_expose (GtkWidget *widget, GdkEventExpose *event);
-static void gtk_spinner_screen_changed (GtkWidget* widget, GdkScreen* old_screen);
-static void gtk_spinner_style_set (GtkWidget *widget, GtkStyle *prev_style);
-static void gtk_spinner_get_property (GObject    *object,
-                                      guint       param_id,
-                                      GValue     *value,
-                                      GParamSpec *pspec);
-static void gtk_spinner_set_property (GObject      *object,
-                                      guint         param_id,
-                                      const GValue *value,
-                                      GParamSpec   *pspec);
-static AtkObject *gtk_spinner_get_accessible (GtkWidget *widget);
-static GType gtk_spinner_accessible_get_type (void);
+static void gtk_spinner_class_init     (GtkSpinnerClass *klass);
+static void gtk_spinner_init           (GtkSpinner      *spinner);
+static void gtk_spinner_dispose        (GObject         *gobject);
+static gboolean gtk_spinner_expose     (GtkWidget       *widget,
+                                        GdkEventExpose  *event);
+static void gtk_spinner_screen_changed (GtkWidget       *widget,
+                                        GdkScreen       *old_screen);
+static void gtk_spinner_style_set      (GtkWidget       *widget,
+                                        GtkStyle        *prev_style);
+static void gtk_spinner_get_property   (GObject         *object,
+                                        guint            param_id,
+                                        GValue          *value,
+                                        GParamSpec      *pspec);
+static void gtk_spinner_set_property   (GObject         *object,
+                                        guint            param_id,
+                                        const GValue    *value,
+                                        GParamSpec      *pspec);
+
+static AtkObject *gtk_spinner_get_accessible      (GtkWidget *widget);
+static GType      gtk_spinner_accessible_get_type (void);
 
 static void
 gtk_spinner_class_init (GtkSpinnerClass *klass)
@@ -91,7 +111,7 @@ gtk_spinner_class_init (GtkSpinnerClass *klass)
   widget_class->style_set = gtk_spinner_style_set;
   widget_class->get_accessible = gtk_spinner_get_accessible;
 
-  /* GtkSpinner::active:
+  /* GtkSpinner:active:
    *
    * Whether the spinner is active
    *
@@ -105,17 +125,17 @@ gtk_spinner_class_init (GtkSpinnerClass *klass)
                                                          FALSE,
                                                          G_PARAM_READWRITE));
   /**
-   * GtkSpinner::num-steps:
+   * GtkSpinner:num-steps:
    *
-   * The number of steps for the spinner to complete a full loop. The animation will
-   * complete a full revolution in one second.
+   * The number of steps for the spinner to complete a full loop.
+   * The animation will complete a full cycle in one second.
    *
    * Since: 2.20
    */
   gtk_widget_class_install_style_property (widget_class,
                                            g_param_spec_uint ("num-steps",
                                                              P_("Number of steps"),
-                                                             P_("The number of steps for the spinner to complete a full loop. The animation will complete a full revolution in one second."),
+                                                             P_("The number of steps for the spinner to complete a full loop. The animation will complete a full cycle in one second."),
                                                              1,
                                                              G_MAXUINT,
                                                              12,
@@ -246,13 +266,9 @@ gtk_spinner_timeout (gpointer data)
   priv = GTK_SPINNER_GET_PRIVATE (data);
 
   if (priv->current + 1 >= priv->num_steps)
-    {
-      priv->current = 0;
-    }
+    priv->current = 0;
   else
-    {
-      priv->current++;
-    }
+    priv->current++;
 
   gtk_widget_queue_draw (GTK_WIDGET (data));
 
@@ -355,8 +371,8 @@ gtk_spinner_accessible_class_init (AtkObjectClass *klass)
 
 static void
 gtk_spinner_accessible_image_get_size (AtkImage *image,
-                                             gint     *width,
-                                             gint     *height)
+                                       gint     *width,
+                                       gint     *height)
 {
   GtkWidget *widget;
 
@@ -465,7 +481,7 @@ gtk_spinner_get_accessible (GtkWidget *widget)
 }
 
 /**
- * gtk_spinner_new
+ * gtk_spinner_new:
  *
  * Returns a new spinner widget. Not yet started.
  *
@@ -480,9 +496,10 @@ gtk_spinner_new (void)
 }
 
 /**
- * gtk_spinner_start
+ * gtk_spinner_start:
+ * @spinner: a #GtkSpinner
  *
- * Starts the animation on the #GtkSpinner
+ * Starts the animation of the spinner.
  *
  * Since: 2.20
  */
@@ -494,18 +511,19 @@ gtk_spinner_start (GtkSpinner *spinner)
   g_return_if_fail (GTK_IS_SPINNER (spinner));
 
   priv = GTK_SPINNER_GET_PRIVATE (spinner);
+
   if (priv->timeout != 0)
-    {
-      return;
-    }
+    return;
+
   priv->timeout = gdk_threads_add_timeout (1000 / priv->num_steps, gtk_spinner_timeout, spinner);
   g_object_notify (G_OBJECT (spinner), "active");
 }
 
 /**
- * gtk_spinner_stop
+ * gtk_spinner_stop:
+ * @spinner: a #GtkSpinner
  *
- * Stops the animation on the #GtkSpinner
+ * Stops the animation of the spinner.
  *
  * Since: 2.20
  */
@@ -518,9 +536,8 @@ gtk_spinner_stop (GtkSpinner *spinner)
 
   priv = GTK_SPINNER_GET_PRIVATE (spinner);
   if (priv->timeout == 0)
-    {
-      return;
-    }
+    return;
+
   g_source_remove (priv->timeout);
   priv->timeout = 0;
   g_object_notify (G_OBJECT (spinner), "active");



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]