Tcl to Sather Callback Interface
================================
The tcl to sather interface consists of a number of callback routines, each
of which uses certain data structures which are registered in
BROWSER::build in browser.sa.

Naming convention
-----------------
	Callback routines are named in sather by the convention
<word1>_<word2>_cb and in tcl by Word1Word2


Sather (Tcl): Description
--------------------------
set_cur_class_name_cb(args: ARRAY{STR}) (setCurClassName):
		Set the sather variable "cur_class_name" to args[0]
-------------------------------------------------------------------
get_class_info_cb(args:ARRAY{STR}) (getClassInfo)
	Get information for the class args[0] - referred to below as A
	The data structure returned has the following form.

<file name where A is located> <line number in file for defn of A> {
	<routine information> *
	}
		
<routine information> ::= { <signature_string> <source file name> <source line num> <routine type> }

<routine type> ::=   <is_iter><is_private><is_attr_writer><is_attr_reader>
			<is_sh_writer><is_shared_reader><is_constant>
<is_iter> ::= "i" | "n"
Likewise with the other attributes, resulting in a string
(if all attributes are true) of "ipwrwrc" and "nnnnnnn" if all are false
-------------------------------------------------------------------------
all_classes_cb (allClasses) : 
	Returns a list of all sather classes and modules.
Called initially to set up the class list pane.
{
{ nodename filename linenumber modulename}
{ nodename filename linenumber modulename}
...
}
-------------------------------------------------------------------------
get_home_cb (getHome) :
	Returns the value of the SATHER_HOME and  $gHome is set to this value
browser.tcl
-------------------------------------------------------------------------
get_full_layout_cb (getFullLayout):
	Returns the complete graph of all classes processed by
the browser. Rarely useful
-------------------------------------------------------------------------
get_restricted_layout_cb (getRestrictedLayout):
	Returns the graph of the reachable classes from the cur_class in the
browser.  Layout graph has the form

{ <layout depth: FLT> <layout width: FLT> }
{ 
	{ <classname1 xpos ypos> <classname2 xpos ypos>} ... 
} 
{ 
	{ source1 destination1} {source2 destination2} ... 
}
-------------------------------------------------------------------------
set_bool_var_cb (setBoolVar): arg[0] = variable name 
			     arg[1] = value (true or false)
Sets the name of a sather variable to a particular value.
-------------------------------------------------------------------------
deactivate_classes_cb (deactivateClasses) : args are a list of class names
	These classes will not be added to the graph during layout
-------------------------------------------------------------------------
activate_classes_cb (activateClasses) : args are a list of class names
	Reverse effect of deactivation
-------------------------------------------------------------------------
flush_graph_cb (flushGraph):
	Delete the graph from the cache of graphs. The cache is flushed
whenever the visibilty of any class changes.
-------------------------------------------------------------------------

-------------------------------------------------------------------------
                          CALLBACKS - The Tcl view
-------------------------------------------------------------------------
setCurClassName     Called in proc selectClass - sets the sather side to the
                     currect class (selected from the list or from the graph)
getHome             Returns the SATHER_HOME directory. Called in showHelp
getFullLayout       Returns the layout for all active nodes
                    (not just ancestors/descendants of the currently 
                    active node)
                    Currently used in the undocumented menu option (
                    dumpFullGraphForDot as an example of what you might do)
getRestrictedLayout  Called in graphInit. Returns the layout of the graph
                     consisting of currently active nodes that are also
                     ancestors/descendants of the current node and are
                     visible. (i.e. including whichever of modules, concrete
                     and abstract types are visible) 
                     { 
                       { layout.depth layout.width}
                       { {clasname1 xpos ypos } {classname2 xpos ypos} ... }
                       { { source1 dest1} { source2 dest2} ....} 
                    }
setBoolVar          Used to set the bool variables that are held by sather.
activateClasses     Make some classes visible
deactivateClasses   Make some classes invisible - see toggleNoShow
                    These two callbacks are used to hide C_ and TEST_
                    classes... 
execName            Unused! Should return the name of the executable...
allClasses          Used in classListInit. Takes the form of 
                    {
                    { classOrModuleName  filename location ContainingModule}
                    { ... }
                    }
getClassInfo       Used in showClassDef (and in updateFeatureList)
                    and showClassDocs
                   { className  { {<routname> <file> <loc> <routineType>}
                                  {<routname> <file> <loc> <routineType>}
                                }   }
where routineType indicates the type of the routine
routine. The string must be treated as a seven element array
Char 0 indicates whether this routine is an iter.
        if it is, then character 0 is 'i' otherwise it is 'n'
Likewise, 
Character  property      if true  if false
char 0, iter             , 'i'   'n'
char 1, private          , 'p'   'n'
char 2, attribute writer,  'w'   'n'
char 3, attribute reader,  'r'   'n'
char 4, shared writer,     'w'   'n'
char 5  shared reader      'r'   'n'
char 6  constant           'c'   'n'
 Used in updateFeatureList
routineType is documented in browser.sa under get_class_info_cb

