]> Pileus Git - ~andy/gtk/blobdiff - gtk/gtkcellview.c
Minor documentation improvements
[~andy/gtk] / gtk / gtkcellview.c
index ea212308b586f20b5d859bbf523b291003190d8a..cc2daf6107e33ad098961a13a6dab37bfeba0f33 100644 (file)
@@ -26,7 +26,7 @@
 #include "gtkcellrenderertext.h"
 #include "gtkcellrendererpixbuf.h"
 #include "gtkprivate.h"
-#include "gtkorientable.h"
+#include "gtkorientableprivate.h"
 #include <gobject/gmarshal.h>
 #include "gtkbuildable.h"
 
  * and #GtkCellAreaContext. A #GtkCellAreaContext can be provided to the 
  * #GtkCellView at construction time in order to keep the cellview in context
  * of a group of cell views, this ensures that the renderers displayed will
- * be properly aligned with eachother (like the aligned cells of #GtkTreeMenu).
+ * be properly aligned with eachother (like the aligned cells in the menus
+ * of #GtkComboBox).
  *
  * #GtkCellView is #GtkOrientable in order to decide in which orientation
- * the underlying #GtkCellAreaContext should be allocated. Taking the #GtkTreeMenu
- * as an example, cellviews should be oriented horizontally if the menus are
+ * the underlying #GtkCellAreaContext should be allocated. Taking the #GtkComboBox
+ * menu as an example, cellviews should be oriented horizontally if the menus are
  * listed top-to-bottom and thus all share the same width but may have separate
  * individual heights (left-to-right menus should be allocated vertically since
  * they all share the same height but may have variable widths).
@@ -247,6 +248,15 @@ gtk_cell_view_class_init (GtkCellViewClass *klass)
    *
    * The #GtkCellAreaContext used to compute the geometry of the cell view.
    *
+   * A group of cell views can be assigned the same context in order to
+   * ensure the sizes and cell alignments match across all the views with
+   * the same context.
+   *
+   * #GtkComboBox menus uses this to assign the same context to all cell views
+   * in the menu items for a single menu (each submenu creates its own
+   * context since the size of each submenu does not depend on parent
+   * or sibling menus).
+   *
    * since 3.0
    */
    g_object_class_install_property (gobject_class,
@@ -337,15 +347,14 @@ gtk_cell_view_constructor (GType                  type,
 
   if (!priv->area)
     {
-      GtkCellArea *area = gtk_cell_area_box_new ();
-
-      priv->area = g_object_ref_sink (area);
+      priv->area = gtk_cell_area_box_new ();
+      g_object_ref_sink (priv->area);
     }
 
   if (!priv->context)
     priv->context = gtk_cell_area_create_context (priv->area);
 
-  priv->size_changed_id = 
+  priv->size_changed_id =
     g_signal_connect (priv->context, "notify",
                      G_CALLBACK (context_size_changed_cb), view);
 
@@ -411,15 +420,18 @@ gtk_cell_view_set_property (GObject      *object,
                             GParamSpec   *pspec)
 {
   GtkCellView *view = GTK_CELL_VIEW (object);
+  GtkCellViewPrivate *priv = view->priv;
   GtkCellArea *area;
   GtkCellAreaContext *context;
 
   switch (param_id)
     {
     case PROP_ORIENTATION:
-      view->priv->orientation = g_value_get_enum (value);
-      if (view->priv->context)
-       gtk_cell_area_context_reset (view->priv->context);
+      priv->orientation = g_value_get_enum (value);
+      if (priv->context)
+        gtk_cell_area_context_reset (priv->context);
+
+      _gtk_orientable_set_style_classes (GTK_ORIENTABLE (object));
       break;
     case PROP_BACKGROUND:
       {
@@ -450,16 +462,34 @@ gtk_cell_view_set_property (GObject      *object,
     case PROP_CELL_AREA:
       /* Construct-only, can only be assigned once */
       area = g_value_get_object (value);
-      
+
       if (area)
-       view->priv->area = g_object_ref_sink (area);
+        {
+          if (priv->area != NULL)
+            {
+              g_warning ("cell-area has already been set, ignoring construct property");
+              g_object_ref_sink (area);
+              g_object_unref (area);
+            }
+          else
+            priv->area = g_object_ref_sink (area);
+        }
       break;
     case PROP_CELL_AREA_CONTEXT:
       /* Construct-only, can only be assigned once */
       context = g_value_get_object (value);
-      
+
       if (context)
-       view->priv->context = g_object_ref (context);
+        {
+          if (priv->context != NULL)
+            {
+              g_warning ("cell-area-context has already been set, ignoring construct property");
+              g_object_ref_sink (context);
+              g_object_unref (context);
+            }
+          else
+            priv->context = g_object_ref (context);
+        }
       break;
 
     case PROP_DRAW_SENSITIVE:
@@ -565,6 +595,9 @@ gtk_cell_view_request_model (GtkCellView        *cellview,
   GtkTreeIter         iter;
   gboolean            valid;
 
+  if (!priv->model)
+    return;
+
   valid = gtk_tree_model_iter_children (priv->model, &iter, parent);
   while (valid)
     {
@@ -794,8 +827,15 @@ static GtkCellArea *
 gtk_cell_view_cell_layout_get_area (GtkCellLayout   *layout)
 {
   GtkCellView *cellview = GTK_CELL_VIEW (layout);
+  GtkCellViewPrivate *priv = cellview->priv;
+
+  if (G_UNLIKELY (!priv->area))
+    {
+      priv->area = gtk_cell_area_box_new ();
+      g_object_ref_sink (priv->area);
+    }
 
-  return cellview->priv->area;
+  return priv->area;
 }
 
 /* GtkBuildable implementation */
@@ -823,9 +863,9 @@ gtk_cell_view_buildable_custom_tag_end (GtkBuildable *buildable,
                                        const gchar  *tagname,
                                        gpointer     *data)
 {
-  if (strcmp (tagname, "attributes") == 0 || strcmp (tagname, "cell-packing") == 0)
-    _gtk_cell_layout_buildable_custom_tag_end (buildable, builder, child, tagname,
-                                              data);
+  if (_gtk_cell_layout_buildable_custom_tag_end (buildable, builder, child, tagname,
+                                                data))
+    return;
   else if (parent_buildable_iface->custom_tag_end)
     parent_buildable_iface->custom_tag_end (buildable, builder, child, tagname,
                                            data);
@@ -1069,7 +1109,6 @@ gtk_cell_view_set_model (GtkCellView  *cell_view,
       cell_view->priv->displayed_row = NULL;
 
       g_object_unref (cell_view->priv->model);
-      cell_view->priv->model = NULL;
     }
 
   cell_view->priv->model = model;
@@ -1167,7 +1206,7 @@ gtk_cell_view_get_displayed_row (GtkCellView *cell_view)
  * gtk_cell_view_get_size_of_row:
  * @cell_view: a #GtkCellView
  * @path: a #GtkTreePath 
- * @requisition: return location for the size 
+ * @requisition: (out): return location for the size 
  *
  * Sets @requisition to the size needed by @cell_view to display 
  * the model row pointed to by @path.
@@ -1285,6 +1324,18 @@ gtk_cell_view_set_background_rgba (GtkCellView   *cell_view,
   gtk_widget_queue_draw (GTK_WIDGET (cell_view));
 }
 
+/**
+ * gtk_cell_view_get_draw_sensitive:
+ * @cell_view: a #GtkCellView
+ *
+ * Gets whether @cell_view is configured to draw all of its
+ * cells in a sensitive state.
+ *
+ * Return value: whether @cell_view draws all of its
+ * cells in a sensitive state
+ *
+ * Since: 3.0
+ */
 gboolean
 gtk_cell_view_get_draw_sensitive (GtkCellView     *cell_view)
 {
@@ -1297,6 +1348,18 @@ gtk_cell_view_get_draw_sensitive (GtkCellView     *cell_view)
   return priv->draw_sensitive;
 }
 
+/**
+ * gtk_cell_view_set_draw_sensitive:
+ * @cell_view: a #GtkCellView
+ * @draw_sensitive: whether to draw all cells in a sensitive state.
+ *
+ * Sets whether @cell_view should draw all of its
+ * cells in a sensitive state, this is used by #GtkComboBox menus
+ * to ensure that rows with insensitive cells that contain
+ * children appear sensitive in the parent menu item.
+ *
+ * Since: 3.0
+ */
 void
 gtk_cell_view_set_draw_sensitive (GtkCellView     *cell_view,
                                  gboolean         draw_sensitive)
@@ -1315,6 +1378,18 @@ gtk_cell_view_set_draw_sensitive (GtkCellView     *cell_view,
     }
 }
 
+/**
+ * gtk_cell_view_get_fit_model:
+ * @cell_view: a #GtkCellView
+ *
+ * Gets whether @cell_view is configured to request space
+ * to fit the entire #GtkTreeModel.
+ *
+ * Return value: whether @cell_view requests space to fit
+ * the entire #GtkTreeModel.
+ *
+ * Since: 3.0
+ */
 gboolean
 gtk_cell_view_get_fit_model (GtkCellView     *cell_view)
 {
@@ -1327,9 +1402,22 @@ gtk_cell_view_get_fit_model (GtkCellView     *cell_view)
   return priv->fit_model;
 }
 
+/**
+ * gtk_cell_view_set_fit_model:
+ * @cell_view: a #GtkCellView
+ * @fit_model: whether @cell_view should request space for the whole model.
+ *
+ * Sets whether @cell_view should request space to fit the entire #GtkTreeModel.
+ *
+ * This is used by #GtkComboBox to ensure that the cell view displayed on
+ * the combo box's button always gets enough space and does not resize
+ * when selection changes.
+ *
+ * Since: 3.0
+ */
 void
-gtk_cell_view_set_fit_model (GtkCellView     *cell_view,
-                            gboolean         fit_model)
+gtk_cell_view_set_fit_model (GtkCellView *cell_view,
+                             gboolean     fit_model)
 {
   GtkCellViewPrivate *priv;