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:

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:

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.