gdl r514 - in trunk: . docs/reference gdl

From: jhs svn gnome org
To: svn-commits-list gnome org
Subject: gdl r514 - in trunk: . docs/reference gdl
Date: Sun, 8 Feb 2009 11:08:45 +0000 (UTC)
Author: jhs
Date: Sun Feb  8 11:08:45 2009
New Revision: 514
URL: http://svn.gnome.org/viewvc/gdl?rev=514&view=rev

Log:
2009-02-08  Johannes Schmid  <jhs gnome org>

        * docs/reference/gdl-docs.sgml:
        * docs/reference/gdl-sections.txt:
        Fixed some documentation issues.

        * gdl/gdl-dock-item-grip.c (gdl_dock_item_grip_instance_init):
        * gdl/gdl-dock-item.c (gdl_dock_item_class_init):
        Patch from Joel Holdsworth <joel airwebreathe org uk>:
        - Add documentation comments



Modified:
   trunk/ChangeLog
   trunk/docs/reference/gdl-docs.sgml
   trunk/docs/reference/gdl-sections.txt
   trunk/gdl/gdl-dock-item-grip.c
   trunk/gdl/gdl-dock-item.c

Modified: trunk/docs/reference/gdl-docs.sgml
==============================================================================
--- trunk/docs/reference/gdl-docs.sgml	(original)
+++ trunk/docs/reference/gdl-docs.sgml	Sun Feb  8 11:08:45 2009
@@ -11,21 +11,18 @@
 
   <chapter id="gdl-main">
     <title>GDL - Gnome Development/Docking library</title>
-    <xi:include href="xml/gdl-dock-layout.xml"/>
-    <xi:include href="xml/gdl-dock-master.xml"/>
-    <xi:include href="xml/gdl-dock-item-grip.xml"/>
-    <xi:include href="xml/gdl-icons.xml"/>
-    <xi:include href="xml/gdl-dock-item.xml"/>
-    <xi:include href="xml/gdl-dock.xml"/>
-    <xi:include href="xml/gdl-dock-object.xml"/>
-    <xi:include href="xml/gdl-dock-tablabel.xml"/>
-    <xi:include href="xml/gdl-dock-notebook.xml"/>
-    <xi:include href="xml/gdl-dock-placeholder.xml"/>
-    <xi:include href="xml/gdl-combo-button.xml"/>
-    <xi:include href="xml/gdl-dock-paned.xml"/>
-    <xi:include href="xml/gdl-dock-bar.xml"/>
-    <xi:include href="xml/gdl-switcher.xml"/>
-    <xi:include href="xml/gdl-stock.xml"/>
-    <xi:include href="xml/gdl-tools.xml"/>
+    <xi:include href="xml/gdl-dock-layout.xml" />
+    <xi:include href="xml/gdl-dock-master.xml" />
+    <xi:include href="xml/gdl-dock-item.xml" />
+    <xi:include href="xml/gdl-dock.xml" />
+    <xi:include href="xml/gdl-dock-object.xml" />
+    <xi:include href="xml/gdl-dock-tablabel.xml" />
+    <xi:include href="xml/gdl-dock-notebook.xml" />
+    <xi:include href="xml/gdl-dock-placeholder.xml" />
+    <xi:include href="xml/gdl-combo-button.xml" />
+    <xi:include href="xml/gdl-dock-paned.xml" />
+    <xi:include href="xml/gdl-dock-bar.xml" />
+    <xi:include href="xml/gdl-switcher.xml" />
+    <xi:include href="xml/gdl-tools.xml" />
   </chapter>
 </book>

Modified: trunk/docs/reference/gdl-sections.txt
==============================================================================
--- trunk/docs/reference/gdl-sections.txt	(original)
+++ trunk/docs/reference/gdl-sections.txt	Sun Feb  8 11:08:45 2009
@@ -27,27 +27,6 @@
 </SECTION>
 
 <SECTION>
-<FILE>gdl-data-model</FILE>
-GdlDataModel
-GdlDataIter
-GdlDataModelIface
-gdl_data_model_get_iter
-gdl_data_model_get_path
-gdl_data_model_get_name
-gdl_data_model_get_value
-gdl_data_model_get_renderer
-gdl_data_model_iter_next
-gdl_data_model_iter_children
-gdl_data_model_iter_has_child
-<SUBSECTION Standard>
-GDL_DATA_MODEL
-GDL_IS_DATA_MODEL
-GDL_TYPE_DATA_MODEL
-gdl_data_model_get_type
-GDL_DATA_MODEL_GET_IFACE
-</SECTION>
-
-<SECTION>
 <FILE>gdl-dock-master</FILE>
 GdlDockMasterPrivate
 <TITLE>GdlDockMaster</TITLE>
