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 TextTags that can be applied within the TextBuffer. TextTagTables can be used with more than one TextBuffer to provide consistent text styles.

13.6.1. Text Tags

TextTags 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. TextTags 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:

nameRead / WriteName of the text tag. None if anonymous.
backgroundWriteBackground color as a string
foregroundWriteForeground color as a string
background-gdkRead / WriteBackground color as a GdkColor
foreground-gdkRead / WriteForeground color as a GdkColor
background-stippleRead / WriteBitmap to use as a mask when drawing the text background
foreground-stippleRead / WriteBitmap to use as a mask when drawing the text foreground
fontRead / WriteFont description as a string, e.g. "Sans Italic 12"
font-descRead / WriteFont description as a PangoFontDescription
familyRead / WriteName of the font family, e.g. Sans, Helvetica, Times, Monospace
styleRead / WriteFont style as a PangoStyle, e.g. pango.STYLE_ITALIC.
variantRead / WriteFont variant as a PangoVariant, e.g. pango.VARIANT_SMALL_CAPS.
weightRead / WriteFont weight as an integer, see predefined values in PangoWeight; for example, pango.WEIGHT_BOLD.
stretchRead / WriteFont stretch as a PangoStretch, e.g. pango.STRETCH_CONDENSED.
sizeRead / WriteFont size in Pango units.
size-pointsRead / WriteFont size in points
scaleRead / WriteFont 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-linesRead / WritePixels of blank space above paragraphs
pixels-below-linesRead / WritePixels of blank space below paragraphs
pixels-inside-wrapRead / WritePixels of blank space between wrapped lines in a paragraph
editableRead / WriteWhether the text can be modified by the user
wrap-modeRead / WriteWhether to wrap lines never, at word boundaries, or at character boundaries
justificationRead / WriteLeft, right, or center justification
directionRead / WriteText direction, e.g. right-to-left or left-to-right
left-marginRead / WriteWidth of the left margin in pixels
indentRead / WriteAmount to indent the paragraph, in pixels
strikethroughRead / WriteWhether to strike through the text
right-marginRead / WriteWidth of the right margin in pixels
underlineRead / WriteStyle of underline for this text
riseRead / WriteOffset of text above the baseline (below the baseline if rise is negative) in pixels
background-full-heightRead / WriteWhether the background color fills the entire line height or only the height of the tagged characters
languageRead / WriteThe 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.
tabsRead / WriteCustom tabs for this text
invisibleRead / WriteWhether 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-setRead / Write
foreground-setRead / Write
background-stipple-setRead / Write
foreground-stipple-setRead / Write
family-setRead / Write
style-setRead / Write
variant-setRead / Write
weight-setRead / Write
stretch-setRead / Write
size-setRead / Write
scale-setRead / Write
pixels-above-lines-setRead / Write
pixels-below-lines-setRead / Write
pixels-inside-wrap-setRead / Write
editable-setRead / Write
wrap-mode-setRead / Write
justification-setRead / Write
direction-setRead / Write
left-margin-setRead / Write
indent-setRead / Write
strikethrough-setRead / Write
right-margin-setRead / Write
underline-setRead / Write
rise-setRead / Write
background-full-height-setRead / Write
language-setRead / Write
tabs-setRead / Write
invisible-setRead / 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()