<!--
  - Authors:
  -   Thorsten Brunklaus <brunklaus@ps.uni-sb.de>
  -
  - Copyright:
  -   Thorsten Brunklaus, 2001
  -
  - Last change:
  -   $Date: 2001-10-12 16:27:10 +0200 (Fri, 12 Oct 2001) $ by $Author: bruni $
  -   $Revision: 14317 $
  -
  - 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.configure"><TITLE/API Reference/
  <P>
    The Inspector functor is available for import at the URI
    <<'x-oz://system/Inspector'>>.  It exports the following
    application programmer's interface:
    <LIST>
      <ENTRY><<inspect>>
      <SYNOPSIS>
	<<{Inspector.inspect ?_{X}}>>
      <ITEM>
	opens a new Inspector window if none exists, then displays
	?_{X} in the active widget.
      <ENTRY><<inspectN>>
      <SYNOPSIS>
	<<{Inspector.inspectN ?+{I} ?_{X}}>>
      <ITEM>
	opens a new Inspector window if none exists, then displays
	?_{X} in the widget with number&nbsp;?_{I}, counting from zero.
        Note that the chosen widget must have been created already. This is always
        the case for number zero.
      <ENTRY><<configure>>
      <SYNOPSIS>
	<<{Inspector.configure ?+{Key} ?+{Value}}>>
      <ITEM>
	sets the configuration option with key&nbsp;?_{Key} to value&nbsp;?_{Value}.
        The following sections starting with <PTR to="section.configure.inspector">
        explain in detail which keys and
        values are valid parameters.
	<!--** missing: description of keys and values -->
      <ENTRY><<configureN>>
      <SYNOPSIS>
	<<{Inspector.configureN ?+{I} ?+{Key} ?_{X}}>>
      <ITEM>
        behaves like <<configure>> but directly addresses
        the widget number&nbsp;?_{I} which must be existing already.
      <ENTRY><<close>>
      <SYNOPSIS>
	<<{Inspector.close}>>
      <ITEM>
	closes the Inspector window, if any.
      <ENTRY><<'class'>>
      <SYNOPSIS>
	<<Inspector.new ?+{OptionRecord}>>
      <ITEM>
        creates are new Inspector instance. This function replaces
        the old class field for safety reasons. Extensions are still
        possible by using adapter construction. This object is concurrency
        safe and can be used in any space.&nbsp?+{OptionRecord}
        denotes a record containing user options,
        with <<unit>> the empty case.
        Of course, all features must denote a valid option. 
      <ENTRY><<object>>
      <SYNOPSIS>
	<<Inspector.object>>
      <ITEM>
	is the default instance of the Inspector and
	is implicitly used by <<Inspect>>, <<Inspector.inspectN>>,
	<<Inspector.configure>>, <<Inspector.configureN>> and
        <<Inspector.close>>. This object is creating using the above
        <<Inspector.new>> function.
      <ENTRY><<reflect>>
      <SYNOPSIS>
        <<Inspector.reflect>>
      <ITEM>
        exports the reflection function used by the inspector to reflect
        deep space values. Use at your own risk.
      <ENTRY><<reflect>>
      <SYNOPSIS>
        <<Inspector.unreflect>>
      <ITEM>
        exports the unreflection function used by the inspector.
        Use at your own risk.
    </LIST>
  <SECTION id="section.configure.methods"><TITLE/Inspector object methods/
   <P>
     The inspector object provides the methods shown below.
     <LIST>
       <ENTRY><<inspect(?_{X})>>
       <ITEM>
         inspects the value ?_{X}.
       <ENTRY><<inspectN(?+{N} ?_{X})>>
       <ITEM>
         inspects the value denoted by ?_{X} using
         widget number ?_{N}. Keep in mind
         then the corresponding widget must have been created already.
       <ENTRY><<configureEntry(?+{Key} ?+{Value})>>
       <ITEM>
         tells the inspector to update the option
         denoted by ?_{Key} with value ?_{Value}.
       <ENTRY><<close>>
       <ITEM>
         closes and unmaps the inspector object.
     </LIST>
    <P>
  <SECTION id="section.configure.inspector"><TITLE/Inspector Options/
    <P>
      This section covers global Inspector options.
      <LIST>
        <ENTRY><<inspectorWidth>>
        <SYNOPSIS>
          <<{Inspector.configure inspectorWidth ?+{I}}>>
        <ITEM>
          adjusts the Inspector's 
          horizontal window dimension to ?_{I}&nbsp;pixels.
          Defaults to 600.
        <ENTRY><<inspectorDepth>>
        <SYNOPSIS>
          <<{Inspector.configure inspectorDepth ?+{I}}>>
        <ITEM>
          adjusts the Inspector's
          vertical window dimension to ?_{I}&nbsp;pixels.
          Defaults to 400.
        <ENTRY><<inspectorOptionsRange>>
        <SYNOPSIS>
          <<{Inspector.configure inspectorOptionsRange ?+{A}}>>
        <ITEM>
           determines which widgets will be affected by reconfiguration.
           ?_{A} can be either <<'active'>> or <<'all'>>,
           with the obvious meaning.
      </LIST>
   <SECTION id="section.configure.representation"><TITLE/Value Represenation/
    <P>
      This section explains how to configure the value representation using the API.
      <LIST>
        <ENTRY><<widgetTreeWidth>>
        <SYNOPSIS>
          <<{Inspector.configure widgetTreeWidth ?+{I}}>>
        <ITEM>
          adjusts the global width traversal limit to&nbsp;?_{I}. Defaults to 50.
        <ENTRY><<widgetTreeDepth>>
        <SYNOPSIS>
          <<{Inspector.configure widgetTreeDepth ?+{I}}>>
        <ITEM>
          adjusts the global depth traversal limit to&nbsp;?_{I}. Defaults to 15.
        <ENTRY><<widgetTreeDisplayMode>>
        <SYNOPSIS>
          <<{Inspector.configure widgetTreeDisplayMode ?+{B}}>>
        <ITEM>
          switches between tree and graph representation, depending on whether&nbsp;?_{B}
          denotes <<true>> or <<false>>, respectively.
        <ENTRY><<widgetUseNodeSet>>
        <SYNOPSIS>
          <<{Inspector.configure widgetUseNodeSet ?+{I}}>>
        <ITEM>
          determines the subtree alignment. If ?_{I} is&nbsp;<<1>>,
          the standard aligment is used. A value of&nbsp;<<2>> selects fixed width indentation.
        <ENTRY><<widgetShowStrings>>
        <SYNOPSIS>
          <<{Inspector.configure widgetShowStrings ?+{B}}>>
        <ITEM>
          switches between normal and readable representation of strings.
          It defaults to <<false>>.
      </LIST>
  <SECTION id="section.configure.visual"><TITLE/Visual Settings/
    <P>
      This section explains how to configure the visual aspects of node drawing using the API.
      <LIST>
        <ENTRY><<widgetTreeFont>>
        <SYNOPSIS>
          <<{Inspector.configure widgetTreeFont font(family:?+{F} size:?+{S} weight:?+{W})}>>
        <ITEM>
          selects the widget font as follows:
          <LIST>
            <ITEM>?+{F} denotes either <<'courier'>> or <<'helvetica'>>.
            <ITEM>?+{S} denotes any integer out of <<{10, 12, 14, 18, 24}>>.
            <ITEM>?+{W} denotes either <<'normal'>> or <<'bold'>>.
          </LIST>
          The default is <<font(family:'courier' size:12 weight:'normal')>>.
        <ENTRY><<widgetContextMenuFont>>
        <SYNOPSIS>
          <<{Inspector.configure widgetContextMenuFont ?+{V})}>>
	<ITEM>
          selects the font used to draw the context menus. ?_{V} denotes any valid
          X font description. It defaults to <<'-adobe-helvetica-bold-r-*-*-*-100-*'>>.
      </LIST>
  <SUBSECTION id="section.configure.colors"><TITLE/Color Assignment/
    <P>
      <LIST>
        <ENTRY><<{Inspector.configure ?+{A} ?+{Color})}>>
        <ITEM>
          assigns color&nbsp;?_{Color} to item type &nbsp;?_{A}.
          ?_{Color} denotes an atom describing any valid hexadecimal RGB color code.
          ?_{A} is composed of a type prefix and a 'Color' suffix. For example,
<<<{Inspector.configure intColor '#AAFF11'}>>>
        <P>
          chooses to draw integer nodes with
          color <<'#AAFF11'>>. The complete list of known types is shown in table
          <PTR to="figure.types">.

          <FIGURE id="figure.types">
            <CAPTION/Known atomic types/
            <TABLE>
            <TR><TD><<int>></TD><TD><<float>></TD><TD><<atom>></TD></TR>
            <TR><TD><<bool>></TD><TD><<unit>></TD><TD><<name>></TD></TR>
            <TR><TD><<bytestring>></TD><TD><<procedure>></TD><TD><<future>></TD></TR>
            <TR><TD><<free>></TD><TD COLSPAN=2>Oz variables</TD></TR>
            <TR><TD><<fdint>></TD><TD COLSPAN=2>Oz finite domain variables</TD></TR>
            <TR><TD><<label>></TD><TD COLSPAN=2>record/tuple labels</TR>
            <TR><TD><<feature>></TD><TD COLSPAN=2>record features</TR>
            <TR><TD><<background>></TD><TD COLSPAN=2>widget backround</TD></TR>
            <TR><TD><<variableref>></TD><TD COLSPAN=2>using occurence of graph reference</TD</TR>
            <TR><TD><<ref>></TD><TD COLSPAN=2>defining occurence of graph reference</TD></TR>
            <TR><TD><<generic>></TD><TD COLSPAN=2>the generic value</TD></TR>
            <TR><TD><<braces>></TD><TD COLSPAN=2>parentheses around mixfix tuples</TD></TR>
            <TR><TD><<colon>></TD><TD COLSPAN=2>separator between feature and subtree</TD></TR>
            <TR><TD><<widthbitmap>></TD><TD COLSPAN=2>left arrow</TD></TR>
            <TR><TD><<depthbitmap>></TD><TD COLSPAN=2>down arrow</TD></TR>
            <TR><TD><<separator>></TD><TD COLSPAN=2>separators such as <<#>> and <<|>></TD></TR>
            <TR><TD><<proxy>></TD><TD COLSPAN=2>background color used for mappings</TD></TR>
            <TR><TD><<selection>></TD><TD COLSPAN=2>background color used for selections</TD></TR>
            </TABLE>
          </FIGURE>      
      </LIST>
  <SECTION id="section.configure.menus"><TITLE/Customizing Context Menus/
    <P>
      This sections explains how to create context menus. The current implementation
      only allows to attach entire context menus to a node. A context menu
      simply is a tuple <<menu(WidthList DepthList MappingList ActionList)>> as follows:
      <LIST>
        <ITEM>
          <<WidthList>> and <<DepthList>> denote integer lists
          describing the possible limit changes.
          The integer zero serves as separator indicator.
          Both lists default to <<[1 5 10 0 ~1 ~5 ~10]>>.
        <ITEM>
          <<MappingList>> denotes a list of tuples following the pattern
          <<'Shown Label'(MapFun)>>. See <PTR to="section.configure.mappings"> for
          details about writing mappings.
          <P>
          If the function should be used for auto-mapping,
          use&nbsp;<<auto('Shown Label'(MapFun))>>
          instead. Each list must not contain more than one auto mapping entry.
        <ITEM>
          <<ActionList>> denotes a list of tuples following the pattern
          <<'Shown Label'(ActionProc)>>. See <PTR to="section.configure.actions">
          for details about writing actions.
      </LIST>
  <SUBSECTION id="section.configure.register"><TITLE/Registering context menus/
    <P>
      Context menus are registered using the statement
