\chapter{Summary of \cp\ functions}\label{cp-summary}

The highest level of the \id|CAM| program is a keyboard interpreter that
turns the \pc\ keyboard into a dedicated \cp\ for \cam.  A list of the
available \cxp\ commands can be obtained by looking at the various
menus, printed by the \keym\ key, as explained in Section \ref{menus}.
For reference, here we give a brief summary of all \cxp\
keys,\index{Control panel/summary of commands}\index{Control-panel
commands/summary} following the order used by the five \keym\
menus.\index{Menus}

The special keys used by the screen editor for control functions are not
part of the \cp\ and are listed in Chapter \ref{editor}.

The heading of each of the following sections coincides with the name of
the corresponding menu; this, in turn, is but the name of the Forth
vocabulary which contains the commands listed in that menu.  Similarly,
in the listings each \cxp\ key is accompanied by the name of the Forth
word that is executed when the corresponding key is hit; this name
(which may slightly differ from the command memonics used in the rest of
the manual) is immediately echoed on the \pc\ screen when you hit a key.


\def\mname#1{{\tt #1}\quad}

\newpage

\setcounter{section}{-1}
\section{{\tt GENERAL}}\label{general}

The commands in the {\tt GENERAL} menu perform functions of general utility
that do not affect \cam.  The digit keys 0 thru 9 can be used
to construct arguments for other keys; after any non-digit key this
argument is reset to ``no argument,'' regardless of whether the non-digit key made
use of an argument or not.  Except when using \keynumber, all numeric
arguments to keys are read in decimal regardless of the default base
(see \prog{SET-BASE} in the glossary).
 $$
  \begin{tabular}{|l|p{4.50in}|} \hline
    \icp\keym\ \icp\keyM & \mname{MENU} Show the menu of menus.  With a numeric argument,
shows one of the submenus. \\\hline 
    \icp\keyf\ \icp\keyF & \mname{Forth...} Leave the \cp\ and begin a dialogue
directly with the Forth interpreter. \\\hline 
    \icp\keyesc & \mname{(ignored)} If you are in Forth, or typing a
text argument to any \cp\ key, this puts you at the top level of the
\cp.  If you are already at the top level of the \cp, this key is
ignored. \\\hline 
    \icp\keytilde & \mname{DOS...} Leave the \cp\ and begin a dialogue
directly with a copy of the DOS command interpreter.  Type \id|exit| to
DOS to return to the \cp. \\\hline 
    \icp\keynumber & \mname{Number:} Used to enter arguments to keys
that are not in decimal notation.  Without a numeric argument, this key
accepts a text argument which it interprets as a hexadecimal number.
If this key is preceded with a numeric argument, then this number is
used as the radix in interpreting the subsequent text argument as a number.
 \\\hline 
  \end{tabular}
$$

\newpage
\section{{\tt DISPLAY-CONTROL}}

These keys affect the display without affecting the contents of the
planes or the tables.
 $$
  \begin{tabular}{|l|p{4.50in}|} \hline
    \icp\keya & \mname{Toggle.display.source} When sharing a single
display, toggles between viewing the \pc\ display and the currently
selected \cam\ display; when \pc\ has its own display, has no effect
without an argument.  In either case, if multiple \cam{}s are sharing
a display, an argument selects the given \cam\ for display. \\\hline
    \icp\keyA & \mname{Show.PC.display} If \cam\ and the \pc\ share a
display, will show the \pc\ display; else has no effect.  With an
argument, shows the \pc\ and selects the given \cam\ as the one to be
seen with \keya. \\\hline 
    \icp\keyx & \mname{Toggle.expanded.view} Toggles between an
expanded view of the central portion of the configuration, and the
normal view.  All keys function in either view. \\\hline 
    \icp\keyX & \mname{Normal.size} Show normal-sized view of
configuration.  \\\hline 
    \icp\keyrtquote & \mname{Toggle.grid} Turn grid on if its off, off
if its on.  Grid is only visible in the expanded view. \\\hline 
    \icp\keyquote & \mname{Grid.off} Turn the grid off. \\\hline 
    \icp\keyfn2 & \mname{IRGB.map} Select the IRGB color map. \\\hline 
    \icp\keyFn2 & \mname{Std.map}  Select the STD color map. \\\hline 
    \icp\keyfn4 & \mname{Toggle.inten} Toggle the visibility of the
intensity ``beam'' of the display. \\\hline 
    \icp\keyFn4 & \mname{Inten.on} Turn intensity back on if it is
toggled off. \\\hline 
    \icp\keyfn6 & \mname{Toggle.red} Toggle visibility of red beam. \\\hline 
    \icp\keyFn6 & \mname{Red.on} Turn red beam back on if its off. \\\hline 
    \icp\keyfn8 & \mname{Toggle.green}  Toggle visibility of green
beam.  \\\hline 
    \icp\keyFn8 & \mname{Green.on} Turn green beam back on if its off. \\\hline 
    \icp\keyfn{10} & \mname{Toggle.blue}  Toggle visibility of blue beam.
