GNOME.org
 

[gtk+] Rename h/v-align to h/valign

commit 2f78aa30249928e9e2f9f476c0ec791cf4b9da79
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Sep 15 18:37:20 2010 -0400

    Rename h/v-align to h/valign
    
    And adjust the getters and setters to match. Also include some
    documentation by Havoc Pennington about adjustment of size requests
    and allocations.

 docs/reference/gtk/gtk3-sections.txt |    4 +
 gtk/gtk.symbols                      |    8 +-
 gtk/gtksizerequest.c                 |   51 ++++++++++++++++
 gtk/gtkwidget.c                      |  108 +++++++++++++++++++++-------------
 gtk/gtkwidget.h                      |   75 +++++++++++++++---------
 tests/testadjustsize.c               |   12 ++--
 6 files changed, 179 insertions(+), 79 deletions(-)
---
diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt
index f204b93..827d815 100644
--- a/docs/reference/gtk/gtk3-sections.txt
+++ b/docs/reference/gtk/gtk3-sections.txt
@@ -4945,6 +4945,10 @@ gtk_requisition_free
 
 <SUBSECTION>
 GtkAlign
+gtk_widget_get_halign
+gtk_widget_set_halign
+gtk_widget_get_valign
+gtk_widget_set_valign
 gtk_widget_get_margin_left
 gtk_widget_set_margin_left
 gtk_widget_get_margin_right
diff --git a/gtk/gtk.symbols b/gtk/gtk.symbols
index 0439420..b6aaed1 100644
--- a/gtk/gtk.symbols
+++ b/gtk/gtk.symbols
@@ -4367,10 +4367,10 @@ gtk_widget_get_mapped
 gtk_widget_get_support_multidevice
 gtk_widget_set_support_multidevice
 gtk_widget_device_is_shadowed
-gtk_widget_get_h_align
-gtk_widget_set_h_align
-gtk_widget_get_v_align
-gtk_widget_set_v_align
+gtk_widget_get_halign
+gtk_widget_set_halign
+gtk_widget_get_valign
+gtk_widget_set_valign
 gtk_widget_get_margin_left
 gtk_widget_set_margin_left
 gtk_widget_get_margin_right
diff --git a/gtk/gtksizerequest.c b/gtk/gtksizerequest.c
index e2ada95..db72826 100644
--- a/gtk/gtksizerequest.c
+++ b/gtk/gtksizerequest.c
@@ -87,6 +87,33 @@
  * width. By following this rule any widget that handles height-for-width
  * or width-for-height requests will always be allocated at least
  * enough space to fit its own content.
+ *
+ * Often a widget needs to get its own request during size request or
+ * allocation, for example when computing height it may need to also
+ * compute width, or when deciding how to use an allocation the widget may
+ * need to know its natural size. In these cases, the widget should be
+ * careful to call its virtual methods directly, like this:
+ * <example>
+ *   <title>Widget calling its own size request method.</title>
+ *   <programlisting>
+ * GTK_SIZE_REQUEST_GET_IFACE(widget)-&gt;get_width(GTK_SIZE_REQUEST(widget), &min, &natural);
+ *   </programlisting>
+ * </example>
+ *
+ * It will not work to use the wrapper functions, such as
+ * gtk_size_request_get_width(), inside your own size request
+ * implementation. These return a request adjusted by #GtkSizeGroup
+ * and by the GtkWidgetClass::adjust_size_request virtual method. If a
+ * widget used the wrappers inside its virtual method implementations,
+ * then the adjustments (such as widget margins) would be applied
+ * twice. GTK+ therefore does not allow this and will warn if you try
+ * to do it.
+ *
+ * Of course if you are getting the size request for
+ * <emphasis>another</emphasis> widget, such as a child of a
+ * container, you <emphasis>must</emphasis> use the wrapper APIs;
+ * otherwise, you would not properly consider widget margins,
+ * #GtkSizeGroup, and so forth.
  * </para>
  * </refsect2>
  */
