org.gnome.gtk

## Class TextTag

- Object
- - org.freedesktop.bindings.Pointer
  - - org.freedesktop.bindings.Proxy
    - - org.gnome.glib.Object
      - - org.gnome.gtk.TextTag

-     public class TextTag
      extends Object

  TextTags are used to apply markup and formatting for regions of text in a TextBuffer.

  All TextTags belong to a TextTagTable, and likewise all TextBuffers are constructed by specifying the TextTagTable that it will draw tags from. That said, if you don't mind sharing your TextTags between all TextBuffers in your application, then you can use the no-arg convenience constructors here and in TextBuffer. We will in all our examples.

  You can create a new and unique TextTag every time you go to apply formatting, but in general you'll want to reuse them and that will be more efficient. Given:

       TextTag bold;
       TextBuffer buffer;
       TextIter start, end, pointer;
       ...

  and assuming the TextBuffer was created with the no-arg constructor, create a TextTag and apply some formatting:

       bold = new TextTag();
       bold.setWeight(Weight.BOLD);
       ...

  As you will see, there are any number of properties and font characteristics that can be applied with a tag. See the setter methods on this class for all the current possibilities.

  Now, to make use of the tag, you'll call TextBuffer's `applyTag()`. It needs a pair of TextIters to delineate the range you want to apply the TextTag to. You could, for example, react to the currently selected region:

       start = buffer.getSelectionBound().getIter();
       end = buffer.getInsert().getIter();

  And now apply your tag:

       buffer.applyTag(bold, start, end);

  As an alternative, you can apply a TextTag when `insert()`ing text:

       buffer.insert(pointer, "Hello World", bold);

  Either way, going forward, you've now got `bold` which you can apply on other regions of your TextBuffer.

  Finally, if you want to know what TextTags are applying at a given spot in a TextBuffer, then get a TextIter pointing there and use its `getTags()` method.

  All TextTags created in java-gnome are "anonymous"; the underlying library has a notion of named tags but we have no need of this and have not exposed it. In order to reuse a TextTag later just keep a reference to it.

  Since:
    4.0.9
  Author:
    Andrew Cowie

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `TextTag()` Create a new TextTag and place it in the default TextTagTable.
    `TextTag(String name)` Create a new TextTag and place it in the default TextTagTable.
    `TextTag(TextTagTable table)` Create a new TextTag.
    `TextTag(TextTagTable table, String name)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `setBackground(String color)` Specify the background colour via a String description.
    `void` | `setBackgroundFullHeight(boolean setting)` Does the background colouring specified by `setBackground()` fills the entire line height or only the height of the tagged characters.
    `void` | `setEditable(boolean setting)` Set whether the region of text covered by this TextTag is editable by the user.
    `void` | `setFamily(String font)` Specify the font family to be used.
    `void` | `setFont(String str)` Pass a string that describes the font you wish to use.
    `void` | `setFontDescription(FontDescription desc)` Pass a FontDescription specifying the metrics and characteristics of the font you wish to be active when this TextTag is applied.
    `void` | `setForeground(String colour)` Specify the foreground colour by name.
    `void` | `setIndent(int pixels)` Specify the amount by which this paragraph is to be indented, in pixels.
    `void` | `setInvisible(boolean setting)` Hide the text formatted with this TextTag.
    `void` | `setJustify(Justification setting)` Adopt the given justification for a given passage of text.
    `void` | `setMarginLeft(int pixels)` Specify the left margin, in pixels.
    `void` | `setMarginRight(int pixels)` Specify the right margin, in pixels.
    `void` | `setPaddingAboveParagraph(int pixels)` Set the padding that will be put above each paragraph of text.
    `void` | `setPaddingBelowParagraph(int pixels)` Set the padding that will be put below each paragraph of text.
    `void` | `setPaddingInsideParagraph(int pixels)` Set the padding that will be put between each line in a paragraph if wrapping is turned on.
    `void` | `setParagraphBackground(String color)` Specify the background colour to be used by the [rectangular] space behind the current paragraph as a whole?
    `void` | `setRise(double rise)` Indicate that a span of characters is to be positioned at other than the baseline.
    `void` | `setScale(Scale scale)` Specify that you want the text scaled up or scaled down from the otherwise extant font size.
    `void` | `setSize(double size)` Set the font size, in points.
    `void` | `setStrikethrough(boolean setting)` Specify that this text be rendered struck through.
    `void` | `setStyle(Style style)` Specify the font style to be used ( `NORMAL`, `OBLIQUE` and `ITALIC`s).
    `void` | `setUnderline(Underline underline)` Specify the underling mode to be used for this text.
    `void` | `setWeight(Weight weight)` Specify the font weight.
    `void` | `setWrapMode(WrapMode mode)` Set the wrapping to be applied within this section of text.
    `String` | `toString()`

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### TextTag

          public TextTag()

      Create a new TextTag and place it in the default TextTagTable. This will be usable by a TextBuffer created with the `no-arg` constructor.
      Since:
        4.0.9

    - #### TextTag

          public TextTag(String name)

      Create a new TextTag and place it in the default TextTagTable. The supplied `name` has no particular effect but can be helpful for debugging. Otherwise just use TextTag `<init>()`.
      Since:
        4.1.1

    - #### TextTag

          public TextTag(TextTagTable table)

      Create a new TextTag. You pass the TextTagTable that will enclose this TextTag as the argument to the constructor.

      In native GTK you have to add TextTags to TextTagTables; we do this for you automatically.

      Since:
        4.0.9

    - #### TextTag

          public TextTag(TextTagTable table,
                 String name)

      Since:
        4.1.1

  - ### Method Detail

    - #### setBackground

          public void setBackground(String color)

      Specify the background colour via a String description.

      See `setForeground()` for discussion of allowable colour names.

      The default is no explicit setting.

      Since:
        4.0.9

    - #### setBackgroundFullHeight

          public void setBackgroundFullHeight(boolean setting)

      Does the background colouring specified by `setBackground()` fills the entire line height or only the height of the tagged characters.
      Since:
        4.1.1

    - #### setEditable

          public void setEditable(boolean setting)

      Set whether the region of text covered by this TextTag is editable by the user.
      Since:
        4.0.9

    - #### setFamily

          public void setFamily(String font)

      Specify the font family to be used. This is a family name like "Bitstream Vera" or "DejaVu" or "Liberation".

      In general, it is better to use the standard aliases "Serif", "Sans", and "Monospaced" than naming a family by hand as this lets the user assign their own meanings to those terms via the Fonts tab in `gnome-appearance-properties`.

      Note that you need to specify this early; if you set this after setting other propertes on the TextTag, it may reset them.

      Since:
        4.0.10

    - #### setFont

          public void setFont(String str)

      Pass a string that describes the font you wish to use. This is essentially a convenience wrapper around creating a FontDescription with FontDescription's `<init>(String)` constructor; see there for details of the syntax allowed.
      Since:
        4.0.10

    - #### setFontDescription

          public void setFontDescription(FontDescription desc)

      Pass a FontDescription specifying the metrics and characteristics of the font you wish to be active when this TextTag is applied.
      Since:
        4.0.10

    - #### setForeground

          public void setForeground(String colour)

      Specify the foreground colour by name.

      Colours can be specified either:

      - as hex, in the form `"#rrggbb"` where `rr`, `gg`, and `bb` are two hexadecimal characters expressing a values between `0x00` and `0xFF` for red, green, and blue respectively; or
      - as a symbolic name, such as `"blue"` and `"medium sea green"`, depending on what constants have been built into your X server. You can likely see a list at `/usr/share/X11/rgb.txt`. Obviously these are unreliable between different systems, but they are undeniably easy to use.

      The default is no explicit setting.

      Since:
        4.0.9

    - #### setIndent

          public void setIndent(int pixels)

      Specify the amount by which this paragraph is to be indented, in pixels. Interestingly, this can be negative, in which case you get a hanging indent. The default is `0`.
      Since:
        4.0.9

    - #### setInvisible

          public void setInvisible(boolean setting)

      Hide the text formatted with this TextTag.

      FIXME what happens when you insert at a point that is marked invisible? Backspace into it? What is the interaction with the editable property and `insertInteractive()`?

      GTK further notes there are problems with invisible text and programmatic navigation of TextBuffers.

      Since:
        Unstable

    - #### setJustify

          public void setJustify(Justification setting)

      Adopt the given justification for a given passage of text.
      Since:
        4.1.1

    - #### setMarginLeft

          public void setMarginLeft(int pixels)

      Specify the left margin, in pixels. The default is `0`.
      Since:
        4.1.1

    - #### setMarginRight

          public void setMarginRight(int pixels)

      Specify the right margin, in pixels. The default is `0`.
      Since:
        4.1.1

    - #### setPaddingAboveParagraph

          public void setPaddingAboveParagraph(int pixels)

      Set the padding that will be put above each paragraph of text. See TextView's `setPaddingAboveParagraph()`.
      Since:
        4.1.1

    - #### setPaddingBelowParagraph

          public void setPaddingBelowParagraph(int pixels)

      Set the padding that will be put below each paragraph of text. See TextView's `setPaddingBelowParagraph()`.
      Since:
        4.1.1

    - #### setPaddingInsideParagraph

          public void setPaddingInsideParagraph(int pixels)

      Set the padding that will be put between each line in a paragraph if wrapping is turned on. See TextView's `setPaddingInsideParagraph()`.
      Since:
        4.1.1

    - #### setParagraphBackground

          public void setParagraphBackground(String color)

      Specify the background colour to be used by the [rectangular] space behind the current paragraph as a whole? Contrast to `setBackground()` which sets the background colour of of just the text itself.
      Since:
        4.1.1

    - #### setRise

          public void setRise(double rise)

      Indicate that a span of characters is to be positioned at other than the baseline. This is typically used to create superscripts and subscripts, although you want to be careful because you are likely also changing font sizes when doing so.

      The measurement is in points. A negative number will take you below the baseline.

      Be aware that whenever non-uniform sizing is used on a line, the TextView will render that line as higher than the other lines in a document. This can often be an unwanted (but hard to trivially avoid) side-effect.

      See also `RiseAttribute` which is the underlying mechanism which powers this in Pango.

      Since:
        4.0.14

    - #### setScale

          public void setScale(Scale scale)

      Specify that you want the text scaled up or scaled down from the otherwise extant font size. The default is `NORMAL` (that is, a scaling factor of `1.0` which thereby has no effect).
      Since:
        4.0.9

    - #### setSize

          public void setSize(double size)

      Set the font size, in points.
      Since:
        4.0.10

    - #### setStrikethrough

          public void setStrikethrough(boolean setting)

      Specify that this text be rendered struck through.
      Since:
        4.0.9

    - #### setStyle

          public void setStyle(Style style)

      Specify the font style to be used ( `NORMAL`, `OBLIQUE` and `ITALIC`s).
      Since:
        4.0.9

    - #### setUnderline

          public void setUnderline(Underline underline)

      Specify the underling mode to be used for this text. Single underlining is `SINGLE`. `NONE` is the default, obviously.
      Since:
        4.0.9

    - #### setWeight

          public void setWeight(Weight weight)

      Specify the font weight. The useful one is `BOLD`; the default is `NORMAL`.
      Since:
        4.0.9

    - #### setWrapMode

          public void setWrapMode(WrapMode mode)

      Set the wrapping to be applied within this section of text.
      Since:
        4.1.1

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `org.freedesktop.bindings.Pointer`