[gtk+] Documentation and stylistic fixups
- From: Matthias Clasen <matthiasc src gnome org>
- To: svn-commits-list gnome org
- Cc:
- Subject: [gtk+] Documentation and stylistic fixups
- Date: Wed, 14 Oct 2009 17:28:18 +0000 (UTC)
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]
