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.
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:
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.
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() |