<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
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
* 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)->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>
*/
* <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
*
* <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
* 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
* 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
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,
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,
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,
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));
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));
* 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,
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,
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,
}
/**
- * 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;
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;
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");
}
/**
*
* 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
* 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
/**
* 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 >*/
gboolean keyboard_tooltip,
GtkTooltip *tooltip);
+ /*< public >*/
+
void (* adjust_size_request) (GtkWidget *widget,
GtkOrientation orientation,
gint for_size,
void (* adjust_size_allocation) (GtkWidget *widget,
GtkAllocation *allocation);
+ /*< private >*/
+
/* Signals without a C default handler class slot:
* gboolean (*damage_event) (GtkWidget *widget,
* GdkEventExpose *event);
gint width;
gint height;
- guint h_align : 4;
- guint v_align : 4;
+ guint halign : 4;
+ guint valign : 4;
GtkBorder margin;
};
/* 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,
}
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;