callisto-debian/gtk3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add some documentation about width-chars and max-width-chars

Browse Source 
Explain how these properties determine the width of ellipsized
and wrapped labels.
This commit is contained in:
Matthias Clasen
2010-04-28 00:48:15 -04:00
parent 538ec4efbb
commit c8dd9895e4
2 changed files with 112 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/reference/gtk/tmpl/gtklabel.sgml
View File

@ -141,7 +141,7 @@ the clipboard. Only labels that contain useful-to-copy information
</para> </para>
</refsect2> </refsect2>
<refsect2> <refsect2 id="label-text-layout">
<title>Text layout</title> <title>Text layout</title>
<para> <para>
@ -159,7 +159,19 @@ gtk_label_set_justify() sets how the lines in a label align
with one another. If you want to set how the label as a whole with one another. If you want to set how the label as a whole
aligns in its available space, see gtk_misc_set_alignment(). aligns in its available space, see gtk_misc_set_alignment().
</para> </para>
<para>
The #GtkLabel:width-chars and #GtkLabel:max-width-chars properties
can be used to control the size allocation of ellipsized or wrapped
labels. For ellipsizing labels, if either is specified (and less
than the actual text size), it is used as the minimum width, and the actual
text size is used as the natural width of the label. For wrapping labels,
width-chars is used as the minimum width, if specified, and max-width-chars
is used as the natural width. Even if max-width-chars specified, wrapping
labels will be rewrapped to use all of the available width.
</para>
<note><para>Note that the interpretation of #GtkLabel:width-chars and
#GtkLabel:max-width-chars has changed a bit with the introduction of
width-for-height geometry management and #GtkExtendedLayout.</para></note>
</refsect2> </refsect2>
<refsect2> <refsect2>

152
gtk/gtklabel.c
View File

