Next: II. Widget Commands Up: I. Using TkSGML Previous: 3. TkSGML Usage Contents Index

4. Widget Contents

The sgml widget displays the contents of an SGML document on one or more lines and allows editing of the document. When displaying a document, the sgml widget distinguishes the SGML markup from the data and displays them differently. The data of the sgml document is shown as text while the markup in the document is graphically distinguished from the data. In addition to text and markup, the sgml widget supports the use of several kinds of annotations on the sgml document.

4.1 Text

Any textual data in the document is shown as text within the sgml widget, possibly interspersed with markup and annotations. The basic layout of any text in the widget is determined by the configuration options of the sgml widget, possibly modified by configuration options for elements and tag annotations (see section ).

4.1.1 Text properties

In particular, every piece of text in the sgml widget can be characterized by the following text properties:

font family, font size, weight, and slant determine the font to be used for the text.
foreground color and background color define the colors to be used when drawing the text.
overstrike and underline values specify if a horizontal line should be drawn over or under the text.
bitmaps for foreground and background stippling can be combined with the characters of the background of the text.
vertical spacing values determine how much additional vertical space is added above and below the line containing the text.
tab settings are used to determine how tab stops in the text are to be expanded.
the line wrapping can be adjusted from no wrapping over word wrapping to wrapping at any character or at a fixed horizontal position.
the justification defines how the text should be justified in the sgml widget.
margins determine how much additional horizontal space should be added to the left or right of a line of text.
offsets are used to move the baseline of a text above (or below) the baseline of the line containing the text.

Configuration options for influencing these properties can be set for the sgml widget, for elements of a given name (e.g. for all elements named heading), for an individual element (e.g. a specific heading element), or for tag annotations that are assigned to a designated region of the document.

The properties of a piece of text to be drawn are derived by examining and combining the configuration options of the sgml widget, the sgml elements that contain the text, and any relevant tag annotations. If no configuration options can be found for a text property, a built-in default is used. This approach establishes a simple property inheritance scheme that is based on configuration options for nested sgml elements.

When determining the text properties, the property values are collected in the following order for each of the properties listed above:

Any tag annotations are examined for the corresponding configuration option. If more than one tag annotation applies to the text in question, the tag priority determines the tag from which to derive the text property.
The individual sgml element containing the text is checked for the appropriate configuration option. E.g. if the text is contained in the third heading element in the document, this specific heading is checked for the configuration option corresponding to the text property.
If a configured XPath matches the sgml element containing the text, the configuration options for this XPath are checked for the text property.
The overall configuration options for the sgml element containing the text are examined. E.g. if the text is contained in a heading element, the configuration options that have been specified for all heading elements in general are checked.
The steps from to are repeated for all elements containing the text. E.g. if the text is part of a paragraph element which occurs inside a section element which occurs inside a chapter element, the configurations options for the paragraph, section, and chapter elements are check in that order.
The configuration options for the sgml widget are examined for the appropriate option.
If all this fails, a built-in default is used.

If any of the steps outline above yields a result for the text property, the text property is set to this value and the search process is restarted with the next text property. This process continues until all text property settings have been collected and the text can be drawn.

4.2 Markup

Markup that occurs in the SGML or XML document is recognized by the sgml widget and displayed in several forms, depending on the type of markup. The individual markup types and their graphical representation is discussed in the following sections.

4.2.1 Elements

Each SGML or XML document contains at least one Element, which will usually contain other elements. Elements are the key concepts used in the sgml widget: Most operations affect elements and the element widget command is the most powerful SGML/XML related command of the sgml widget.

Each Element in the document instance is enclosed in a pair of matching delimiters that correspond to the tags in the SGML document. These delimiters are drawn in the shape of an arrow that points to the right at the beginning of the element; they point to the left at the end of the enclosed element.

For the sake of simplicity and because of their close relation to SGML tags, we will call these delimiters element tags or tags. One important difference between SGML tags and the element tags drawn by the sgml widget is that every element in the document instance is enclosed in a pair of tags, even if tag omission has been specified for one or both SGML tags in the DTD.^4.1

Apart from delimiting elements, element tags serve two important purposes:

They are used to display the element name, the attributes and the attribute values for the enclosed element.
They are used to mark invalid elements, i.e. elements that have become temporarily invalid during the editing process.

