[gdl] More documenation improvements
- From: Sebastien Granjoux <sgranjoux src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gdl] More documenation improvements
- Date: Mon, 28 May 2012 10:15:55 +0000 (UTC)
commit 9f262d1f300949690297c172e7bb87b11bbfdf41
Author: SÃbastien Granjoux <seb sfo free fr>
Date: Mon May 28 12:14:41 2012 +0200
More documenation improvements
docs/reference/gdl-docs.sgml | 4 +-
docs/reference/gdl-sections.txt | 2 +-
gdl/gdl-dock-item.c | 10 ++--
gdl/gdl-dock-item.h | 123 ++++++++++++++++++++++++++++++++++----
gdl/gdl-dock-layout.c | 1 +
gdl/gdl-dock-master.c | 6 ++
gdl/gdl-dock-master.h | 6 ++
gdl/gdl-dock-notebook.c | 4 +-
gdl/gdl-dock-object.c | 15 +++++
gdl/gdl-dock-object.h | 6 +-
gdl/gdl-dock-paned.c | 4 +-
gdl/gdl-dock.c | 6 ++
gdl/gdl-dock.h | 1 +
13 files changed, 161 insertions(+), 27 deletions(-)
---
diff --git a/docs/reference/gdl-docs.sgml b/docs/reference/gdl-docs.sgml
index e5dae20..9be5c3f 100644
--- a/docs/reference/gdl-docs.sgml
+++ b/docs/reference/gdl-docs.sgml
@@ -8,7 +8,9 @@
<bookinfo>
<title>GNOME Docking Library Reference Manual</title>
<releaseinfo>
- for libgdl &version;
+ This document is for libgdl version &version;.
+ The latest versions can be found online at
+ <ulink role="online-location" url="http://developer.gnome.org/gdl/";>http://developer.gnome.org/gdl/</ulink>.
</releaseinfo>
</bookinfo>
diff --git a/docs/reference/gdl-sections.txt b/docs/reference/gdl-sections.txt
index ad288e4..081b4b3 100644
--- a/docs/reference/gdl-sections.txt
+++ b/docs/reference/gdl-sections.txt
@@ -7,7 +7,6 @@
<FILE>gdl-dock</FILE>
<TITLE>GdlDock</TITLE>
GdlDock
-GdlDockClass
gdl_dock_new
gdl_dock_new_from
gdl_dock_add_item
@@ -20,6 +19,7 @@ gdl_dock_get_named_items
gdl_dock_get_placeholder_by_name
gdl_dock_object_get_toplevel
<SUBSECTION Standard>
+GdlDockClass
GDL_DOCK
GDL_DOCK_CLASS
GDL_DOCK_GET_CLASS
diff --git a/gdl/gdl-dock-item.c b/gdl/gdl-dock-item.c
index 3d7f54e..0ff0b5e 100644
--- a/gdl/gdl-dock-item.c
+++ b/gdl/gdl-dock-item.c
@@ -1179,7 +1179,7 @@ gdl_dock_item_button_changed (GtkWidget *widget,
item->priv->start_x = event->x;
item->priv->start_y = event->y;
- GDL_DOCK_ITEM_SET_FLAGS (item, GDL_DOCK_IN_PREDRAG);
+ GDL_DOCK_OBJECT_SET_FLAGS (item, GDL_DOCK_IN_PREDRAG);
cursor = gdk_cursor_new_for_display (gtk_widget_get_display (widget),
GDK_FLEUR);
@@ -1226,7 +1226,7 @@ gdl_dock_item_motion (GtkWidget *widget,
item->priv->start_y,
event->x,
event->y)) {
- GDL_DOCK_ITEM_UNSET_FLAGS (item, GDL_DOCK_IN_PREDRAG);
+ GDL_DOCK_OBJECT_UNSET_FLAGS (item, GDL_DOCK_IN_PREDRAG);
item->dragoff_x = item->priv->start_x;
item->dragoff_y = item->priv->start_y;
@@ -1662,7 +1662,7 @@ gdl_dock_item_drag_start (GdlDockItem *item)
if (!gtk_widget_get_realized (GTK_WIDGET (item)))
gtk_widget_realize (GTK_WIDGET (item));
- GDL_DOCK_ITEM_SET_FLAGS (item, GDL_DOCK_IN_DRAG);
+ GDL_DOCK_OBJECT_SET_FLAGS (item, GDL_DOCK_IN_DRAG);
/* grab the keyboard & pointer. The pointer has already been grabbed by the grip
* window when it has received a press button event. See gdk_pointer_grab. */
@@ -1682,10 +1682,10 @@ gdl_dock_item_drag_end (GdlDockItem *item,
g_signal_emit (item, gdl_dock_item_signals [DOCK_DRAG_END], 0, cancel);
gtk_widget_grab_focus (GTK_WIDGET (item));
- GDL_DOCK_ITEM_UNSET_FLAGS (item, GDL_DOCK_IN_DRAG);
+ GDL_DOCK_OBJECT_UNSET_FLAGS (item, GDL_DOCK_IN_DRAG);
}
else if (GDL_DOCK_ITEM_IN_PREDRAG (item)) {
- GDL_DOCK_ITEM_UNSET_FLAGS (item, GDL_DOCK_IN_PREDRAG);
+ GDL_DOCK_OBJECT_UNSET_FLAGS (item, GDL_DOCK_IN_PREDRAG);
}
else {
/* No drag not pre-drag has been started */
diff --git a/gdl/gdl-dock-item.h b/gdl/gdl-dock-item.h
index e48f657..1224452 100644
--- a/gdl/gdl-dock-item.h
+++ b/gdl/gdl-dock-item.h
@@ -8,7 +8,7 @@
*
* Copyright (C) 1998 Ettore Perazzoli
* Copyright (C) 1998 Elliot Lee
- * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
+ * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
* All rights reserved.
*
* This library is free software; you can redistribute it and/or
@@ -122,8 +122,12 @@ struct _GdlDockItemClass {
GdlDockItemClassPrivate *priv;
gboolean has_grip;
-
+
/* virtuals */
+ void (* set_orientation) (GdlDockItem *item,
+ GtkOrientation orientation);
+
+ /* signals */
void (* dock_drag_begin) (GdlDockItem *item);
void (* dock_drag_motion) (GdlDockItem *item,
gint x,
@@ -132,40 +136,133 @@ struct _GdlDockItemClass {
gboolean cancelled);
void (* move_focus_child) (GdlDockItem *item,
GtkDirectionType direction);
- void (* set_orientation) (GdlDockItem *item,
- GtkOrientation orientation);
};
+#ifndef GDL_DISABLE_DEPRECATED
+/**
+ * GDL_DOCK_ITEM_FLAGS:
+ * @item: A #GdlDockObject
+ *
+ * Get all flags of #GdlDockObject.
+ *
+ * Deprecated: 3.6: Use GDL_DOCK_OBJECT_FLAGS instead
+ */
#define GDL_DOCK_ITEM_FLAGS(item) (GDL_DOCK_OBJECT (item)->flags)
+
+
+/**
+ * GDL_DOCK_ITEM_SET_FLAGS:
+ * @item: A #GdlDockObject
+ * @flag: One or more #GdlDockObjectFlags
+ *
+ * Set one or more flags of a dock object.
+ *
+ * Deprecated: 3.6: Use GDL_DOCK_OBJECT_SET_FLAGS instead
+ */
+#define GDL_DOCK_ITEM_SET_FLAGS(item,flag) \
+ G_STMT_START { (GDL_DOCK_OBJECT_FLAGS (item) |= (flag)); } G_STMT_END
+
+/**
+ * GDL_DOCK_ITEM_UNSET_FLAGS:
+ * @item: A #GdlDockObject
+ * @flag: One or more #GdlDockObjectFlags
+ *
+ * Clear one or more flags of a dock object.
+ *
+ * Deprecated: 3.6: Use GDL_DOCK_OBJECT_UNSET_FLAGS instead
+ */
+#define GDL_DOCK_ITEM_UNSET_FLAGS(item,flag) \
+ G_STMT_START { (GDL_DOCK_OBJECT_FLAGS (item) &= ~(flag)); } G_STMT_END
+
+#endif
+
+/**
+ * GDL_DOCK_ITEM_IN_DRAG:
+ * @item: A #GdlDockObject
+ *
+ * Evaluates to %TRUE if the user is dragging the item.
+ */
#define GDL_DOCK_ITEM_IN_DRAG(item) \
- ((GDL_DOCK_ITEM_FLAGS (item) & GDL_DOCK_IN_DRAG) != 0)
+ ((GDL_DOCK_OBJECT_FLAGS (item) & GDL_DOCK_IN_DRAG) != 0)
+
+/**
+ * GDL_DOCK_ITEM_IN_PREDRAG:
+ * @item: A #GdlDockObject
+ *
+ * Evaluates to %TRUE if the user has clicked on the item but hasn't made a big
+ * enough move to start the drag operation.
+ */
#define GDL_DOCK_ITEM_IN_PREDRAG(item) \
- ((GDL_DOCK_ITEM_FLAGS (item) & GDL_DOCK_IN_PREDRAG) != 0)
+ ((GDL_DOCK_OBJECT_FLAGS (item) & GDL_DOCK_IN_PREDRAG) != 0)
+
+/**
+ * GDL_DOCK_ITEM_ICONIFIED:
+ * @item: A #GdlDockObject
+ *
+ * Evaluates to %TRUE if the item is iconified, appearing only as a button in
+ * the dock bar.
+ */
#define GDL_DOCK_ITEM_ICONIFIED(item) \
- ((GDL_DOCK_ITEM_FLAGS (item) & GDL_DOCK_ICONIFIED) != 0)
+ ((GDL_DOCK_OBJECT_FLAGS (item) & GDL_DOCK_ICONIFIED) != 0)
+
+/**
+ * GDL_DOCK_ITEM_USER_ACTION:
+ * @item: A #GdlDockObject
+ *
+ * Evaluates to %TRUE if the user currently use the item, by example dragging
+ * division of a #GdlDockPaned object.
+ */
#define GDL_DOCK_ITEM_USER_ACTION(item) \
- ((GDL_DOCK_ITEM_FLAGS (item) & GDL_DOCK_USER_ACTION) != 0)
+ ((GDL_DOCK_OBJECT_FLAGS (item) & GDL_DOCK_USER_ACTION) != 0)
+
+/**
+ * GDL_DOCK_ITEM_NOT_LOCKED:
+ * @item: A #GdlDockObject
+ *
+ * Evaluates to %TRUE the item can be moved, closed, or iconified.
+ */
#define GDL_DOCK_ITEM_NOT_LOCKED(item) !((item)->behavior & GDL_DOCK_ITEM_BEH_LOCKED)
+
+/**
+ * GDL_DOCK_ITEM_NO_GRIP:
+ * @item: A #GdlDockObject
+ *
+ * Evaluates to %TRUE the item has not handle, so it cannot be moved.
+ */
#define GDL_DOCK_ITEM_NO_GRIP(item) ((item)->behavior & GDL_DOCK_ITEM_BEH_NO_GRIP)
-#define GDL_DOCK_ITEM_SET_FLAGS(item,flag) \
- G_STMT_START { (GDL_DOCK_ITEM_FLAGS (item) |= (flag)); } G_STMT_END
-#define GDL_DOCK_ITEM_UNSET_FLAGS(item,flag) \
- G_STMT_START { (GDL_DOCK_ITEM_FLAGS (item) &= ~(flag)); } G_STMT_END
+/**
+ * GDL_DOCK_ITEM_HAS_GRIP:
+ * @item: A #GdlDockObject
+ *
+ * Evaluates to %TRUE the item has a handle, so it can be moved.
+ */
#define GDL_DOCK_ITEM_HAS_GRIP(item) ((GDL_DOCK_ITEM_GET_CLASS (item)->has_grip)&& \
! GDL_DOCK_ITEM_NO_GRIP (item))
+/**
+ * GDL_DOCK_ITEM_CANT_CLOSE:
+ * @item: A #GdlDockObject
+ *
+ * Evaluates to %TRUE the item cannot be closed.
+ */
#define GDL_DOCK_ITEM_CANT_CLOSE(item) \
((((item)->behavior & GDL_DOCK_ITEM_BEH_CANT_CLOSE) != 0)|| \
! GDL_DOCK_ITEM_NOT_LOCKED(item))
+/**
+ * GDL_DOCK_ITEM_CANT_ICONIFY:
+ * @item: A #GdlDockObject
+ *
+ * Evaluates to %TRUE the item cannot be iconifyed.
+ */
#define GDL_DOCK_ITEM_CANT_ICONIFY(item) \
((((item)->behavior & GDL_DOCK_ITEM_BEH_CANT_ICONIFY) != 0)|| \
! GDL_DOCK_ITEM_NOT_LOCKED(item))
/* public interface */
-
+
GtkWidget *gdl_dock_item_new (const gchar *name,
const gchar *long_name,
GdlDockItemBehavior behavior);
diff --git a/gdl/gdl-dock-layout.c b/gdl/gdl-dock-layout.c
index d3a99d4..8fb04b2 100644
--- a/gdl/gdl-dock-layout.c
+++ b/gdl/gdl-dock-layout.c
@@ -606,6 +606,7 @@ gdl_dock_layout_save (GdlDockMaster *master,
/**
* gdl_dock_layout_new:
* @dock: The dock item.
+ *
* Creates a new #GdlDockLayout
*
* Returns: New #GdlDockLayout item.
diff --git a/gdl/gdl-dock-master.c b/gdl/gdl-dock-master.c
index 9eeeff1..724d017 100644
--- a/gdl/gdl-dock-master.c
+++ b/gdl/gdl-dock-master.c
@@ -189,6 +189,12 @@ gdl_dock_master_class_init (GdlDockMasterClass *klass)
GDL_SWITCHER_STYLE_BOTH,
G_PARAM_READWRITE));
+ /**
+ * GdlDockMaster::layout-changed:
+ *
+ * Signals that the layout has changed, one or more widgets have been moved,
+ * added or removed.
+ */
master_signals [LAYOUT_CHANGED] =
g_signal_new ("layout-changed",
G_TYPE_FROM_CLASS (klass),
diff --git a/gdl/gdl-dock-master.h b/gdl/gdl-dock-master.h
index 4cf5cd7..ad5bd9b 100644
--- a/gdl/gdl-dock-master.h
+++ b/gdl/gdl-dock-master.h
@@ -83,6 +83,12 @@ struct _GdlDockMasterClass {
/* additional macros */
+/**
+ * GDL_DOCK_OBJECT_GET_MASTER:
+ * @object: A #GdlDockObject
+ *
+ * Evaluates to the #GdlDockMaster object managing the object.
+ */
#define GDL_DOCK_OBJECT_GET_MASTER(object) \
(GDL_DOCK_OBJECT (object)->master ? \
GDL_DOCK_MASTER (GDL_DOCK_OBJECT (object)->master) : NULL)
diff --git a/gdl/gdl-dock-notebook.c b/gdl/gdl-dock-notebook.c
index a89917d..ca6d726 100644
--- a/gdl/gdl-dock-notebook.c
+++ b/gdl/gdl-dock-notebook.c
@@ -177,9 +177,9 @@ gdl_dock_notebook_button_cb (GtkWidget *widget,
gpointer user_data)
{
if (event->type == GDK_BUTTON_PRESS)
- GDL_DOCK_ITEM_SET_FLAGS (user_data, GDL_DOCK_USER_ACTION);
+ GDL_DOCK_OBJECT_SET_FLAGS (user_data, GDL_DOCK_USER_ACTION);
else
- GDL_DOCK_ITEM_UNSET_FLAGS (user_data, GDL_DOCK_USER_ACTION);
+ GDL_DOCK_OBJECT_UNSET_FLAGS (user_data, GDL_DOCK_USER_ACTION);
return FALSE;
}
diff --git a/gdl/gdl-dock-object.c b/gdl/gdl-dock-object.c
index 2b6b08f..ee60ddf 100644
--- a/gdl/gdl-dock-object.c
+++ b/gdl/gdl-dock-object.c
@@ -207,6 +207,13 @@ gdl_dock_object_class_init (GdlDockObjectClass *klass)
klass->present = gdl_dock_object_real_present;
klass->child_placement = NULL;
+ /**
+ * GdlDockObject::detach:
+ * @item: The detached dock object.
+ * @recursive: %TRUE if children have to be detached too.
+ *
+ * Signals that the #GdlDockObject is detached.
+ **/
gdl_dock_object_signals [DETACH] =
g_signal_new ("detach",
G_TYPE_FROM_CLASS (klass),
@@ -219,6 +226,14 @@ gdl_dock_object_class_init (GdlDockObjectClass *klass)
1,
G_TYPE_BOOLEAN);
+ /**
+ * GdlDockObject::dock:
+ * @requestor: The widget to dock
+ * @position: The position for the child
+ * @other_data: (allow-none): Optional data giving additional information
+ *
+ * Signals that the #GdlDockObject has been docked.
+ **/
gdl_dock_object_signals [DOCK] =
g_signal_new ("dock",
G_TYPE_FROM_CLASS (klass),
diff --git a/gdl/gdl-dock-object.h b/gdl/gdl-dock-object.h
index 69089e5..0e83962 100644
--- a/gdl/gdl-dock-object.h
+++ b/gdl/gdl-dock-object.h
@@ -218,7 +218,7 @@ struct _GdlDockObjectClass {
/**
* GDL_DOCK_OBJECT_SET_FLAGS:
* @obj: A #GdlDockObject
- * @flags: One or more #GdlDockObjectFlags
+ * @flag: One or more #GdlDockObjectFlags
*
* Set one or more flags of a dock object.
*/
@@ -229,7 +229,7 @@ struct _GdlDockObjectClass {
/**
* GDL_DOCK_OBJECT_UNSET_FLAGS:
* @obj: A #GdlDockObject
- * @flags: One or more #GdlDockObjectFlags
+ * @flag: One or more #GdlDockObjectFlags
*
* Clear one or more flags of a dock object.
*/
@@ -306,7 +306,7 @@ GType gdl_dock_object_set_type_for_nick (const gchar *nick,
/* helper macros */
/**
* GDL_TRACE_OBJECT:
- * @obj: A #GdlDockObject
+ * @object: A #GdlDockObject
* @format: Additional printf format string
* @...: Additional arguments
*
diff --git a/gdl/gdl-dock-paned.c b/gdl/gdl-dock-paned.c
index 5367828..e5e6e16 100644
--- a/gdl/gdl-dock-paned.c
+++ b/gdl/gdl-dock-paned.c
@@ -180,9 +180,9 @@ gdl_dock_paned_button_cb (GtkWidget *widget,
paned = GDL_DOCK_PANED (user_data);
if (event->button == 1) {
if (event->type == GDK_BUTTON_PRESS)
- GDL_DOCK_ITEM_SET_FLAGS (user_data, GDL_DOCK_USER_ACTION);
+ GDL_DOCK_OBJECT_SET_FLAGS (user_data, GDL_DOCK_USER_ACTION);
else {
- GDL_DOCK_ITEM_UNSET_FLAGS (user_data, GDL_DOCK_USER_ACTION);
+ GDL_DOCK_OBJECT_UNSET_FLAGS (user_data, GDL_DOCK_USER_ACTION);
if (paned->position_changed) {
/* emit pending layout changed signal to track separator position */
if (GDL_DOCK_OBJECT (paned)->master)
diff --git a/gdl/gdl-dock.c b/gdl/gdl-dock.c
index be4b3d7..5525488 100644
--- a/gdl/gdl-dock.c
+++ b/gdl/gdl-dock.c
@@ -282,6 +282,12 @@ gdl_dock_class_init (GdlDockClass *klass)
/* signals */
+ /**
+ * GdlDock::layout-changed:
+ *
+ * Signals that the layout has changed, one or more widgets have been moved,
+ * added or removed.
+ */
dock_signals [LAYOUT_CHANGED] =
g_signal_new ("layout-changed",
G_TYPE_FROM_CLASS (klass),
diff --git a/gdl/gdl-dock.h b/gdl/gdl-dock.h
index 419a4f7..33d8f6c 100644
--- a/gdl/gdl-dock.h
+++ b/gdl/gdl-dock.h
@@ -51,6 +51,7 @@ struct _GdlDock {
};
struct _GdlDockClass {
+ /*< private >*/
GdlDockObjectClass parent_class;
void (* layout_changed) (GdlDock *dock); /* proxy signal for the master */
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
