Commit 2f78aa30 authored by Matthias Clasen's avatar Matthias Clasen

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.
parent bf2a7ee1
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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,
......
......@@ -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;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment