Object-Viewing "Whiteboards"

Author: Jeff Dalton

What are they?

Object-viewing "whiteboards" are a way to view and modify property values of objects in a panel's world state. The model is a whiteboard on which a table has been drawn, with one row per object and one column per property, so that it's possible to erase and write in values for the properties. This facility was designed with the following features in mind:

A view can show specific objects and/or all objects of specified types.
Any (reasonable) number of specified properties can be shown.
The information is presented in a straightforward and easy to understand form.
Property values can be quite long, such as a paragraph or more of text, and still be fully displayed.
Tricky syntactic details, such as quote marks around a value that's meant to be a string, can be avoided.
Editing is reasonably free-form and intuitive.
More than one view can be seen at once, in separate windows.
Views can be defined in the general-purpose I-X XML syntax.

Object-View syntax

To use the viewer, you will need to define some object-view objects which specify what is in each view you wish to be able to display.

Here is the XML syntax for object-view and related classes. (Other representations correspond to this in the usual way.)

OBJECT-VIEW ::=
   <object-view>
      <name>STRING</name>
      <object-header>STRING</object-header>
      <objects><list>...</list></objects>
      <types><list>...</list></types>
      <properties><list>OBJECT-PROPERTY...</list></properties>
   </object-view>

OBJECT-PROPERTY ::=
   <object-property
         name="SYMBOL"
         value-class-name="SYMBOL"
         syntax="OBJECT-PROPERTY$SYNTAX">
   </object-property>

OBJECT-PROPERTY$SYNTAX ::= number | symbol | string | list | object | default

An object-view has the following fields:

name string: The name used to identify the view in menus and other places. In future versions, a name might be supplied automatically if a view is loaded from a file, but for now it must always be specified explicitly.
object-header string: The text to put in the leftmost column header -- the column where the objects are listed. It should be a brief description of the objects. For example, if the objects are all blocks, it could just be "Blocks". If no header is specified, "Object" will be used.
objects list-of-objects: A list of the objects to be viewed. It will typically be a list of symbols that are being used as object ids. These objects will be in the table regardless of their type. This field is optional.
types list-of-objects: A list of the object types to be viewed. It will typically be a list of symbols that are being used as type names in state information of the form type object = type. All objects of any of the listed types will be displayed in the table, and objects should automatically be added to or removed from the display if they gain or lose one of the listed types. This field is optional.
properties list-of-object-properties: A list of descriptions of the properties to be viewed. In state information, properties are objects, usually symbols, that are used in statements of the form property object = value. In object-views, only properties that are represented by symbols can be used.

An object-property gives a property's name and syntax:

name symbol: A symbol that is being used as a property name in state information of the form property object = value.
syntax syntax: One of the names listed as a possible "OBJECT-PROPERTY$SYNTAX" above. The aim is to let the value be represented in a reasonably natural way as text. For example, if the syntax is string, the characters in the string are written without enclosing them in double-quotes. list means that the outermost enclosing parentheses (which are often the only parentheses) are omitted. number and symbol are chiefly to indicate how a value that "looks like a number" should be parsed. If the syntax is object, then no special processing is performed and the value must be written in the usual way with quotes around strings, etc. default, which is equivalent to omitting the field, is similar to object but allows a better syntax to be determined by looking at the current world-state at run time.

An example:

<object-view name="blocks-type">
  <types>
    <list>
      <symbol>block</symbol>
    </list>
  </types>
  <properties>
    <list>
      <object-property name="size" syntax="symbol" />
      <object-property name="colour" syntax="symbol" />
      <object-property name="cleartop" syntax="symbol" />
      <object-property name="notes" syntax="string" />
    </list>
  </properties>
</object-view>

A table showing that view might look like this:

Object size colour cleartop notes

a large blue yes

b small red no the heaviest block

c small green no

Object	size	colour	cleartop	notes
a	large	blue	yes
b	small	red	no	the heaviest block
c	small	green	no

Adding the "Object Views" tool to a panel

Object-view "whiteboards" are currently packaged as a "tool" that can be added to an I-X Process Panel or similar agent. The tool is not present automatically; you have to add it using the agent extension mechanism. This is done by specifying a command-line argument or props file entry

   extension-classes=ix.ip2.ObjectViewExtension

Another useful parameter is

  object-view-directory=directory-name

The directory should contain a set of object-views, one per file. Any of the general-purpose file syntaxes supported by the agent can be used. In practice, this usually means the XML syntax. The directory can also contain files that are written in a syntax that cannot specify an object-view; but any files that could contain an object-view must actually contain one rather than some other sort of object such as a plan.

An "Object Views" entry should then be present in the "Tools" menu. If selected, a window should appear. Initially, it will contain an empty view; the desired view can then be selected from a menu. The window's "File" menu allows new viewing windows to be created, so that several can be in use at once (usually showing different views.)

It is also possible to specify a set of views to be created when the tool is first selected by using an "initial-whiteboards" parameter:

  initial-whiteboards=:all
  initial-whiteboards=comma-separated-list

Editing in the view should be reasonably intuitive. The view is represented as an HTML table, and you should be able to edit within table cells. (If you can edit anything else, or break down the walls between cells, it is a bug and should be reported.) Your changes do not take effect until you press the "Commit changes" button.

Adding a row

Pressing the "New Row" button will pop up a dialog that looks like this:

In that picture, the "object-header" for the view is "block", so that is what is shown above the text area that's used to type in the new object's name.

If a type is selected, the new object will be given that type. Only types that are included in the view will appear in the menu.

Jeff Dalton <J.Dalton@ed.ac.uk>