Carousel/CAROUSEL.cdr/mactosh/appl/microema.sit/Mouser

Text File | 1989-04-28 | 20KB | 464 lines

             Mousing in MicroEmacs
        Topics of Interest to the Macintosh User
                Earle R. Horton
              Wednesday, October 26, 1988

     This version of MicroEmacs for the Macintosh incorporates several
enhancements to make life easier for the typical Macintosh user.  Most
important is that the mouse is supported to a much greater extent than
in previous versions.  This document is meant for both the experienced
MicroEmacs user and the novice, but those new to emacs editors are
encouraged to read the emacs tutorial (emacs.tut) first.  Those who are
already familiar with emacs in one form or another are welcome to forge
ahead.

# General.

     The Mac version of MicroEmacs incorporates many Macintosh-specific
features.  For this reason, and because Dan Lawrence seems to seldom
answer computer mail, it is usually a revision level or two behind the
version that Dan puts out.  The present sources I have can be compiled
with either LightSpeed C 2.15, Aztec C 3.6c, or MPW C 2.0.2.

# Windows.

     MicroEmacs uses only one proper Macintosh "window" as a terminal
emulator for the emacs editor.  Several rows of text in this window can
be separated into distinct areas, known also as "windows" in the emacs
tutorial.  For purposes of this document, a window is the area between
one mode line and the next, and not the terminal emulator window within
which editing is done.

# Mousing.

     Several things can be done with the mouse, and many are analogous
to functions which can be performed with a "regular" Macintosh text
editor or word processor.

## Standard mousing.

     The action of the scroll bar in MicroEmacs is fairly normal, except
that the insertion point is always kept visible.  Pressing the close box
in the title bar causes MicroEmacs to quit, but it will ask for
confirmation if modified buffers exist.  Typing 'y' at this point goes
ahead anyway, while 'n' backs out.  The zoom box and drag region of the
title bar work normally.  Note that it is possible to drag the terminal
emulator window such that the message line is not visible.  This is not
recommended, since important messages may be missed.

## Mousing in mode lines.

     Several things can happen when the mouse is pressed in a mode line.
If one double-clicks in the mode line, the "next" buffer is displayed in
the associated window.  This is the same as first typing ^X-O the
required number of times to make the window active, then typing ^X-X.
It works much faster, of course.

     Mode lines may be dragged, either with single or double clicks.
Double-click-drag switches to the next buffer first.  A drag then moves
the mode line to follow the mouse, resizing the window.  A window can be
deleted by dragging its mode line upwards until it contains zero lines.
A window cannot, however, be deleted by making the window above it
larger.  When there is only window and the user attempts to drag the
bottom mode line, then the one window is split.  Dragging the bottom
mode line when there are multiple windows has the same effect as
dragging one of the other mode lines, but it looks quite different.
Since the bottom mode line is always one line above the bottom of the
terminal emulator, drags on this line cause the mode line above to move.
The result is the same, however:  Dragging up makes the window smaller;
dragging down makes it bigger.

## Entering commands with the aid of the mouse.

     Pressing the mouse in the message line moves the cursor into the
message line, a ':' prompt appears, and the user may type a named
command.  This is the same as typing M-X.  If you didn't mean to type a
command, click in some other area to get out of the message line.

## Mousing in text.

     A key difference in the user interface between MicroEmacs and other
Macintosh software is that there is no concept of a "selection range."
There is a similar entity known as the "region," discussed in the
tutorial, but it behaves differently from the standard selection range.
Once the user has set the mark, a region always exists in a window.
Keys for modifying text, such as the delete key and characters which are
inserted into the buffer, do not erase the region, but merely change it.
Cut and Copy work on the contents of the region in the standard way, but
Paste does not overwrite the region, rather inserting the 'TEXT'
contents of the clipboard after point.  For these reasons (and for
performance, I admit it) the region is not highlighted.

### Simple cursor moves.

     Pressing the mouse in the text region of a window makes that window
the active window, and moves point to where the mouse was pressed.

     Double-clicking moves point to the mouse cursor, then swaps the mark
and the point.  This is equivalent to moving the text cursor over the
character where the mouse cursor is, then typing ^X-X.  This can be
convenient for defining a region which is larger than one screenful.

### Dragging and stuff.

     Pressing the mouse in the text, then dragging, causes the mark to
be set to the first character clicked on, and point to wind up at the
character where the mouse was released.  You can drag beyond the bounds
of the present window, and new text is scrolled into view.  Horizontal
scrolling is not supported.

     Shift-clicking moves the point but never the mark.

# Menus.

     MicroEmacs has eight menus.  The PopUp menu is gone.  Sorry if you