<<<{Inspector.configure ?+{Type} ?+{Menu}}
>>>
    <P>
      where ?_{Type} denotes an atom composed of a valid type prefix as shown in
      <PTR to="figure.prefixes"> and a <<Menu>> suffix.
      ?_{Menu} denotes the menu as described in <PTR to="section.configure.menus">.
      <FIGURE id="figure.prefixes">
        <CAPTION/Menu types/
        <TABLE>
          <TR><TD><<hashtuple>></TD><TD>Tuples with label <<#>></TD></TR>
          <TR><TD><<pipetuple>></TD><TD>Possible open lists such as streams</TD></TR>
          <TR><TD><<list>></TD><TD>Closed lists</TD></TR>
          <TR><TD>labeltuple</TD><TD>Tuple with any other label</TD></TR>
          <TR><TD>record</TD><TD>Oz Records (without kinded reocrds)</TD></TR>
          <TR><TD>kindedrecord</TD><TD>Feature constraints</TD></TR>
          <TR><TD>future</TD><TD>Futures</TD></TR>
          <TR><TD>free</TD><TD>Variables</TD></TR>
          <TR><TD>fdint</TD><TD>Finite domain variables</TD></TR>
          <TR><TD>fset</TD><TD>Finite set menus</TD></TR>
          <TR><TD>array</TD><TD>Oz arrays</TD></TR>
          <TR><TD>dictionary</TD><TD>Oz dictionaries</TD></TR>
          <TR><TD>class</TD><TD>Oz classes</TD></TR>
          <TR><TD>object</TD><TD>Oz objects</TD></TR>
          <TR><TD>chunk</TD><TD>Oz chunks</TD></TR>
          <TR><TD>cell</TD><TD>Oz cell</TD></TR>
        </TABLE>
      </FIGURE>
    <P>
      For example, executing
