<!--
  - Authors:
  -   Thorsten Brunklaus <brunklaus@ps.uni-sb.de>
  -
  - Copyright:
  -   Thorsten Brunklaus, 2001
  -
  - Last change:
  -   $Date: 2001/05/09 20:59:37 $ by $Author: kornstae $
  -   $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.basic"><TITLE/Inspector Basics/
  <P>
    This chapter provides some basic understanding about how the Inspector
    can be used.
  <SECTION><TITLE/Simple Invocation/
  <P>
    The simplest usage of the Inspector is to execute the statement
    <<{Inspect ?_{X}}>>, where ?_{X} can be any Oz value.  Unless the
    Inspector window is already open, this will create a new window
    displaying the given value.  For instance, the window in
    <PTR to="figure.usage"> was created using the statement
    <<<{Inspect label(i am a sample tuple)}>>>
    It is possible to inspect more than one value at the same time.
    By default, new values are appended to the current window.
    <FIGURE id="figure.usage">
      <CAPTION/The Oz Inspector/
      <PICTURE.EXTERN to="use.gif" type=gif>
    </FIGURE>
  <SECTION><TITLE/Inspecting within Multiple Widgets/
  <P>
    The Inspector can handle an arbitrarily number of viewing windows
    (called <EM/widgets/) which can be accessed and configured independently.
  <SUBSECTION><TITLE/Adding and Deleting Widgets/
  <P>
    To open a new display widget, click <Q/Add new Widget/ from the Inspector
    menu as shown in <PTR to="figure.panes">.
    <FIGURE id="figure.panes">
      <CAPTION/Adding a new display widget/
      <TABLE>
        <TR><TD><PICTURE.EXTERN to="panes1.gif" type=gif>
        <TR><TD><PICTURE.EXTERN to="panes2.gif" type=gif>
      </TABLE>
    </FIGURE>
  <P>
    When more than one widget is used, the notion of the <EM/active widget/
    becomes important.  The active widget receives all work caused by
    applications of <<Inspect>>.  By default, the initial widget is the
    active widget. This can be changed using the <KEY/TAB/ key.  The active
    widget is indicated by a box with extra-thick line width around its
    viewing area.
  <P>
    To show the value ?_{X} in the ?_{I}-th window, execute the statement
    <<{InspectN ?_{I} ?_{X}}>>.  The widgets are numbered starting from zero.
  <P>
    The currently active widget can be removed by clicking <Q/Delete active
    Widget/ from the Inspector menu (see <PTR to="figure.panes">).  The widget
    below the active widget becomes the new active widget.  If only a single
    widget is left, this action is ignored.
  <SECTION><TITLE/Value Representation/
  <P>
    The Inspector can be configured to display values using either a
    tree-like or graph-like representation (see <PTR to="figure.views">).
    <FIGURE id="figure.views">
      <CAPTION/Three views on the same datastructure/
      <PICTURE.EXTERN to="views.gif" type=gif>
    </FIGURE>
  <PARA><TITLE/Tree/
    The value will be shown as a tree with respect to given depth and width
    exploration limits.  Values larger than the given limits are truncated,
    the cut positions being indicated by down and right arrows, respectively.
  <PARA><TITLE/Graph/
    The value will be shown not only with respect to given depth and width
    exploration limits but also with respect to an equivalence relation:
    Repeatedly occurring sub-values will only be displayed once, all later
    occurrences being replaced by references to the first occurrence.
    This yields a more compact representation revealing more information
    about the value's structure. Equivalence is computed in a depth-first
    left-to-right traversal over the entire (truncated) value.
  </PARA>
</CHAPTER>
