org.gnome.gtk
Class Label

Object
  org.freedesktop.bindings.Pointer
      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, Guillaume Mazoyer

Label

public Label()

Create an empty Label. You'll need to call setLabel() to place some text it.

Since:

4.0.11

Label

public Label(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

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

getEllipsizeMode

public EllipsizeMode getEllipsizeMode()

Get the current ellipsization used.

Since:

4.0.13

getJustify

public Justification getJustify()

Gets the justification of the text within the Label.

Since:

4.0.4

getLabel

public 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 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

setEllipsize

public void setEllipsize(EllipsizeMode setting)

Set the ellipsization mode to use to make the text fits the label width.

Since:

4.0.13

setJustify

public void setJustify(Justification setting)

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(String text)

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

WARNING:
If you have enabled use-markup (as is often the case), beware that you must escape whatever you to this method (like you would for feeding user data to any other XML or HTML like target). This specifically means you need to convert & into & and likewise for angle brackets. Use Glib.markupEscapeText().

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

setUseUnderline

public void setUseUnderline(boolean setting)

Set whether underscores will be interpreted as signifying that the next character should be drawn with an underline, thereby creating the visual effect of a mnemonic. For example, with this set to true, text of the form "Op_en a copy" will result in

Open a copy

The default is false.

Since:

4.0.11

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

Overview  Package   Class		java-gnome
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD