User definable hooks in TrEd
============================

Before and sometimes after some action is performed, TrEd tries to
call a user defined hook function. These function may be used to alter
TeEd's default behaviour or even to prevent the execution of the
planned action. If the later is the case, the hook function must
return a scalar value of "stop". Here is the list of defined hook
functions with a description of the parameters passed to them by TrEd.


hook	       parameters	       stop   description
----------------------------------------------------------------------

start_hook	none			yes	executed before the
						MainLoop is entered

exit_hook	none			no	executed when
						top-level window is
						destroyed, before
						askSaveFile is
						executed

enable_attr_hook	attr,type	yes	executed before
						attribute "attr" is edited by
						user in a GUI. Type "type"
						may be one of
						"ambiguous", "normal"

goto_file_hook				yes	executed before every
						gotoFile command is executed

file_opened_hook			no	executed after a file
						is opened but before 
						first tree is redrawed

file_close_hook                         no      executed before a file
                                                is closed.

file_resumed_hook			no	executed after a
						postponed file
						is resumed

file_save_hook		out-filename	yes	executed before a file
						is saved

file_autosave_hook	fsfile		yes	executed before a file
						is auto-saved. Note:
						$grp may not be a window
						displaying fsfile if
						no window displays it.

pre_switch_context_hook			yes	executed before
						context is
						switched. Takes two
						argumetns:
						the name of the
						current context and
						the name of the new context.

switch_context_hook			no	executed after
						context is
						switched. Takes two
						argumetns:
						the name of the
						previous context and
						the name of the current context.

about_file_hook				no	executed before About
						window is
						displayed. Takes one
						argument: a reference
						to scalar
						variable. Hook may
						populate this scalar
						with any information
						it wants to be
						displayed in the About
						window.

customize_attrs_hook			yes	executed before a
						attribute
						customization dialog
						is displayed

sort_attrs_hook				no	executed when
						attribute names are
						pre-sorted (see TrEd's
						sortAttributes
						option). It is given a
						reference to an
						unsorted list of attributes. If
						non-zero value is retured,
						the (possibly
						modified by the hook)
						list is used without
						any further sorting.

after_edit_node_hook			no	executed after
						node attribute values
						are edited via the
						tred's edit attributes
						dialog window
						Arguments:node,result
						where result==1 if
						the user has pressed Ok
						and result==0 if the user
						pressed has pressed Cancel

after_edit_attr_hook			no	executed after
						a node attribute is
						edited via the
						tred's edit attribute
						dialog window
						Arguments:node,attr,result
						where attr is the name
						of the edited
						attribute result==1 if
						the user has pressed Ok
						and result==0 if the user
						pressed has pressed Cancel


get_value_line_hook			no      supply custom
                                                value-line content
                                                based on given fsfile
                                                and treeNo

get_nodelist_hook			no      supply custom
                                                node ordering
						given a fsfile,
                                                treeNo, current node and hidden node
						visibility state

node_release_hook node,target-node,mod yes     called when node is
                                                released over another
                                                node after a mouse
                                                drag (mod is keyboard
                                                modifiers - Control/Alt/Shift/Meta/...)

node_doubleclick_hook node,mod         no       called when node is
                                                double-clicked with a modifier
                                                Ctrl/Alt/Shift/Meta/...

text_doubleclick_hook node,attr,mod    no       called when an attribute is
                                                double-clicked with a modifier
                                                Ctrl/Alt/Shift/Meta/...

line_click_hook node,tag,button,double,mod,ev	no    called when an edge is
                                                clicked. node=origin, 
						tag=value of #{Line-tag:} style,
						button=1,2,3, double=0,1,
                                                modif=Control,Alt,Shift,Meta, ev=Tk::XEvent

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_doubleclick_hook tags...	no	called when users
                                                double-clicks the
                                                status-line. Arguments are
                                                a list of style names
                                                associated with the
                                                clicked field. Style
                                                names may obey
                                                arbitrary user-defined
                                                convention.

get_backends_hook      backend-list-ref no      gets list of IO backends, and
                                                should return narrowed
                                                or extended list. This
                                                allows dynamically
                                                add/block certain backends

highlight_value_line_tag_hook node      no      invoked whenever a
                                                node is
                                                selected. Supposed to
                                                return a tag to
                                                highlight on the value line.

determine_node_type_hook  node               no      invoked before tred needs to
                                                determine node-type of a node
                                                without one

after_save_hook  filename            yes   called after a file is saved 
		                           (not autosaved). Die or warn messages
                                           appear as warnings to the user.
                                           May return "stop" to recover
                                           backup.

after_autosave_hook  filename       no     Called after a file is auto-saved.
                                           Errors/warnings appear on the console.

NOTE:
Unlike other macros, hooks are expected not to modify the file. If the
file is modified, the hook-function should set the $FileNotSaved
variable to 1. Also no getNodes or setCurrent or redraw_tree or
centerTo is performed when a hook is called!