@@ -273,32 +252,6 @@
 </SECTION>
 
 <SECTION>
-<FILE>gdl-data-row</FILE>
-GdlDataRowPrivate
-<TITLE>GdlDataRow</TITLE>
-GdlDataRow
-gdl_data_row_new
-gdl_data_row_get_size
-gdl_data_row_set_show_name
-gdl_data_row_layout
-gdl_data_row_render
-gdl_data_row_at
-gdl_data_row_event
-gdl_data_row_get_cell_area
-gdl_data_row_set_split
-gdl_data_row_set_selected
-gdl_data_row_set_focused
-gdl_data_row_get_title
-<SUBSECTION Standard>
-GDL_DATA_ROW
-GDL_IS_DATA_ROW
-GDL_TYPE_DATA_ROW
-gdl_data_row_get_type
-GDL_DATA_ROW_CLASS
-GDL_IS_DATA_ROW_CLASS
-</SECTION>
-
-<SECTION>
 <FILE>gdl-dock-bar</FILE>
 GdlDockBarPrivate
 GdlDockBarStyle

Modified: trunk/gdl/gdl-dock-item-grip.c
==============================================================================
--- trunk/gdl/gdl-dock-item-grip.c	(original)
+++ trunk/gdl/gdl-dock-item-grip.c	Sun Feb  8 11:08:45 2009
@@ -328,6 +328,7 @@
     grip->_priv->icon_pixbuf = NULL;
     grip->_priv->title_layout = NULL;
 
+    /* create the close button */
     gtk_widget_push_composite_child ();
     grip->_priv->close_button = gtk_button_new ();
     gtk_widget_pop_composite_child ();
@@ -344,6 +345,7 @@
     g_signal_connect (G_OBJECT (grip->_priv->close_button), "clicked",
                       G_CALLBACK (gdl_dock_item_grip_close_clicked), grip);
 
+    /* create the iconify button */
     gtk_widget_push_composite_child ();
     grip->_priv->iconify_button = gtk_button_new ();
     gtk_widget_pop_composite_child ();
@@ -360,6 +362,7 @@
     g_signal_connect (G_OBJECT (grip->_priv->iconify_button), "clicked",
                       G_CALLBACK (gdl_dock_item_grip_iconify_clicked), grip);
 
+    /* set tooltips on the buttons */
     gtk_widget_set_tooltip_text (grip->_priv->iconify_button,
                           _("Iconify this dock"));
     gtk_widget_set_tooltip_text (grip->_priv->close_button,
@@ -681,6 +684,15 @@
     gdl_stock_init ();
 }
 
