After a new sgml widget has been created with the sgml pathname command, widget commands are be used to communicate with the new widget. When a new sgml widget is created with the command sgml pathname, a new Tcl command is established where the name of the command equals the pathname of the new sgml widget.
Widget commands are used to communicate with an existing sgml widget. For example, if you create a new sgml widget with the widget pathname .s, a new Tcl command .s is created that can be used to talk to the sgml widget with the pathname .s. Widget commands are passed as arguments to the .s Tcl command that tell the sgml widget which operations should be performed.
The following command creates a new sgml widget with the widget pathname .s and a new Tcl command .s for communicating with this widget:
| sgml .s |
The Tcl command .s can then be used to tell the sgml widget what to do. The requested operation must be a widget command that is understood by the sgml widget. The following command tells the sgml widget .s to load the document example1.sgml by using the load widget command:
| .s load example1.sgml |
In this example, the file name example1.sgml for the document is passed as an argument to the load widget command.
Any of these values may be abbreviated, and upper-case spellings are also acceptable.
Many of the widget commands for sgml widgets take one or more indices as arguments. An index is a string used to indicate a particular place within a text, such as a place to insert characters or one endpoint of a range of characters to delete. Indices have the syntax
base modifier modifier modifier ...
Where base gives a starting point and the modifiers adjust the index from the starting point (e.g. move forward or backward one character). Every index must contain a base but the modifiers are optional.
The base for an index must have one of the following forms:
Indicates char'th character on line line. Lines are numbered from 1 for consistency with other programs that use this numbering scheme. Within a line, characters are numbered from 0. If char is end then it refers to the newline character that ends the line.
Indicates the character that covers the pixel whose x and y coordinates within the text's window are x and y.
Indicates the end of the text (the character just after the last newline).
Indicates the character just after the mark whose name is mark.
Indicates the first character in the text that has been tagged with tag. This form generates an error if no characters are currently tagged with tag.
Indicates the character just after the last one in the text that has been tagged with tag. This form generates an error if no characters are currently tagged with tag.
Indicates the position of the embedded window whose name is pathName. This form generates an error if there is no embedded window by the given name.
Indicates the position of the embedded image whose name is imageName. This form generates an error if there is no embedded image by the given name.
If the base could match more than one of the above forms, then the form earlier in the above list takes precedence.
If modifiers follow the base index, each one of them must have one of the forms listed below. Keywords such as chars and wordend may be abbreviated as long as the abbreviation is unambiguous.
Adjust the index forward by count characters, moving to later lines in the text if necessary. If there are fewer than count characters in the text after the current index, then set the index to the last character in the text. Spaces on either side of count are optional.
Adjust the index backward by count characters, moving to earlier lines in the text if necessary. If there are fewer than count characters in the text before the current index, then set the index to the first character in the text. Spaces on either side of count are optional.
Adjust the index forward by count lines, retaining the same character position within the line. If there are fewer than count lines after the line containing the current index, then set the index to refer to the same character position on the last line of the text. Then, if the line is not long enough to contain a character at the indicated character position, adjust the character position to refer to the last character of the line (the newline). Spaces on either side of count are optional.
Adjust the index backward by count lines, retaining the same character position within the line. If there are fewer than count lines before the line containing the current index, then set the index to refer to the same character position on the first line of the text. Then, if the line is not long enough to contain a character at the indicated character position, adjust the character position to refer to the last character of the line (the newline). Spaces on either side of count are optional.
Adjust the index to refer to the first character on the line.
Adjust the index to refer to the last character on the line (the newline).
Adjust the index to refer to the first character of the word containing the current index. A word consists of any number of adjacent characters that are letters, digits, or underscores, or a single character that is not one of these.
Adjust the index to refer to the character just after the last one of the word containing the current index. If the current index refers to the last character of the text then it is not modified.
If more than one modifier is present then they are applied in left-to-right order. For example, the index end - 1 chars refers to the next-to-last character in the text and insert wordstart - 1 c refers to the character just before the first one in the word containing the insertion cursor.
Any of the valid textual names for a color defined in the server's color database file, such as red or Peach-Puff. On system that do not support color names, a set of standard colors is supported.
#RGB, #RRGGBB, #RRRGGGBBB, or #RRRRGGGGBBBB
A numeric specification of the red, green, and blue intensities to use
to display the color. Each R, G, or B represents a single hexadecimal
digit. The four forms permit colors to be specified with 4-bit,
8-bit, 12-bit or 16-bit values. When fewer than 16 bits are provided
for each color, they represent the most significant bits of the color.
For example, #3a7 is the same as #3000a0007000.
Fonts of the first type (dynamic fonts) are constructed from
different parts of the font description that is collected from various
sources. Typically, these bits of information are provided as the
values for -family, -size, -weight, and -slant
configuration options for SGML elements. Dynamic fonts are constructed
when they are needed by combining these pieces of
information. Section ![[*]](crossref.png)
contains a description of the
internals of this combination process.
Fonts of the second type (we call them static fonts) are completely determined by the user (with the possible exception that font details that have not been specified are defaulted by the Tk font system). Typically, static fonts appear as the value of a -font configuration option. See the Tk documentation for a description of the several ways in which fonts may be specified.
Screen distances are expressed by a string that specifies the screen distance as a floating-point number followed by one of the following characters that indicates units:
The number specifies a distance in pixels. The physical distance expressed by the number depends on the monitor and resolution of the graphics hardware.
The number specifies a distance in centimeters on the screen. The physical distance is computed according to the information about the display hardware provided by the underlying operating system.
The number specifies a distance in inches on the screen.
The number specifies a distance in millimeters on the screen.
The number specifies a distance in printer's points (1/72 inch) on the screen.
When a bitmap must be specified as a the value of a configuration option or as a parameter to a widget command, the name of an existing bitmap must be used.
Tk provides a set of predefined bitmaps that are useful for stippling:
75% gray: a checkerboard pattern where three out of four bits are on.
50% gray: a checkerboard pattern where every other bit is on.
25% gray: a checkerboard pattern where one out of every four bits is on.
12.5% gray: a pattern where one-eighth of the bits are on, consisting of every fourth pixel in every other row.
In addition to these predefined bitmaps, user-defined bitmaps can be used by specifying their name or by providing the name of a file containing the bitmap in standard X10 or X11 format in the form @filename. Please refer to the Tk documentation for details about defining new bitmaps.
Some widget commands and configuration options expect a relief specification to determine how to draw a 3-D effect. Acceptable relief values are raised, sunken, flat, ridge, solid, and groove.
Handles are Tcl tokens that are used to manipulate certain objects in the sgml widget, e.g. elements or marked sections. Handles must be obtained from the sgml widget and can not be arbitrarily constructed.
Handles belong to individual instances of the sgml widget and can only be used in the widget that has created the handle. If two or more sgml widgets are created in an application, a handle that has been returned from one of these widgets is not valid in any of the other sgml widgets.