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