GNOME.org
 

[egg-list-box/flow-box-enhancements] Add docs

commit 60fea3fe7dc66a9cf8788d2036b3ff2e809e9ef3
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Sep 28 23:31:28 2013 -0400

    Add docs

 egg-flow-box.c |  397 +++++++++++++++++++++++++++++++++++++++++++-------------
 egg-flow-box.h |    2 +-
 2 files changed, 309 insertions(+), 90 deletions(-)
---
diff --git a/egg-flow-box.c b/egg-flow-box.c
index 2c45c8f..518647d 100644
--- a/egg-flow-box.c
+++ b/egg-flow-box.c
@@ -28,17 +28,60 @@
  * @Short_Description: A container that allows reflowing its children
  * @Title: EggFlowBox
  *
- * #EggFlowBox positions child widgets in sequence according to its
- * orientation. For instance, with the horizontal orientation, the widgets
- * will be arranged from left to right, starting a new row under the
- * previous row when necessary. Reducing the width in this case will
- * require more rows, so a larger height will be requested.
+ * An #EggFlowBox positions child widgets in sequence according to its
+ * orientation. For instance, with the horizontal orientation, the
+ * widgets will be arranged from left to right, starting a new row
+ * under the previous row when necessary. Reducing the width in this
+ * case will require more rows, so a larger height will be requested.
  *
  * Likewise, with the vertical orientation, the widgets will be arranged
  * from top to bottom, starting a new column to the right when necessary.
- * Reducing the height will require more columns, so a larger width will be
- * requested.
+ * Reducing the height will require more columns, so a larger width will
+ * be requested.
  *
+ * The children of #EggFlowBox can be dynamicaly sorted and filtered.
+ *
+ * Although an #EggFlowBox must have only #EggFlowBoxChild children,
+ * you can add any kind of widget to it via gtk_container_add(), and
+ * a #EggFlowBoxChild widget will automatically be inserted between
+ * the box and the widget.
+ *
+ * Also see #GtkListBox.
+ */
+
+/**
+ * EggFlowBoxForeachFunc:
+ * @box: a #EggFlowBox
+ * @child: a #EggFlowBoxChild
+ * @user_data: (closure): user data
+ *
+ * A function used by egg_flow_box_selected_foreach().
+ * It will be called on every selected child of tht @box.
+ */
+
+/**
+ * EggFlowBoxFilterFunc:
+ * @child: a #EggFlowBoxChild that may be filtered
+ * @user_data: (closure): user data
+ *
+ * A function that will be called whenrever a child changes
+ * or is added. It lets you control if the child should be
+ * visible or not.
+ *
+ * Returns: %TRUE if the row should be visible, %FALSE otherwise
+ */
+
+/**
+ * EggFlowBoxSortFunc:
+ * @child1: the first child
+ * @child2: the second child
+ * @user_data: (closure): user data
+ *
+ * A function to compare two children to determine which
+ * should come first.
+ *
+ * Returns: < 0 if @child1 should be before @child2, 0 if
+ *     the are equal, and > 0 otherwise
  */
 
 #include <config.h>
@@ -572,12 +615,29 @@ egg_flow_box_child_class_init (EggFlowBoxChildClass *class)
   gtk_widget_class_set_accessible_role (widget_class, ATK_ROLE_LIST_ITEM);
 }
 
+/**
+ * egg_flow_box_child_new:
+ *
+ * Creates a new #EggFlowBoxChild, to be used as a child
+ * of a #EggFlowBox.
+ *
+ * Returns: a new #EggFlowBoxChild
+ */
 GtkWidget *
 egg_flow_box_child_new (void)
 {
   return g_object_new (EGG_TYPE_FLOW_BOX_CHILD, NULL);
 }
 
+/**
+ * egg_flow_box_child_get_index:
+ * @child: a #EggFlowBoxChild
+ *
+ * Gets the current index of the @child in its #EggFlowBox container.
+ *
+ * Returns: the index of the @child, or -1 if the @chil dis not
+ *     in a flow box.
+ */
 gint
 egg_flow_box_child_get_index (EggFlowBoxChild *child)
 {
@@ -593,6 +653,66 @@ egg_flow_box_child_get_index (EggFlowBoxChild *child)
   return -1;
 }
 