Figure illustrates how element tags are displayed. It shows an ELEMENT1 element that contains some text.

**Figure:** Element tags
$\begin{figure}\begin{center} \leavevmode\epsfbox{images/element1.eps}\end{center}\end{figure}$

Naturally, elements can be nested with each other. The element tags of an embedded element will appear within the content of the enclosing element.

Element tags count as single characters in the sgml widget, independently of the size they occupy in the widget's window and the amount of information they display. For example, if the insertion cursor is located just to the left of an element tag and it is moved one character to the right, the new location would be immediately to the right of the element tag.

Element tags are drawn by the sgml widget in two different colors. An element that matches the elements content definition is shown in the default color for element tags. If something is wrong with an element, e.g. because a required sub-element is missing and must be inserted, the text in the element tags is drawn in a different color^4.2 to signal that the element needs attention.

4.2.1.1 Elements with attributes

For every element in the SGML document, the sgml widget maintains a list of attributes and attribute values. For each element, the current contents of this list are displayed in in the start tag of the element.

Figure illustrates how attributes and attribute values are displayed in element tags. It shows the begin and end tags for a single element ELEMENT1. This element has two attributes ATT1 and ATT2 which have the attribute values of value1 and value2, respectively.

**Figure:** Tags for elements with attributes
$\begin{figure}\begin{center} \leavevmode\epsfbox{images/element2.eps}\end{center}\end{figure}$

When an element is created while an SGML document is loaded from file, the attribute list of the element is initialized with the attributes and values determined by the SGML parser during the analysis of the element structure.

The sgml widget provides the necessary commands to modify the attribute list of an element. Whenever an attribute value is changed, the start tag of the element is redrawn to reflect the new attribute value.

It is possible to disable the display of attributes in general by a widget configuration option. In this case, the element's start tag will be shown as if no attribute values were specified. The display of individual attributes can be disabled on a per-attribute basis for each element in the document.

4.2.1.2 Empty elements

Elements that have been defined as EMPTY in the DTD will be shown with a minimized end tag that does not contain the element name. Since no data or other tags can occur between the start tag and the minimized end tag, this does not introduce any ambiguity. Figure shows an example of an empty element ELEMENT2.

**Figure:** Tags for empty elements
$\begin{figure}\begin{center} \leavevmode\epsfbox{images/element3.eps}\end{center}\end{figure}$

This display is used only for elements that have a declared content type of EMPTY; elements which must be empty because of a conref attribute are shown as normal elements.^4.3

4.2.2 Entities

Entity references that occur in the SGML document are displayed depending on the type of entity that is referenced. Any entity that is not a simple text entity (i.e. a CDATA, NDATA, SDATA and PI entity) is shown as a entity reference. Entity references look very much like text and contain the name of the entity enclosed in entity reference delimiters. Like an element tag, an entity reference counts as a single character in the sgml widget. Figure shows some text containing a reference to the entity entity2.

**Figure:** Entity references
$\begin{figure}\begin{center} \leavevmode\epsfbox{images/entity1.eps}\end{center}\end{figure}$

Entity configuration options can be used to specify which text properties apply to the entity reference. If configuration options have been specified for an entity, they are checked after the configuration options for tag annotations but before any configuration options for the enclosing elements. This means that entity configuration options override the configuration options of the element context when the text properties are determined.

It is possible to modify the display of an entity reference to show an image or an arbitrary string instead of the entity name (and the entity delimiters). By using an arbitrary string for the entity reference and setting the appropriate configuration options (such as -font) for the entity, arbitrary replacement glyphs can be specified that are displayed in place of the entity reference. This approach is useful e.g. for providing a graphical representation for character entities.

**Figure:** Modified entity reference
$\begin{figure}\begin{center} \leavevmode\epsfbox{images/entity3.eps}\end{center}\end{figure}$

Figure shows the entity reference from figure where the appropriate configuration options have been set to display a down-arrow symbol instead of the entity name.

4.2.2.1 Text entities

