It is sometimes necessary to react on certain changes to the structure of an SGML document in a flexible manner that depends on the exact type of change and the element to which it occurs. To deal with these situations, the sgml widgets allows you to define notification commands that are invoked when certain edit events occur in the sgml widget.
You may be familiar with this usage of notification commands
from other Tk widgets where you specify a Tcl command that should be
evaluated by the widget in response to certain events or user
actions. For example, the Tk scrollbar widgets accept a
-command option that defines which command should be invoked
when the user manipulates the scrollbar.
Edit event are alterations related to the document structure. The sgml widget knows about the following predefined edit events:
Depending on the type of the edit event, a notification command will be invoked that can react on the edit event and perform any required actions. Notification commands are installed using the configure widget command. The relevant configuration options are described below:
The command script is invoked when an element is inserted or when a deleted element is re-created by an undo command.
The script is invoked with three additional argument: the name of the sgml widget in which the insertion took place, the keyword insert, and a handle for the new element.
If several elements are inserted by a single operation (e.g. by inserting a large piece of text), the script is invoked once for every element that is created.
The command script is invoked when an element is deleted or when an element is removed by undoing an insert or split operation.
The script is invoked with three additional argument: the name of the sgml widget in which the deletion took place, the keyword delete, and a handle for the element that is being deleted.
The command script is invoked when the parent of an element is changed. This can happen because the containing element has been split, because a new element has been inserted that encloses the affected element, or because the parent element has been removed and the affected element becomes a child of its former grandparent element.
The script is invoked with three additional arguments: the name of the sgml widget, the keyword parent, and a handle for the element for which the parent element has changed.
the command script is invoked when the attributes of an element have been modified.
The script is invoked with three additional arguments: the name of the sgml widget, the keyword attribute, and a handle for the element that has been modified.
the command script is invoked when the context of the insert mark changes, e.g. because the insertion cursor is moved in or out of an element.
The script is invoked with two additional arguments: the name of the sgml widget and the keyword context.
the command script is invoked when the valid status of an element has changed, e.g. a missing chidl element has been inserted and the element containg it has changed it's status from incomplete to complete.
The script is invoked with three additional arguments: the name of the sgml widget, the keyword valid, and a handle for the element that has been modified.
the command script is invoked when the status of the selection changes, e.g. when the sgml widget looses the selection because it was claimed by another widget.
The script is invoked with one additional argument: the name of the sgml widget for which the selection status has changed.
A notification command is a Tcl script that must accept additional parameters depending that are appended to the command when it is invoked:
The following example procedure keeps track of the number of elements that have been inserted (or deleted) by the user. This is accomplished by storing a count for each element type in a global hash ecount that is indexed by the element name.
To utilize this example, the sgml widget must be instructed to invoke the procedure every time an element is deleted or inserted, i.e. the the procedure update_ecount must be installed as a notification command.
Notification commands for the sgml widget are specified as configuration options; either when the widget is created or by using the configure widget command. The following configuration options deal with notifications:
To install the example above as a notification command for delete and insert operations in an existing sgml widget .s, the following Tcl commands would be used:
.s configure -insertnotify update_ecount .s configure -deletenotify update_ecount
After a notification command has been configured, it will be invoked every time the associated edit event occurs in the sgml widget.