@@ -420,6 +447,12 @@ gtk_size_request_get_request_mode (GtkSizeRequest *widget)
  * <note><para>This call is specific to height-for-width
  * requests.</para></note>
  *
+ * The returned request will be modified by the
+ * GtkWidgetClass::adjust_size_request virtual method and by any
+ * #GtkSizeGroup that have been applied. That is, the returned request
+ * is the one that should be used for layout, not necessarily the one
+ * returned by the widget itself.
+ *
  * Since: 3.0
  */
 void
@@ -442,6 +475,12 @@ gtk_size_request_get_width (GtkSizeRequest *widget,
  *
  * <note><para>This call is specific to width-for-height requests.</para></note>
  *
+ * The returned request will be modified by the
+ * GtkWidgetClass::adjust_size_request virtual method and by any
+ * #GtkSizeGroup that have been applied. That is, the returned request
+ * is the one that should be used for layout, not necessarily the one
+ * returned by the widget itself.
+ *
  * Since: 3.0
  */
 void
@@ -465,6 +504,12 @@ gtk_size_request_get_height (GtkSizeRequest *widget,
  * Retrieves a widget's minimum and natural width if it would be given
  * the specified @height.
  *
+ * The returned request will be modified by the
+ * GtkWidgetClass::adjust_size_request virtual method and by any
+ * #GtkSizeGroup that have been applied. That is, the returned request
+ * is the one that should be used for layout, not necessarily the one
+ * returned by the widget itself.
+ *
  * Since: 3.0
  */
 void
@@ -487,6 +532,12 @@ gtk_size_request_get_width_for_height (GtkSizeRequest *widget,
  * Retrieves a widget's minimum and natural height if it would be given
  * the specified @width.
  *
+ * The returned request will be modified by the
+ * GtkWidgetClass::adjust_size_request virtual method and by any
+ * #GtkSizeGroup that have been applied. That is, the returned request
+ * is the one that should be used for layout, not necessarily the one
+ * returned by the widget itself.
+ *
  * Since: 3.0
  */
 void
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 2de732f..ddc9237 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -279,8 +279,8 @@ enum {
   PROP_TOOLTIP_TEXT,
   PROP_WINDOW,
   PROP_DOUBLE_BUFFERED,
-  PROP_H_ALIGN,
-  PROP_V_ALIGN,
+  PROP_HALIGN,
+  PROP_VALIGN,
   PROP_MARGIN_LEFT,
   PROP_MARGIN_RIGHT,
   PROP_MARGIN_TOP,
@@ -871,15 +871,15 @@ gtk_widget_class_init (GtkWidgetClass *klass)
                                                          GTK_PARAM_READWRITE));
 
   /**
-   * GtkWidget:h-align
+   * GtkWidget:halign:
    *
    * How to distribute horizontal space if widget gets extra space, see #GtkAlign
    *
    * Since: 3.0
    */
   g_object_class_install_property (gobject_class,
-                                   PROP_H_ALIGN,
-                                   g_param_spec_enum ("h-align",
+                                   PROP_HALIGN,
+                                   g_param_spec_enum ("halign",
                                                       P_("Horizontal Alignment"),
                                                       P_("How to position in extra horizontal space"),
                                                       GTK_TYPE_ALIGN,
@@ -887,15 +887,15 @@ gtk_widget_class_init (GtkWidgetClass *klass)
                                                       GTK_PARAM_READWRITE));
 
   /**
-   * GtkWidget:v-align
+   * GtkWidget:valign:
    *
    * How to distribute vertical space if widget gets extra space, see #GtkAlign
    *
    * Since: 3.0
    */
   g_object_class_install_property (gobject_class,
-                                   PROP_V_ALIGN,
-                                   g_param_spec_enum ("v-align",
+                                   PROP_VALIGN,
+                                   g_param_spec_enum ("valign",
                                                       P_("Vertical Alignment"),
                                                       P_("How to position in extra vertical space"),
                                                       GTK_TYPE_ALIGN,
@@ -2941,11 +2941,11 @@ gtk_widget_set_property (GObject         *object,
     case PROP_DOUBLE_BUFFERED:
       gtk_widget_set_double_buffered (widget, g_value_get_boolean (value));
       break;
-    case PROP_H_ALIGN:
-      gtk_widget_set_h_align (widget, g_value_get_enum (value));
+    case PROP_HALIGN:
+      gtk_widget_set_halign (widget, g_value_get_enum (value));
       break;
-    case PROP_V_ALIGN:
-      gtk_widget_set_v_align (widget, g_value_get_enum (value));
+    case PROP_VALIGN:
+      gtk_widget_set_valign (widget, g_value_get_enum (value));
       break;
     case PROP_MARGIN_LEFT:
       gtk_widget_set_margin_left (widget, g_value_get_int (value));
@@ -3077,11 +3077,11 @@ gtk_widget_get_property (GObject         *object,
     case PROP_DOUBLE_BUFFERED:
       g_value_set_boolean (value, gtk_widget_get_double_buffered (widget));
       break;
-    case PROP_H_ALIGN:
-      g_value_set_enum (value, gtk_widget_get_h_align (widget));
+    case PROP_HALIGN:
+      g_value_set_enum (value, gtk_widget_get_halign (widget));
       break;
-    case PROP_V_ALIGN:
-      g_value_set_enum (value, gtk_widget_get_v_align (widget));
+    case PROP_VALIGN:
+      g_value_set_enum (value, gtk_widget_get_valign (widget));
       break;
     case PROP_MARGIN_LEFT:
       g_value_set_int (value, gtk_widget_get_margin_left (widget));
@@ -4185,8 +4185,10 @@ gtk_widget_queue_shallow_draw (GtkWidget *widget)
  * and position to their child widgets.
  *
  * In this function, the allocation may be adjusted. It will be forced
- * to a 1x1 minimum size, and the adjust_size_allocation virtual method
- * on the child will be used to adjust the allocation.
+ * to a 1x1 minimum size, and the adjust_size_allocation virtual
+ * method on the child will be used to adjust the allocation. Standard
+ * adjustments include removing the widget's margins, and applying the
+ * widget's #GtkWidget:halign and #GtkWidget:valign properties.
  **/
 void
 gtk_widget_size_allocate (GtkWidget	*widget,
@@ -4569,7 +4571,7 @@ get_span_inside_border_horizontal (GtkWidget              *widget,
                                    int                    *width_inside_p)
 {
   get_span_inside_border (widget,
-                          aux_info->h_align,
+                          aux_info->halign,
                           aux_info->margin.left,
                           aux_info->margin.right,
                           allocated_outside_width,
@@ -4587,7 +4589,7 @@ get_span_inside_border_vertical (GtkWidget              *widget,
                                  int                    *height_inside_p)
 {
   get_span_inside_border (widget,
-                          aux_info->v_align,
+                          aux_info->valign,
                           aux_info->margin.top,
                           aux_info->margin.bottom,
                           allocated_outside_height,
@@ -11484,31 +11486,31 @@ gtk_widget_size_request_init (GtkSizeRequestIface *iface)
 }
 
 /**
- * gtk_widget_get_h_align:
+ * gtk_widget_get_halign:
  * @widget: a #GtkWidget
  *
- * Gets the value of the #GtkWidget:h-align property.
+ * Gets the value of the #GtkWidget:halign property.
  *
  * Returns: the horizontal alignment of @widget
  */
 GtkAlign
-gtk_widget_get_h_align (GtkWidget *widget)
+gtk_widget_get_halign (GtkWidget *widget)
 {
   g_return_val_if_fail (GTK_IS_WIDGET (widget), GTK_ALIGN_FILL);
-  return _gtk_widget_get_aux_info_or_defaults (widget)->h_align;
+  return _gtk_widget_get_aux_info_or_defaults (widget)->halign;
 }
 
 /**
- * gtk_widget_set_h_align:
+ * gtk_widget_set_halign:
  * @widget: a #GtkWidget
  * @align: the horizontal alignment
  *
  * Sets the horizontal alignment of @widget.
- * See the #GtkWidget:h-align property.
+ * See the #GtkWidget:halign property.
  */
 void
-gtk_widget_set_h_align (GtkWidget *widget,
-                        GtkAlign   align)
+gtk_widget_set_halign (GtkWidget *widget,
+                       GtkAlign   align)
 {
   GtkWidgetAuxInfo *aux_info;
 
@@ -11516,40 +11518,40 @@ gtk_widget_set_h_align (GtkWidget *widget,
 
   aux_info = _gtk_widget_get_aux_info (widget, TRUE);
 
-  if (aux_info->h_align == align)
+  if (aux_info->halign == align)
     return;
 
-  aux_info->h_align = align;
+  aux_info->halign = align;
   gtk_widget_queue_resize (widget);
-  g_object_notify (G_OBJECT (widget), "h-align");
+  g_object_notify (G_OBJECT (widget), "halign");
 }
 
 /**
- * gtk_widget_get_v_align:
+ * gtk_widget_get_valign:
  * @widget: a #GtkWidget
  *
- * Gets the value of the #GtkWidget:v-align property.
+ * Gets the value of the #GtkWidget:valign property.
  *
  * Returns: the vertical alignment of @widget
  */
 GtkAlign
-gtk_widget_get_v_align (GtkWidget *widget)
+gtk_widget_get_valign (GtkWidget *widget)
 {
   g_return_val_if_fail (GTK_IS_WIDGET (widget), GTK_ALIGN_FILL);
-  return _gtk_widget_get_aux_info_or_defaults (widget)->v_align;
+  return _gtk_widget_get_aux_info_or_defaults (widget)->valign;
 }
 
 /**
- * gtk_widget_set_v_align:
+ * gtk_widget_set_valign:
  * @widget: a #GtkWidget
  * @align: the vertical alignment
  *
  * Sets the vertical alignment of @widget.
- * See the #GtkWidget:h-align property.
+ * See the #GtkWidget:valign property.
  */
 void
-gtk_widget_set_v_align (GtkWidget *widget,
-                        GtkAlign   align)
+gtk_widget_set_valign (GtkWidget *widget,
+                       GtkAlign   align)
 {
   GtkWidgetAuxInfo *aux_info;
 
@@ -11557,12 +11559,12 @@ gtk_widget_set_v_align (GtkWidget *widget,
 
   aux_info = _gtk_widget_get_aux_info (widget, TRUE);
 
-  if (aux_info->v_align == align)
+  if (aux_info->valign == align)
     return;
 
-  aux_info->v_align = align;
+  aux_info->valign = align;
   gtk_widget_queue_resize (widget);
-  g_object_notify (G_OBJECT (widget), "v-align");
+  g_object_notify (G_OBJECT (widget), "valign");
 }
 
 /**
@@ -12202,6 +12204,21 @@ gtk_widget_get_has_tooltip (GtkWidget *widget)
  *
  * Retrieves the widget's allocation.
  *
+ * Note, when implementing a #GtkContainer: a widget's allocation will
+ * be its "adjusted" allocation, that is, the widget's parent
+ * container typically calls gtk_widget_size_allocate() with an
+ * allocation, and that allocation is then adjusted (to handle margin
+ * and alignment for example) before assignment to the widget.
+ * gtk_widget_get_allocation() returns the adjusted allocation that
+ * was actually assigned to the widget. The adjusted allocation is
+ * guaranteed to be completely contained within the
+ * gtk_widget_size_allocate() allocation, however. So a #GtkContainer
+ * is guaranteed that its children stay inside the assigned bounds,
+ * but not that they have exactly the bounds the container assigned.
+ * There is no way to get the original allocation assigned by
+ * gtk_widget_size_allocate(), since it isn't stored; if a container
+ * implementation needs that information it will have to track it itself.
+ *
  * Since: 2.18
  */
 void
@@ -12226,6 +12243,13 @@ gtk_widget_get_allocation (GtkWidget     *widget,
  * Sets the widget's allocation.  This should not be used
  * directly, but from within a widget's size_allocate method.
  *
+ * The allocation set should be the "adjusted" or actual
+ * allocation. If you're implementing a #GtkContainer, you want to use
+ * gtk_widget_size_allocate() instead of gtk_widget_set_allocation().
+ * The GtkWidgetClass::adjust_size_allocation virtual method adjusts the
+ * allocation inside gtk_widget_size_allocate() to create an adjusted
+ * allocation.
+ *
  * Since: 2.18
  */
 void
diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h
index baf77dc..36cd35d 100644
--- a/gtk/gtkwidget.h
+++ b/gtk/gtkwidget.h
@@ -266,30 +266,47 @@ struct _GtkWidget
 
 /**
  * GtkWidgetClass:
- * @parent_class:
- * @activate_signal:
- * @set_scroll_adjustments_signal:
- *
- * <structfield>activate_signal</structfield>
- * The signal to emit when a widget of this class is activated,
- * gtk_widget_activate() handles the emission. Implementation of this
- * signal is optional.
- *
- *
- * <structfield>set_scroll_adjustment_signal</structfield>
- * This signal is emitted  when a widget of this class is added
- * to a scrolling aware parent, gtk_widget_set_scroll_adjustments()
- * handles the emission.
- * Implementation of this signal is optional.
+ * @parent_class: The object class structure needs to be the first
+ *   element in the widget class structure in order for the class mechanism
+ *   to work correctly. This allows a GtkWidgetClass pointer to be cast to
+ *   a GtkObjectClass pointer.
+ * @activate_signal: The signal to emit when a widget of this class is
+ *   activated, gtk_widget_activate() handles the emission.
+ *   Implementation of this signal is optional.
+ * @set_scroll_adjustments_signal: This signal is emitted  when a widget of
+ *   this class is added to a scrolling aware parent,
+ *   gtk_widget_set_scroll_adjustments() handles the emission.
+ *   Implementation of this signal is optional.
+ * @adjust_size_request: Convert an initial size request from a widget's
+ *   #GtkSizeRequest virtual method implementations into a size request to
+ *   be used by parent containers in laying out the widget.
+ *   adjust_size_request adjusts <emphasis>from</emphasis> a child widget's
+ *   original request <emphasis>to</emphasis> what a parent container should
+ *   use for layout. The @for_size argument will be -1 if the request should
+ *   not be for a particular size in the opposing orientation, i.e. if the
+ *   request is not height-for-width or width-for-height. If @for_size is
+ *   greater than -1, it is the proposed allocation in the opposing
+ *   orientation that we need the request for. Implementations of
+ *   adjust_size_request should chain up to the default implementation,
+ *   which applies #GtkWidget's margin properties and imposes any values
+ *   from gtk_widget_set_size_request(). Chaining up should be last,
+ *   <emphasis>after</emphasis> your subclass adjusts the request, so
+ *   #GtkWidget can apply constraints and add the margin properly.
+ * @adjust_size_allocation: Convert an initial size allocation assigned
+ *   by a #GtkContainer using gtk_widget_size_allocate(), into an actual
+ *   size allocation to be used by the widget. adjust_size_allocation
+ *   adjusts <emphasis>to</emphasis> a child widget's actual allocation
+ *   <emphasis>from</emphasis> what a parent container computed for the
+ *   child. The adjusted allocation must be entirely within the original
+ *   allocation. In any custom implementation, chain up to the default
+ *   #GtkWidget implementation of this method, which applies the margin
+ *   and alignment properties of #GtkWidget. Chain up
+ *   <emphasis>before</emphasis> performing your own adjustments so your
+ *   own adjustments remove more allocation after the #GtkWidget base
+ *   class has already removed margin and alignment.
  */
 struct _GtkWidgetClass
 {
-  /* The object class structure needs to be the first
-   *  element in the widget class structure in order for
-   *  the class mechanism to work correctly. This allows a
-   *  GtkWidgetClass pointer to be cast to a GtkObjectClass
-   *  pointer.
-   */
   GtkObjectClass parent_class;
 
   /*< public >*/
@@ -474,6 +491,8 @@ struct _GtkWidgetClass
 				       gboolean    keyboard_tooltip,
 				       GtkTooltip *tooltip);
 
+  /*< public >*/
+
   void         (* adjust_size_request)    (GtkWidget         *widget,
                                            GtkOrientation     orientation,
                                            gint               for_size,
@@ -482,6 +501,8 @@ struct _GtkWidgetClass
   void         (* adjust_size_allocation) (GtkWidget         *widget,
                                            GtkAllocation     *allocation);
 
+  /*< private >*/
+
   /* Signals without a C default handler class slot:
    * gboolean	(*damage_event)	(GtkWidget      *widget,
    *                             GdkEventExpose *event);
@@ -503,8 +524,8 @@ struct _GtkWidgetAuxInfo
   gint width;
   gint height;
 
-  guint   h_align : 4;
-  guint   v_align : 4;
+  guint   halign : 4;
+  guint   valign : 4;
 
   GtkBorder margin;
 };
@@ -741,11 +762,11 @@ AtkObject*       gtk_widget_get_accessible               (GtkWidget          *wi
 
 
 /* Margin and alignment */
-GtkAlign gtk_widget_get_h_align       (GtkWidget *widget);
-void     gtk_widget_set_h_align       (GtkWidget *widget,
+GtkAlign gtk_widget_get_halign        (GtkWidget *widget);
+void     gtk_widget_set_halign        (GtkWidget *widget,
                                        GtkAlign   align);
-GtkAlign gtk_widget_get_v_align       (GtkWidget *widget);
-void     gtk_widget_set_v_align       (GtkWidget *widget,
+GtkAlign gtk_widget_get_valign        (GtkWidget *widget);
+void     gtk_widget_set_valign        (GtkWidget *widget,
                                        GtkAlign   align);
 gint     gtk_widget_get_margin_left   (GtkWidget *widget);
 void     gtk_widget_set_margin_left   (GtkWidget *widget,
diff --git a/tests/testadjustsize.c b/tests/testadjustsize.c
index b0389d9..c13d9d8 100644
--- a/tests/testadjustsize.c
+++ b/tests/testadjustsize.c
@@ -291,21 +291,21 @@ enum_to_string (GType enum_type,
 }
 
 static GtkWidget*
-create_aligned (GtkAlign    h_align,
-                GtkAlign    v_align)
+create_aligned (GtkAlign halign,
+                GtkAlign valign)
 {
   GtkWidget *widget;
   char *label;
 
   label = g_strdup_printf ("h=%s v=%s",
-                           enum_to_string (GTK_TYPE_ALIGN, h_align),
-                           enum_to_string (GTK_TYPE_ALIGN, v_align));
+                           enum_to_string (GTK_TYPE_ALIGN, halign),
+                           enum_to_string (GTK_TYPE_ALIGN, valign));
 
   widget = create_widget_visible_border (label);
 
   g_object_set (G_OBJECT (TEST_WIDGET (widget)),
-                "h-align", h_align,
-                "v-align", v_align,
+                "halign", halign,
+                "valign", valign,
                 NULL);
 
   return widget;
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]