WhiteboardDoc.tioga
Last Edited by: Donahue.pa on June 5, 1984 9:35:33 am PDT
Last Edited by: Subhana, June 6, 1984 2:09:37 pm PDT
Last Edited by: Widom, August 25, 1984 0:47:32 am PDT
Last Edited by: Donahue, September 3, 1984 10:12:05 am PDT
WHITEBOARDS
CEDAR 5.2 — FOR INTERNAL XEROX USE ONLY
Whiteboards
Jim Donahue
Release as [Indigo]<Cedar5.2>Documentation>WhiteboardDoc.Tioga

© Copyright 1984 Xerox Corporation. All rights reserved.
XEROX   Xerox Corporation
    Palo Alto Research Center
    3333 Coyote Hill Road
    Palo Alto, California 94304
    
For Internal Xerox Use Only
Introduction
The noun "Whiteboard" refers both to an object found on PARC office walls and to a particular kind of Cypress database. A Whiteboard database contains information about the positions of "text boxes" (filled with Tioga text) and Cedar icons that will be displayed on a Whiteboard viewer; the whiteboard code allows a user to move icons and text boxes in a viewer and save the resulting arrangement permanently in a database. The "Cedar Whiteboards" are a whiteboard database containing references to both documentation on the Cedar system and a large (and growing) collection of Cedar tools (so that you don't have to know that to read your mail, you need to run a program called Walnut). John Maxwell had the initial idea for a whiteboard database; Jim Donahue redesigned both the implementation and database schema and put together the Cedar Whiteboards; Jennifer Widom did a large part of the reimplementation.
Below we give a discussion of what a whiteboard database is, discuss creating and editing your own whiteboards, and then describe how you can browse the Cedar Whiteboards.
What a Whiteboard Is
A whiteboard database records the spatial arrangement of icons and text boxes in a whiteboard viewer. The text boxes can contain arbitrary Tioga text and the icons can be any of the normal Cedar icons you find on the screen, ie., they can be icons referencing text files, other whiteboards, entities in other databases (like Walnut message sets) and Cedar tools (like Walnut or the EditTool). The whiteboard browser is responsible for storing the arrangement of a whiteboard in a database and then later reconstructing the viewer from the stored information. Additionally, the browser implements the semantics of "opening" an icon on a whiteboard; this may involve opening a file (for text file icons), performing database manipulations (for opening other whiteboards) or loading a program (for tool icons). Below is a picture of the Whiteboard named Cedar that is the root of the Cedar Whiteboards.
/ivy/donahue/pictures/screen1.ais height: 6.5 in
Operations on Whiteboards
Commands for examining whiteboards
A Whiteboard may be displayed using the Whiteboard command registered with the Commander:
Whiteboard name (displays the named whiteboard).
The whiteboard is looked up in the Cypress database named by the Whiteboard.Segment entry in your user profile. If no whiteboard with the given name is found in this database, a new one will be created (if you have write access to the database).
Whiteboards may be manipulated using the menu at the top of a whiteboard window, or by using mouse buttons with special meanings within the whiteboard itself. For the purposes of browsing, only middle-button selection within the window itself will be needed. Middle-button selection means "open": whenever the user points at an icon on a whiteboard and presses the middle button, a new window is opened on the screen displaying the entity represented by that icon.
Use middle-button selection to examine items on the Cedar whiteboard. Note that documents and programs open Tioga windows or start programs, respectively. Documents appear as the familiar Cedar icons for ducments, and programs as their normal icons as well. Whiteboards may be nested inside whiteboards: they appear as icons resembling phyusical whiteboards. Try browsing through some of these. Each time you select an icon, a new window will be created on the screen. You will require only the middle mouse button for this browsing. For browsing of the network structure of the whiteboards, try middle-button selection of a whiteboard while holding down the control key. All of the whiteboards contained in the selected whiteboard will be iconically displayed, with lines drawn to illustrate the structure. These new whiteboards can be opened or similarly expanded.
Commands for editing whiteboards
The Cedar Whiteboards are readOnly for almost everyone, so you won't be able to edit them (you can however, move things around on a whiteboard -- you just won't be able to make any permanent changes). If you plan to create or edit your own whiteboards, you will need to know about more than just browsing with middle-button selection.
The meaning of the menu buttons on a Whiteboard are as follows:
Freeze: Retains this whiteboard on the screen, rather than replacing it with another whiteboard, when middle-button selection would normally display something else in it.
Reset: Restores a whiteboard to its state before any edits were made.
AddSelected: You select an icon somewhere at the bottom of the Cedar Viewers screen for this command. The selected entity is added to the whiteboard. It may already be a database entity (e.g. another whiteboard entity), or it may be a Tioga document or Cedar program (in which case a database entity may be created to represent it).
AddTool: You select a portion of text anywhere on the screen that is the command for a Cedar tool (e.g. "Waterlily"). The selected command is added to the whiteboard as a typescript icon. When such an icon is opened from the whiteboard, the tool is loaded and a new typescript viewer is created in which the command is executed.
Erase: Erases the entire whiteboard, but no need to panic ... this edit isn't commited to the database until you actually Save the whiteboard.
HELP: Adds a text box to the whiteboard which contains the instructions for editing the whiteboard using the mouse.
Grid: You may want the icons and text boxes on the whiteboard to line up either vertically or horizontally. The Grid menu item lets you set the size of a grid (in pixels) on which to place viewers on a whiteboard. The default grid size is 1; it can be doubled (up to a maximum of 32) by left-clicking the menu item and halved by right-clicking the menu item. Each time the grid is changed, the whiteboard will be redisplayed. Moreover, new items added to the whiteboard will only be allowed to settle on points on the grid (for icons, this means that the top left corner will be on a grid point, for text boxes that all of the corners will be on grid points).
Save: Stores any edits to the whiteboard in the database; removes "[New Version]" at top of window.
In addition to the commands at the top of a Whiteboard window, mouse button presses within the window area itself have specific effects on the entity the mouse is pointing at. Because mouse selections have their Tioga meanings when the cursor is inside text boxes, you must select just outside to get these effects on text boxes. The mouse buttons and their effects are:
Left: Selects and moves the icon for the entity (or a text box) around on the whiteboard.
Shift Left: Adds a new text box to the whiteboard at the location of the cursor. The text box can then be grown, moved, or typed into.
Control Left: Deletes the entity from this whiteboard.
Middle : Opens a displayer on the entity (or activates a tool).
Shift Middle : Opens a full-sized displayer on the entity
Control Middle : Expands the selected whiteboard. All whiteboards contained in the selected whiteboard are displayed, with lines drawn to illustrate the network structure. The added whiteboards can be opened, moved, deleted, etc... , but are not saved as permanent edits. 
Right: Grows (or shrinks) a text box.
Finally, there are a few command-tool commands available for manipulating whiteboards. They are:
OpenWBDatabase <filename>: Opens the whiteboard database specified by the file name (the default is "[Luther.Alpine]<CedarDocs>Whiteboard.segment"). If you already have a whiteboard database open, the old one will be closed and all whiteboard viewers on the screen will be destroyed.
Whiteboard <name>: Opens the named whiteboard, creating a new (empty) whiteboard if the named whiteboard doesn't exist in your database.
DestroyWB <name>: Destroys the named whiteboard, erasing it entirely from the database (be careful!).
CopyWB <from> <to>: Copies the whiteboard <from> to the whiteboard <to>. If <to> already exists in the database it is erased before the copy takes place; otherwise a new whiteboard is created.
EnumerateWBs <name>: Lists the names of the whiteboards contained in the named whiteboard. This allows the user to browse the whiteboard network structure from a command tool.
Browsing the Cedar Whiteboards
If you are on a public machine (or any non-rogue private machine), you can begin to browse the Cedar Whiteboards by using the command:
Whiteboard Cedar
The Cedar whiteboard is the "root" of the documentation; it contains some basic information about CSL and Cedar and also includes icons for a collection of additional whiteboards that give more specific information on various aspects of the system. Here is a brief summary of the contents of the whiteboards referenced from the root (pictures of these whiteboards can be found at the end of this document):
Basics: Information about user profiles, the set of basic DF files in Cedar, the CommandTool and (perhaps most importantly) how to boot a Dorado.
Language: An overview of the Cedar language, with pointers to documentation giving the complete Cedar language syntax, some suggestions for Cedar program style, and a collection of example programs.
Components: Information about some of the more important components of Cedar: Tioga, Viewers, the CommandTool (from the programmer's viewpoint) and Cypress. This also contains a reference to the Cedar Catalog.
Tools: The most widely used tools are described here, including Walnut, the DFTool, the EditTool, Chat, TSetter and Remember.
Interfaces: The most widely used interfaces in Cedar include Rope, Viewers, and IO (both the IO and FS interfaces).
ToolBox: A large (and growing) collection of Cedar tools can be started here just by opening the appropriate icon (but it wouldn't hurt to read the documentation for the tools first!).
Games: When you tire of doing serious work, there is a small collection of Cedar games to play: Mazewar, Football and Tank.
Many of these whiteboards contain references to other whiteboards, either to go more deeply into the structure (for instance, on the ToolBox whiteboard is a PerformanceTool whiteboard, which contains a collection of tools related to measuring performance) or to permit browsing in a less hierarchical fashion (the Cedar whiteboard can be found on many of the other whiteboards in the database, making it pretty easy to find your way back to the root).
The structure of this database and its contents should change over time -- this is just the beginning of an experiment! If you have comments on the organization of the database or on missing (or just wrong) contents, please send them along to Donahue.pa. If you're interested in either massaging the database or writing new applications code to improve the utility of the system, I would be especially interested in talking to you.
User profile options
There are three user profile options that you can change when using Whiteboards. The defaults are set up to use the Cedar Whiteboards; if you want to experiment with your own whiteboards, you'll have to at least change the Whiteboard.Segment entry.
Whiteboard.Segment: The name of the default Whiteboard segment; the default is "[Luther.Alpine]<CedarDoc>Whiteboard.segment" (so that browsers of the Cedar documentation don't have to specify anything).
Icons.Segment: The name of the default icon database to be used when displaying whiteboards; the default is "[Luther.Alpine]<CedarDoc>Icons.segment" (if you want to build a private icon database for your own application, see Jim Donahue)
Tool.Segment: The name of the default tool database used to store and access information about
the tools coontained in whiteboards; the default is "[Luther.Alpine]<CedarDoc>Tool.segment"
(again, if you want to build a private tool database for your application, see Jim Donahue).