<<<{Inspector.configure recordMenu Menu}
>>>
   <P>
     assigns a new record context menu denoted by ?_{Menu}.
  <SUBSECTION id="section.configure.mappings"><TITLE/Mapping Functions/
    <P>
      Writing mapping functions is easy: Every function follows the
      pattern below.
<<<fun {MyMapFunction Value MaxWidth MaxDepth}
   if {WantToMap Value} then
      &ellipsis; /* computations */ &ellipsis;
   else Value
   end
end>>>
    <P>
      <<MaxWidth>> and <<MaxDepth>> are integers denoting the node's width
      and depth limits.  This allows to handle cycles independently of whether
      they would have been recognized or not.  Keep in mind that mapping
      functions should not have side-effects.
  <SUBSECTION id="section.configure.actions"><TITLE/Action Procedures/
    <P>
      Action procedures follow the pattern below.
<<<proc {MyAction Value}
   &ellipsis; /* computations */ &ellipsis;
end>>>
  <SECTION id="section.configure.relations"><TITLE/Equivalence Relations/
    <P>
      Equivalence relations are registered using the statement
<<<{Inspector.configure widgetRelationList ['RelationName'(RelFun) /* ... more relations */]}
>>>
    <P>
     Every ?_{RelFun} is expected to compute the characteristic function of its relation
     and therefore follows the pattern
<<<fun {RelFun X Y}
      /* computations resulting true or false */
end>>>
    <P>
      These functions should not have side effects.
      Again, the implementation currently only supports the replacement of the all relations.
  <SECTION><TITLE/Inspecting user-defined types/
  <P>
    Oz allows to add new types to the system. The Inspector is able to display such values
    without beeing rebuilt provided that they can be distinguished using <<Value.status>>
    and transformed to a built-in type. In this case,
    it is sufficient to add a new mapping function attached to that type.
    In the default case, the inspector will use
    <<Value.toVirtualString>> to obtain a useful representation of
    the unknown value. Depending on its type, the value
    will be monitored und updated, too.
  <P>
    For example, to
    introduce weak dictionaries to the inspector use the code shown below.
<<<local
   fun {ItemFun V W D}
      {WeakDictionary.items V}
   end
   Key     = case {Value.status {WeakDictionary.new _}} of det(T) then T [] _ then generic end
   TypeKey = {VirtualString.toAtom Key#'Menu'}
in 
   {Inspector.configure TypeKey menu(nil nil [auto('Show Contents'(ItemFun))] nil)}
end>>>
  <P>
    See <PTR to="section.configure.mappings"> for details about how <<ItemFun>> is built.
</CHAPTER>