\\\hline 
    \icp\keyFn{10} & \mname{Blue.on}  Turn blue back on if its off. \\\hline 
   \end{tabular}
 $$

\newpage
\section{{\tt EDITING,RUNNING}}

These keys control the editing, loading, and running of \cam\
experiments. 
 $$
  \begin{tabular}{|l|p{4.50in}|} \hline
      \icp\keye & \mname{Edit.screen} Continue editing the most recently
edited screen.  With an argument, will edit the indicated screen of
the current file. \\\hline 
    \icp\keyE & \mname{Edit.new.file:} Takes a text argument of a new
file to edit.  If you just hit return, or if the name you give has any
wild-card characters, gives a directory listing and asks again for a
filename. Default extension is {\tt .EXP}.  If you give a filename
that doesn't exist, will offer to create the file.  With a numeric
argument, editing starts at the indicated screen; otherwise it starts
at screen number 1. \\\hline
    \icp\keyl & \mname{Load} Load the current file.  With an argument,
will load just the indicated screen of the current file. \\\hline 
    \icp\keyL & \mname{Load.new.file:} Like \prog{E}, except that the
indicated file is loaded, and it won't offer to create any files.
With an argument, will just load the indicated screen. \\\hline 
    \icp\keytab & \mname{Tab.-->.file:}  Save the selected \cam's
lookup tables to a file. Like \keyE, it can provide a directory
listing. \\\hline 
    \icp\keybacktab & \mname{Tab.<--.file:} Load the selected \cam's
lookup tables from a file. Can provide a directory listing. \\\hline 
    \icp\keys & \mname{Step(s)} Run one step.  With an argument, runs
the indicated number of steps.  If the argument is zero, starts to run
$2^{32}$ steps, counting as it goes. \\\hline 
    \icp\keyS & \mname{Continue.steps...} Resume running steps;
continue count where you left off. \\\hline 
    \icp\keycomma & \mname{Slower} Run more slowly. \\\hline 
    \icp\keyless & \mname{Slowest!} Run about one step a second. \\\hline 
    \icp\keyperiod & \mname{Faster} Run faster. \\\hline 
    \icp\keygreater & \mname{Fastest!} Run 60 steps a second. \\\hline 
    \icp\keyspace & \mname{Stop running} Stop running, and print the
current step number. \\\hline 
  \end{tabular}
 $$
\newpage
\section{{\tt PLANE-OPS}}

