13.6. Text Tags and Tag Tables
Prev | Chapter 13. TextView Widget | Next

## 13.6. Text Tags and Tag Tables

TextTags specify attributes that can be applied to a range of text in a TextBuffer. Each `TextBuffer` has a `TextTagTable` that contains the `TextTag`s that can be applied within the `TextBuffer`. `TextTagTable`s can be used with more than one `TextBuffer` to provide consistent text styles.

### 13.6.1. Text Tags

`TextTag`s can be named or anonymous. A `TextTag` is created using the function:

      tag = gtk.TextTag(name=None)

If `name` is not specified or is `None` the `tag` will be anonymous. `TextTag`s can also be created using the `TextBuffer` convenience method `create_tag`() which also allows you specify the `tag` attributes and adds the `tag` to the buffer's tag table (see Section 13.3, “Text Buffers”).

The attributes that can be contained in a `TextTag` are:

name | Read / Write | Name of the text tag. `None` if anonymous.
background | Write | Background color as a string
foreground | Write | Foreground color as a string
background-gdk | Read / Write | Background color as a GdkColor
foreground-gdk | Read / Write | Foreground color as a GdkColor
background-stipple | Read / Write | Bitmap to use as a mask when drawing the text background
foreground-stipple | Read / Write | Bitmap to use as a mask when drawing the text foreground
font | Read / Write | Font description as a string, e.g. "Sans Italic 12"
font-desc | Read / Write | Font description as a PangoFontDescription
family | Read / Write | Name of the font family, e.g. Sans, Helvetica, Times, Monospace
style | Read / Write | Font style as a PangoStyle, e.g. pango.STYLE_ITALIC.
variant | Read / Write | Font variant as a PangoVariant, e.g. pango.VARIANT_SMALL_CAPS.
weight | Read / Write | Font weight as an integer, see predefined values in PangoWeight; for example, pango.WEIGHT_BOLD.
stretch | Read / Write | Font stretch as a PangoStretch, e.g. pango.STRETCH_CONDENSED.
size | Read / Write | Font size in Pango units.
size-points | Read / Write | Font size in points
scale | Read / Write | Font size as a scale factor relative to the default font size. This properly adapts to theme changes etc. so is recommended. Pango predefines some scales such as pango.SCALE_X_LARGE.
pixels-above-lines | Read / Write | Pixels of blank space above paragraphs
pixels-below-lines | Read / Write | Pixels of blank space below paragraphs
pixels-inside-wrap | Read / Write | Pixels of blank space between wrapped lines in a paragraph
editable | Read / Write | Whether the text can be modified by the user
wrap-mode | Read / Write | Whether to wrap lines never, at word boundaries, or at character boundaries
justification | Read / Write | Left, right, or center justification
direction | Read / Write | Text direction, e.g. right-to-left or left-to-right
left-margin | Read / Write | Width of the left margin in pixels
indent | Read / Write | Amount to indent the paragraph, in pixels
strikethrough | Read / Write | Whether to strike through the text
right-margin | Read / Write | Width of the right margin in pixels
underline | Read / Write | Style of underline for this text
rise | Read / Write | Offset of text above the baseline (below the baseline if rise is negative) in pixels
background-full-height | Read / Write | Whether the background color fills the entire line height or only the height of the tagged characters
language | Read / Write | The language this text is in, as an ISO code. Pango can use this as a hint when rendering the text. If you don't understand this parameter, you probably don't need it.
tabs | Read / Write | Custom tabs for this text
invisible | Read / Write | Whether this text is hidden. Not implemented in GTK+ 2.0

The attributes can be set by using the method:

      tag.set_property(name, value)

Where `name` is a string containing the name of the property and `value` is what the property should be set to.

Likewise the attribute value can be retrieved with the method:

      value = tag.get_property(name)

Since the tag does not have a value set for every attribute there are a set of boolean properties that indicate whether the attribute has been set in the tag:

background-set | Read / Write
foreground-set | Read / Write
background-stipple-set | Read / Write
foreground-stipple-set | Read / Write
family-set | Read / Write
style-set | Read / Write
variant-set | Read / Write
weight-set | Read / Write
stretch-set | Read / Write
size-set | Read / Write
scale-set | Read / Write
pixels-above-lines-set | Read / Write
pixels-below-lines-set | Read / Write
pixels-inside-wrap-set | Read / Write
editable-set | Read / Write
wrap-mode-set | Read / Write
justification-set | Read / Write
direction-set | Read / Write
left-margin-set | Read / Write
indent-set | Read / Write
strikethrough-set | Read / Write
right-margin-set | Read / Write
underline-set | Read / Write
rise-set | Read / Write
background-full-height-set | Read / Write
language-set | Read / Write
tabs-set | Read / Write
invisible-set | Read / Write

Therefore to obtain the attribute from a tag, you have to first check whether the attribute has been set in the tag. For example to get a valid justification attribute you may have to do something like:

      if tag.get_property("justification-set"):
    	justification = tag.get_property("justification")

The priority of a tag is by default the order in which they are added to the `TextTagTable`. The higher priority tag takes precedence if multiple tags try to set the same attribute for a range of text. The priority can be obtained and set with the methods:

      priority = tag.get_priority()

      tag.set_priority(priority)

The priority of a tag must be between 0 and one less than the `TextTagTable` size.

### 13.6.2. Text Tag Tables

A `TextTagTable` will be created by default when a `TextBuffer` is created. A `TextTagTable` can also be created with the function:

      table = TextTagTable()

A `TextTag` can be added to a `TextTagTable` using the method:

      table.add(tag)

The `tag` must not be in the `table` and must not have the same name as another tag in the table.

You can find a `TextTag` in a `TextTagTable` using the method:

      tag = table.lookup(name)

The method returns the `tag` in the table with the given `name` or `None` if no tag has that `name`.

A `TextTag` can be removed from a `TextTagTable` with the method:

      table.remove(tag)

The size of the `TextTagTable` can be obtained with the method:

      size = table.get_size()

Prev | Up | Next
13.5. Text Marks | Home | 13.7. A TextView Example