TopButtonDoc.tioga
Weiser, August 29, 1993 10:55 pm PDT
TopButton
PCEDAR 2.0 % FOR INTERNAL XEROX USE ONLY
TopButton
Weiser
Ó Copyright 1990 Xerox Corporation. All rights reserved.
Abstract: TopButton provides a facility similar to the Commander command "CreateButton", except the button is put on the top line of the Cedar screen (next to the message window).
Created by: Bloomenthal, Welch, Weiser
Maintained by: Weiser
Keywords: button, topbutton, createbutton, message window
XEROX  Xerox Corporation
   Palo Alto Research Center
   3333 Coyote Hill Road
   Palo Alto, California 94304

For Internal Xerox Use Only
1. What it does
TopButton puts a new button at the top of the Cedar screen, and binds it to a command string. When the button is pressed, the command string happens, with appropriate substitutions (see below). The output of the command is sent to the message window. The first argument to TopButton is the name of the button.
The command DestroyTopButton removes a button. The command ReplaceTopButton changes the command string executed by an existing button.
The substitutions are the same as those used when creating buttons in Commanders with CreateButton (as of 12/28/90 when TopButton was written). These are described below.
The main difference between CreateButton and TopButton is that buttons executed by CreateButton are run in the Commander containing the button, which means in that current directory, with those aliases, etc. TopButton commands are not run in a viewer, but are passed to a disembodied Commander. Depending on a particular current directory is not recommended.
The substitutions are:
$CurrentSelection$ => replaced by the current selection up to but not including the first carriage return
$CurrentEscapedSelection$ => replaced by a rope literal (minus the surrounding quotes) for the entire current selection
$CurrentSpacedSelection$ => replaced by the whole current selection, with spaces substituted for newlines
$FileNameSelection$ => replaced by the current selection if it appears to be a file name, otherwise replaced by the name of the selected viewer
$ShortFileNameSelection$ => same as $FileNameSelection$ except that version number and directory are omitted
$BaseFileNameSelection$ => same as $ShortFileNameSelection$ except that extensions are ommited
$SpaceFileNameSelection$ => replaced by the current selection if it appears to be a file name (may include white space), otherwise replaced by the name of the selected viewer
$ShortSpaceFileNameSelection$ => same as $SpaceFileNameSelection$ except that version number and directory are omitted
$QuotedFileNameSelection$ => replaced by the current selection if it appears to be a file name (may include white space), otherwise replaced by the name of the selected viewer. The results will have double quotes around it.
$ShortQuotedFileNameSelection$ => same as $QuotedFileNameSelection$ except that version number and directory are omitted.
$SelectedViewerName$ => replaced by the name of the selected viewer
$ViewerPosition$ => replaced by the position of the current selection in a viewer
$MouseButton$ => left|middle|right
$ShiftKey$ => shift|noShift
$ControlKey$ control|noControl
2. Examples
The following mimics the behavior of the built-in "open" button:
TopButton Open Open $CurrentSelection$
The following simply prints the mouse button that was used to click it:
TopButton echo $MouseButton$
3. Bugs
1. Does not catch EndOfStream when reading arguments, so typing TopButton with no arguments requires the user to respond "N" to the message:
*** Uncaught ERROR or SIGNAL: EndOfStream
*** Do you want to try to debug this?
2. Lots of output sent to the message window is hard to follow.
3. The implementation required copying code from CommanderViewerImpl.mesa (in CommandToolCompatibility). That is a shame. The proc ButtonCommandToRope in TopButton.mesa could perhaps be used by both, if someone thinks that that is worth it.