12.6. Gtk2::TextTags and Gtk2::TextTagTables

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

12.6.1. Gtk2::TextTags

Gtk2::TextTags can be named or anonymous. A Gtk2::TextTag is created using the function:

texttag = Gtk2::TextTag->new ($name=undef) 
	* $name (string or undef)
If $name is not specified or is undef the tag will be anonymous. Gtk2::TextTags can also be created using the Gtk2::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 12.3).

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

Table 12-2. Gtk2::TextTag Attributes

nameRead / WriteName of the text tag. undef 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 Gtk2::Pango::FontDescription
familyRead / Write Name 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 / Write Whether to strike through the text
right-marginRead / Write Width 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 Glib::Object's set_property method:

$object->set_property (key => $value, ...) 
Where key 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 Glib::Object's method:

list = $object->get_property (...) 
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:

Table 12-3. Gtk2::TextTag Attributes

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:

($justification = $object->get_property("justification")); 
The priority of a tag is by default the order in which they are added to the Gtk2::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:
integer = $tag->get_priority
$tag->set_priority ($priority) 
	* $priority (integer)
The priority of a tag must be between 0 and one less than the Gtk2::TextTagTable size.

12.6.2. Gtk2::TextTagTable

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

texttagtable = Gtk2::TextTagTable->new 
A Gtk2::TextTag can be added to a Gtk2::TextTagTable using the method:
$table->add ($tag) 
	* $tag (Gtk2::TextTag)
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 Gtk2::TextTag in a Gtk2::TextTagTable using the method:

texttag = $table->lookup ($name) 
	* $name (string)
The method returns the tag in the table with $name or undef if no tag has $name.

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

$table->remove ($tag) 
	* $tag (Gtk2::TextTag)
The size of the Gtk2::TextTagTable can be obtained with the method:
integer = $table->get_size