References to entities that are defined as text entities are treated differently from references to other entities. Depending on a configuration option, instead of displaying an entity reference, the contents of the text entity can be shown, enclosed in text entity tags. Since text entities are normally used to provide blocks of text that are used repeatedly in a set of documents, the content of a text entity should not be hidden to avoid disrupting the textual structure of the document. Figure shows an example of a text entity with the text entity content. Here, the name of the text entity entity1 is enclosed in entity reference delimiters to distinguish the text entity tags from element tags.

**Figure:** Text entity tags
$\begin{figure}\begin{center} \leavevmode\epsfbox{images/entity2.eps}\end{center}\end{figure}$

Since the content of the text entity is not defined at the place where the text entity is referenced, the sgml widget blocks any alterations to the text between the start and end tag of the text entity.

Text entities can be nested. In this case, the start and end tags of embedded text entities would occur within the contents of the enclosing text entity.

4.2.3 Marked Sections

The contents of a marked section are enclosed in marked section tags as shown in figure . The effective status of a marked section is shown in square brackets in the start end end tags of the marked section.

**Figure:** Marked section tags
$\begin{figure}\begin{center} \leavevmode\epsfbox{images/msection1.eps}\end{center}\end{figure}$

The marked section contents can be edited like any other widget contents, but certain operations may be blocked by the sgml widget depending on the effective status of a marked section. For example, the sgml widget will refuse to create a new element inside a marked section that has an effective status of CDATA.

Like elements and text entities, marked sections can be nested. For nested marked sections, the start end end tags of the embedded marked section occurs within the content of the enclosing marked section.

4.2.4 Comments

Comments that occur inside an sgml widget are enclosed in a pair of comment tags where the text of the comment is shown between the tags. Figure shows an example of a comment as it is displayed by the sgml widget.

**Figure:** Comment tags
$\begin{figure}\begin{center} \leavevmode\epsfbox{images/comment1.eps}\end{center}\end{figure}$

The text of the comment can be edited like any other document data. The sgml widget blocks all attempts to create any markup inside of the comment.

The text properties of the comment text can be modified by widget configuration options (see section for details).

4.2.5 Processing Instructions

Processing instructions, PIs for short, are displayed as a pair of PI tags. The contents of the PI are shown in the start tag of the PI, preceeded by a question mark. Figure shows an example of a PI.

**Figure:** PI tags
$\begin{figure}\begin{center} \leavevmode\epsfbox{images/pi1.eps}\end{center}\end{figure}$

The end tag of the PI is minimized like the end tags of empty elements. At most 40 characters are shown in the start tag of a PI. If the PI contains more than 40 characters, the first 37 characters are shown in the start tag, followed by a sequence of three periods.

The sgml widget provides widget commands to access and modify the PI text. When a PI is changed, the PI tags are updated to reflect the new contents. The sgml widget blocks any attempts to insert any data between the start and end tag of the PI.

4.3 Annotations

Annotations are additional items that are displayed by the sgml widget which are not considered to be part of the sgml document. These annotations are marks, tag annotations, windows, and images.

4.3.1 Marks

The first form of annotation in sgml widgets is a mark. Marks are used for remembering particular places in a document. They are something like tags (see below), in that they have names and they refer to places in the file, but a mark isn't associated with particular characters.

Instead, a mark is associated with the gap between two characters. Only a single position may be associated with a mark at any given time.

If the characters around a mark are deleted the mark will still remain; it will just have new neighbor characters. In contrast, if the characters containing a tag annotation are deleted then the tag will no longer have an association with characters in the file.

Marks may be manipulated with the pathName mark widget command, and their current locations may be determined by using the mark name as an index in widget commands.

Each mark also has a gravity , which is either left or right.

The gravity for a mark specifies what happens to the mark when text is inserted at the point of the mark. If a mark has left gravity, then the mark is treated as if it were attached to the character on its left, so the mark will remain to the left of any text inserted at the mark position. If the mark has right gravity, new text inserted at the mark position will appear to the left of the mark. The gravity for a mark defaults to right.

The name space for marks is different from that for tag annotations: the same name may be used for both a mark and a tag, but they will refer to different things.

Two marks have special significance. First, the mark insert is associated with the insertion cursor, as described in section below.

Second, the mark current is associated with the character closest to the mouse and is adjusted automatically to track the mouse position and any changes to the text in the widget (one exception: current is not updated in response to mouse motions if a mouse button is down; the update will be deferred until all mouse buttons have been released).