+/* ----- Public interface ----- */
+
+/**
+ * gdl_dock_item_grip_new:
+ * @item: The dock item that will "own" this grip widget.
+ * 
+ * Creates a new GDL dock item grip object.
+ * Returns: The newly created dock item grip widget.
+ **/
 GtkWidget *
 gdl_dock_item_grip_new (GdlDockItem *item)
 {

Modified: trunk/gdl/gdl-dock-item.c
==============================================================================
--- trunk/gdl/gdl-dock-item.c	(original)
+++ trunk/gdl/gdl-dock-item.c	Sun Feb  8 11:08:45 2009
@@ -238,6 +238,16 @@
 
     /* properties */
 
+    /**
+     * GdlDockItem:orientation:
+     *
+     * The orientation of the docking item. If the orientation is set to
+     * #GTK_ORIENTATION_VERTICAL, the grip widget will be shown along
+     * the top of the edge of item (if it is not hidden). If the
+     * orientation is set to #GTK_ORIENTATION_HORIZONTAL, the grip
+     * widget will be shown down the left edge of the item (even if the
+     * widget text direction is set to RTL).
+     */
     g_object_class_install_property (
         g_object_class, PROP_ORIENTATION,
         g_param_spec_enum ("orientation", _("Orientation"),
@@ -296,6 +306,12 @@
 
     /* signals */
     
+    /**
+     * GdlDockItem::dock-drag-begin:
+     * @item: The dock item which is being dragged.
+     * 
+     * Signals that the dock item has begun to be dragged.
+     **/
     gdl_dock_item_signals [DOCK_DRAG_BEGIN] = 
         g_signal_new ("dock-drag-begin",
                       G_TYPE_FROM_CLASS (klass),
@@ -306,7 +322,15 @@
                       gdl_marshal_VOID__VOID,
                       G_TYPE_NONE, 
                       0);
-
+    
+    /**
+     * GdlDockItem::dock-drag-motion:
+     * @item: The dock item which is being dragged.
+     * @x: The x-position that the dock item has been dragged to.
+     * @y: The y-position that the dock item has been dragged to.
+     * 
+     * Signals that a dock item dragging motion event has occured.
+     **/
     gdl_dock_item_signals [DOCK_DRAG_MOTION] = 
         g_signal_new ("dock-drag-motion",
                       G_TYPE_FROM_CLASS (klass),
@@ -320,6 +344,14 @@
                       G_TYPE_INT,
                       G_TYPE_INT);
 
+    /**
+     * GdlDockItem::dock-drag-end:
+     * @item: The dock item which is no longer being dragged.
+     * @cancel: This value is set to TRUE if the drag was cancelled by
+     * the user. #cancel is set to FALSE if the drag was accepted.
+     * 
+     * Signals that the dock item dragging has ended.
+     **/
     gdl_dock_item_signals [DOCK_DRAG_END] = 
         g_signal_new ("dock_drag_end",
                       G_TYPE_FROM_CLASS (klass),
@@ -1551,6 +1583,17 @@
 
 /* ----- Public interface ----- */
 
+/**
+ * gdl_dock_item_new:
+ * @name: Unique name for identifying the dock object.
+ * @long_name: Human readable name for the dock object.
+ * @behavior: General behavior for the dock item (i.e. whether it can
+ *            float, if it's locked, etc.), as specified by
+ *            #GdlDockItemBehavior flags.
+ * 
+ * Creates a new dock item widget.
+ * Returns: The newly created dock item grip widget.
+ **/
 GtkWidget *
 gdl_dock_item_new (const gchar         *name,
                    const gchar         *long_name,
@@ -1569,6 +1612,18 @@
     return GTK_WIDGET (item);
 }
 
+/**
+ * gdl_dock_item_new_with_stock:
+ * @name: Unique name for identifying the dock object.
+ * @long_name: Human readable name for the dock object.
+ * @stock_id: Stock icon for the dock object.
+ * @behavior: General behavior for the dock item (i.e. whether it can
+ *            float, if it's locked, etc.), as specified by
+ *            #GdlDockItemBehavior flags.
+ * 
+ * Creates a new dock item grip widget with a given stock id.
+ * Returns: The newly created dock item grip widget.
+ **/
 GtkWidget *
 gdl_dock_item_new_with_stock (const gchar         *name,
                               const gchar         *long_name,
@@ -1590,6 +1645,15 @@
 }
 
 /* convenient function (and to preserve source compat) */
+/**
+ * gdl_dock_item_dock_to:
+ * @item: The dock item that will be relocated to the dock position.
+ * @target: The dock item that will be used as the point of reference.
+ * @position: The position to dock #item, relative to #target.
+ * @docking_param: This value is unused, and will be ignored.
+ * 
+ * Relocates a dock item to a new location relative to another dock item.
+ **/
 void
 gdl_dock_item_dock_to (GdlDockItem      *item,
                        GdlDockItem      *target,
@@ -1625,6 +1689,18 @@
                               position, NULL);
 }
 
+/**
+ * gdl_dock_item_set_orientation:
+ * @item: The dock item which will get it's orientation set.
+ * @orientation: The orientation to set the item to. If the orientation
+ * is set to #GTK_ORIENTATION_VERTICAL, the grip widget will be shown
+ * along the top of the edge of item (if it is not hidden). If the
+ * orientation is set to #GTK_ORIENTATION_HORIZONTAL, the grip widget
+ * will be shown down the left edge of the item (even if the widget
+ * text direction is set to RTL).
+ * 
+ * This function sets the layout of the dock item.
+ **/
 void
 gdl_dock_item_set_orientation (GdlDockItem    *item,
                                GtkOrientation  orientation)
@@ -1649,6 +1725,16 @@
     }
 }
 
+/**
+ * gdl_dock_item_get_tablabel:
+ * @item: The dock item from which to get the tab label widget.
+ * 
+ * Gets the current tab label widget. Note that this label widget is
+ * only visible when the "switcher-style" property of the #GdlDockMaster
+ * is set to #GDL_SWITCHER_STYLE_TABS
+ * 
+ * Returns: Returns the tab label widget.
+ **/
 GtkWidget *
 gdl_dock_item_get_tablabel (GdlDockItem *item)
 {
@@ -1658,6 +1744,15 @@
     return item->_priv->tab_label;
 }
 
+/**
+ * gdl_dock_item_set_tablabel:
+ * @item: The dock item which will get it's tab label widget set.
+ * @tablabel: The widget that will become the tab label.
+ * 
+ * Replaces the current tab label widget with another widget. Note that
+ * this label widget is only visible when the "switcher-style" property
+ * of the #GdlDockMaster is set to #GDL_SWITCHER_STYLE_TABS
+ **/
 void
 gdl_dock_item_set_tablabel (GdlDockItem *item,
                             GtkWidget   *tablabel)
@@ -1690,6 +1785,12 @@
     }
 }
 
