org.gnome.gtk
Class Label

java.lang.Object
  org.freedesktop.bindings.Proxy
      org.gnome.glib.Object
          org.gnome.gtk.Object
              org.gnome.gtk.Widget
                  org.gnome.gtk.Misc
                      org.gnome.gtk.Label

Direct Known Subclasses:

AccelLabel

public class Label
extends Misc

A Widget that displays a small amount of text.

Labels are the backbone of any Window. They are frequently used to identify other controls with names, as headings in Windows, and are the building blocks that Menus and Buttons are made up of. All the difficult parts about rendering text are taken care of here, such as text direction, fonts. And, of course, you can enable them to allow their text to be copied.

Labels can display normal text or text that has been formatted with Pango markup. FIXME with a reference to our Pango guide page.

Although you can pack multiple lines into a Label, there does come a point when the amount of text you're trying to show gets out of hand. At that point you might want to investigate the TextView Widget.

Since:

4.0.1

Author:

Andrew Cowie, Srichand Pendyala, Wouter Bolsterlee

Nested Class Summary

Nested classes/interfaces inherited from class org.gnome.gtk.Widget

Widget.BUTTON_PRESS_EVENT, Widget.BUTTON_RELEASE_EVENT, Widget.ENTER_NOTIFY_EVENT, Widget.EXPOSE_EVENT, Widget.FOCUS_IN_EVENT, Widget.FOCUS_OUT_EVENT, Widget.HIDE, Widget.KEY_PRESS_EVENT, Widget.KEY_RELEASE_EVENT, Widget.LEAVE_NOTIFY_EVENT, Widget.UNMAP_EVENT, Widget.VISIBILITY_NOTIFY_EVENT

Constructor Summary

Label(java.lang.String text)
Create a Label with the specified text.

Method Summary

double	getAngle() Get the current angle of the Label.
Justification	getJustify() Gets the justification of the text within the Label.
java.lang.String	getLabel() Get the text showing in the Label, including any characters which indicate Pango markup syntax and embedded mnemonic underline characters that may be present.
java.lang.String	getText() Get the text showing in the Label, but with any Pango markup stripped away.
boolean	getUseMarkup() Get the current setting indicating whether the the label text is to be interpreted as marked up with Pango's text markup language.
void	selectRegion(int start, int end) Select a region of the text in this Label.
void	setAngle(double angle) Sets the angle of rotation for the Label.
void	setJustify(Justification justification) Sets the justification of the text within the Label.
void	setLabel(java.lang.String text) Set the text showing in the Label.
void	setLineWrap(boolean setting) Set whether this Label will attempt to wrap the text provided.
void	setMaxWidthChars(int width) Set a maximum width for the Label, in characters.
void	setSelectable(boolean setting) Whether the text in this Label can be selected by the user.
void	setUseMarkup(boolean setting) Set whether the text showing in the Label is to be parsed as containing markup in Pango's text markup language.
void	setWidthChars(int width) Explicitly set the width of the Label, in characters.

Methods inherited from class org.gnome.gtk.Misc

getAlignmentX, getAlignmentY, getPaddingX, getPaddingY, setAlignment, setPadding

Methods inherited from class org.gnome.gtk.Widget

activate, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, getAllocation, getHasFocus, getParent, getRequisition, getToplevel, getWindow, grabFocus, hide, modifyBackground, modifyText, setCanFocus, setSensitive, setSizeRequest, setTooltipMarkup, setTooltipText, show, showAll

Methods inherited from class org.freedesktop.bindings.Proxy

toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Label

public Label(java.lang.String text)

Create a Label with the specified text. This Label will be an ordinary one and will interpret the argument as plain unformatted text. Note that if you use this constructor you can later switch the Label to interpreting the text as Pango markup by calling setUseMarkup(true).

Parameters:

text - the text you wish on the Label.

Since:

4.0.1

Method Detail

getAngle

public double getAngle()

Get the current angle of the Label. An angle of 90° means the text reads in an upwards direction (ie from bottom to top), whereas an angle of 270° means the text reads in a downwards direction (ie from top to bottom).

Since:

4.0.1

getJustify

public Justification getJustify()

Gets the justification of the text within the Label.

Since:

4.0.4