Operations on \cam's bit-planes, or between memory buffers and
bit-planes.  Note that when the cage is active, all operations apply
only to the cage region, treating it as if it were the screen, and
treating the bit-plane area masked by the cage as if it were the buffer.  All
operations whose name involves the term `plane(s)' take an optional plane
argument: no argument means operate on all four planes; 0, 1, 2, or 3
indicate a single plane to operate on, and 4 or 5 indicate both planes
of either \cama\ or \camb\ respectively.  All logical operations
involving data from both a buffer and a bit-plane leave their results in
the bit-plane.
 $$
  \begin{tabular}{|l|p{4.50in}|} \hline
    \icp\keyc & \mname{Toggle.cage} Toggle visibility of the cage.
With an argument, creates a new (empty) cage of the given size: first decimal
digit in argument is width, second is height, both in units of eight.
If only one digit is given, it is used for both height and width. \\\hline 
    \icp\keyC & \mname{Cage.off} Hide the cage. \\\hline 
    \icp\keyz & \mname{Zero.plane(s)} Clear plane(s) to all zeros. \\\hline 
    \icp\keyZ & \mname{Fill.plane(s)} Fill plane(s) with all ones. \\\hline 
    \icp\keyr & \mname{CW.plane(s)} Rotate plane(s) clockwise
$90^\circ$. \\\hline
    \icp\keyR & \mname{CCW.plane(s)} Rotate plane(s) counter clockwise
$90^\circ$. \\\hline
    \icp\keybackslash & \mname{{\char"5C}-flip plane(s)} Flip plane(s)
across the {\tt\char"5C} diagonal. \\\hline 
    \icp\keyslash & \mname{/-flip.plane(s)} Flip plane(s) across the
{\tt /} diagonal. \\\hline
    \icp\keyunder & \mname{T/B-flip.plane(s)} Flip plane(s) from
top to bottom. \\\hline
    \icp\keybar & \mname{S/S-flip.plane(s)}Flip plane(s) from side to
side. \\\hline
    \icp\keyplus & \mname{OR.plane(s)} Bit by bit logical OR of bit
plane(s) with corresponding buffers. \\\hline 
    \icp\keyampersand & \mname{AND.plane(s)} Logical AND of bit
plane(s) with corresponding buffers. \\\hline 
    \icp\keydollar & \mname{XOR.plane(s)} Logical XOR of bit plane(s)
with corresponding buffers. \\\hline 
    \icp\keyminus & \mname{NOT.plane(s)} Logical NOT of bit plane(s). \\\hline 
  \end{tabular}
 $$

 $$
  \begin{tabular}{|l|p{4.50in}|} \hline
    \icp\keyg & \mname{Get.image.from.buffer} Get bit plane(s) from
buffer. \\\hline
    \icp\keyG & \mname{Get.image.from.the.file:} Get an image for the
entire screen (not just the cage or any other active region) from a
file. \\\hline
    \icp\keyp & \mname{Put.image.into.buffer} Put bit plane(s) into
corresponding buffers. \\\hline 
    \icp\keyP & \mname{Put.image.into.the.file:} Put the image
contained on the entire screen (not just the cage or any other active
region) and store it into a file. \\\hline 
    \icp\keyasterisk & \mname{Exchange.display.and.buffer} Exchange
plane(s) with plane buffers. \\\hline 
    \icp\keypercent & \mname{Percent.of.ones} Set the percent of ones
to be used by \keysemicolon. \\\hline 
    \icp\keysemicolon & \mname{Random.configuration} Generate a random
configuration on the indicated bit plane(s). \\\hline 
    \icp\keycolon & \mname{Number.of.ones} Set the expected number of
ones to be used by \keysemicolon. \\\hline 
    \icp\keyi\ \icp\keyI & \mname{Init.random.number.generator} Initialize the
software random number generator to a standard state. With an argument, uses it
as part of its seed.\\\hline 
    \icp\keyhat & \mname{Permute/copy.planes} Permute or copy the
contents of the indicated planes.  A four-digit argument indicates the
data source (i.e., which plane) for each of the four planes---in the order
0, 1, 2, 3. With no argument, re-uses most recent argument.\\\hline 
  \end{tabular}
 $$

\section{{\tt DOTS,SHIFTS}}

Keys used for dot editing (editing individual bits of \cam\ cell
values).  When the dot-cursor is visible, the arrows (and the mouse,
if you have one) move the dot cursor rather than the bit-planes.
Note that the four corner keys of the numeric keypad are used as
additional diagonal-arrow keys by the \cp.  On the mouse, the left
button is used for drawing horizontal and vertical lines, the right
button for diagonal lines, the middle button for unconstrained
placement of dots.  If the \keyins\ key is held down while the cursor
is moved (with the arrows or the mouse) dots will be toggled as the
cursor goes by.  On some keyboards the auto-repeat function on some
keys doesn't work while the insert key is down: any of the shift-lock
keys (including \keycapslock) can be used within the \cp\ instead of
\keyins\ for this purpose.
 $$
  \begin{tabular}{|l|p{4.50in}|} \hline
    \icp\keyd & \mname{Toggle.dots} Toggle dot cursor on or off. With
an argument, turns dot cursor on on the indicated bit-plane, otherwise
the bit plane in use doesn't change. \\\hline 
    \icp\keyD & \mname{Dots.off} Turn dot cursor off. \\\hline 
    \icp\keyh & \mname{Hold.fixed} Hold the specified plane(s) fixed
during shifts using the arrow keys. \\\hline 
    \icp\keyH & \mname{Un-hold} Free the specified plane(s) to shift.
\\\hline
    \icp\keyo & \mname{Cursor.to.origin} Move the dot-cursor to the
center of the screen. \\\hline 
    \icp\keyO & \mname{Shift.to.origin} Shift all planes until the
dot cursor is at the center of the screen. \\\hline 
    \icp\keyup & \mname{Up}  Shift un-held bit planes upward: use
auto-repeat of keyboard for continuous shift.  With an argument, shift
by the indicated amount until the default argument is again changed by
giving an explicit argument.  When an argument has been given, all
subsequent shifts are a multiple of the given value;
the inital default is multiples of 8.\\\hline 
    \icp\keydown & \mname{Down} Similar to \keyup, but shift down. \\\hline 
    \icp\keyleft & \mname{Left} Similar to \keyup, but shift left. \\\hline 
    \icp\keyright & \mname{Right} Similar to \keyup, but shift right. \\\hline 
    \icp\keyhome & \mname{UpLt} Similar to \keyup, but shift
diagonally up and to the left. \\\hline 
    \icp\keypgup & \mname{UpRt} Similar to \keyup, but shift
diagonally up and to the right. \\\hline 
    \icp\keyend & \mname{DnLt} Similar to \keyup, but shift diagonally
down and to the left. \\\hline 
    \icp\keypgdn & \mname{DnRt} Similar to \keyup, but shift
diagonally down and to the right. \\\hline 
    \icp\keyins & \mname{Insert.dot} Inserts a dot at the cursor
position, and on the cursor bit-plane, even if the cursor isn't
visible. \\\hline
  \end{tabular}
 $$

\section{{\tt ALTERNATE}}

The {\tt Alt-} keys are reserved for application-specific, user-defined
commands (custom \cxp\ commands).  When the word \iprog{ALIAS} is used
to attach a key to a Forth word in an experiment, the name of the key
should be written in upper case.  (For example, {\tt ALIAS F2} would
attach a Forth word to the key \altfn2).