+/**
+ * egg_flow_box_child_is_selected:
+ * @child: a #EggFlowBoxChild
+ *
+ * Returns whether the @child is currently selected in its
+ * #EggFlowBox container.
+ *
+ * Returns: %TRUE if @child is selected
+ */
+gboolean
+egg_flow_box_child_is_selected (EggFlowBoxChild *child)
+{
+  g_return_if_fail (EGG_IS_FLOW_BOX_CHILD (child));
+
+  return CHILD_PRIV (child)->selected;
+}
+
+/**
+ * egg_flow_box_child_changed:
+ * @child: a #EggFlowBoxChild
+ *
+ * Marks @child as changed, causing any state that depends on this
+ * to be updated. This affects sorting and filtering.
+ *
+ * Note that calls to this method must be in sync with the data
+ * used for the sorting and filtering functions. For instance, if
+ * the list is mirroring some external data set, and *two* children
+ * changed in the external data set when you call
+ * egg_flow_box_child_changed() on the first child, the sort function
+ * must only read the new data for the first of the two changed
+ * children, otherwise the resorting of the children will be wrong.
+ *
+ * This generally means that if you don't fully control the data
+ * model, you have to duplicate the data that affects the sorting
+ * and filtering functions into the widgets themselves. Another
+ * alternative is to call egg_flow_box_invalidate_sort() on any
+ * model change, but that is more expensive.
+ */
+void
+egg_flow_box_child_changed (EggFlowBoxChild *child)
+{
+  EggFlowBox *box;
+
+  g_return_if_fail (EGG_IS_FLOW_BOX_CHILD (child));
+
+  box = egg_flow_box_child_get_box (child);
+
+  if (box == NULL)
+    return;
+
+  if (BOX_PRIV (box)->sort_func != NULL)
+    {
+      g_sequence_sort_changed (CHILD_PRIV (child)->iter,
+                               (GCompareDataFunc)egg_flow_box_sort, box);
+      gtk_widget_queue_resize (GTK_WIDGET (box));
+    }
+
+  egg_flow_box_apply_filter (box, child);
+}
+
 void
 egg_flow_box_set_hadjustment (EggFlowBox    *box,
                               GtkAdjustment *adjustment)