liked it.

     The Apple menu is for the credits, and for opening Desk Accessories.
The credits contain names of people who are known by me to have worked
on MicroEmacs, or whose names I have found in the source.  If I have
missed anyone, I am sorry.

     The Edit menu is primarilly for use by Desk Accessories, but also
for Cut, Copy, and Paste, which are Macintosh MicroEmacs commands.  Note
that Cut is a lot like kill-region, Copy is like copy-region, and Paste
is like yank.  Cut-Copy-Paste uses the clipboard, however, while kill,
kill-region, and yank use MicroEmacs' own internal kill buffer.  This
gives you two places to stash stuff.

     The Buffers menu is used to switch between buffers.  Its contents
change dynamically as buffers are added and deleted.  A modified
buffer's name appears in italics.  To make a buffer current in the
active window, select its name from the Buffers menu.

     The other five menus are named File, Search, Modes, User, and Help.
The contents of a menu item in these five menus can be any valid
MicroEmacs named command or command line.  These can be changed to
whichever commands you like using a resource editor or compiler.
Consider customizing the menus for frequently used commands.

# Keyboard.

     Most of this section is for programmer types, but towards the end
is some stuff of general use.

     Keyboard events are interpreted by a stand alone code resource of
type 'GetC' and ID 606.  This code resource has its entry point at the
top, and accepts a pointer to an Event Record on the stack.  The Event
Record was returned by GetNextEvent() when the last keyboard event was
detected.  The routine returns a short integer in register D0.  The
return value is the character value of the returned key, ORed with one
of the following flags.

#define CTRL    0x0100        /* Control flag, or'ed in       */
#define META    0x0200        /* Meta flag, or'ed in          */
#define CTLX    0x0400        /* ^X flag, or'ed in            */
#define SPEC    0x0800        /* special key (function key)    */

     Control-A is CTRL OR 'A', or 0x0100 | 'A', or 0x0141.  Similarly,
META-A is 0x0241, and so forth.  The two high bytes of D0 are ignored.
Values less than ASCII space (0x0020) are converted to the internal CTRL
representation by MicroEmacs:  0x0001 => 0x0141 and so forth.

     On entry, the stack looks like this:

    4(a7)    ->    Event Record
    (a7)    -    return address

     To return, pop the return address off the stack, and jump to it.
Alternately, position the stack as it was on entry, and do an RTS.  You
do NOT pop the argument off the stack before returning.  The 'GetC'
resource may trash registers a0, a1, and d1; all others must be
preserved.  Satisfactory 'GetC' resources may be created with most any C
compiler which can create stand alone code, with an assembler, or with
Pascal compilers which know how to implement the C calling conventions.

     When MicroEmacs is first loaded, the 'GetC' resource is loaded into
memory, moved high, locked, and made non-purgeable.  You do not have to
lock it yourself.

     The default code resource included with MicroEmacs converts command
key combinations to control keys, command number combinations to
"function" keys, and knows about some of the special keys on the
standard and extended ADB keyboards.

     On the extended keyboard, the page-up, page-down, and
forward-delete keys have the obvious effect.  The help key is bound to
"describe-bindings," and the home and end keys move to either end of the
buffer.  The Cut-Copy-Paste keys are bound to the functions for which
they are named.

     The default META prefix key is escape, labelled "esc" on the ADB
keyboards.  The key labelled "clear" produces the same key code.  It is
possible to use the backquote key, '`' for this function using the
bind-to-key command.

# Tags.

     This version of MicroEmacs supports ctags, just like vi.  The tag
command first looks for a file named "tags" in the current folder, then
for the file named in the variable $tags, which may be set in the
command line or in your startup file.  How you create the tags file is
up to you, but copies of ctags.c may be found in the comp.sources.unix
archives at j.cc.purdue.edu, in the GNU Emacs distribution sources, and
lots of other places.  Both regular expression tags and line number tags
are supported.

     The named command "tag" prompts for a tag, and then looks for it.
The command "dotag," bound to META-T, treats the next word after the
text cursor as the tag.  Vi uses ^] for this function, but that is a
Macintosh arrow key.

# File access.

     File access is preferably by use of Standard File dialogs.  This
saves the user and MicroEmacs the trouble of knowing pathnames.  Files
may also be accessed by pathname, but only from within macros and
command files.  When opening a file using a partial pathname within a
command file or macro, the default folder is the folder containing the
last-opened file.  For the tags commands, the default folder is the
folder containing the file associated with the current buffer.

     MicroEmacs tries to find out if there is enough room on disk before
