-- CreateButtonDoc.tioga
-- last edited by: L. Stewart, December 16, 1983 2:33 pm
name  CreateButton:
<<syntax>>
<<CreateButton buttonName commandLine>>
<<description>>
<<The command appends a button to the herald of the CommandTool in which it is run.  The name of the button is buttonName.  When 
the button is clicked, the commandLine is transformed as described below and stuffed into the CommandTool input.  Before stuffing, 
the button procedure checks to see whether or not the current input buffer of the CommandTool ends with a CR.  If it does not, then 
the buffer is erased back to the last CR.>>
<<The button procedure appends a CR to the end of commandLine if there is not one there already.>>
<<Substitutions are done on commandLine before stuffing it.  The following special strings are replaced as shown:>>
<<>>
$CurrentSelection$  => replaced by the current selection up to but not including the first carriage return
$FileNameSelection$ => replaced by the current selection if it appears to be a file name, otherwise replaced by the name of the 
selected viewer
$SelectedViewerName$ => replaced by the name of the selected viewer
$ViewerPosition$ => replaced by the position of the current selection in a viewer
$MouseButton$ => "left", "middle", or "right"
$ShiftKey$ => "shift", "noShift"
$ControlKey$ "control", "noControl"

The idea is that one writes an ordinary command line CommandProc to do some job, then use CreateButton to hook up a button to it.
<<examples>>
<<% CreateButton Test // CurrentSelection = $CurrentSelection$, FileNameSelection = $FileNameSelection$, SelectedViewerName = 
$SelectedViewerName$, ViewerPosition = $ViewerPosition$, MouseButton = $MouseButton$, ShiftKey = $ShiftKey$, ControlKey = 
$ControlKey$
% -- Select something like "Atom" in the viewer CommandsCImpl.mesa and click control shift middle
% // CurrentSelection = Atom, FileNameSelection = Atom, SelectedViewerName = []<>ct>commandscimpl.mesa, ViewerPosition = 12, 
MouseButton = middle, ShiftKey = shift, ControlKey = control
% >>
<<warnings>>
<<For now, you have to type a carriage return yourself to make the button push really happen.>>
<<stop/undo >>
<<Probably too fast to stop.>>
<<implementation >>
<<CommandsCImpl.mesa in CommandTool.df>>
<<contact>>
<<L. C. Stewart <Stewart.pa>>>
<<keyword hints>>
<<
help button info man>>
<<keywords>>
<<
to be supplied by the Index Czar>>