org.gnome.gtk

## Class Label

- Object
- - org.freedesktop.bindings.Pointer
  - - org.freedesktop.bindings.Proxy
    - - org.gnome.glib.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

- - ### Nested Class Summary

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

      `Widget.ButtonPressEvent, Widget.ButtonReleaseEvent, Widget.Destroy, Widget.Draw, Widget.EnterNotifyEvent, Widget.FocusInEvent, Widget.FocusOutEvent, Widget.Hide, Widget.KeyPressEvent, Widget.KeyReleaseEvent, Widget.LeaveNotifyEvent, Widget.MapEvent, Widget.MotionNotifyEvent, Widget.PopupMenu, Widget.QueryTooltip, Widget.ScrollEvent, Widget.SizeAllocate, Widget.UnmapEvent, Widget.VisibilityNotifyEvent`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Label()` Create an empty Label.
    `Label(String text)` Create a Label with the specified text.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `double` | `getAngle()` Get the current angle of the Label.
    `EllipsizeMode` | `getEllipsizeMode()` Get the current ellipsization used.
    `Justification` | `getJustify()` Gets the justification of the text within the Label.
    `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.
    `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` | `setEllipsize(EllipsizeMode setting)` Set the `ellipsization mode` to use to make the text fits the label width.
    `void` | `setJustify(Justification setting)` Sets the justification of the text within the Label.
    `void` | `setLabel(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` | `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.
    `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, addEvents, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, destroy, getAllocatedHeight, getAllocatedWidth, getAllocation, getCanDefault, getCanFocus, getHasFocus, getName, getParent, getPreferredHeightForWidthMinimum, getPreferredHeightForWidthNatural, getPreferredHeightMinimum, getPreferredHeightNatural, getPreferredWidthForHeightMinimum, getPreferredWidthForHeightNatural, getPreferredWidthMinimum, getPreferredWidthNatural, getRequestMode, getRequisition, getSensitive, getStyleContext, getToplevel, getWindow, grabAdd, grabDefault, grabFocus, grabRemove, hide, isSensitive, overrideBackground, overrideColor, overrideFont, queueDraw, queueDrawArea, realize, setAlignHorizontal, setAlignVertical, setCanDefault, setCanFocus, setEvents, setExpandHorizontal, setExpandVertical, setName, setSensitive, setSizeRequest, setTooltipMarkup, setTooltipText, show, showAll`

    - ### Methods inherited from class org.freedesktop.bindings.Pointer

      `toString`

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

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

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

    - #### 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 `&amp;` 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