\subsection{TextPort keybindings}

The following list shows {\tt TextPort}'s keybindings.  The
modifiers (control, option, and shift) are part of the
{\tt VBT.KeyRec} passed to {\tt TextPort} by Trestle.  The key that
Trestle says is the ``option'' key may actually be labeled as
something else, such as ``Compose Character'' on an LK201
keyboard.

\begin{center}
\begin{tabbing}
option-LongKeyName \= This is just a tab-setting line. \kill
 Return              \> invoke the {\tt returnAction} method \\
 shift-Return        \> call {\tt Newline} \\
 option-Return       \> insert a newline after the cursor \\
 Backspace           \> delete primary selection or the \\
                        \> previous character \\
 option-Backspace    \> swap the two previous characters \\
 control-A           \> delete previous character \\
 control-B           \> delete whole line \\
 control-C           \> delete to start of line \\
 option-C            \> call {\tt EditCmd.Copy} \\
 control-D           \> call {\tt EditCmd.DeleteToStartOfWord} \\
 control-E           \> call {\tt EditCmd.Move} \\
 control-F           \> call {\tt EditCmd.DeleteToEndOfWord} \\
 control-G           \> delete whole word \\
 control-H           \> switch selections \\
 control-I           \> call {\tt EditCmd.ToNextWord} \\
 control-J           \> move to previous character \\
 control-K           \> move to next character \\
 control-L           \> move to first non-blank and select line \\
 control-M           \> find previous occurrence \\
 option-M            \> find previous occurrence of primary \\
 control-N           \> find next occurrence of primary \\
 option-N            \> find first occurrence of primary \\
 control-O           \> move up in column \\
 control-P           \> move down in column \\
 control-Q           \> call {\tt EditCmd.Clear} \\
 control-R           \> call {\tt EditCmd.Swap} \\
 control-S           \> delete next char \\
 control-U           \> call {\tt EditCmd.ToPrevWord} \\
 control-V           \> delete to end of line \\
 option-V            \> call {\tt EditCmd.Paste} \\
 control-W           \> call {\tt EditCmd.Paste} \\
 option-X            \> call {\tt EditCmd.Cut} \\
 control-Y           \> move to opposite end of selection \\
 control-Z           \> undo previous edit \\
 control-shift-Z     \> undo undo (reinstate previous edit) \\
 control-,           \> find next occurrence \\
 control-;           \> move to end of line and select line \\
 control-Space       \> call {\tt Normalize}

\end{tabbing}
\end{center}

\subsection{The selection model}\label{TextPortSelection}

{\tt TextPort} was designed after an editor called Ivy that was
developed at SRC.  Ivy was written in Modula-2 and includes a
wealth of features; {\tt TextPort} implements only a small subset of them.

The best description of the selection model used by {\tt TextPort}
is in documentation for Ivy itself, from which the following
section is adapted.

{\tt TextPort} uses two selections, the primary selection and the secondary
selection.  Briefly, the primary selection is {\it established} by
   clicking the left mouse button; it is {\it extended} by
   dragging the right mouse button. The secondary selection
   is established and extended the same way, but while holding
   down the control key. 

The primary selection is used for almost all editing, and for other
things as well. {\tt TextPort} highlights the primary selection either by
underlining the selected characters with a heavy black line or by
displaying the selected characters in reverse video.

The secondary selection is used by {\tt EditCmd.Copy}, {\tt EditCmd.Paste}, {\tt EditCmd.Move}, and {\tt EditCmd.Swap}. {\tt TextPort} highlights the secondary
selection by underlining the selected characters with a grey line.

When the primary and secondary selections overlap, the text in
common is indicated by an ugly stippled background.
Fortunately, this does not happen very often.

No matter how many {\tt TextPort} windows you have, you can have at
most one primary and one secondary selection at any one time.

The type-in point tells you where {\tt TextPort} is going to insert
characters when you type.  It is always located at one end or
the other of the primary selection.  It is indicated by a blinking
vertical bar.

\subsection{Making a single-unit primary selection}

You use the Left and Middle buttons on your mouse to select a
unit: a point, a word, a line, a paragraph, or the entire file.

