Help System The Help System for the Midas package splits into 2 components - 1) features which are executed within each task These facilities give immediate help on the use of each widget within the task using the window footer and slightly more information using a pop-up dialog window. 2) features which are executed within the help task. These facilities allow for more extensive help possibly envoking an external viewer program to show a document. The response time may be measured in several seconds if an external program has to be started. Task local features These require that help information is available in the TCL array :help. Help is linked to a widget and (by default) help information for widget FRED is in :help(FRED). It is possible to specify the help item name to be used by the parameter :helpitem name in the widget creation procedure call. For example :button ATTACH :helpitem CONNECT would create a button labelled as Attach but take help information from :help(CONNECT). If the array element DEFAULTHELP exists then this information is used for any widget which does not have its own private help information. The parameter :help F in the widget creation procedure call causes setup of the bindings which implement the task local help for a widget to be bypassed. The task TCL script can load help information in one of 4 ways 1) directly by a set command - set :help(FRED) "This is the FRED widget" 2) using the :help procedure - :help FRED "This is the FRED widget" 3) as an argument to the procedure creating the widget - :button FRED :help "This is the FRED widget" 4) within the file $taskname.txt which is searched for using the TCLPATH variable. Normally this would imply that for a task there are 2 files $taksname.tcl and $taskname.txt The format of the .txt file is +widget FRED This is the FRED widget The FRED widget is a really wonderful thing +widget JIM etc The first line of the help information for the widget is put into the window footer while the mouse is over the widget and removed when the mouse leaves the window. Since this action can in some cases cause problems by overwritting other useful footer information it can be controlled by the TCL global variable _suppresshelp. Setting _suppresshelp to 0 enables the action and setting _suppresshelp to 1 disables it. The whole of the help information is shown in a dialog window if button F1 is pressed while the mouse is over the widget. To implement the level 1 help feature bindings are made by all widget creation procedures for the events Enter and Leave (unless suppressed by the :help F parameter). Facilities within the help task 1) These can be called by creating a button using :button HELP :command click-help The default click-help procedure then calls the help task help-on-task procedure with (by default) the calling task's name. The task name used in the call to the Help task can be specified by the TCL variable helpname. For example: click-help in the task ap will invoke help-on-task ap but if set helpname apparatus were specified then click-help would invoke help-on- task apparatus. 2) Pressing the Shift-F1 button while the mouse is over a window calls (by default) the help task help-on-widget procedure with the widget name. Note that when the mouse is positioned over the window background the help-on-task procedure is called. The task name and widget name to be used can be specified as described previously. For example in the task ap widget ATTACH would invoke help- on-widget ap ATTACH but this could be changed as shown to help-on- widget apparatus CONNECT. The help information will be searched for taking the TCLPATH variable but first substituting manual for tcl. help-on-widget will look for a file of the form $taskname.$widget.fmt or $taskname/$widget.fmt and help-on-task will look for $taskname.fmt or $taskname/$taskname.fmt or $taskname/fmt where fmt can be one of html dvi ps prn txt The latter examples allow all help for a task to be within a directory having the name of the task (or the specified alternative). example - for the task ap (apparatus access) manual information on the Claim command can be found in the file /MIDAS/manual/ap.CLAIM.txt and the Help button shows information in the file /MIDAS/manual/ap.txt Note - since the task help information probably contains information from the individual widget files records of the form +++widget.txt are permitted in the task.txt file and cause the contents of the file task.widget.txt to be substituted. NOTES If an action calls the help task which then cannot find any information the task level actions are then tried as a secondary source. Also if the task level action for a widget is invoked but no help is available then the help task is tried as a secondary source. All procedures used at task level to implement the Help System are in the common.tk.tcl file. The necessary bindings are included within the :frame and individual widget procedures. The Alt+F1 binding is available to aid implementors check new and updated level 1 help. The binding calls the :load-help procedure (which is also called when the task loads the common.tk.tcl file) to update the local help information held within the task.