Neither of these special marks may be deleted.

4.3.1.1 The insertion cursor

The mark named insert has special significance in sgml widgets. It is defined automatically when an sgml widget is created and it may not be unset with the mark unset widget command. The insert mark represents the position of the insertion cursor, and the insertion cursor will automatically be drawn at this point whenever the sgml widget has the input focus. To move position of the insertion cursor, the position of the insert mark can be moved by a widget command.

4.3.2 Tags

The second form of annotation in sgml widgets is a tag. Tag annotations should not be confused with markup tags. A tag annotation is a textual string that is associated with some of the characters in a text. Tags may contain arbitrary characters, but it is probably best to avoid using the the characters `` '' (space), +, or -: these characters have special meaning in indices, so tags containing them can't be used as indices.

There may be any number of tags associated with characters in a document.

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 tag raise and tag lower widget commands.

Tags serve three purposes in sgml 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 sgml widget.
However, display options may be associated with individual tags using the tag configure widget command. If a character has been tagged, then the display options associated with the tag annotation override the default display style.
If a character has several tag annotations 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 events occur on characters with the given tag, a given Tcl 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 section below.

Please note that it is possible to associate bindings with SGML elements instead of tag annotations. In many cases, it is preferable to determine reactions on events based on the element structure rather than on tag annotations. Using tags for determining display options should be reserved for special purposes like handling the selection. In many cases, it is easier and more efficient to use element configuration options for controlling the display.

4.3.2.1 The selection

Selection support is implemented via tags. If the -exportSelection option for the sgml widget is true then the sel tag will be associated with the selection:

Whenever characters are tagged with sel the sgml widget will claim ownership of the selection.
Attempts to retrieve the selection will be serviced by the sgml widget, returning all the characters with the sel tag.
If the selection is claimed away by another application or by another window within this application, then the sel tag will be removed from all characters in the document.

The sel tag is automatically defined when an sgml widget is created, and it may not be deleted with the tag delete widget command. Furthermore, the -selectBackground, -selectBorderWidth, and -selectForeground options for the sgml widget are tied to the -background, -borderwidth, and -foreground options for the sel tag: changes in either will automatically be reflected in the other.

4.3.3 Windows

The third form of annotation in sgml widgets is an embedded window. Each embedded window annotation causes a window to be displayed at a particular point in the document.

There may be any number of embedded windows in an sgml widget, and any widget may be used as an embedded window (subject to the usual rules for geometry management, which require the sgml window to be the parent of the embedded window or a descendant of its parent).

The embedded window's position on the screen will be updated as the document text is modified or scrolled, and it will be mapped and unmapped as it moves into and out of the visible area of the sgml widget.

Each embedded window occupies one character's worth of index space in the sgml widget, and it may be referred to either by the name of its embedded window or by its position in the widget's index space.

If the range of text containing the embedded window is deleted then the window is destroyed.

When an embedded window is added to an sgml widget with the window create widget command, several configuration options may be associated with it. These options may be modified later with the window configure widget command. See section for a description of the available options.

4.3.4 Images

The final form of annotation in sgml widgets is an embedded image. Each embedded image annotation causes an image to be displayed at a particular point in the document. There may be any number of embedded images in an sgml widget, and a particular image may be embedded in multiple places in the same sgml widget. The embedded image's position on the screen will be updated as the document is modified or scrolled. Each embedded image occupies one character's worth of index space in the sgml widget, and it may be referred to either by its position in the widget's index space, or the name it is assigned when the image is inserted into the sgml widget with image create. If the range of text containing the embedded image is deleted then that copy of the image is removed from the screen.^4.4

Using image annotations is deprecated because the same effects can be achieved by configuring elements or entity references to display an image.

Footnotes

... DTD.^4.1: This is true even for empty elements; however, the SGML widget prevents any attempt to create content for empty elements.
... color ^4.2: red unless modified by a widget configuration option.
... elements.^4.3: Data insertion in elements with a conref attribute is prohibited by the sgml widget.
... screen.^4.4: See also the -image configuration options for elements (section ) and entities (section ).

Next: II. Widget Commands Up: I. Using TkSGML Previous: 3. TkSGML Usage Contents Index

TkSGML Reference Manual