To primary-select a point between characters, point the cursor
below or at that point, and click Left.  A blinking vertical bar
(the type-in point) appears at the point you selected.

A word is a maximal non-empty character sequence containing
(1) only letters and digits, or (2) one or more space and tab
characters, or (3) a single character that is not a letter, a digit, a
space, or a tab. E.g., in this sequence:

\begin{quote}
    The cat sat on\\
    /proj/packages.
\end{quote}

the words are:

\begin{quote}
   the initial spaces on the first line \\
   {\tt The} \\
   space \\
   {\tt cat} \\
   space \\
   {\tt sat} \\
   space \\
   {\tt on} \\
   newline \\
   the initial spaces on the second line \\
   "/" \\
   {\tt proj} \\
   "/" \\
   {\tt packages} \\
   {\tt .}
\end{quote}

To primary-select a word, point the cursor at that word and click
Middle. A black underline appears under the word you selected.

You can also select a word more deliberately by holding down
Middle and mousing around; the underline will track the mouse.
When you reach the word you're interested in, release Middle.
The effect is the same as clicking Middle at the final cursor
position.

A line is a non-empty character sequence containing at most one
newline, whose first character immediately follows either
start-of-file or a newline, and whose final character is
either a newline or the character immediately preceding
end-of-file; if the line ends with end-of-file it
contains no newline.  This sounds weird; mostly, a line is what
you think it is---all the characters from immediately after one
newline up to and including the next newline.  If the line
doesn't need to be turned, it looks like a line; if it's turned,
it looks like two or more lines with a grey vertical bar at the
far-right extreme of each line except the last.

To select a line, double-click Left; a black underline appears
under the line you selected.  Just as for points and words, the
underline of the selected line tracks the cursor while Left is
down; so you can make a click-and-a-half and then hold Left down
while you move the cursor to select just the line you are after.

A paragraph is a sequence of lines---either a maximal sequence of
non-blank lines or a maximal sequence of blank lines. (A blank
line contains only spaces, tabs, and at most one newline.)

To select a paragraph, double-click Middle; a black underline
appears under the paragraph you selected.

To select all of the characters in a {\tt TextPort}, triple-click
Left or Middle; a black underline appears under the entire text.

Fine point:  Unlike points, words, lines, and paragraphs, the
underline showing that you have selected an entire text does not
track the cursor while you hold Left down.  (In typescripts,
for instance, you can triple-Left-click to select one file
and then drag to another; the first file is still selected.)

\subsection{Using the mouse to adjust a selection}

You use the cursor and the Right mouse button to lengthen
or shorten a selection.  You can make these adjustments at any
time---immediately after you've made the initial selection or
at any time thereafter---and you can make as many adjustments
as you like.

Once you've chosen a unit with the Left or Middle button, the
Right button uses that same unit for adjusting the selection. So
for instance if you made your selection by double-clicking Middle,
which gives you a paragraph, then Right adjusts the selection by
increments of paragraphs. If you made your selection by clicking
Left, which gives a point, then Right adjusts the selection in
increments of one character.

To extend a primary selection, point to where you want the
selection to end and click Right.

The highlight for an adjusted primary selection depends on
whether the text containing the selection is read-only or
editable.  In read-only text, the highlight is the usual black
underline.  In editable text, an adjusted primary selection is
called a {\em replace selection} (short for
``replace-mode\index{ReplaceMode} primary selection'') and
highlighted with reverse video.  As you can guess from the word
``replace'' and from the garishness of the reverse-video
highlight, replace selections have interesting properties.

Often you will click to adjust a selection, but you can also
adjust a selection more deliberately by pressing Right, adjusting
the cursor position until the correct selection is highlighted,
and then releasing Right.  In dragging, you may notice that {\tt TextPort}'s
adjustment behavior varies subtly according to whether you press
Right before, inside, or after the old selection.

You can adjust either end of the selection, but not both ends with
the same Right click or Right drag. Most users find it natural to
adjust the selection by extending it toward the end of the buffer,
and the adjustment mechanism is biased toward that case.

It is perfectly OK to adjust a selection more than once.

\subsection{Changing the selection unit}

(Special section only for the nimble-fingered:)

