3. TkSGML Usage

3.1 Loading TkSGML

Since TkSGML is delivered as a loadable extension for Tcl/Tk in the form of a shared library (or dll), the library must be loaded into a running Tcl application to be used. Loading the library can be achieved by two means: By directly loading the library with the load command or by telling the Tcl package system that the package TkSGML is required.

3.1.1 Loading TkSGML using the package system

If TkSGML has been properly installed, the Tcl package system should be capable of loading the sgml extension when the following Tcl command is used:

	package require Tksgml
$\Rightarrow$	1.2

The package require command returns the version number of the loaded library. The exact result depends on the installed version of TkSGML.

Normally, you will not have to deal with the details of the package naming scheme unless you have more than one version of TkSGML installed. In this case, you may want to use the exact package name to make sure that the correct TkSGML version is used. For example, to load TkSGML 1.2, you could use the command

package require -exact Tksgml 1.2

Please consult chapter  of this manual if the package system fails to load the sgml extension.

3.1.2 Loading TkSGML using the load command

The shared library can be directly loaded with the Tcl load command. The load command requires the name of the shared library that should be loaded; it is advisable to provide an absolute or relative path name instead of the basename of the file. For a Unix-like System, the following command would be used:

load ./libtksgml.so.1.2

For a Windows-based system, the corresponding load command would be:

load ./tksgml.dll

When the TkSGML package is loaded into an Tcl interpreter, the activation key for TkSGML is tested and a number of initialization steps are performed.

3.1.3 The activation key

The activation key is a piece of data that is stored in a operating system file. When the sgml extension is loaded into an Tcl application, the contents of the activation key is read and verified. TkSGML refuses to load when no activation key is present, when the activation key is invalid, or when the activation key has expired.

An activation key contains a serial number that identifies the activation key itself and a version number that specifies the major version of TkSGML that can be activated by this key. For time-restricted licenses such as demo licenses, the activation key contains an expiration date that specifies when the key ceases to be valid.

After the license key has been loaded, some fields in the global Tcl array TkSGML are filled with information from the license key file. These fields are described below:

• TkSGML(keyfile) contains the fully qualified name of the file from which the license key has been read.

• TkSGML(license) contains the license number found in the key file.

• TkSGML(licensee) is the name of the owner of the TkSGML license.

• TkSGML(expires) is the expiration date of the activation key. This is either a numerical date value or the string never for an unlimited license.

• TkSGML(key_major_version) is the version number of TkSGML that can be activated with this activation key. Only the major version of TkSGML is used. This means that an activation key for Release 1.2 can be used for all TkSGML version below 2.0.

3.1.4 Details about the load process

Loading TkSGML (either by using the package system or by loading the extension with the load command) is performed in three steps:

1. The binary of the sgml extension is loaded into the applications address space.
2. After the binary has been loaded, a built-in initialization routine in the binary is called that incorporates it into the Tcl interpreter within the application. This routine loads some utility procedures and the default bindings (see section ) for the sgml widget. It does this by searching for a file with the name tksgml.tcl in the following places:
   1. In the directory specified by the environment variable TKSGML_LIBRARY if this environment variable is set.
   2. In the current directory.
   3. In a subdirectory of the current directory with the name TkSGML-m.n where m.n is the version number of TkSGML.
   4. For MS-Windows based systems: In the directory specified by the registry entry Software\\Epc\\TkSGML\\m.n.
      On Unix-like systems, the predefined value /usr/local/lib/tksgml is used unless the Tcl-variable TkSGML_library is set (in which case the value of this variable is used instead of /usr/local/lib/tksgml).
   5. In a subdirectory with the name TkSGML-m.n of any of the directories in the global Tcl-variable auto_path.
   The first tksgml.tcl file that is found and could be loaded without errors is used. The global Tcl-variable TkSGML_library is set to the directory where this file was found.
3. The activation key is loaded from the file tksgml.key. TkSGML searches for the activation key in the following locations:
   1. In the directory from which tksgml.tcl was loaded.
   2. In the directory containing the Tcl executable (normally the wish program).
   3. In the home directory of the current user.
   4. In the subdirectory tksgml of the user's home directory.
4. The activation key is decoded and compared to the version of TkSGML that you are running. For time-limited licenses (e.g. for demonstration versions of TkSGML), the system time is compared with the expiration date of the license key.

After the sgml extension has been loaded, a number of Tcl variables has been initialized by TkSGML. The following table describes in which of the above steps a variable is initialized. This table can be used to assist in resolving problems related to the load process.

Variable Name	Step
TkSGML(major_version)
TkSGML(minor_version)
TkSGML(version)
TkSGML_library
TkSGML(keyfile)
TkSGML(license)
TkSGML(licensee)
TkSGML(expires)
TkSGML(key_major_version)

After loading the shared library into the Tcl interpreter, a new Tcl command pcrmsgml is created in this interpreter. The pcrmsgml command can then be used to creat any number of sgml widgets in this interpreter.

3.2 Creating a Widget

The sgml command

sgml name ?specs?
	creates a new window name and makes it into an sgml widget. Optionally configures the window with the configuration options in specs.

To use the sgml widget inside a Tk application, it is necessary to create a widget. Like any other Tk widget, an sgml widget is created by invoking a command named after the widget's class. For sgml widget, the command name is simply sgml. The pcrmsgml command has the following general form:

sgml name ?specs?

The only required parameter for the sgml command is the pathname for the new widget in the widget hierarchy. The widget must not already exist, but it's parent must exist. The sgml command will create the widget and its corresponding window. For example, the following command will create the sgml widget .s as a child of the applications main window '.':

	sgml .s
$\Rightarrow$	.s

The widget name is followed by any number of pairs of arguments, where the first argument for the widget specifies the name of a configuration option for the widget. The sgml widget supports most of the configuration options for the Tk text widget and some additional options that are specific for the sgml widget. See chapter  for details on the configuration options.

Like any other Tk widget, the sgml widget must be managed by a geometry manager to become visible on the screen. When the packer is used, the following command would pack the sgml widget we have just created inside the main window of the Tk application:

pack .s

The Tk documentation describes the geometry managers in detail. For more specific information on the packer, consult the manual page for the pack command, normally pack(n).

Whenever a new sgml widget has been created, a new Tcl command is created whose name is identical to the widget's name. This command is called the widget command for the sgml widget. After the sgml widget .s has been created, a command .s appeared in the applications Tcl interpreter. This command exists as long as the sgml widget exists; if the widget is deleted, then the command will disappear from the Tcl interpreter.

The widget command is used to communicate with the existing sgml widget. Like in any other widget command, the command name is the name of the widget and the first argument specifies an operation to invoke on the widget. Here are some examples of widget commands that can be invoked for the sgml widget .s:

	.s configure -foreground blue
	.s insert 4.3 "A string"

The sgml widget supports most of the commands of the Tk text widget and a number of additional commands that are specific to sgml widgets. A detailed description of the supported configuration options can be found in section .