ViewerCommandsDoc.tioga
Copyright Ó 1993 by Xerox Corporation. All rights reserved.
Mike Spreitzer, June 7, 1988
Last tweaked by Mike Spreitzer on June 8, 1988 3:32:47 pm PDT
Polle Zellweger (PTZ) June 20, 1988 3:46:37 pm PDT
Swinehart, September 17, 1993 2:45 pm PDT
ViewerCommands
CEDAR 10.1 — FOR INTERNAL XEROX USE ONLY
ViewerCommands
Mike Spreitzer
© Copyright 1988, 1993 Xerox Corporation. All rights reserved.
Abstract: ViewerCommands provides command-tool commands for manipulating Viewers. This is useful when you can only access a machine via the RemoteCommandTool or if you wish to manipulate Viewers from a scripted document.
Created by: Mike Spreitzer
Maintained by: Mike Spreitzer, Polle Zellweger, Dan Swinehart
Keywords: Command, Viewer
XEROX Xerox Corporation
Palo Alto Research Center
3333 Coyote Hill Road
Palo Alto, California 94304
For Internal Xerox Use Only
1. General
Every Viewer has a name. Some names are user-friendly, and some are not. The unfriendly ones are simply the octal address of the Viewer's data structure.
Viewers are organized into a tree. Some Viewers have parents, and every Viewer has a sequence of children, which may be empty. A Viewer is top-level iff it has no parent. Sometimes we think about a fictitous root Viewer, which has all the top-level Viewers as children. A subtree of the Viewers tree is a Viewer, all its children, all their children, and so on, as far as it goes. The superparent of a Viewer is the top-level viewer that contains the given viewer in its subtree.
Some top-level Viewers are iconic. A non-top-level Viewer is iconic if and only if its superparent is iconic.
A viewer has a menu, which may be empty. Some viewers are Buttons. Some viewers are TiogaButtons, which means they contain a bunch of logical buttons.
In commands, a viewer name need not be quoted, unless it contains characters that would otherwise cause it to be parsed as multiple names.
A path name is a series of name patterns, enclosed in parentheses. A name pattern is like a name, except that it may contain a star (*), which means to match any substring. Names are matched against patterns `caselessly'. The name ** has special meaning: it matches across levels (note that ordinary * doesn't match across levels, because a path is not a single token); precisely, it matches every viewer in the subtree of where it was given. The name / also has a special meaning: go to root. And the name .. also has a special meaning: go to parent.
There is a notion of the `working viewer', analogous to the working directory. It is a command-tool property ($CurrentViewer).
2. Commands
2.1 Working viewer & list viewers
PWV:
syntax: PWV
description: Prints the working viewer.
CV:
syntax: CV path
description: Sets the working viewer.
VLs:
syntax: VLs [switches] path*
description: Like LS, except that it is exploring the Viewers tree, rather than the filesystem. Switches may be negated by preceeding them with a dash (-) or tilde (~). Valid switches are:
i => include icons (defaults TRUE). When FALSE, iconic viewers are omitted.
l => include labels (defaults TRUE). When FALSE, certain really trivial kinds of Viewers (Labels, NumberLabels, and Rules) are omitted.
m => list menu (defaults FALSE). When TRUE, the menus, if any, of the viewers will also be listed.
p => list position (defaults FALSE). When TRUE, the positions of the viewers will also be listed.
examples
% VLs ( / *error* )
list all top-level Viewers with the string "error" (in any case) in their names. This is a way to find debugger windows due to uncaught ERRORs.
% VLs ( .. * )
list all siblings of the working viewer
% VLs ( ** )
list the current subtree
% VLs ( ** *foo*)
list the viewers in the subtree of the working viewer that have "foo" in their names.
2.2 Viewer contents
VType:
syntax: VType path*
description: Prints contents of the indicated viewers
examples
% VType ( / *error* )
Find out what's wrong.
VSet:
syntax: VType path newContents
description: Sets the contents of the indicated viewer
examples
% VSet ( "EditTool" 10562062B ) "a target"
Sets the target field of the edit tool.
VConnect:
syntax: VConnect path
description: `Connects' with a typescript. Input to the command goes into the typescript, and output to the typescript also becomes output of the command. Stop this with STOP!
examples
% VConnect ( / *error* )
Prepare to play with the only debugger window.
2.3 Buttons, menus & notification
VNotify:
syntax: VNotify path input
description: Passes the given input to the given viewer's notify procedure. Where the token "Coords" appears in the input, it will be replaced by invented screen coordinates. The token RealCoords will be replaced by an invented Imager.VEC.
examples
% VNotify ( ) Coords Mark Hit
This is how to push a Button.
BPush:
syntax: BPush path (Red|Yellow|Blue|Shift|Control)*
description: Pushes a button. Could be done with VNotify, but this is easier.
examples
% BPush ( / Boot ) Blue
Open the boot tool.
MPush:
syntax: MPush path menuEntryName (Red|Yellow|Blue|Shift|Control)*
description: Invokes a menu entry.
examples
% MPush ( ) Abort
If the working viewer were a debugger window, this would push its Abort menu entry.
TPush:
syntax: TPush path tiogaButtonName (Red|Yellow|Blue|Shift|Control)*
description: Pushes a TiogaButton. tiogaButtonName can contain *s to indicate that 0 or more characters will match. Case is ignored.
examples
% TPush ( "Walnut 7.0" ) Deleted Yellow
Open the Deleted message set.
% TPush ( *TDir* ) *Time* Yellow
Call Time announcement via a Finch telephone directory.
2.4 Screen operations
MoveBoundary:
syntax: MoveBoundary integer|real
description: Sets the division between the columns. If the argument has a decimal point in it, it is taken as a fraction to be applied to the width of the black-and-white screen. If the argument has no decimal point, it is taken to be the width of the left column, in pixels.
examples
% MoveBoundary 0.5
The sensible way to be.
% MoveBoundary 600
Establish Viewers' current initial state.
Paint:
syntax: Paint
description: Repaints the screen.
2.5 Viewer placement
These operations apply only to top-level viewers. Most are equivalent to pushing some Viewers menu button (provided under a viewer's caption).
VOpen:
syntax: VOpen path
description: Opens all top-level iconic viewers in path.
examples
% VOpen ( *commandtool* )
Open all command tool viewers.
VClose:
syntax: VClose path
description: Closes all top-level iconic viewers in path.
VDestroy:
syntax: VDestroy path
description: Closes all top-level viewers in path.
VTop:
syntax: VTop path
description: Moves all top-level viewers in path to the tops of their respective columns. If more than one of the viewers is in a given column, the last one wins.
VBottom:
syntax: VBottom path
description: Moves all top-level viewers in path to the bottoms of their respective columns.
VLeft:
syntax: VLeft path
description: Moves all top-level viewers in path to the left column.
VRight:
syntax: VRight path
description: Moves all top-level viewers in path to the right column.
VColor:
syntax: VColor path
description: Moves all top-level viewers in path to the color display.
VGrow:
syntax: VGrow path
description: Perform the Viewers Grow function for each top-level viewer in path: close all other viewers in the column if any are open, growing the specified viewer to full column; otherwise open the previously-closed viewers, shrinking the specified viewer.
VFull:
syntax: VFull path
description: Makes all top-level viewers in path occupy their full column by closing all other viewers in the column; a no-op if already true. Will open an iconic viewer if necessary (equivalent to shift-middle click for an icon).
VShrink:
syntax: VShrink path
description: Makes all top-level viewers in path occupy a partial column by re-opening other viewers that shared the column before the most recent Grow or VGrow command; a no-op if already true.