Summary of commands
===================

In term browser window:
Single-click left mouse-button: select node clicked as current node.
Double-click left mouse-button: toggle expansion or collapse of clicked node.
Press and hold right 
mouse-button:                   options menu for the node.
Arrow keys:                     move selected node relative to current node.

Navigation panel arrows:        move selected node relative to current node.


Summary of function
===================

This tool is used to examine terms in a browser-like fashion.  A selected
term is displayed hierarchically in a tree format. The user can browse
and traverse the term in a similar fashion to a directory browser. 

The terms are displayed using the global output mode option, and it is this
representation of the term that is inspected. As changing the output mode
may change the way the term is represented, this is not allowed during the
inspection. To view the terms under different output modes, quit from the
inspector, change the global output modes, and inspect the term
again. Print depth can be set from within the inspector, but if the global
output mode is set to `full', then the terms would always be printed with
full depth, and the inspector print depth setting is ignored.

Note that when the inspector is active, the user cannot interact with other
ECLiPSe windows.


Layout
======

The inspector consists of the following components:

Navigation and settings panel: this panel across the top contains
arrow buttons for movements, parameter input entries, and a close-button.

Main term browser window: displays the selected term in the hierarchical
tree format.

Status line: shows messages from the inspector.

Browser y-scroll control panel: this window needs to be launched from the
inspector from the Windows menu. It allows the changing of parameters for
controlling the behaviour of the y scrollbar in the term browser window.


Functionality
=============

Main term browser window
------------------------

The selected term can be browsed and examined in this window. The term is
displayed in a tree-like fashion, with nodes of the tree representing
sub-terms of the selected term. As with directories in a directory browser,
nodes which contains its own sub-terms can be toggled between two states:
expanded, in which its child sub-terms are shown; or collapsed, when its
children are not shown. The user can toggle between these two states by
double clicking the left mouse button over the node. Nodes which can be
expanded are shown in a red bold font.

A node can be selected by single clicking the mouse button on it.

For convenience, the list elements of a list are displayed at the same
level, rather than as the actual recursive tree structure of the head and
the tail. The elements are displayed in the order they are in the list from
the top. The number of elements displayed at one level is controlled by the
structure threshold. The last child node of a list is the tail of the
list, and if the list is longer than the threshold, then the rest of the
list beyond the threshold is displayed as the tail, which can then be
further expanded at the next level. The threshold can be changed from the
Options menu. List elements are prefixed by labels: `[   :' for the first
element, `,    :' for the other elements, and `|    :' for the tail. So a
list [1,2,3,4] with a threshold of 2 will be displayed as:

./2
 |
 |-- [   1
 |
 |-- ,   2
 |
  -- |   [3,4]

The threshold setting is applied when the list node is expanded. 

Press and hold the right mouse button over a term will bring up a menu
related to the term: summary information on it is given (Name/Arity, type,
and information on what sort of argument it is: position/field name in a
structure, list element `position', attribute name); and the option to
observe the term. This option is designed to be used in conjunction with
the tracer for debugging: it will allow the term to be observed for any 
changes in a display matrix.

The option to observe terms will only work when the inspector was launched
when the user is at a tracer debug port and if forward execution continues.
A display matrix with the terms selected for observation will be created
immediately before ECLiPSe execution continues after the debug
port (note: although terms can be selected for observation while the tracer is
not active, they will not be displayed because there is no continuation of
execution from a debug port). 

When a term is selected for observation, the user is prompted to give a
label to the term by a dialogue box. This label will be placed next to the
observed term in the display matrix to allow the user to identify it. If
the `Cancel' button of the dialogue box is clicked, then the term will not
be added for observation. Multiple terms can be selected, and each term
will be given a row in the display matrix -- the matrix will be a column of
label-term pairs of the observed terms. 

The observe terms facilities can be seen as a way for the user to create
display matrices interactively. It is equivalent to the user adding the call
to display_matrix/2 with the selected terms just after the goal at the
debug port. See the documentation on display matrix for more information on
how to use it. 
 

The sub-terms can be displayed in the browser window with icons that gives
type information if the `Display term type symbols' option is ticked.

In the browser window, attributes are prefixed with their attribute names.
For structures with field names (declared using local struct or
global struct), the arguments are prefixed with their field names. If a
normal structure has more arguments than the structure threshold, then its
elements will be prefixed with their argument number. 

The viewable area of the term browser window can be adjusted by using the
scrollbars. The y scrollbars implements a `follow-node' mode. In this mode,
when the y scrollbars is used to scroll the screen, the viewable x area is
adjusted so that nodes are always visible. This means that unlike
conventional scrollbars, when scrolling through the term means alternating
between the x and y scrollbars, only the y scrollbar has to be
manipulated. In this follow-node mode, a node, which is in the visible
area, is defined as the `leading' node. It is this leading node that will
always be visible -- if the normal y scrolling would place the leading node
outside pre-defined left and right boundaries in the x direction, the
viewable x area will be adjusted so that the node will be displayed in the
centre of the viewable x area. Which node is regarded as the leading node
depends on the direction of scrolling: if scrolling upwards, the node is
located relative to the top edge of the visible area; if scrolling
downwards, it is relative to the bottom edge. The actual node selected is
at the node that is closest to some pre-defined distance from the
appropriate edge.

 
Navigation buttons 
------------------

Navigation through the term is also possible using the navigation buttons.
They allow the user to move the selected node in relation to the current node:
to one of its sibling, parent or child node. The number of times a
particular move is to be repeated can be set by setting the `repeat' entry
in the middle of the panel. For moving to a child node, the particular
child argument to move to at each stage is set in the `child' entry to the
right of the descendant arrow. This is particularly useful in moving down
many levels of deeply nested structures. The default child position is 2.

The keyboard arrow keys can be used in place of the arrow buttons.


Settings
--------

Next to the navigation buttons there are the following entries:

Argument position for child move
    this determines to which child the current selection moves
    when the right-arrow is pressed.

Repeat count for all movements
    this determines how many steps are executed in the given direction,
    when an arrow is pressed.  If the move has to be terminated early,
    a message is displayed in the status line.

Print depth setting
    the nesting depth at which the textual representation of a subterm in
    a tree node is truncated.  This has no effect on the tree structure.

Structure threshold/List unfolding chunk size
    Lists are unfolded and displayed in chunks of the given length.  This
    is usually more readable than the true structure of the list, which is
    a deeply nested term of ./2 structures.

    Also, in structures with an arity higher than this setting, all the
    arguments will be displayed together with argument position numbers,
    for better orientation.

Display term type symbols option
    When ticked, every subterm is marked with a symbold indicating its type.
    Depending on the data, this may improve or diminish readability.


Browser y-scroll control panel
------------------------------

This window allows the parameters for controlling y-scroll in the term
browser window to be modified. It consists of 3 subsections:

Check button for `follow-node' mode: 

If selected, the y scrollbar has the `follow-node' behaviour. If not
selected, then the y scrollbar has the conventional behaviour,
i.e. manipulating it does not have an effect on the viewable x area. Note
that the x scrollbars have the conventional behaviour in both modes,
i.e. the viewable x area can be adjusted independently of the viewable y
area through the x scrollbar.

Sliders for adjusting the left and right boundaries:

The left and right boundaries defines the limits within which the leading
node must be displayed during y-scroll. The limits are measured against the
left-edge of the text of the node: if this edge is outside either the left
or right edge as a result of manipulating the y scrollbar, then the
viewable y area will be adjusted so that the left-edge of the node is
displayed in the centre of the viewable x area. Note that this adjustment
would not place the viewable area beyond the edges of the whole term
display canvas.    

The left and right boundaries (LB and RB respectively) are shown below, 

                              W
     <----------------------------------------------------->

  Left edge          viewable x area                   Right edge
     |-----------------------------------------------------|
     <----->|                                  |<---------->
        A   LB                                RB      B
     

with A and B defining how far LB and RB are from the left and right edges
respectively. The sliders allows A and B to be adjusted, expressed as % of
the width of the viewable X area (W). Both range from 0% (at the edge) to
50% (at the centre).

Sliders for adjusting distances to leading node:

The leading node is selected from the nodes which are in the viewable y
area (they may not be visible because they are not in the viewable x
area). The node selected is the node that is closest to one of two
boundaries in the viewable y area. The boundary used depends on the
direction of y scrolling -- the upper boundary when scrolling upwards, the
lower boundary when scrolling downwards. These two boundaries are defined
in terms of their distance from the upper and lower edges of the viewable y
area respectively, expressed as a % of the height of the viewable y
area. The sliders allows these two boundaries to be adjusted between 0% (at
their respective edges) and 50% (at the centre of the viewable y area). 
  
Update button:

Adjusting the sliders and the check button would not cause any immediate
changes in the y-scroll parameters. The changes are applied only when the
update button is pressed.

Close button:

Closes the window when pressed.

Menu Bar
--------

  Windows - this launches sub-windows of the inspector:

       Browser y-scroll control
           this launches the browser y-scroll control panel
       Show symbol key
           this launches a window that shows what the type icons represents.
       Close
           quit the inspector tool.

  Select - this allows the selection of the term that is to be inspected:

       Current goal
           selects the current goal - the goal that is being
           executed or traced.
       Invoked goal
           selects an invoked goal by its invocation number.

  Help
       Balloon Help
           toggles balloon help.
       Inspector Help
           this window.