@ -656,7 +656,7 @@ gtk_label_class_init (GtkLabelClass *class)
g_object_class_install_property (gobject_class, g_object_class_install_property (gobject_class,
PROP_ELLIPSIZE, PROP_ELLIPSIZE,
g_param_spec_enum ("ellipsize", g_param_spec_enum ("ellipsize",
P_("Ellipsize"), >P_("Ellipsize"),
P_("The preferred place to ellipsize the string, if the label does not have enough room to display the entire string"), P_("The preferred place to ellipsize the string, if the label does not have enough room to display the entire string"),
PANGO_TYPE_ELLIPSIZE_MODE, PANGO_TYPE_ELLIPSIZE_MODE,
PANGO_ELLIPSIZE_NONE, PANGO_ELLIPSIZE_NONE,
@ -666,10 +666,11 @@ gtk_label_class_init (GtkLabelClass *class)
* GtkLabel:width-chars: * GtkLabel:width-chars:
* *
* The desired width of the label, in characters. If this property is set to * The desired width of the label, in characters. If this property is set to
* -1, the width will be calculated automatically, otherwise the label will * -1, the width will be calculated automatically.
* request either 3 characters or the property value, whichever is greater. *
* If the "width-chars" property is set to a positive value, then the * See the section on <link linkend="label-text-layout">text layout</link>
* #GtkLabel:max-width-chars property is ignored. * for details of how #GtkLabel:width-chars and #GtkLabel:max-width-chars
* determine the width of ellipsized and wrapped labels.
* *
* Since: 2.6 * Since: 2.6
**/ **/
@ -726,10 +727,11 @@ gtk_label_class_init (GtkLabelClass *class)
* GtkLabel:max-width-chars: * GtkLabel:max-width-chars:
* *
* The desired maximum width of the label, in characters. If this property * The desired maximum width of the label, in characters. If this property
* is set to -1, the width will be calculated automatically, otherwise the * is set to -1, the width will be calculated automatically.
* label will request space for no more than the requested number of *
* characters. If the #GtkLabel:width-chars property is set to a positive * See the section on <link linkend="label-text-layout">text layout</link>
* value, then the "max-width-chars" property is ignored. * for details of how #GtkLabel:width-chars and #GtkLabel:max-width-chars
* determine the width of ellipsized and wrapped labels.
* *
* Since: 2.6 * Since: 2.6
**/ **/
@ -3278,8 +3280,6 @@ get_single_line_height (GtkWidget *widget,
return ascent + descent; return ascent + descent;
} }
static void static void
gtk_label_extended_layout_init (GtkExtendedLayoutIface *iface) gtk_label_extended_layout_init (GtkExtendedLayoutIface *iface)
{ {
@ -3291,7 +3291,7 @@ gtk_label_extended_layout_init (GtkExtendedLayoutIface *iface)
} }
static gboolean static gboolean
gtk_label_is_height_for_width (GtkExtendedLayout *layout) gtk_label_is_height_for_width (GtkExtendedLayout *layout)
{ {
GtkLabel *label = GTK_LABEL (layout); GtkLabel *label = GTK_LABEL (layout);
gdouble angle = gtk_label_get_angle (label); gdouble angle = gtk_label_get_angle (label);
@ -3304,10 +3304,10 @@ gtk_label_is_height_for_width (GtkExtendedLayout *layout)
static void static void
get_size_for_allocation (GtkLabel *label, get_size_for_allocation (GtkLabel *label,
GtkOrientation orientation, GtkOrientation orientation,
gint allocation, gint allocation,
gint *minimum_size, gint *minimum_size,
gint *natural_size) gint *natural_size)
{ {
PangoLayout *layout; PangoLayout *layout;
GtkWidgetAuxInfo *aux_info = GtkWidgetAuxInfo *aux_info =
@ -3321,9 +3321,9 @@ get_size_for_allocation (GtkLabel *label,
if (aux_info) if (aux_info)
{ {
if (orientation == GTK_ORIENTATION_HORIZONTAL) if (orientation == GTK_ORIENTATION_HORIZONTAL)
aux_size = aux_info->width; aux_size = aux_info->width;
else else
aux_size = aux_info->height; aux_size = aux_info->height;
} }
else else
aux_size = 0; aux_size = 0;
@ -3346,7 +3346,7 @@ get_size_for_allocation (GtkLabel *label,
static void static void
gtk_label_get_desired_size (GtkExtendedLayout *layout, gtk_label_get_desired_size (GtkExtendedLayout *layout,
GtkOrientation orientation, GtkOrientation orientation,
gint *minimum_size, gint *minimum_size,
gint *natural_size) gint *natural_size)
{ {
@ -3407,13 +3407,13 @@ gtk_label_get_desired_size (GtkExtendedLayout *layout,
* full natural size, or it may be that pango needs a fix here). * full natural size, or it may be that pango needs a fix here).
*/ */
if (label->ellipsize && angle != 0 && angle != 90 && angle != 180 && angle != 270 && angle != 360) if (label->ellipsize && angle != 0 && angle != 90 && angle != 180 && angle != 270 && angle != 360)
{ {
/* For some reason we only need this at about 110 degrees, and only /* For some reason we only need this at about 110 degrees, and only
* when gaining in height * when gaining in height
*/ */
natural_rect.height += ROTATION_ELLIPSIZE_PADDING * 2 * PANGO_SCALE; natural_rect.height += ROTATION_ELLIPSIZE_PADDING * 2 * PANGO_SCALE;
natural_rect.width += ROTATION_ELLIPSIZE_PADDING * 2 * PANGO_SCALE; natural_rect.width += ROTATION_ELLIPSIZE_PADDING * 2 * PANGO_SCALE;
} }
} }
required_rect.width = PANGO_PIXELS_CEIL (required_rect.width); required_rect.width = PANGO_PIXELS_CEIL (required_rect.width);
@ -3427,41 +3427,53 @@ gtk_label_get_desired_size (GtkExtendedLayout *layout,
/* Note, we cant use get_size_for_allocation() when rotating /* Note, we cant use get_size_for_allocation() when rotating
* ellipsized labels. * ellipsized labels.
*/ */
if (!(label->ellipsize && label->have_transform) && (angle == 90 || angle == 270)) if (!(label->ellipsize && label->have_transform) &&
{ (angle == 90 || angle == 270))
/* Doing a h4w request on a rotated label here, return the {
/* Doing a h4w request on a rotated label here, return the
* required width for the minimum height. * required width for the minimum height.
*/ */
get_size_for_allocation (label, GTK_ORIENTATION_VERTICAL, get_size_for_allocation (label,
required_rect.height, minimum_size, natural_size); GTK_ORIENTATION_VERTICAL,
required_rect.height,
minimum_size, natural_size);
} }
else else
{ {
/* Normal desired width */ /* Normal desired width */
*minimum_size = required_rect.width; *minimum_size = required_rect.width;
*natural_size = natural_rect.width; *natural_size = natural_rect.width;
} }
*minimum_size += label->misc.xpad * 2; *minimum_size += label->misc.xpad * 2;
*natural_size += label->misc.xpad * 2; *natural_size += label->misc.xpad * 2;
} }
else /* GTK_ORIENTATION_VERTICAL */ else /* GTK_ORIENTATION_VERTICAL */
{ {
/* Note, we cant use get_size_for_allocation() when rotating ellipsize labels. /* Note, we cant use get_size_for_allocation() when rotating
* ellipsized labels.
*/ */
if (!(label->ellipsize && label->have_transform) && (angle == 0 || angle == 180)) if (!(label->ellipsize && label->have_transform) &&
{ (angle == 0 || angle == 180))
/* Doing a w4h request on a label here, return the required height for the minimum width. */ {
get_size_for_allocation (label, GTK_ORIENTATION_HORIZONTAL, /* Doing a w4h request on a label here, return the required
required_rect.width, minimum_size, natural_size); * height for the minimum width.
} */
get_size_for_allocation (label,
GTK_ORIENTATION_HORIZONTAL,
required_rect.width,
minimum_size, natural_size);
}
else else
{ {
/* A vertically rotated label does w4h, so return the base desired height (text length) */ /* A vertically rotated label does w4h, so return the base
*minimum_size = required_rect.height; * desired height (text length)
*natural_size = natural_rect.height; */
} *minimum_size = required_rect.height;
*natural_size = natural_rect.height;
}
*minimum_size += label->misc.ypad * 2; *minimum_size += label->misc.ypad * 2;
*natural_size += label->misc.ypad * 2; *natural_size += label->misc.ypad * 2;
} }
@ -3480,18 +3492,22 @@ gtk_label_get_desired_size (GtkExtendedLayout *layout,
static void static void
gtk_label_get_desired_width (GtkExtendedLayout *layout, gtk_label_get_desired_width (GtkExtendedLayout *layout,
gint *minimum_size, gint *minimum_size,
gint *natural_size) gint *natural_size)
{ {
gtk_label_get_desired_size (layout, GTK_ORIENTATION_HORIZONTAL, minimum_size, natural_size); gtk_label_get_desired_size (layout,
GTK_ORIENTATION_HORIZONTAL,
minimum_size, natural_size);
} }
static void static void
gtk_label_get_desired_height (GtkExtendedLayout *layout, gtk_label_get_desired_height (GtkExtendedLayout *layout,
gint *minimum_size, gint *minimum_size,
gint *natural_size) gint *natural_size)
{ {
gtk_label_get_desired_size (layout, GTK_ORIENTATION_VERTICAL, minimum_size, natural_size); gtk_label_get_desired_size (layout,
GTK_ORIENTATION_VERTICAL,
minimum_size, natural_size);
} }
static void static void
@ -3506,17 +3522,17 @@ gtk_label_get_width_for_height (GtkExtendedLayout *layout,
if (label->wrap && (angle == 90 || angle == 270)) if (label->wrap && (angle == 90 || angle == 270))
{ {
if (label->wrap) if (label->wrap)
gtk_label_clear_layout (label); gtk_label_clear_layout (label);
get_size_for_allocation (label, GTK_ORIENTATION_VERTICAL, get_size_for_allocation (label, GTK_ORIENTATION_VERTICAL,
MAX (1, height - (label->misc.ypad * 2)), MAX (1, height - (label->misc.ypad * 2)),
minimum_width, natural_width); minimum_width, natural_width);
if (minimum_width) if (minimum_width)
*minimum_width += label->misc.xpad * 2; *minimum_width += label->misc.xpad * 2;
if (natural_width) if (natural_width)
*natural_width += label->misc.xpad * 2; *natural_width += label->misc.xpad * 2;
} }
else else
GTK_EXTENDED_LAYOUT_GET_IFACE (layout)->get_desired_width (layout, minimum_width, natural_width); GTK_EXTENDED_LAYOUT_GET_IFACE (layout)->get_desired_width (layout, minimum_width, natural_width);
@ -3534,17 +3550,17 @@ gtk_label_get_height_for_width (GtkExtendedLayout *layout,
if (label->wrap && (angle == 0 || angle == 180 || angle == 360)) if (label->wrap && (angle == 0 || angle == 180 || angle == 360))
{ {
if (label->wrap) if (label->wrap)
gtk_label_clear_layout (label); gtk_label_clear_layout (label);
get_size_for_allocation (label, GTK_ORIENTATION_HORIZONTAL, get_size_for_allocation (label, GTK_ORIENTATION_HORIZONTAL,
MAX (1, width - label->misc.xpad * 2), MAX (1, width - label->misc.xpad * 2),
minimum_height, natural_height); minimum_height, natural_height);
if (minimum_height) if (minimum_height)
*minimum_height += label->misc.ypad * 2; *minimum_height += label->misc.ypad * 2;
if (natural_height) if (natural_height)
*natural_height += label->misc.ypad * 2; *natural_height += label->misc.ypad * 2;
} }
else else
GTK_EXTENDED_LAYOUT_GET_IFACE (layout)->get_desired_height (layout, minimum_height, natural_height); GTK_EXTENDED_LAYOUT_GET_IFACE (layout)->get_desired_height (layout, minimum_height, natural_height);
@ -3560,8 +3576,8 @@ gtk_label_size_allocate (GtkWidget *widget,
GTK_WIDGET_CLASS (gtk_label_parent_class)->size_allocate (widget, allocation); GTK_WIDGET_CLASS (gtk_label_parent_class)->size_allocate (widget, allocation);
/* The layout may have been recently cleared in get_size_for_orientation(), but the /* The layout may have been recently cleared in get_size_for_orientation(),
* width at that point may not be the same as the allocated width * but the width at that point may not be the same as the allocated width
*/ */
if (label->wrap) if (label->wrap)
gtk_label_clear_layout (label); gtk_label_clear_layout (label);
@ -3571,7 +3587,7 @@ gtk_label_size_allocate (GtkWidget *widget,
if (label->ellipsize) if (label->ellipsize)
{ {
if (label->layout) if (label->layout)
{ {
PangoRectangle logical; PangoRectangle logical;
PangoRectangle bounds; PangoRectangle bounds;