Tags

The first form of annotation in text widgets is a tag. A tag is a textual string that is associated with some of the characters in a text. Tags may contain any characters but not these:

- . ' , ; + : @

There may be any number of tags associated with characters in a text. Each tag may refer to a single character, a range of characters, or several ranges of characters. An individual character may have any number of tags associated with it.

A priority order is defined among tags, and this order is used in implementing some of the tag-related functions described below. When a tag is defined (by associating it with characters or setting its display options or binding commands to it), it is given a priority higher than any existing tag. The priority order of tags may be redefined using the ``pathName tag raise'' and ``pathName tag lower'' widget commands.

Tags serve three purposes in text widgets. First, they control the way information is displayed on the screen. By default, characters are displayed as determined by the background, font, and foreground options for the text widget. However, display options may be associated with individual tags using the ``pathName tag configure'' widget command. If a character has been tagged, then the display options associated with the tag override the default display style. The following options are currently supported for tags:

#:background color

Color specifies the background color to use for characters associated with the tag. It may have any of the forms accepted by Tk_GetColor.

#:bgstipple bitmap

Bitmap specifies a bitmap that is used as a stipple pattern for the background. It may have any of the forms accepted by Tk_GetBitmap. If bitmap hasn't been specified, or if it is specified as an empty string, then a solid fill will be used for the background.

#:borderwidth pixels

Pixels specifies the width of a 3-D border to draw around the background. It may have any of the forms accepted by Tk_GetPixels. This option is used in conjunction with the #:relief option to give a 3-D appearance to the background for characters; it is ignored unless the #:background option has been set for the tag.

#:elide boolean

Elide specifies whether the data should be elided. Elided data is not displayed and takes no space on screen, but further on behaves just as normal data.

#:fgstipple bitmap

Bitmap specifies a bitmap that is used as a stipple pattern when drawing text and other foreground information such as underlines. It may have any of the forms accepted by Tk_GetBitmap. If bitmap hasn't been specified, or if it is specified as an empty string, then a solid fill will be used.

#:font fontName

FontName is the name of a font to use for drawing characters. It may have any of the forms accepted by Tk_GetFont.

#:foreground color

Color specifies the color to use when drawing text and other foreground information such as underlines. It may have any of the forms accepted by Tk_GetColor.

#:justify justify

If the first character of a display line has a tag for which this option has been specified, then justify determines how to justify the line. It must be one of left, right, or center. If a line wraps, then the justification for each line on the display is determined by the first character of that display line.

#:lmargin1 pixels

If the first character of a text line has a tag for which this option has been specified, then pixels specifies how much the line should be indented from the left edge of the window. Pixels may have any of the standard forms for screen distances. If a line of text wraps, this option only applies to the first line on the display; the #:lmargin2 option controls the indentation for subsequent lines.

#:lmargin2 pixels

If the first character of a display line has a tag for which this option has been specified, and if the display line is not the first for its text line (i.e., the text line has wrapped), then pixels specifies how much the line should be indented from the left edge of the window. Pixels may have any of the standard forms for screen distances. This option is only used when wrapping is enabled, and it only applies to the second and later display lines for a text line.

#:offset pixels

Pixels specifies an amount by which the text's baseline should be offset vertically from the baseline of the overall line, in pixels. For example, a positive offset can be used for superscripts and a negative offset can be used for subscripts. Pixels may have any of the standard forms for screen distances.

#:overstrike boolean

Specifies whether or not to draw a horizontal rule through the middle of characters. Boolean may have any of the forms accepted by Tk_GetBoolean.

#:relief relief

Relief specifies the 3-D relief to use for drawing backgrounds, in any of the forms accepted by Tk_GetRelief. This option is used in conjunction with the #:borderwidth option to give a 3-D appearance to the background for characters; it is ignored unless the #:background option has been set for the tag.

#:rmargin pixels

If the first character of a display line has a tag for which this option has been specified, then pixels specifies how wide a margin to leave between the end of the line and the right edge of the window. Pixels may have any of the standard forms for screen distances. This option is only used when wrapping is enabled. If a text line wraps, the right margin for each line on the display is determined by the first character of that display line.

#:spacing1 pixels

Pixels specifies how much additional space should be left above each text line, using any of the standard forms for screen distances. If a line wraps, this option only applies to the first line on the display.

#:spacing2 pixels

For lines that wrap, this option specifies how much additional space to leave between the display lines for a single text line. Pixels may have any of the standard forms for screen distances.

#:spacing3 pixels

Pixels specifies how much additional space should be left below each text line, using any of the standard forms for screen distances. If a line wraps, this option only applies to the last line on the display.

#:tabs tabList

TabList specifies a set of tab stops in the same form as for the #:tabs option for the text widget. This option only applies to a display line if it applies to the first character on that display line. If this option is specified as an empty string, it cancels the option, leaving it unspecified for the tag (the default). If the option is specified as a non-empty string that is an empty list, such as #:tags '(), then it requests default 8-character tabs as described for the tags widget option.

#:underline boolean

Boolean specifies whether or not to draw an underline underneath characters.

#:wrap mode

Mode specifies how to handle lines that are wider than the text's window. It has the same legal values as the #:wrap option for the text widget:

• none
• char
• word

If this tag option is specified, it overrides the #:wrap option for the text widget.

If a character has several tags associated with it, and if their display options conflict, then the options of the highest priority tag are used. If a particular display option hasn't been specified for a particular tag, or if it is specified as an empty string, then that option will never be used; the next-highest-priority tag's option will used instead. If no tag specifies a particular display option, then the default style for the widget will be used.

The second purpose for tags is event bindings. You can associate bindings with a tag in much the same way you can associate bindings with a widget class: whenever particular X events occur on characters with the given tag, a given command will be executed. Tag bindings can be used to give behaviors to ranges of characters; among other things, this allows hypertext-like features to be implemented. For details, see the description of the tag bind widget command below.

The third use for tags is in managing the selection. See selection below.

© Author | Home | Sitemap