There is a special set of macros that was not mentioned yet. These macros, called hooks, are automatically executed by TrEd on certain occasions. By defining such macros a little more of the TrEd's implicit behaviour may be influenced, for example the execution of a planned action may be aborted.
Hooks differ from other macros in the following aspects:
User cannot choose a name for a hook; on the contrary hook is recognized as a macro having a special name identifying it as being a certain hook.
Sometimes parameters are passed to hooks.
No modifications of the tree or current node are reflected after the hook returns, i.e. the tree is not redrawn, changes to $this variable are not reflected. If necessary, a hook must provide this functionality itself.
Unlike macros, hooks are not expected to modify the tree unless they explicitly state that by setting the $FileChanged to 1.
There is a special class of hooks that may be used to prevent TrEd from finishing a planned action, e.g. enabling the user to modify certain attribute value etc. The value returned by a hook of this class is checked and the action is aborted in case the value equals to “stop”.
In the following table the hooks which may be used to prevent TrEd from executing a certain action are marked by yes in the column “Stop”.
Table 6. Hooks
| Name | Stop | Hook event description |
|---|---|---|
| start_hook | yes | Executed on start-up, before the main event loop is entered. |
| exit_hook | no | Executed when the main window of TrEd is destroyed, before the user is prompted to save the modified files. |
| do_edit_attrs_hook(attr,node) | yes | Executed before a dialog window for editing an attribute value is displayed (usually when the user double-clicks the displayed attribute value). |
| enable_attr_hook(attr, type) | yes | Executed before any text field for an attribute value modification or list of possible values is created. If the hook returns “stop”, the field or list is made read-only. The type argument may have one of the following values: ambiguous (in case of multiple values or an attribute with a given list of possible values) or normal. |
| goto_file_hook | yes | Executed before the next or previous file in the current file-list is opened. |
| file_opened_hook | no | Executed after a file is opened but before the first tree is displayed. |
| file_resumed_hook | no | Executed after an already open (kept) file is resumed. |
| pre_switch_context_hook(previous,next) | yes | Executed before the macro context is changed (see Section 9.9). The previous argument contains the name of the current context while next contains the name of the future mode. |
| about_file_hook(stringref) | no | This hook is executed before the About window is displayed. The hook takes one argument: a reference to a scalar variable. The hook may populate the referenced variable with any information which is then displayed as a part of the About window message. |
| customize_attrs_hook | yes | Executed before the dialog for customizing attribute patterns is displayed. |
| sort_attrs_hook(attibsref) | no | Executed when attribute names are pre-sorted (see SortAttributes configuration options). The attribsref parameter passed to the hook is a reference pointing to a list variable. The list is populated with all attribute names and the hook may modify the list by changing the order of its elements or by removing certain elements from the list. If then non-zero value is returned by the hook, the (possibly modified) list is used for displaying purposes without any further sorting. |
| after_edit_node_hook(node,result) | no | Executed after a node's attribute values were edited in the Edit Node Attributes dialog window. The result argument contains 1 if the user pressed Ok button to close the dialog, and it contains 0 if the user closed the dialog with the Close button. |
| after_edit_attr_hook | no | Executed after a node's attribute was edited in the Edit Attribute dialog window. The result argument contains 1 if the user pressed Ok button to close the dialog, and it contains 0 if the user closed the dialog with the Close button. |
| get_value_line_hook (fsfile,treeNo) | no | Supply custom value-line content based on given fsfile and treeNo. The value returned from the hook may be either a string to appear in the value line on the top of TrEd's main window or an array reference consisting of a list of array references representing individual nodes. In the later case, the array references representing individual nodes must be of the form [text, node,options...] where text is a text to appear on the value-line, node is the node represented by the array reference and options is arbitrary set of strings. If these strings are of the form -option => value where option is one of foreground, background, underline, they are used to alter visual appearance of the corresponding part of the text displayed on the value-line. All other strings are ignored. |
| highlight_value_line_tag_hook | no | Invoked every time a node is selected. The hook should return a tag associated with some text in the value line. The text is then highlighted in the value line. |
| get_nodelist_hook (fsfile,treeNo,show_hidden) | no | This hook may be used to supply custom node ordering given a fsfile, treeNo and hidden node visibility state. If used, it should return a two-element array reference with the first element being a array reference to a list of nodes to be displayed (in a left-to-right order) and the second element being a node to be set up as the initial active node. |
| node_release_hook (node, target-node, mod) | yes | Called when a node is released over another node after a mouse drag. mod is a keyboard modifier string, such as Control, Shift, Alt or Meta. It can also be empty. If mod is empty, the hook should either result 'stop', to disable rehanging node on target-node or take no action. In all other cases, the hook may reorganize the tree in arbitrary way, but it should call Redraw_FSFile_Tree() and set $FileChanged=1 if needed. |
| node_doubleclick_hook (node, mod) | no | Called when a node is double-clicked while a modifier key was pressed. mod is a keyboard modifier string, such as Control, Shift, Alt or Meta. The hook is responsible for calling Redraw_FSFile_Tree() or similar default macro to redraw the tree as well as for setting $FileChanged=1 if needed. |
| text_doubleclick_hook (node, attr, mod) | no | Called when an attribute in a displayed node or edge label is double-clicked while a modifier key was pressed. mod is a keyboard modifier string, such as Control, Shift, Alt or Meta. node is the FSNode object whose attribute was clicked. attr is name of the attribute which was clicked. The hook is responsible for calling Redraw_FSFile_Tree() or similar default macro to redraw the tree as well as for setting $FileChanged=1 if needed. |
| node_moved_hook (node, old-parent) | no | called after a node is moved using a mouse |
| get_status_line_hook | no | Supply status-line content. Status line is an experimental feature which can be enabled by setting displayStatusLine configuration option to 1. This hook is responsible for providing the content for a status-line. The value returned from get_status_line_hook should have the form [field-definitions, style-definitions, ]. field-definitions is an array reference of the form [text1,tags1, text2,tags2,... ] specifying one or more pieces of textual content of the status-line. Each piece of text is followed by another array reference, containing a list of tags associated with the text. Tags may be arbitrary strings. style-definitions is an array reference which can map some tags to visual appearance attributes. It has a form [tag1, [option => value, option => value, ...], tag2, [option => value, option => value, ...], ... ] where option may be one of -foreground, -background and -underline. |
| status_line_doubleclick_hook tags... | no | Called when users double-clicks the status-line. Arguments are a list of tags associated with the clicked field (see above). Tag may be arbitrary strings and it is up to user's will to set up some useful convention for tagging text of the status-line. |