+/**
+ * gdl_dock_item_hide_grip:
+ * @item: The dock item to hide the grip of.
+ * 
+ * This function hides the dock item's grip widget.
+ **/
 void 
 gdl_dock_item_hide_grip (GdlDockItem *item)
 {
@@ -1701,6 +1802,12 @@
     g_warning ("Grips always show unless GDL_DOCK_ITEM_BEH_NO_GRIP is set\n" );
 }
 
+/**
+ * gdl_dock_item_show_grip:
+ * @item: The dock item to show the grip of.
+ * 
+ * This function shows the dock item's grip widget.
+ **/
 void
 gdl_dock_item_show_grip (GdlDockItem *item)
 {
@@ -1712,6 +1819,14 @@
 }
 
 /* convenient function (and to preserve source compat) */
+/**
+ * gdl_dock_item_bind:
+ * @item: The item to bind.
+ * @dock: The #GdlDock widget to bind it to. Note that this widget must
+ * be a type of #GdlDock.
+ * 
+ * Binds this dock item to a new dock master.
+ **/
 void
 gdl_dock_item_bind (GdlDockItem *item,
                     GtkWidget   *dock)
@@ -1724,6 +1839,12 @@
 }
 
 /* convenient function (and to preserve source compat) */
+/**
+ * gdl_dock_item_unbind:
+ * @item: The item to unbind.
+ * 
+ * Unbinds this dock item from it's dock master.
+ **/
 void
 gdl_dock_item_unbind (GdlDockItem *item)
 {
@@ -1732,6 +1853,15 @@
     gdl_dock_object_unbind (GDL_DOCK_OBJECT (item));
 }
 
+/**
+ * gdl_dock_item_hide_item:
+ * @item: The dock item to hide.
+ * 
+ * This function hides the dock item. When dock items are hidden they
+ * are completely removed from the layout.
+ * 
+ * The dock item close button causes the panel to be hidden.
+ **/
 void
 gdl_dock_item_hide_item (GdlDockItem *item)
 {
@@ -1794,6 +1924,15 @@
     gdl_dock_object_thaw (GDL_DOCK_OBJECT (item));
 }
 
+/**
+ * gdl_dock_item_iconify_item:
+ * @item: The dock item to iconify.
+ * 
+ * This function iconifies the dock item. When dock items are iconified
+ * they are hidden, and appear only as icons in dock bars.
+ * 
+ * The dock item iconify button causes the panel to be iconified.
+ **/
 void
 gdl_dock_item_iconify_item (GdlDockItem *item)
 {
@@ -1803,6 +1942,13 @@
     gdl_dock_item_hide_item (item);
 }
 
+/**
+ * gdl_dock_item_show_item:
+ * @item: The dock item to show.
+ * 
+ * This function shows the dock item. When dock items are shown, they
+ * are displayed in their normal layout position.
+ **/
 void
 gdl_dock_item_show_item (GdlDockItem *item)
 {
@@ -1854,12 +2000,26 @@
     gtk_widget_show (GTK_WIDGET (item));
 }
 
+/**
+ * gdl_dock_item_lock:
+ * @item: The dock item to lock.
+ * 
+ * This function locks the dock item. When locked the dock item cannot
+ * be dragged around and it doesn't show a grip.
+ **/
 void
 gdl_dock_item_lock (GdlDockItem *item)
 {
     g_object_set (item, "locked", TRUE, NULL);
 }
 
+/**
+ * gdl_dock_item_unlock:
+ * @item: The dock item to unlock.
+ * 
+ * This function unlocks the dock item. When unlocked the dock item can
+ * be dragged around and can show a grip.
+ **/
 void
 gdl_dock_item_unlock (GdlDockItem *item)
 {
@@ -1894,6 +2054,14 @@
     }
 }
 
+/**
+ * gdl_dock_item_preferred_size:
+ * @item: The dock item to get the preferred size of.
+ * @req: A pointer to a #GtkRequisition into which the preferred size
+ * will be written.
+ * 
+ * Gets the preferred size of the dock item in pixels.
+ **/
 void 
 gdl_dock_item_preferred_size (GdlDockItem    *item,
                               GtkRequisition *req)
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]