@@ -2175,10 +2295,10 @@ egg_flow_box_get_column_spacing (EggFlowBox *box)
 /**
  * egg_flow_box_set_min_children_per_line:
  * @box: An #EggFlowBox
- * @n_children: The minimum amount of children per line.
+ * @n_children: The minimum number of children per line
  *
- * Sets the minimum amount of children to line up
- * in @box's orientation before flowping.
+ * Sets the minimum number of children to line up
+ * in @box's orientation before flowing.
  */
 void
 egg_flow_box_set_min_children_per_line (EggFlowBox *box,
@@ -2199,9 +2319,9 @@ egg_flow_box_set_min_children_per_line (EggFlowBox *box,
  * egg_flow_box_get_min_children_per_line:
  * @box: An #EggFlowBox
  *
- * Gets the minimum amount of children per line.
+ * Gets the minimum number of children per line.
  *
- * Returns: The minimum amount of children per line.
+ * Returns: The minimum number of children per line.
  */
 guint
 egg_flow_box_get_min_children_per_line (EggFlowBox *box)
@@ -2214,14 +2334,14 @@ egg_flow_box_get_min_children_per_line (EggFlowBox *box)
 /**
  * egg_flow_box_set_max_children_per_line:
  * @box: An #EggFlowBox
- * @n_children: The natural amount of children per line.
+ * @n_children: The maximum number of children per line.
  *
- * Sets the natural length of items to request and
+ * Sets the maximum number of children to request and
  * allocate space for in @box's orientation.
  *
- * Setting the natural amount of children per line
+ * Setting the maximum number of children per line
  * limits the overall natural size request to be no more
- * than @n_children items long in the given orientation.
+ * than @n_children children long in the given orientation.
  */
 void
 egg_flow_box_set_max_children_per_line (EggFlowBox *box,
@@ -2242,9 +2362,9 @@ egg_flow_box_set_max_children_per_line (EggFlowBox *box,
  * egg_flow_box_get_max_children_per_line:
  * @box: An #EggFlowBox
  *
- * Gets the natural amount of children per line.
+ * Gets the maximum number of children per line.
  *
- * Returns: The natural amount of children per line.
+ * Returns: The maximum number of children per line.
  */
 guint
 egg_flow_box_get_max_children_per_line (EggFlowBox *box)
@@ -2259,9 +2379,9 @@ egg_flow_box_get_max_children_per_line (EggFlowBox *box)
  * @box: An #EggFlowBox
  * @single: %TRUE to emit child-activated on a single click
  *
- * Causes the #EggFlowBox::child-activated signal to be emitted on
- * a single click instead of a double click.
- **/
+ * If @single is %TRUE, rows will be activated when you click
+ * on them, otherwise you need to double-click.
+ */
 void
 egg_flow_box_set_activate_on_single_click (EggFlowBox *box,
                                            gboolean    single)
@@ -2281,10 +2401,11 @@ egg_flow_box_set_activate_on_single_click (EggFlowBox *box,
  * egg_flow_box_get_activate_on_single_click:
  * @box: An #EggFlowBox
  *
- * Gets the setting set by egg_flow_box_set_activate_on_single_click().
+ * Returns whether rows activate on single clicks.
  *
- * Return value: %TRUE if child-activated will be emitted on a single click
- **/
+ * Returns: %TRUE if rows are activated on single click,
+ *     %FALSE otherwise
+ */
 gboolean
 egg_flow_box_get_activate_on_single_click (EggFlowBox *box)
 {
@@ -3231,37 +3352,6 @@ egg_flow_box_move_cursor (EggFlowBox      *box,
   egg_flow_box_update_selection (box, child, modify_selection, extend_selection);
 }
 
-void
-egg_flow_box_select_all (EggFlowBox *box)
-{
-  g_return_if_fail (EGG_IS_FLOW_BOX (box));
-
-  if (BOX_PRIV (box)->selection_mode != GTK_SELECTION_MULTIPLE)
-    return;
-
-  if (g_sequence_get_length (BOX_PRIV (box)->children) > 0)
-    {
-      egg_flow_box_select_all_between (box, NULL, NULL);
-      g_signal_emit (box, signals[SELECTED_CHILDREN_CHANGED], 0);
-    }
-}
-
-void
-egg_flow_box_unselect_all (EggFlowBox *box)
-{
-  gboolean dirty = FALSE;
-
-  g_return_if_fail (EGG_IS_FLOW_BOX (box));
-
-  if (BOX_PRIV (box)->selection_mode == GTK_SELECTION_BROWSE)
-    return;
-
-  dirty = egg_flow_box_unselect_all_internal (box);
-
-  if (dirty)
-    g_signal_emit (box, signals[SELECTED_CHILDREN_CHANGED], 0);
-}
-
 static gboolean
 egg_flow_box_draw (GtkWidget *widget,
                    cairo_t   *cr)
@@ -3635,12 +3725,14 @@ egg_flow_box_new (void)
 
 /**
  * egg_flow_box_get_selected_children:
- * @box: An #EggFlowBox.
+ * @box: a #EggFlowBox
  *
  * Creates a list of all selected children.
  *
- * Return value: (element-type GtkWidget) (transfer container): A #GList containing the #GtkWidget for each 
selected child.
- **/
+ * Returns: (element-type GtkWidget) (transfer container):
+ *     A #GList containing the #GtkWidget for each selected child.
+ *     Free with g_list_free() when done.
+ */
 GList *
 egg_flow_box_get_selected_children (EggFlowBox *box)
 {
@@ -3662,6 +3754,14 @@ egg_flow_box_get_selected_children (EggFlowBox *box)
   return g_list_reverse (selected);
 }
 
+/**
+ * egg_flow_box_select_child:
+ * @box: a #EggFlowBox
+ * @child: a child of @box
+ *
+ * Selects a single child of @box, if the selection
+ * mode allows it.
+ */
 void
 egg_flow_box_select_child (EggFlowBox      *box,
                            EggFlowBoxChild *child)
@@ -3672,6 +3772,14 @@ egg_flow_box_select_child (EggFlowBox      *box,
   egg_flow_box_select_child_info (box, child);
 }
 
+/**
+ * egg_flow_box_unselect_child:
+ * @box: a #EggFlowBox
+ * @child: a child of @box
+ *
+ * Unselects a single child of @box, if the selection
+ * mode allows it.
+ */
 void
 egg_flow_box_unselect_child (EggFlowBox      *box,
                              EggFlowBoxChild *child)
@@ -3682,22 +3790,61 @@ egg_flow_box_unselect_child (EggFlowBox      *box,
   egg_flow_box_unselect_child_info (box, child);
 }
 
-gboolean
-egg_flow_box_child_is_selected (EggFlowBoxChild *child)
+/**
+ * egg_flow_box_select_all:
+ * @box: a #EggFlowBox
+ *
+ * Select all children of @box, if the selection
+ * mode allows it.
+ */
+void
+egg_flow_box_select_all (EggFlowBox *box)
 {
-  g_return_if_fail (EGG_IS_FLOW_BOX_CHILD (child));
+  g_return_if_fail (EGG_IS_FLOW_BOX (box));
 
-  return CHILD_PRIV (child)->selected;
+  if (BOX_PRIV (box)->selection_mode != GTK_SELECTION_MULTIPLE)
+    return;
+
+  if (g_sequence_get_length (BOX_PRIV (box)->children) > 0)
+    {
+      egg_flow_box_select_all_between (box, NULL, NULL);
+      g_signal_emit (box, signals[SELECTED_CHILDREN_CHANGED], 0);
+    }
+}
+
+/**
+ * egg_flow_box_unselect_all:
+ * @box: a #EggFlowBox
+ *
+ * Unselect all children of @box, if the selection
+ * mode allows it.
+ */
+void
+egg_flow_box_unselect_all (EggFlowBox *box)
+{
+  gboolean dirty = FALSE;
+
+  g_return_if_fail (EGG_IS_FLOW_BOX (box));
+
+  if (BOX_PRIV (box)->selection_mode == GTK_SELECTION_BROWSE)
+    return;
+
+  dirty = egg_flow_box_unselect_all_internal (box);
+
+  if (dirty)
+    g_signal_emit (box, signals[SELECTED_CHILDREN_CHANGED], 0);
 }
 
 /**
  * egg_flow_box_selected_foreach:
- * @box: An #EggFlowBox.
- * @func: (scope call): The function to call for each selected child.
- * @data: User data to pass to the function.
+ * @box: a #EggFlowBox
+ * @func: (scope call): the function to call for each selected child
+ * @data: user data to pass to the function
+ *
+ * Calls a function for each selected child.
  *
- * Calls a function for each selected child. Note that the
- * selection cannot be modified from within this function.
+ * Note that the selection cannot be modified from within
+ * this function.
  */
 void
 egg_flow_box_selected_foreach (EggFlowBox            *box,
@@ -3719,6 +3866,14 @@ egg_flow_box_selected_foreach (EggFlowBox            *box,
     }
 }
 
+/**
+ * egg_flow_box_set_selection_mode:
+ * @box: a #EggFlowBox
+ * @mode: the new selection mode
+ *
+ * Sets how selection works in @box.
+ * See #GtkSelectionMode for details.
+ */
 void
 egg_flow_box_set_selection_mode (EggFlowBox       *box,
                                  GtkSelectionMode  mode)
@@ -3745,6 +3900,14 @@ egg_flow_box_set_selection_mode (EggFlowBox       *box,
     g_signal_emit (box, signals[SELECTED_CHILDREN_CHANGED], 0);
 }
 
+/**
+ * egg_flow_box_get_selection_mode:
+ * @box: a #EggFlowBox
+ *
+ * Gets the selection mode of @box.
+ *
+ * Returns: the #GtkSelectionMode
+ */
 GtkSelectionMode
 egg_flow_box_get_selection_mode (EggFlowBox *box)
 {
@@ -3783,6 +3946,23 @@ egg_flow_box_apply_filter_all (EggFlowBox *box)
 
 }
 
+/**
+ * egg_flow_box_set_filter_func:
+ * @box: a #EggFlowBox
+ * @filter_func: (closure user_data) (allow-none): callback that
+ *     lets you filter which children to show
+ * @user_data: user data passed to @filter_func
+ * @destroy: destroy notifier for @user_data
+ *
+ * By setting a filter function on the @box one can decide dynamically
+ * which of the children to show. For instance, to implement a search
+ * function that only shows the children matching the search terms.
+ *
+ * The @filter_func will be called for ach child after the call, and
+ * it will continue to be called each time a child changes (via
+ * egg_flow_box_child_changed()) or when egg_flow_box_invalidate_filter()
+ * is called.
+ */
 void
 egg_flow_box_set_filter_func (EggFlowBox           *box,
                               EggFlowBoxFilterFunc  filter_func,
@@ -3805,6 +3985,18 @@ egg_flow_box_set_filter_func (EggFlowBox           *box,
   egg_flow_box_invalidate_filter (box);
 }
 
+/**
+ * egg_flow_box_invalidate_filter:
+ * @box: a #EggFlowBox
+ *
+ * Updates the filtering for all children.
+ *
+ * Call this function when the result of the filter
+ * function on the @box is changed due ot an external
+ * factor. For instance, this would be used if the
+ * filter function just looked for a specific search
+ * term, and the entry with the string has changed.
+ */
 void
 egg_flow_box_invalidate_filter (EggFlowBox *box)
 {
@@ -3814,6 +4006,22 @@ egg_flow_box_invalidate_filter (EggFlowBox *box)
   gtk_widget_queue_resize (GTK_WIDGET (box));
 }
 
+/**
+ * egg_flow_box_set_sort_func:
+ * @box: a #EggFlowBox
+ * @sort_func: (closure user_data) (allow-none): the sort function
+ * @user_data: user data passed to @sort_func
+ * @destroy: destroy notifier for @user_data
+ *
+ * By setting a sort function on the @box, one can dynamically
+ * reorder the children of the box, based on the contents of
+ * the children.
+ *
+ * The @sort_func will be called for each child after the call,
+ * and will continue to be called each time a child changes (via
+ * egg_flow_box_child_changed()) and when egg_flow_box_invalidate_sort()
+ * is called.
+ */
 void
 egg_flow_box_set_sort_func (EggFlowBox         *box,
                             EggFlowBoxSortFunc  sort_func,
@@ -3846,6 +4054,15 @@ egg_flow_box_sort (EggFlowBoxChild *a,
   return priv->sort_func (a, b, priv->sort_data);
 }
 
+/**
+ * egg_flow_box_invalidate_sort:
+ * @box: a #EggFlowBox
+ *
+ * Updates the sorting for all children.
+ *
+ * Call this when the result of the sort function on
+ * @box is changed due to an external factor.
+ */
 void
 egg_flow_box_invalidate_sort (EggFlowBox *box)
 {
@@ -3863,28 +4080,21 @@ egg_flow_box_invalidate_sort (EggFlowBox *box)
     }
 }
 
-void
-egg_flow_box_child_changed (EggFlowBoxChild *child)
-{
-  EggFlowBox *box;
-
-  g_return_if_fail (EGG_IS_FLOW_BOX_CHILD (child));
-
-  box = egg_flow_box_child_get_box (child);
-
-  if (box == NULL)
-    return;
-
-  if (BOX_PRIV (box)->sort_func != NULL)
-    {
-      g_sequence_sort_changed (CHILD_PRIV (child)->iter,
-                               (GCompareDataFunc)egg_flow_box_sort, box);
-      gtk_widget_queue_resize (GTK_WIDGET (box));
-    }
-
-  egg_flow_box_apply_filter (box, child);
-}
-
+/**
+ * egg_flow_box_insert:
+ * @box: a #EggFlowBox
+ * @widget: the #GtkWidget to add
+ * @position: the position to insert @child in
+ *
+ * Inserts the @child into @box at @position.
+ *
+ * If a sort function is set, the widget will actually be inserted
+ * at the calculated position and this function has the same effect
+ * as gtk_container_add().
+ *
+ * If @position is -1, or larger than the total number of children
+ * in the @box, then the @child will be appended to the end.
+ */
 void
 egg_flow_box_insert (EggFlowBox *box,
                      GtkWidget  *widget,
@@ -3927,6 +4137,15 @@ egg_flow_box_insert (EggFlowBox *box,
   egg_flow_box_apply_filter (box, child);
 }
 
+/**
+ * egg_flow_box_get_child_at_index:
+ * @box: a #EggFlowBox
+ * @idx: the position of the child
+ *
+ * Gets the nth child in the @box.
+ *
+ * Returns: (transfer none): the child #GtkWidget
+ */
 EggFlowBoxChild *
 egg_flow_box_get_child_at_index (EggFlowBox *box,
                                  gint        idx)
diff --git a/egg-flow-box.h b/egg-flow-box.h
index 9885f17..8904e2a 100644
--- a/egg-flow-box.h
+++ b/egg-flow-box.h
@@ -142,7 +142,7 @@ EggFlowBoxChild      *egg_flow_box_get_child_at_index           (EggFlowBox
 
 typedef void (* EggFlowBoxForeachFunc) (EggFlowBox      *box,
                                         EggFlowBoxChild *child,
-                                        gpointer         data);
+                                        gpointer         user_data);
 
 void                  egg_flow_box_selected_foreach             (EggFlowBox        *box,
                                                                  EggFlowBoxForeachFunc func,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]