<!--
  - Authors:
  -   Thorsten Brunklaus <brunklaus@ps.uni-sb.de>
  -
  - Copyright:
  -   Thorsten Brunklaus, 2001
  -
  - Last change:
  -   $Date: 2001/05/10 08:11:39 $ by $Author: bruni $
  -   $Revision: 1.4 $
  -
  - This file is part of Mozart, an implementation
  - of Oz 3
  -    http://www.mozart-oz.org
  -
  - See the file "LICENSE" or
  -    http://www.mozart-oz.org/LICENSE.html
  - for information on usage and redistribution
  - of this file, and for a DISCLAIMER OF ALL
  - WARRANTIES.
  -
  -->

<CHAPTER id="chapter.interactive"><TITLE/Interactive Examination/
  <P>
    Once a value is displayed, it can be examined more closely by using
    the context menus attached to its nodes.  A node's context menu offers
    a configurable set of type-specific operations on that node and can be
    opened by right-clicking the node's so-called <EM/access point/.
  <SECTION><TITLE/Node Access Points/
  <P>
    Node access points are defined as follows:
  <P>
    <LIST>
      <ITEM>
        Any atomic node is a node access point for itself.
	(An <EM/atomic node/ is a node that has no subnodes.)
      <ITEM>
        For any tuple excluding lists, the label and the parentheses are
	access points for the entire tuple node.
      <ITEM>
        For any record, the label and and the parentheses are access points
	for the entire record node.  In particular, the record's features
	are defined <EM/not/ to be node access points.
      <ITEM>
         The node access points of lists depend on the display mode.
	 In tree mode, the brackets and pipe symbols (<<'|'>>) are node access
	 points for the entire list.  In graph mode, each pipe symbol is
	 a node access point for the sublist starting at that point.
    </LIST>
  <SECTION><TITLE/Node Operations/
  <P>
    The Inspector offers three types of operations on nodes: exploration,
    filtering and mapping, and actions (see <PTR to="figure.context">).
    <FIGURE id="figure.context">
      <CAPTION/A context menu opened over the closing parenthesis/
      <PICTURE.EXTERN to="context.gif" type=gif>
    </FIGURE>
  <P>
    <LIST>
      <ITEM>
        <EM/Exploration/ allows to locally modify the depth and width
	exploration limits, thereby expanding or shrinking the value to
	the region of interest.
      <ITEM>
        <EM/Mappings/ allow to transform values for display with respect
	to a given mapping function.  This makes it possible to either
	arbitrarily prune regions of the value (also called <EM/filtering/)
	or to extract information from abstract datatypes.
      <ITEM>
        <EM/Actions/ allow to apply side-effecting operations on displayed
	values.  For instance, this allows to make values available to
	external tools such as the experimental Constraint Investigator,
        for gathering information beyond the scope of the Inspector.
    </LIST>
    These types of operations are explained in the following sections.
  <SUBSECTION id="section.interactive.exploration"><TITLE/Exploration/
  <P>
    When inspecting a large data structure, one often needs to zoom in
    on a subvalue or hide currently irrevelant data.  This is what the
    exploration operations are intended for.  Two different kinds of
    operations exist, for modifying the depth and the width limits
    respectively (see <PTR to="figure.exploration">).
    <FIGURE id="figure.exploration">
      <CAPTION/Sample inspection and various results/
      <TABLE>
        <TR><TD><PICTURE.EXTERN to="explore1.gif" type=gif>
        <TR><TD><PICTURE.EXTERN to="explore2.gif" type=gif>
      </TABLE>
    </FIGURE>
  <PARA><TITLE/Depth/
    Applying the operation <Q/Depth +?{n}/ to a node causes the subtree
    starting at that node to be redrawn, with a depth of ?{n}&nbsp;levels.
    Applying the operation <Q/Depth -?{n}/ causes the node to be pruned,
    as well as its ?{n} - 1 parent nodes.  The effect of the global depth
    limit is that when new values are inspected, immediately the operation
    <Q/Depth +?{d}/ is applied to them, where ?{d} is the global depth limit.
  <PARA><TITLE/Width/
    Every node also has a display width associated with it.  If a node has
    a display width ?{w}, only its first ?{w}&nbsp;subtrees will be displayed
    (in the case that ?{w} is zero, that means none).  Initially, <EM/all/
    nodes are created with the default display width.  Applying the operation
    <Q/Width +?{n}/ or <Q/Width -?{n}/ to a node modifies that node's display
    width by the specified amount and causes it to be redrawn accordingly.
  <P>
    <PTR to="figure.exploration"> shows some examples of the effects of
    the operations described above.  They have all been obtained from
    inspecting the sample tuple given above, and applying operations to
    it as follows:
    <LIST ENUM>
      <ITEM>
        The sample tuple has been shrinked by applying <Q/Width -5/.
      <ITEM>
        The sample tuple has been subject to applying <Q/Width -5/ once
	and <Q/Width +1/ twice.
      <ITEM>
        The sample tuple has been collapsed by applying <Q/Depth -1/.
      <ITEM>
        The sample tuple is only partially displayed when applying
	<Q/Depth +1/.  Note that the operation does not augment the
	display depth, but replaces it.
      <ITEM>
        The sample tuple has been partially displayed using <Q/Depth +1/
	and then shrinked in width by applying <Q/Width -1/ twice.
	This shows that the exploration functions are compositional.
    </LIST>
  <SUBSECTION><TITLE/Filtering and Mapping/
  <P>
    The Inspector defines default mappings for many data types, to perform
    commonly-used operations such as inspecting the state of mutable data
    structures.  <PTR to="figure.mapping"> demonstrates an example of this:
    By default, dictionaries are displayed as the unspecific tag
    <SAMP/&lt;dictionary&gt;/.  The default mapping <Q/Show Items/ for
    dictionaries replaces the dictionary node by a snapshot of its contents
    (specifically, as the result of the <<Dictionary.items>> procedure).
    <FIGURE id="figure.mapping">
      <CAPTION/Example mapping invocation and its result/
      <TABLE>
        <TR><TD><PICTURE.EXTERN to="mapping1.gif" type=gif>
        <TR><TD><PICTURE.EXTERN to="mapping2.gif" type=gif>
      </TABLE>
    </FIGURE>
  <P>
    Note how the different choice of background color indicates that this
    is, in fact, a mapped representation.  Mappings can be undone using
    the context menu option <Q/unmap/.
  <P>
    Mappings have the following properties:
    <LIST>
      <ITEM>
	Mappings are fully compositional, meaning that any other mapping can
	be applied to an already-mapped node.
      <ITEM>
	Mapping works on a per-node basis.  In particular, the Inspector will
	apply new mappings to any child nodes of a mapped node.
      <ITEM>
	Mapping functions are type-specific. That means that every type offers
	its own collection of mapping functions.
    </LIST>
  <P>
    Mapping functions can be applied automaticly before inspection of the
    value.  See <PTR to="section.gui.structure"> for details on how to
    do this.  Keep in mind that the results can be confusing due to the
    per-node mapping strategy.
  <SUBSECTION><TITLE/Triggering Actions/
  <P>
    <PTR to="figure.action"> demonstrates the invocation of an action.
    The by-need future is forced, whereupon the Inspector will update its
    display accordingly, showing its value.
    <FIGURE id="figure.action">
      <CAPTION/Example action invocation and its result/
      <TABLE>
        <TR><TD><PICTURE.EXTERN to="action1.gif" type=gif>
        <TR><TD><PICTURE.EXTERN to="action2.gif" type=gif>
      </TABLE>
    </FIGURE>
  <P>
    Like mappings, actions are type-specific.
    See <PTR to="section.configure.actions"> for details on how to
    register new actions.
  <SECTION><TITLE/Using Selections/
  <P>
    Some of the operations presented above can also be triggered on the
    selected node by the <Q/Selection/ menu.  To <Q/select/ a node means
    to left-click a node access point:  The corresponding node will be
    drawn with a selection frame around it.  <PTR to="figure.selection">
    shows the operations that can be applied to the selected node.
    <FIGURE id="figure.selection">
      <CAPTION/The selection interface/
      <PICTURE.EXTERN to="selection.gif" type=gif>
    </FIGURE>
  <SUBSECTION><TITLE/Substructure Lifting/
  <P>
    <PTR to="figure.lifting"> demonstrates another application of selections:
    Any selected substructure can be lifted to toplevel by applying the
    <Q/Clear all but Selection/ command from the Inspector menu.
    <FIGURE id="figure.lifting">
      <CAPTION/Substructure lifting/
      <TABLE>
        <TR><TD><PICTURE.EXTERN to="lift1.gif" type=gif>
        <TR><TD><PICTURE.EXTERN to="lift2.gif" type=gif>
      </TABLE>
    </FIGURE>
  <P>
    Substructure lifting is intended to rapidly prune large trees and
    currently works only with one structure selection.  It cannot be undone.
</CHAPTER>
