[gdl] Document GdlDockObject
- From: Sebastien Granjoux <sgranjoux src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gdl] Document GdlDockObject
- Date: Sun, 20 May 2012 20:48:20 +0000 (UTC)
commit 51c6bb9080879f6239d62c7236d1757620513907
Author: SÃbastien Granjoux <seb sfo free fr>
Date: Sun May 20 19:13:15 2012 +0200
Document GdlDockObject
gdl/gdl-dock-master.c | 4 +-
gdl/gdl-dock-object.c | 270 ++++++++++++++++++++++++++++++++++++------------
gdl/gdl-dock-object.h | 127 +++++++++++++++++++++--
3 files changed, 323 insertions(+), 78 deletions(-)
---
diff --git a/gdl/gdl-dock-master.c b/gdl/gdl-dock-master.c
index edd704a..8cbb83b 100644
--- a/gdl/gdl-dock-master.c
+++ b/gdl/gdl-dock-master.c
@@ -41,7 +41,7 @@
* @title: GdlDockMaster
* @short_description: Manage all dock widgets
* @stability: Internal
- * @see_also: #GdlDockNotebook, #GdlDockPaned
+ * @see_also: #GdlDockObject, #GdlDockNotebook, #GdlDockPaned
*
* For the toplevel docks to be able to interact with each other, when the user
* drags items from one place to another, they're all kept in a user-invisible
@@ -49,6 +49,8 @@
* every #GdlDockObject must have the same master, the binding to the master is
* done automatically. The master also keeps track of the manual items,
* mostly those created with gdl_dock_*_new functions which are in the dock.
+ * This is so the user doesn't need to keep track of them, but can perform
+ * operations like hiding and such.
*
* The master is responsible for creating automatically compound widgets.
* When the user drops a widget on a simple one, a notebook or a paned compound
diff --git a/gdl/gdl-dock-object.c b/gdl/gdl-dock-object.c
index 6e67583..fdac720 100644
--- a/gdl/gdl-dock-object.c
+++ b/gdl/gdl-dock-object.c
@@ -1,4 +1,4 @@
-/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
*
* gdl-dock-object.c - Abstract base class for all dock related objects
*
@@ -41,6 +41,17 @@
#include "gdl-dock-notebook.h"
#include "gdl-dock-placeholder.h"
+/**
+ * SECTION:gdl-dock-object
+ * @title: GdlDockObject
+ * @short_description: Base class for all dock objects
+ * @stability: Unstable
+ * @see_also: #GdlDockMaster
+ *
+ * A #GdlDockObject is an abstract class which defines the basic interface
+ * for docking widgets.
+ */
+
/* ----- Private prototypes ----- */
@@ -118,6 +129,12 @@ gdl_dock_object_class_init (GdlDockObjectClass *klass)
g_object_class->get_property = gdl_dock_object_get_property;
g_object_class->finalize = gdl_dock_object_finalize;
+ /**
+ * GdlDockObject:name
+ *
+ * The object name. If the object is manual the name can be used
+ * to recall the object from any other object in the ring
+ */
g_object_class_install_property (
g_object_class, PROP_NAME,
g_param_spec_string (GDL_DOCK_NAME_PROPERTY, _("Name"),
@@ -126,6 +143,11 @@ gdl_dock_object_class_init (GdlDockObjectClass *klass)
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
GDL_DOCK_PARAM_EXPORT));
+ /**
+ * GdlDockObject:long-name
+ *
+ * A long descriptive name.
+ */
g_object_class_install_property (
g_object_class, PROP_LONG_NAME,
g_param_spec_string ("long-name", _("Long name"),
@@ -133,6 +155,11 @@ gdl_dock_object_class_init (GdlDockObjectClass *klass)
NULL,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
+ /**
+ * GdlDockObject:stock-id
+ *
+ * A stock id to use for the icon of the dock object.
+ */
g_object_class_install_property (
g_object_class, PROP_STOCK_ID,
g_param_spec_string ("stock-id", _("Stock Icon"),
@@ -146,27 +173,32 @@ gdl_dock_object_class_init (GdlDockObjectClass *klass)
* A GdkPixbuf to use for the icon of the dock object.
*
* Since: 3.3.2
- */
+ */
g_object_class_install_property (
g_object_class, PROP_PIXBUF_ICON,
g_param_spec_pointer ("pixbuf-icon", _("Pixbuf Icon"),
_("Pixbuf icon for the dock object"),
G_PARAM_READWRITE));
+ /**
+ * GdlDockObject:master
+ *
+ * The master which manages all the objects in a dock ring
+ */
g_object_class_install_property (
g_object_class, PROP_MASTER,
g_param_spec_object ("master", _("Dock master"),
_("Dock master this dock object is bound to"),
GDL_TYPE_DOCK_MASTER,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
-
+
widget_class->destroy = gdl_dock_object_destroy;
-
+
widget_class->show = gdl_dock_object_show;
widget_class->hide = gdl_dock_object_hide;
-
+
klass->is_compound = TRUE;
-
+
klass->detach = gdl_dock_object_real_detach;
klass->reduce = gdl_dock_object_real_reduce;
klass->dock_request = NULL;
@@ -174,7 +206,7 @@ gdl_dock_object_class_init (GdlDockObjectClass *klass)
klass->reorder = NULL;
klass->present = gdl_dock_object_real_present;
klass->child_placement = NULL;
-
+
gdl_dock_object_signals [DETACH] =
g_signal_new ("detach",
G_TYPE_FROM_CLASS (klass),
@@ -234,7 +266,7 @@ gdl_dock_object_set_property (GObject *g_object,
object->pixbuf_icon = g_value_get_pointer (value);
break;
case PROP_MASTER:
- if (g_value_get_object (value))
+ if (g_value_get_object (value))
gdl_dock_object_bind (object, g_value_get_object (value));
else
gdl_dock_object_unbind (object);
@@ -319,11 +351,11 @@ gdl_dock_object_destroy (GtkWidget *dock_object)
/* detach ourselves */
gdl_dock_object_detach (object, FALSE);
}
-
+
/* finally unbind us */
if (object->master)
gdl_dock_object_unbind (object);
-
+
GTK_WIDGET_CLASS(gdl_dock_object_parent_class)->destroy (dock_object);
}
@@ -365,7 +397,7 @@ gdl_dock_object_real_detach (GdlDockObject *object,
{
GdlDockObject *parent;
GtkWidget *widget;
-
+
g_return_if_fail (object != NULL);
/* detach children */
@@ -374,7 +406,7 @@ gdl_dock_object_real_detach (GdlDockObject *object,
(GtkCallback) gdl_dock_object_detach,
GINT_TO_POINTER (recursive));
}
-
+
/* detach the object itself */
GDL_DOCK_OBJECT_UNSET_FLAGS (object, GDL_DOCK_ATTACHED);
parent = gdl_dock_object_get_parent_object (object);
@@ -390,7 +422,7 @@ gdl_dock_object_real_reduce (GdlDockObject *object)
{
GdlDockObject *parent;
GList *children;
-
+
g_return_if_fail (object != NULL);
if (!gdl_dock_object_is_compound (object))
@@ -401,7 +433,7 @@ gdl_dock_object_real_reduce (GdlDockObject *object)
if (g_list_length (children) <= 1) {
GList *l;
GList *dchildren = NULL;
-
+
/* detach ourselves and then re-attach our children to our
current parent. if we are not currently attached, the
children are detached */
@@ -412,16 +444,16 @@ gdl_dock_object_real_reduce (GdlDockObject *object)
* way the children can have access to the whole object hierarchy.
* Set the InDetach flag now, so the children know that this object
* is going to be detached. */
-
-
+
+
GDL_DOCK_OBJECT_SET_FLAGS (object, GDL_DOCK_IN_DETACH);
-
+
for (l = children; l; l = l->next) {
GdlDockObject *child;
-
+
if (!GDL_IS_DOCK_OBJECT (l->data))
continue;
-
+
child = GDL_DOCK_OBJECT (l->data);
g_object_ref (child);
@@ -433,7 +465,7 @@ gdl_dock_object_real_reduce (GdlDockObject *object)
}
/* Now it can be detached */
gdl_dock_object_detach (object, FALSE);
-
+
/* After detaching the reduced object, we can add the
children (the only child in fact) to the new parent */
for (l = dchildren; l; l = l->next) {
@@ -441,8 +473,8 @@ gdl_dock_object_real_reduce (GdlDockObject *object)
g_object_unref (l->data);
}
g_list_free (dchildren);
-
-
+
+
/* sink the widget, so any automatic floating widget is destroyed */
g_object_ref_sink (object);
/* don't reenter */
@@ -465,7 +497,7 @@ gdl_dock_object_dock_unimplemented (GdlDockObject *object,
object, G_OBJECT_TYPE_NAME (object));
}
-static void
+static void
gdl_dock_object_real_present (GdlDockObject *object,
GdlDockObject *child)
{
@@ -475,6 +507,14 @@ gdl_dock_object_real_present (GdlDockObject *object,
/* ----- Public interface ----- */
+/**
+ * gdl_dock_object_is_compound:
+ * @object: A #GdlDockObject
+ *
+ * Check if an object is a compound object, accepting children widget or not.
+ *
+ * Returns: %TRUE if @object is a compound object.
+ */
gboolean
gdl_dock_object_is_compound (GdlDockObject *object)
{
@@ -487,6 +527,13 @@ gdl_dock_object_is_compound (GdlDockObject *object)
return klass->is_compound;
}
+/**
+ * gdl_dock_object_detach:
+ * @object: A #GdlDockObject
+ * @recursive: %TRUE to detach children
+ *
+ * Dissociate a dock object from its parent, including or not its children.
+ */
void
gdl_dock_object_detach (GdlDockObject *object,
gboolean recursive)
@@ -495,10 +542,10 @@ gdl_dock_object_detach (GdlDockObject *object,
if (!GDL_IS_DOCK_OBJECT (object))
return;
-
+
if (!GDL_DOCK_OBJECT_ATTACHED (object))
return;
-
+
/* freeze the object to avoid reducing while detaching children */
gdl_dock_object_freeze (object);
GDL_DOCK_OBJECT_SET_FLAGS (object, GDL_DOCK_IN_DETACH);
@@ -507,26 +554,41 @@ gdl_dock_object_detach (GdlDockObject *object,
gdl_dock_object_thaw (object);
}
+/**
+ * gdl_dock_object_get_parent_object:
+ * @object: A #GdlDockObject
+ *
+ * Returns a parent #GdlDockObject if it exists.
+ *
+ * Returns: a #GdlDockObject or %NULL if such object does not exist.
+ */
GdlDockObject *
gdl_dock_object_get_parent_object (GdlDockObject *object)
{
GtkWidget *parent;
-
+
g_return_val_if_fail (object != NULL, NULL);
parent = gtk_widget_get_parent (GTK_WIDGET (object));
while (parent && !GDL_IS_DOCK_OBJECT (parent)) {
parent = gtk_widget_get_parent (parent);
}
-
+
return parent ? GDL_DOCK_OBJECT (parent) : NULL;
}
+/**
+ * gdl_dock_object_freeze:
+ * @object: A #GdlDockObject
+ *
+ * Temporarily freezes a dock object, any call to reduce on the object has no
+ * immediate effect.
+ */
void
gdl_dock_object_freeze (GdlDockObject *object)
{
g_return_if_fail (object != NULL);
-
+
if (object->freeze_count == 0) {
g_object_ref (object); /* dock objects shouldn't be
destroyed if they are frozen */
@@ -534,12 +596,20 @@ gdl_dock_object_freeze (GdlDockObject *object)
object->freeze_count++;
}
+/**
+ * gdl_dock_object_thaw:
+ * @object: A #GdlDockObject
+ *
+ * Thaws a dock object frozen with gdl_dock_object_freeze().
+ * Any pending reduce calls are made, maybe leading to the destruction of
+ * the object.
+ */
void
gdl_dock_object_thaw (GdlDockObject *object)
{
g_return_if_fail (object != NULL);
g_return_if_fail (object->freeze_count > 0);
-
+
object->freeze_count--;
if (object->freeze_count == 0) {
if (object->reduce_pending) {
@@ -550,6 +620,13 @@ gdl_dock_object_thaw (GdlDockObject *object)
}
}
+/**
+ * gdl_dock_object_reduce:
+ * @object: A #GdlDockObject
+ *
+ * Remove a compound object if it is not longer useful to hold the child. The
+ * object has to be removed and the child reattached to the parent.
+ */
void
gdl_dock_object_reduce (GdlDockObject *object)
{
@@ -564,6 +641,17 @@ gdl_dock_object_reduce (GdlDockObject *object)
GDL_DOCK_OBJECT_GET_CLASS (object)->reduce (object);
}
+/**
+ * gdl_dock_object_dock_request:
+ * @object: A #GdlDockObject
+ * @x: X coordinate
+ * @y: Y coordinate
+ * @request: A #GdlDockRequest with information about the docking position
+ *
+ * Dock a dock widget in @object at the defined position.
+ *
+ * Returns: %TRUE if @object has been docked.
+ */
gboolean
gdl_dock_object_dock_request (GdlDockObject *object,
gint x,
@@ -580,11 +668,14 @@ gdl_dock_object_dock_request (GdlDockObject *object,
/**
* gdl_dock_object_dock:
- * @object:
- * @requestor:
- * @position:
- * @other_data: (allow-none):
- **/
+ * @object: A #GdlDockObject
+ * @requestor: The widget to dock
+ * @position: The position for the child
+ * @other_data: (allow-none): Optional data giving additional information
+ * depending on the dock object.
+ *
+ * Dock a dock widget in @object at the defined position.
+ */
void
gdl_dock_object_dock (GdlDockObject *object,
GdlDockObject *requestor,
@@ -592,16 +683,16 @@ gdl_dock_object_dock (GdlDockObject *object,
GValue *other_data)
{
GdlDockObject *parent;
-
+
g_return_if_fail (object != NULL && requestor != NULL);
-
+
if (object == requestor)
return;
-
+
if (!object->master)
g_warning (_("Dock operation requested in a non-bound object %p. "
"The application might crash"), object);
-
+
if (!gdl_dock_object_is_bound (requestor))
gdl_dock_object_bind (requestor, object->master);
@@ -618,7 +709,7 @@ gdl_dock_object_dock (GdlDockObject *object,
(parent && gdl_dock_object_reorder (parent, requestor, position, other_data)))
return;
}
-
+
/* freeze the object, since under some conditions it might be destroyed when
detaching the requestor */
gdl_dock_object_freeze (object);
@@ -627,7 +718,7 @@ gdl_dock_object_dock (GdlDockObject *object,
g_object_ref (requestor);
if (GDL_DOCK_OBJECT_ATTACHED (requestor))
gdl_dock_object_detach (requestor, FALSE);
-
+
if (position != GDL_DOCK_NONE)
g_signal_emit (object, gdl_dock_object_signals [DOCK], 0,
requestor, position, other_data);
@@ -636,17 +727,25 @@ gdl_dock_object_dock (GdlDockObject *object,
gdl_dock_object_thaw (object);
}
+/**
+ * gdl_dock_object_bind:
+ * @object: A #GdlDockObject
+ * @master: A #GdlDockMaster
+ *
+ * Add a link between a #GdlDockObject and a master. It is normally not used
+ * directly because it is automatically called when a new object is docked.
+ */
void
gdl_dock_object_bind (GdlDockObject *object,
GObject *master)
{
g_return_if_fail (object != NULL && master != NULL);
g_return_if_fail (GDL_IS_DOCK_MASTER (master));
-
+
if (object->master == master)
/* nothing to do here */
return;
-
+
if (object->master) {
g_warning (_("Attempt to bind to %p an already bound dock object %p "
"(current master: %p)"), master, object, object->master);
@@ -660,6 +759,12 @@ gdl_dock_object_bind (GdlDockObject *object,
g_object_notify (G_OBJECT (object), "master");
}
+/**
+ * gdl_dock_object_unbind:
+ * @object: A #GdlDockObject
+ *
+ * This removes the link between an dock object and its master.
+ */
void
gdl_dock_object_unbind (GdlDockObject *object)
{
@@ -670,7 +775,7 @@ gdl_dock_object_unbind (GdlDockObject *object)
/* detach the object first */
if (GDL_DOCK_OBJECT_ATTACHED (object))
gdl_dock_object_detach (object, TRUE);
-
+
if (object->master) {
GObject *master = object->master;
g_object_remove_weak_pointer (master, (gpointer *) &object->master);
@@ -681,6 +786,14 @@ gdl_dock_object_unbind (GdlDockObject *object)
g_object_unref (object);
}
+/**
+ * gdl_dock_object_is_bound:
+ * @object: A #GdlDockObject
+ *
+ * Check if the object is bound to a master.
+ *
+ * Returns: %TRUE if @object has a master
+ */
gboolean
gdl_dock_object_is_bound (GdlDockObject *object)
{
@@ -688,6 +801,18 @@ gdl_dock_object_is_bound (GdlDockObject *object)
return (object->master != NULL);
}
+/**
+ * gdl_dock_object_reorder:
+ * @object: A #GdlDockObject
+ * @child: The child widget to reorder
+ * @new_position: New position for the child
+ * @other_data: (allow-none): Optional data giving additional information
+ * depending on the dock object.
+ *
+ * Move the @child widget at another place.
+ *
+ * Returns: %TRUE if @child has been moved
+ */
gboolean
gdl_dock_object_reorder (GdlDockObject *object,
GdlDockObject *child,
@@ -702,12 +827,21 @@ gdl_dock_object_reorder (GdlDockObject *object,
return FALSE;
}
-void
+/**
+ * gdl_dock_object_present:
+ * @object: A #GdlDockObject
+ * @child: The child widget to present or %NULL
+ *
+ * Presents the GDL object to the user. By example, this will select the
+ * corresponding page if the object is in a notebook. If @child is missing,
+ * only the @object will be show.
+ */
+void
gdl_dock_object_present (GdlDockObject *object,
GdlDockObject *child)
{
GdlDockObject *parent;
-
+
g_return_if_fail (object != NULL && GDL_IS_DOCK_OBJECT (object));
parent = gdl_dock_object_get_parent_object (object);
@@ -738,7 +872,7 @@ gdl_dock_object_present (GdlDockObject *object,
*
* Returns: %TRUE if @child is a child of @object.
*/
-gboolean
+gboolean
gdl_dock_object_child_placement (GdlDockObject *object,
GdlDockObject *child,
GdlDockPlacement *placement)
@@ -748,7 +882,7 @@ gdl_dock_object_child_placement (GdlDockObject *object,
/* simple case */
if (!gdl_dock_object_is_compound (object))
return FALSE;
-
+
if (GDL_DOCK_OBJECT_GET_CLASS (object)->child_placement)
return GDL_DOCK_OBJECT_GET_CLASS (object)->child_placement (object, child, placement);
else
@@ -758,35 +892,35 @@ gdl_dock_object_child_placement (GdlDockObject *object,
/* ----- dock param type functions start here ------ */
-static void
+static void
gdl_dock_param_export_int (const GValue *src,
GValue *dst)
{
dst->data [0].v_pointer = g_strdup_printf ("%d", src->data [0].v_int);
}
-static void
+static void
gdl_dock_param_export_uint (const GValue *src,
GValue *dst)
{
dst->data [0].v_pointer = g_strdup_printf ("%u", src->data [0].v_uint);
}
-static void
+static void
gdl_dock_param_export_string (const GValue *src,
GValue *dst)
{
dst->data [0].v_pointer = g_strdup (src->data [0].v_pointer);
}
-static void
+static void
gdl_dock_param_export_bool (const GValue *src,
GValue *dst)
{
dst->data [0].v_pointer = g_strdup_printf ("%s", src->data [0].v_int ? "yes" : "no");
}
-static void
+static void
gdl_dock_param_export_placement (const GValue *src,
GValue *dst)
{
@@ -815,35 +949,35 @@ gdl_dock_param_export_placement (const GValue *src,
}
}
-static void
+static void
gdl_dock_param_import_int (const GValue *src,
GValue *dst)
{
dst->data [0].v_int = atoi (src->data [0].v_pointer);
}
-static void
+static void
gdl_dock_param_import_uint (const GValue *src,
GValue *dst)
{
dst->data [0].v_uint = (guint) atoi (src->data [0].v_pointer);
}
-static void
+static void
gdl_dock_param_import_string (const GValue *src,
GValue *dst)
{
dst->data [0].v_pointer = g_strdup (src->data [0].v_pointer);
}
-static void
+static void
gdl_dock_param_import_bool (const GValue *src,
GValue *dst)
{
dst->data [0].v_int = !strcmp (src->data [0].v_pointer, "yes");
}
-static void
+static void
gdl_dock_param_import_placement (const GValue *src,
GValue *dst)
{
@@ -902,9 +1036,9 @@ gdl_dock_object_register_init (void)
if (dock_register)
return;
- dock_register
+ dock_register
= g_array_new (FALSE, FALSE, sizeof (struct DockRegisterItem));
-
+
/* add known types */
default_items[0].nick = "dock";
default_items[0].type = (gpointer) GDL_TYPE_DOCK;
@@ -935,18 +1069,18 @@ gdl_dock_object_nick_from_type (GType type)
{
gchar *nick = NULL;
guint i = 0;
-
+
if (!dock_register)
gdl_dock_object_register_init ();
for (i=0; i < dock_register->len; i++) {
- struct DockRegisterItem item
+ struct DockRegisterItem item
= g_array_index (dock_register, struct DockRegisterItem, i);
if (g_direct_equal (item.type, (gpointer) type))
nick = g_strdup (item.nick);
}
-
+
return nick ? nick : g_type_name (type);
}
@@ -965,12 +1099,12 @@ gdl_dock_object_type_from_nick (const gchar *nick)
GType type = G_TYPE_NONE;
gboolean nick_is_in_register = FALSE;
guint i = 0;
-
+
if (!dock_register)
gdl_dock_object_register_init ();
for (i = 0; i < dock_register->len; i++) {
- struct DockRegisterItem item
+ struct DockRegisterItem item
= g_array_index (dock_register, struct DockRegisterItem, i);
if (!g_strcmp0 (nick, item.nick)) {
@@ -982,7 +1116,7 @@ gdl_dock_object_type_from_nick (const gchar *nick)
/* try searching in the glib type system */
type = g_type_from_name (nick);
}
-
+
return type;
}
@@ -1006,14 +1140,14 @@ gdl_dock_object_set_type_for_nick (const gchar *nick,
struct DockRegisterItem new_item;
new_item.nick = g_strdup(nick);
new_item.type = (gpointer) type;
-
+
if (!dock_register)
gdl_dock_object_register_init ();
g_return_val_if_fail (g_type_is_a (type, GDL_TYPE_DOCK_OBJECT), G_TYPE_NONE);
-
+
for (i = 0; i < dock_register->len; i++) {
- struct DockRegisterItem item
+ struct DockRegisterItem item
= g_array_index (dock_register, struct DockRegisterItem, i);
if (!g_strcmp0 (nick, item.nick)) {
diff --git a/gdl/gdl-dock-object.h b/gdl/gdl-dock-object.h
index 09d912b..69089e5 100644
--- a/gdl/gdl-dock-object.h
+++ b/gdl/gdl-dock-object.h
@@ -1,4 +1,4 @@
-/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
*
* gdl-dock-object.h - Abstract base class for all dock related objects
*
@@ -37,6 +37,16 @@ G_BEGIN_DECLS
#define GDL_DOCK_OBJECT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_DOCK_OBJECT, GdlDockObjectClass))
/* data types & structures */
+
+/**
+ * GdlDockParamFlags:
+ * @GDL_DOCK_PARAM_EXPORT: The parameter is to be exported for later layout rebuilding
+ * @GDL_DOCK_PARAM_AFTER: The parameter must be set after adding the children objects
+ *
+ * Used to flag additional characteristics to GObject properties used in dock
+ * object.
+ *
+ **/
typedef enum {
/* the parameter is to be exported for later layout rebuilding */
GDL_DOCK_PARAM_EXPORT = 1 << G_PARAM_USER_SHIFT,
@@ -47,6 +57,16 @@ typedef enum {
#define GDL_DOCK_NAME_PROPERTY "name"
#define GDL_DOCK_MASTER_PROPERTY "master"
+/**
+ * GdlDockObjectFlags:
+ * @GDL_DOCK_AUTOMATIC: Object is created and destroyed by the master, not the user
+ * @GDL_DOCK_ATTACHED: Object has a parent
+ * @GDL_DOCK_IN_REFLOW: Object is currently part of a rearrangement
+ * @GDL_DOCK_IN_DETACH: Object will be removed
+ *
+ * Described the state of a #GdlDockObject.
+ *
+ **/
typedef enum {
GDL_DOCK_AUTOMATIC = 1 << 0,
GDL_DOCK_ATTACHED = 1 << 1,
@@ -56,6 +76,19 @@ typedef enum {
#define GDL_DOCK_OBJECT_FLAGS_SHIFT 8
+/**
+ * GdlDockPlacement:
+ * @GDL_DOCK_NONE: No position defined
+ * @GDL_DOCK_TOP: Dock object on the top
+ * @GDL_DOCK_BOTTOM: Dock object on the bottom
+ * @GDL_DOCK_RIGHT: Dock object on the right
+ * @GDL_DOCK_LEFT: Dock object on the left
+ * @GDL_DOCK_CENTER: Dock object on top of the other
+ * @GDL_DOCK_FLOATING: Dock object in its own window
+ *
+ * Described the docking position.
+ *
+ **/
typedef enum {
GDL_DOCK_NONE = 0,
GDL_DOCK_TOP,
@@ -70,6 +103,16 @@ typedef struct _GdlDockObject GdlDockObject;
typedef struct _GdlDockObjectClass GdlDockObjectClass;
typedef struct _GdlDockRequest GdlDockRequest;
+/**
+ * GdlDockRequest:
+ * @applicant: A #GdlDockObject to dock
+ * @target: The #GdlDockObject target
+ * @position: how to dock @applicant in @target
+ * @rect: Precise position
+ * @extra: Additional information
+ *
+ * Full docking information.
+ **/
struct _GdlDockRequest {
GdlDockObject *applicant;
GdlDockObject *target;
@@ -83,13 +126,13 @@ struct _GdlDockObject {
GdlDockObjectFlags flags;
gint freeze_count;
-
+
GObject *master;
gchar *name;
gchar *long_name;
gchar *stock_id;
GdkPixbuf *pixbuf_icon;
-
+
gboolean reduce_pending;
};
@@ -97,7 +140,7 @@ struct _GdlDockObjectClass {
GtkContainerClass parent_class;
gboolean is_compound;
-
+
void (* detach) (GdlDockObject *object,
gboolean recursive);
void (* reduce) (GdlDockObject *object);
@@ -111,7 +154,7 @@ struct _GdlDockObjectClass {
GdlDockObject *requestor,
GdlDockPlacement position,
GValue *other_data);
-
+
gboolean (* reorder) (GdlDockObject *object,
GdlDockObject *child,
GdlDockPlacement new_position,
@@ -126,26 +169,84 @@ struct _GdlDockObjectClass {
};
/* additional macros */
+
+/**
+ * GDL_DOCK_OBJECT_FLAGS:
+ * @obj: A #GdlDockObject
+ *
+ * Get all flags of #GdlDockObject.
+ */
#define GDL_DOCK_OBJECT_FLAGS(obj) (GDL_DOCK_OBJECT (obj)->flags)
+
+/**
+ * GDL_DOCK_OBJECT_AUTOMATIC:
+ * @obj: A #GdlDockObject
+ *
+ * Evaluates to %TRUE if the object's lifecycle is entirely managed by the dock
+ * master.
+ */
#define GDL_DOCK_OBJECT_AUTOMATIC(obj) \
((GDL_DOCK_OBJECT_FLAGS (obj) & GDL_DOCK_AUTOMATIC) != 0)
+
+/**
+ * GDL_DOCK_OBJECT_ATTACHED:
+ * @obj: A #GdlDockObject
+ *
+ * Evaluates to %TRUE if the object has a parent.
+ */
#define GDL_DOCK_OBJECT_ATTACHED(obj) \
((GDL_DOCK_OBJECT_FLAGS (obj) & GDL_DOCK_ATTACHED) != 0)
+
+/**
+ * GDL_DOCK_OBJECT_IN_REFLOW:
+ * @obj: A #GdlDockObject
+ *
+ * Evaluates to %TRUE if the object is currently rearranged.
+ */
#define GDL_DOCK_OBJECT_IN_REFLOW(obj) \
((GDL_DOCK_OBJECT_FLAGS (obj) & GDL_DOCK_IN_REFLOW) != 0)
+
+/**
+ * GDL_DOCK_OBJECT_IN_DETACH:
+ * @obj: A #GdlDockObject
+ *
+ * Evaluates to %TRUE if the object will be detached.
+ */
#define GDL_DOCK_OBJECT_IN_DETACH(obj) \
((GDL_DOCK_OBJECT_FLAGS (obj) & GDL_DOCK_IN_DETACH) != 0)
+/**
+ * GDL_DOCK_OBJECT_SET_FLAGS:
+ * @obj: A #GdlDockObject
+ * @flags: One or more #GdlDockObjectFlags
+ *
+ * Set one or more flags of a dock object.
+ */
#define GDL_DOCK_OBJECT_SET_FLAGS(obj,flag) \
G_STMT_START { (GDL_DOCK_OBJECT_FLAGS (obj) |= (flag)); } G_STMT_END
+
+
+/**
+ * GDL_DOCK_OBJECT_UNSET_FLAGS:
+ * @obj: A #GdlDockObject
+ * @flags: One or more #GdlDockObjectFlags
+ *
+ * Clear one or more flags of a dock object.
+ */
#define GDL_DOCK_OBJECT_UNSET_FLAGS(obj,flag) \
G_STMT_START { (GDL_DOCK_OBJECT_FLAGS (obj) &= ~(flag)); } G_STMT_END
-
+
+/**
+ * GDL_DOCK_OBJECT_FROZEN:
+ * @obj: A #GdlDockObject
+ *
+ * Evaluates to %TRUE if the object is frozen.
+ */
#define GDL_DOCK_OBJECT_FROZEN(obj) (GDL_DOCK_OBJECT (obj)->freeze_count > 0)
/* public interface */
-
+
GType gdl_dock_object_get_type (void);
gboolean gdl_dock_object_is_compound (GdlDockObject *object);
@@ -203,6 +304,14 @@ GType gdl_dock_object_set_type_for_nick (const gchar *nick,
/* helper macros */
+/**
+ * GDL_TRACE_OBJECT:
+ * @obj: A #GdlDockObject
+ * @format: Additional printf format string
+ * @...: Additional arguments
+ *
+ * Output a debugging message for the corresponding dock object.
+ */
#define GDL_TRACE_OBJECT(object, format, args...) \
G_STMT_START { \
g_log (G_LOG_DOMAIN, \
@@ -215,8 +324,8 @@ GType gdl_dock_object_set_type_for_nick (const gchar *nick,
G_OBJECT (object)->ref_count, \
(GTK_IS_OBJECT (object) && g_object_is_floating (object)) ? "(float)" : "", \
GDL_IS_DOCK_OBJECT (object) ? GDL_DOCK_OBJECT (object)->freeze_count : -1, \
- ##args); } G_STMT_END
-
+ ##args); } G_STMT_END
+
G_END_DECLS
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