getLabel

public java.lang.String getLabel()

Get the text showing in the Label, including any characters which indicate Pango markup syntax and embedded mnemonic underline characters that may be present. Contrast with getText() which returns the text unadorned.

Since:

4.0.1

getText

public java.lang.String getText()

Get the text showing in the Label, but with any Pango markup stripped away. This is useful if you've applied some fancy formatting but just want to find out the actual words that appear to the user. It also strips away any embedded underlines indicating mnemonics. If you need the raw text including markup, then you want getLabel().

Since:

4.0.1

getUseMarkup

public boolean getUseMarkup()

Get the current setting indicating whether the the label text is to be interpreted as marked up with Pango's text markup language. When enabled, the label can show formatted text instead of just a simple line of text.

Since:

4.0.4

selectRegion

public void selectRegion(int start,
                         int end)

Select a region of the text in this Label. The characters between start up to but not including end will be selected. This assumes that the Label has been made selectable with setSelectable(true).

Parameters:

end - If negative, then the selection will be from start to the end of the text in the Label.

Since:

4.0.6

setAngle

public void setAngle(double angle)

Sets the angle of rotation for the Label. The angle is measured in degrees from the horizontal, going counter-clockwise. An angle of 90° reads from bottom to top, an angle of 270° from top to bottom. The angle setting for the Label will be ignored if the Label is selectable, wrapped, or ellipsized.

Parameters:

angle - The angle that the baseline of the Label's text makes with the horizontal. The valid range (as you'd expect) is from 0° through 360°.

Since:

4.0.1

setJustify

public void setJustify(Justification justification)

Sets the justification of the text within the Label. The default is LEFT. Note that this has no effect on Labels only containing a single line of text.

If you're trying to control the positioning of the Label within its parent, see Misc's setAlignment().

Since:

4.0.4

setLabel

public void setLabel(java.lang.String text)

Set the text showing in the Label.

Parameters:

text - If the Label has been told to interpret Pango markup with setUseMarkup(true), then any markup included in text will be interpreted as such.

Since:

4.0.1

setLineWrap

public void setLineWrap(boolean setting)

Set whether this Label will attempt to wrap the text provided. This will always work, but not necessarily as you might expect. The nature of the size-request/size-allocate process is such that the Label cannot make it's requisition based on the parent's size because the parent's size will depend on the child's request. To enforce wrapping at a specific width, simply enforce the width of the Label itself with setSizeRequest().

The default is false.

Since:

4.0.6

setMaxWidthChars

public void setMaxWidthChars(int width)

Set a maximum width for the Label, in characters. This will allow the Label to dynamically size up to a maximum of width but not to expand beyond that point. This is useful in conjunction with turning setEllipsize() on.

This sets the max-width-chars property.

Warning: If a value greater than -1 has been explicitly set as the width using setWidthChars(), setting this property will have no effect.

Parameters:

width - The width you wish to truncate the Label at, in characters. A value of -1 to remove the override and return the Label to automatic sizing.

Since:

4.0.4

setSelectable

public void setSelectable(boolean setting)

Whether the text in this Label can be selected by the user.

Since:

4.0.6

setUseMarkup

public void setUseMarkup(boolean setting)

Set whether the text showing in the Label is to be parsed as containing markup in Pango's text markup language. Using this allows Labels to be created with expressive formatting considerably more advanced than a simple line of text.

Parameters:

setting - If setting is true, then any markup included in the text is interpreted as such. If its set to false, markup is ignored and included as-is.

Since:

4.0.1

setWidthChars

public void setWidthChars(int width)

Explicitly set the width of the Label, in characters.

This sets the width-chars property. Note that if set, this will take precedence over the max-width-chars property as set by setMaxWidthChars().

This is not precisely reliable as a way to enforce sizing across different Labels, since the character sizes could be different owing to differing languages or fonts that may be in use. Still, this is superior to trying to manually control Widget size by specifying the horizontal dimension in pixels. If you need a series of Widgets (be they Labels or otherwise) to have the same size, apply a SizeGroup.

Parameters:

width - The width to base the size of the Label on, in characters. A value of -1 will turn off the override, and return the Label to automatically sizing based on the content within and the max-width property, if activated.

Since:

4.0.4