writing out a buffer.  Since I generally use a hard disk, I have not
tested this.  It is not a good idea to edit files on almost-full disks,
anyway.  When a file is written out, the volume containing the file is
flushed.  This takes more time, but is much safer, and those who have
written to me wanted it this way.

     MicroEmacs no longer deletes the resource fork of a pre-existing
file when saving over it.  It no longer changes the creator to itself.
New files will have MicroEmacs as the creator, however.  MicroEmacs
ignores any information in the resource fork.

     This version of MicroEmacs now knows that the line terminator
character is 0x0D everywhere.  It will no longer tell you that the
current character is 0x0A when you do a "buffer-position" at the end of
a line.

     Binary files may be edited with MicroEmacs.  If a file is not of
type 'TEXT' it must be read using:

execute-command-line "find-file <whatever>"

     The file type and creator will not be changed if the file is
altered and saved.  Files which are written out are always terminated
with a carriage return, however.  This may confuse the "real owner" of
the file.

     If you need to do anything with binary files, MicroEmacs is
recommended only for occasional or emergency use.  In most cases,
setting "over" mode is recommended.

# Tabs.

     All tabs are real.  The code to emulate tabs with spaces has been
removed.  As a consolation, tab stops may be set globally to any
positive number.  META-<number>-TAB may be used to do this.  The default
tab stop is eight, which may be changed in the emacs.rc file by a line
of the form:

<n>    handle-tab

# Miscellaneous.

     The Macintosh specific function "Insert-date" takes an argument to
determine the format of the string produced.  Valid arguments and
results are shown below:

        Arg.    Result
        ---     ------
          0     10/24/88
          1     Monday, October 24, 1988
          2     Mon, Oct 24, 1988

     Gee, that's today!

     MicroEmacs handles the full Macintosh character set.  That is why
there is no META key.  It also thinks the "enter" key is Control-C,
which is exactly what it returns on the Macintosh!

     Kill-buffer now defaults to the current buffer, and is capable of
killing a buffer which is being displayed.  It will, of course, ask for
confirmation if you attempt to kill a modified buffer.  In fact, you can
kill buffers all day long if you want to, and MicroEmacs will keep
giving you new ones named "main" and "MAIN."

# Command files.

     The startup command file is named "emacs.rc" and may be located in
the system folder, the folder MicroEmacs is in, or in the folder where
documents exist when opening MicroEmacs by double-clicking on a
document.  Other command files may be loaded later using Standard File,
or by name from within a macro or using "execute-command-line."

# The command language.

     Since there is not much said about the command language in the
tutorial, I give a few comments here.  Most of this stuff comes from the
header files where these things are defined.

     An identifier which starts with '$' is taken to be a MicroEmacs
environment variable.  These generally are tied to internal variables
used directly used by the editor code.  Example: $cbufname points to a C
string containing the name of the current buffer.  Another: $tpause sets
the time to pause when doing fence-matching (jumping to matching braces
and back when in C mode).

     Identifiers starting with '%' are names of user variables.  User
variable names may be up to ten characters each, and up to 255 of them
may be defined.

     If it starts with a '&' then it is a user function.  User function
is a misnomer, since these are all executed by C code in a big switch
statement, which does the appropriate operation on the arguments.  Four
kinds of user functions exist:

#define NILNAMIC    0
#define MONAMIC     1
#define DYNAMIC     2
#define TRINAMIC    3

     Their type names indicate how many arguments are expected.  All
take C strings as arguments, and return C strings as results.

     Procedures written in the command language can be executed in a
number of ways.  Forty macros can be defined, in addition to the
keyboard macro.  Named procedures can be stored and run later.  Buffers
may be executed.  Files can be executed.

     All work the same way, by execution of a buffer.  Macros are stored
in buffers named "[Macro nn]" where "nn" is the macro number.
Procedures are stored in buffers named "[proc]" where "proc" is the
procedure name.  Files are executed by first reading them into buffers.
Buffers are executed by the C function dobuf().  This information can be
helpful in debugging macros.  You could peek in the appropriate buffer
if you have trouble with a stored macro, for instance.  By the way, if
"list-buffers" is given an argument, it shows all "hidden" buffers,
including macro buffers.

     The macro language also includes command directives.  The following
comment was extracted from the header to dobuf().

-------------------------------------------------------------------
    Directives start with a "!" and include:

    !endm        End a macro
    !if (cond)    conditional execution
    !else
    !endif
    !return     Return (terminating current macro)
    !goto <label>    Jump to a label in the current macro
    !force        Force macro to continue...even if command fails
    !while (cond)    Execute a loop if the condition is true
    !endwhile

    Line Labels begin with a "*" as the first nonblank char, like:

    *LBL01