Occasionally you want to start a selection in one unit, but adjust
it in another. {\tt TextPort} allows you to decrease the selection unit while
you are holding down on the Right button by ``tapping'' Right
(making a quick up-down button movement). Each tap decreases
the selection unit size: file goes to paragraph, paragraph to
line, line to word, and word to point.

Suppose, for instance, that you want to select a paragraph and
the first sentence of the following paragraph.  You start by
double-clicking Middle somewhere inside the first paragraph.
Then you hold down on Right and tap to reduce the selection unit
from paragraphs to lines; tap again to reduce the selection unit
from lines to words.  Now move the cursor to the end of the
sentence at the top of the second paragraph and click Right.
Tapping is something you resort to when you haven't planned
ahead, especially in dealing with selections that are too big
to fit in a single view.

\subsection{Typing at a replace selection}

As you'll recall, if you adjust a primary selection in an
editable {\tt TextPort}, the highlight is reverse video instead of
the usual black underline.  A primary selection in replace
mode---``replace selection'' for short---stands ready for you
to replace it with something else.

The simplest use you can make of a replace selection is to type
at it.  The selection disappears and the new characters appear.
As you type them, the type-in point moves along apace.

\subsection{Type-in point}

The type-in point is that blinking vertical bar that shows
where characters are inserted when you type.  If you have a primary
selection, the type-in point is located at one end or the other
of the primary selection.  If the primary selection is empty
(because, for instance, you've just deleted it), the type-in
point is located by itself in your text, in between characters.

You set the type-in point whenever you make a single-unit
selection using Left or Middle.  It is at the beginning of the
primary selection unless you made the selection by single-clicking
Middle.  In that case it is at the end of the primary selection
closer to where you let the Middle button up.  If you point near
the middle of a nice long word with Middle down and move the
cursor back and forth, you will see the type-in point jump from
one end of the word to the other.  This is called the
``balance-beam'' rule for locating the type-in point.

You can reduce the need for careful pointing by using selection
modes to set the type-in point. Often you want to put your
type-in point at the start of something that is a selection unit;
just point at the unit rather than pointing between characters.
For instance, to place the type-in point at the start of a
paragraph, point anywhere in the paragraph and double-click
Middle. {\tt TextPort} treats words specially because you place the type-in
point at the end of a word just as often as you place it at the
beginning. To place the type-in point at the end of a word, point
near the end of the word and click Middle.

If the type-in point is on the screen and typing (or deleting)
a character would move it offscreen, {\tt TextPort} scrolls in order to
keep it onscreen.  If the type-in point is offscreen, typing
(or deleting) a character makes {\tt TextPort} scroll to put it onscreen.

\subsection{Making secondary selections with the mouse}

Minor selection with the mouse works just like primary selection
except that you hold the Control key down as you're clicking or dragging.

The highlight for secondary selection is a grey underline. A point-sized
secondary selection is a black vertical bar between characters.

Hold the Control key down and use the Left and Middle buttons to
secondary-select the same units as for primary selection:

\begin{center}
\begin{tabbing}
quadruple-click \= AllThree \= This is just a tab-setting line \kill
          click \> Left   \> to select a point between characters\\
   double-click \> Left   \> to select a single line\\
   triple-click \> Left   \> to select an entire file\\
          click \> Middle \> to select a single word\\
   double-click \> Middle \> to select a single paragraph\\
   triple-click \> Middle \> to select an entire file
\end{tabbing}
\end{center}

Just as with the primary selection, you can secondary-select by clicking
or by using a more deliberate dragging motion.

To extend a secondary selection, hold the Control key down, point to where
you want the selection to end, and click Right. (You're probably
holding the Control key down already, since you've probably just
made the secondary selection. But if you want you can adjust either
the primary or the secondary selection at any time.)

\subsection{Using the secondary selection and the type-in point}

To {\em copy} text from one place to another, place the type-in point
where you want the text to go.  Minor-select the text to be
copied.  Then give the Copy command, which is bound to the
keystroke control-W.  Or use the other order:  First
secondary-select, then place the type-in point, then do Copy.  A copy
of the text will appear where the type-in point was, the type-in
point will go down to the end of the copied text, and the copied
text will be primary-selected.  The highlight disappears from the
secondary selection.

{\em Moving} text from one place to another is just like copying it:
Place the type-in point where you want the text to go,
secondary-select the text to be moved and give the Move command,
which is bound to the keystroke control-E.  Or use the other
order:  First secondary-select, then place the type-in point, then
do Move.  The text will appear where the type-in point was, the
type-in point will go down to the end of the moved text, and
the moved text will be primary-selected.

When you use Copy, the highlight disappears from the secondary
selection. But the secondary selection is still defined; only its
highlight is gone. This means that you can use Copy to copy the
same text to different places without re-selecting it.

It may seem strange that the highlight disappears but the
selection is still defined. Most of the time you make a secondary
selection and use it only once. This argues for taking down the
highlight, since it is annoying to have the extra highlight
cluttering up the screen. But sometimes the ability to copy the
same text repeatedly without re-selecting it is very useful. This
argues for leaving the selection defined.

\subsection{Making a secondary selection from the primary selection}

Sometimes the text that you want to copy or move is
primary-selected, rather than secondary-selected, at the time you want
to use it.  So there's a SwitchSelections command, which is bound
to the keystroke control-H.  When you type control-H, the
primary-selection highlight will be replaced by the grey
secondary-selection underline, and the grey secondary-selection underline
will change to the primary selection highlight.

There are several things that you can do to a primary selection
that you can't do to a secondary, so a useful idiom is control-H
do-something-to-the-selection control-H.  For instance, you can't
normalize the secondary; but you can do control-H
control-SpaceBar (Normalize) control-H.

And suppose that your secondary selection highlight has disappeared
because you've used the secondary in a Copy or a Swap.  The way to
get the highlight back is to do control-H control-H.

\subsection{Making a replace selection into a non-replace selection}

If you have a replace selection and want to make it a non-replace
selection, type control-Y.  This moves the cursor from one end
of the primary selection ot the other, and it also takes the
selection out of replace mode.

\subsection{Restoring the primary selection to a window}
\label{RestoringPrimary}

Sometimes you make a primary selection in one window, then shift
your attention to another window and make a primary selection
there.  The first window loses the primary selection, but remembers
where it was.  If you want to return to what you were doing in
that window, just Right-click anywhere inside of it.  This
re-selects the most recent primary selection that was made there.
If this selection is not visible, the window scrolls to make
it visible.

\subsection{``Clipboard'' selections}\label{Clipboard}

In addition to the two-selection model described in the previous
sections, {\tt TextPort} supports a single-selection model with three
basic editing commands:

\begin{center}
\begin{tabbing}

option-C    \= Copy primary selection to Clipboard \\
            \> This calls {\tt EditCmd.Copy} \\
option-X    \> Cut primary selection to Clipboard \\
            \> This calls {\tt EditCmd.Cut} \\ 
option-V    \> Paste Clipboard to primary selection \\
            \> This calls {\tt EditCmd.Paste} \\

\end{tabbing}
\end{center}

The ``Clipboard'' is simply another name for the secondary
selection, {\tt VBT.Source}.  The text-selection used by many
standard X applications such as {\tt xterm} corresponds to
{\tt VBT.Source}, so these commands are convenient for moving text
between X windows and {\tt TextPort}s.

\subsection{``xterm mode''}\label{xterm mode}

If the environment-variable named {\tt VBTSELECTION} is assigned the
value {\tt xterm} when an application using TextPort starts up, then
Textport will use a single-selection model corresponding to the way
xterm(1) works.  (In fact, xterm is programmable, but this implements
the default behavior.)

There is only one selection.  It is the same as VBT.Source, which is the same as
X's primary selection.

A single-left-click establishes the keyboard focus but does not change
(acquire) the selection. A double-left-click selects the current word;
a triple-left-click selects the current line. More clicks rotate among these
three options.

Single-left-click and drag selects a range of characters.
Double-left-click and drag selects a range of words, and
triple-left-click and drag selects a range of lines.

Middle-click pastes the current selection.

Right-click extends the current selection, re-highlighting it if needed.

The shift key has no effect on the mouse in xterm-mode; it is ignored,
so that shift-left-click, for example, has the same effect as
left-click.  The control and option keys, however, are not ignored;
they cause the mouse-clicks to be no-ops; control-left-click, for example,
has no effect.