-------------------------------------------------------------------

     There is also a "!break" which jumps to the endwhile from within
the while loop.

     Two other tokens exist.

         '@'            /* interactive argument     */

     This writes the text following '@' as a prompt on the message line,
then returns the text typed in.

    '#'            /* buffer argument        */

     This returns the text after point, in the line containing point, in
the buffer named after the '#'.  Point is advanced one line in the
buffer from which the text is extracted.

     The following pre-defined "environment variables" exist in
MicroEmacs.  Some are not real appropriate in the Macintosh environment,
and contain nonsense or nil values.

    "fillcol",        /* current fill column */
    "pagelen",        /* number of lines used by editor */
    "curcol",        /* current column pos of cursor */
    "curline",        /* current line in file */
    "ram",            /* ram in use by malloc */    ( kilobytes )
    "flicker",        /* flicker supression */
    "curwidth",        /* current screen width */
    "cbufname",        /* current buffer name */
    "cfname",        /* current file name */
    "sres",         /* current screen resolution */
    "debug",        /* macro debugging */
    "status",        /* returns the status of the last command */
    "palette",        /* current palette string */
    "asave",        /* # of chars between auto-saves */
    "acount",        /* # of chars until next auto-save */
    "lastkey",        /* last keyboard char struck */
    "curchar",        /* current character under the cursor */
    "discmd",        /* display commands on command line */
    "version",        /* current version number */
    "progname",        /* returns current prog name - "MicroEMACS" */
    "seed",         /* current random number seed */
    "disinp",        /* display command line input characters */
    "wline",        /* # of lines in current window */
    "cwline",        /* current screen line in window */
    "target",        /* target for line moves */
    "search",        /* search pattern */
    "replace",        /* replacement pattern */
    "match",        /* last matched magic pattern */
    "kill",         /* kill buffer (read only) */
    "cmode",        /* mode of current buffer */
    "gmode",        /* global modes */
    "tpause",        /* length to pause for paren matching */
    "pending",        /* type ahead pending flag */
    "lwidth",        /* width of current line */
    "line",         /* text of current line */
    "gflags",        /* global internal emacs flags */
    "rval",         /* child process return value */
    "tags",         /* name of tags file */

     The following functions may be called from macros or procedures:

    "add", DYNAMIC,     /* add two numbers together */
    "sub", DYNAMIC,     /* subtraction */
    "tim", DYNAMIC,     /* multiplication */
    "div", DYNAMIC,     /* division */
    "mod", DYNAMIC,     /* mod */
    "neg", MONAMIC,     /* negate */
    "cat", DYNAMIC,     /* concatinate string */
    "lef", DYNAMIC,     /* left string(string, len) */
    "rig", DYNAMIC,     /* right string(string, pos) */
    "mid", TRINAMIC,    /* mid string(string, pos, len) */
    "not", MONAMIC,     /* logical not */
    "equ", DYNAMIC,     /* logical equality check */
    "les", DYNAMIC,     /* logical less than */
    "gre", DYNAMIC,     /* logical greater than */
    "seq", DYNAMIC,     /* string logical equality check */
    "sle", DYNAMIC,     /* string logical less than */
    "sgr", DYNAMIC,     /* string logical greater than */
    "ind", MONAMIC,     /* evaluate indirect value */
    "and", DYNAMIC,     /* logical and */
    "or",  DYNAMIC,     /* logical or */
    "len", MONAMIC,     /* string length */
    "upp", MONAMIC,     /* uppercase string */
    "low", MONAMIC,     /* lower case string */
    "tru", MONAMIC,     /* Truth of the universe logical test */
    "asc", MONAMIC,     /* char to integer conversion */
    "chr", MONAMIC,     /* integer to char conversion */
    "gtk", NILNAMIC,    /* get 1 charater */
    "rnd", MONAMIC,     /* get a random number */
    "abs", MONAMIC,     /* absolute value of a number */
    "sin", DYNAMIC,     /* find the index of one string in another */
    "env", MONAMIC,     /* retrieve a system environment var */
    "bin", MONAMIC,     /* loopup what function name is bound to a key */
    "exi", MONAMIC,     /* check if a file exists */
    "fin", MONAMIC,     /* look for a file on the path... */
    "ban", DYNAMIC,     /* bitwise and     9-10-87  jwm */
    "bor", DYNAMIC,     /* bitwise or     9-10-87  jwm */
    "bxo", DYNAMIC,     /* bitwise xor     9-10-87  jwm */
    "bno", MONAMIC,     /* bitwise not */
    "xla", TRINAMIC,    /* XLATE character string translation */