Aminet 10/aminetcdnumber101996.iso/Aminet/text/edit/Luminus.lha/Luminus/Docs/Luminus.doc

Text File | 1995-10-23 | 147KB | 3,644 lines

                                   Luminus
                              Version 0.1 (Beta)

                        Written by Paul A. Schifferer

        Copyright © 1995 Gandalf's Middle-Earth Software Wizardry Labs
                             All rights reserved.

Terms

You may copy and distribute verbatim copies of the programs' executable code
and documentation as you receive it, in any medium, provided that you conspic-
uosly and appropriately publish only the original, unmodified programs, with
all copyright notices and disclaimers of warranty intact and including all the
accompanying documentation, example files and anything else that came with the
original.

You may not copy and/or distribute these programs without the accompanying
documentation and other additional files that came with the original.   You
may not copy and/or distribute modified versions of these programs.

You may not disassemble, decompile, re-source or otherwise reverse engineer
the programs.

You may charge a fee to recover distribution costs.  The fee for diskette
distribution may not be more than the cost to obtain a public domain diskette
from Fred Fish.

Disclaimer of Warranty

THERE IS NO WARRANTY FOR THE PROGRAMS, TO THE EXTENT PERMITTED BY APPLICABLE
LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING, THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE PROGRAMS "AS IS" WITHOUT WARRANTY OF ANY KIND,
EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.   THE
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAMS IS WITH YOU.
SHOULD THE PROGRAMS PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
SERVICING, REPAIR OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE PROGRAMS AS
PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
THE PROGRAMS (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE
PROGRAMS TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Introduction

I got to writing Luminus as a request from my wife, who enjoys designing ANSI
pictures and animations, and after using TheDraw on her MS-DOS machine, found
no suitable alternative for the Amiga.  The few programs we ran across were
sorely lacking in features and/or friendly operating interfaces.  As I have
recently learned, there are actually quite a few available, but alas, none
that suit her particular tastes.  And so was born Luminus.

Luminus' features include:

- Operates in any display environment (supports any screen display available
  in the display database).

- Amiga User Interface Style Guide compliant.

- On-line help (requires AmigaGuide).

- Built-in ARexxTM and Workbench App support.

- Supports all ANSI BBS codes.

- Ability to load and save IFF and ASCII files.

System requirements

Luminus requires version 2.04 or higher of the Amiga OS.  It is designed to
take advantage of some features available in higher versions, if they are
available..  As yet, Luminus does not have Locale support.

Luminus also requires a stack size of at least 16,000 bytes.  See the chapter
Using Luminus below on how you may change the stack size from either the Shell
or the Workbench.

Registration

Luminus is technically giftware.  (I hate all the different -ware terms.)  I
don't believe or subscribe to the current shareware philosophy.  If I wanted
(read: demanded) money for my work, I would release it as a commercial
product.  I've written and released this program in this form because I
believe the Amiga is an awesome computer, and I want to lend my support to its
(hopefully) long and glorious life.  I want to make your use of the Amiga
productive, efficient, and most of all enjoyable.  All I want is a 'thank you'
or 'great job'.  (Of course, I don't object to receiving money :) (see below),
but I'm not going to get nasty about it, like some other authors.)

But enough blithering; here's the bottom line:  This program is NOT crippled
in any way, shape or form, thus no fee is required to make it fully
functional.  You have it in all its splendor and glory.  Use it, enjoy it.  If
you like it, send me a postcard, or a program you've written, or something to
say thanks.

If you want to, you can send me $5US, which will get you the next release sent
right to you.  The money's only to cover disk and mailer costs (and a teeny
profit).  Another $5US will get you a nicely typeset, printed manual, done in
FinalWriter.

The address to which you can send me money, postcards, a spare Amiga, or any-
thing else is:

Paul A. Schifferer
515 11th Street
Edwards AFB, CA  93523

I can also be contacted via Internet at:

[e-mail]

Undocumented Features

Some people call these things 'bugs'.  If you happen to notice one of these
little critters, let me know, please!  I've done my best to make sure all the
bugs were discovered and removed, but I can't find them all.  If finances are
favorable, I may send you the next release at my cost.  (See Beta-Testers'
Note below.)

Beta-Testers' Note

This release is in general distribution as a beta version.  If you wish to be
a beta-tester for future versions of this program, or for any other program I
may release, drop me a postcard or e-mail.  I will put you on the list of
beta-testers, for which you will receive test-releases via Snail mail, FidoNet
or the most cost-effective means for me to get the program to you.

Acknowledgements

I'd like to thank the following people:

My wife, Michelle, who gave me the idea for this program, provided construct-
ive critique during its development and pre-release testing and encouragement
to continue when things got frustrating or bleak.  Thanks, hon.  I love you.

The authors of the Amiga ROM Kernel Reference Manual: Libraries.  This was one
of the most useful books I've ever picked up, and taught me a lot about pro-
gramming the Amiga.

Stephen Provencher and Andrew Toth, who provided a lot of insight into pro-
gramming in C, and always had another point of view.

Using Luminus

This chapter will discuss the general usage of Luminus, both from Workbench
and the Shell, what command line options/ToolTypes are available, and Luminus'
general behavior.

Workbench

Luminus requires a stack size of at least 16,000 bytes to run.  You can check
that the icon's stack size is set properly by clicking once on the icon, then
selecting Information from the Workbench's Icon menu.  In the upper left cor-
ner of the Information window is an integer gadget marked "Stack:".  If the
value in this gadget is less than 16,000, click in it, change it to 16000,
press Return, and click the button marked Save.  Now you may run Luminus.

To start Luminus from the Workbench environment, simply double-click on its
icon.  Luminus' behavior can be modified by using ToolTypes.  The following
ToolTypes are supported:

SETTINGS=file      Lets you specify a particular settings file to use.  You
                   can supply the complete pathname here, or Luminus will use
                   its current directory to find the file.  If this file can-
                   not be found or loaded, Luminus will resort to its stored
                   internal defaults.  The default file is Luminus.prefs.

NOTE:  Any of the following ToolTypes will override the corresponding default
loaded from the settings file.

CUSTOMSCREEN=name  This ToolType will signal Luminus to open on a custom
                   screen (the default behavior).  You must provide a screen
                   name when using this ToolType.  The custom screen opened
                   will be a public screen, for use by other programs and
                   identified by the name given.  The default name is LUMINUS.

NOSHANGHAI         Specifying this ToolType tells Luminus not to set the
                   global public screen SHANGHAI flag.  The default behavior
                   is to set it, which causes the current default public
                   screen to try to make windows open on its screen.  This
                   ToolType is ignored if Luminus is not opened on a custom
                   screen.

NOPOPPUB           Specifying this ToolType tells Luminus not to set the
                   global public screen POPPUBSCREEN flag.  The default
                   behavior is to set it, which causes the current default
                   public screen to pop to the front of the display when a
                   window is opened on it.  This ToolType is ignored if
                   Luminus is not opened on a custom screen.

PUBSCREEN=name     Use this ToolType when you want to open Luminus on another
                   program's existing public screen.  The name you supply is
                   the name of the screen on which to open.  This ToolType may
                   be specified in a project icon, and will be effective only
                   for that document.

PORTNAME=name      Lets you specify an alternate basename for Luminus' ARexx
                   port. Each document that you open in this invocation of
                   Luminus will use this basename plus a numeric suffix, i.e.,
                   the first document opened will be called 'LUMINUS.0'.  The
                   default name is 'LUMINUS'.  This ToolType, if specified in
                   a project icon, will completely override the naming conven-
                   tion, and will be effective only for that document.

UNIT=number        This will specify the default Clipboard unit to use for
                   cut, copy and paste operations.  All documents opened will
                   use this unit.  The default unit is 0.  This ToolType may
                   be specified in a project icon, and will be effective only
                   for that document.

IOBUFFER=size      This ToolType sets the size (in Kilobytes) of Luminus'
                   internal input/output buffer.  This buffer speeds access to
                   and from disk.  Setting this to 0 will disable the buffer.
                   The default size is 16.

STARTUP=script     Specifying this ToolType tells Luminus to attempt to start
                   execution of the specified ARexx script following its
                   initialization.  By default, no script will be started.

The Shell

Before you start Luminus, you must make sure your Shell's stack size is at
least 16,000 bytes or greater.  You can check this by entering

    stack

at the prompt.  This will tell you the size of your Shell's stack.  If it's
less than 16,000, then enter

    stack 16000.

This will change the stack size so it's large enough for Luminus to run.

To start Luminus from the Shell, simply enter its name at the command line,
and the program will begin execution.  The following options are available
from the Shell:

files              Anything typed on the command line that does not correspond
                   to a supported command line option will be taken to be a
                   file to be loaded.  You may enter as many as you like that
                   will fit into memory.

SETTINGS file      This option allows you to specify the settings file to use
                   for this invocation of Luminus.  You may enter a complete
                   path specification with the filename.

CUSTOMSCREEN name  Lets you set the name of the custom screen which Luminus is
                   to open.  When using this option, you must specify a name
                   for the screen.

PUBSCREEN name     Use this option when you want to open Luminus on another
                   program's existing public screen.  The name you supply is
                   the name of the screen on which to open.

PORTNAME name      Lets you specify an alternate basename for Luminus' ARexx
                   port. Each document that you open in this invocation of
                   Luminus will use this basename plus a numeric suffix, i.e.,
                   the first document opened will be called 'LUMINUS.0'.  The
                   default name is 'LUMINUS'.

STARTUP script     Specifying this option tells Luminus to attempt to start
                   execution of the specified ARexx script following its
                   initialization.  By default, no script will be started.

NOPOPPUB           Specifying this option tells Luminus not to set the global
                   public screen POPPUBSCREEN flag.  The default behavior is
                   to set it, which causes the current default public screen
                   to pop to the front of the display when a window is opened
                   on it.  This option is ignored if Luminus is not opened on
                   a custom screen.

NOSHANGHAI         Specifying this option tells Luminus not to set the global
                   public screen SHANGHAI flag.  The default behavior is to
                   set it, which causes the current default public screen to
                   try to make windows open on its screen.  This option is
                   ignored if Luminus is not opened on a custom screen.

UNIT number        This will specify the default Clipboard unit to use for
                   cut, copy and paste operations.  All documents opened will
                   use this unit.  The default unit is 0.

IOBUFFER size      This option sets the size (in Kilobytes) of Luminus' inter-
                   nal input/output buffer.  This buffer speeds access to and
                   from disk.  Setting this to 0 will disable the buffer.  The
                   default size is 16.

NOGUI              Specify this option if you want Luminus to start without
                   opening up its interface, i.e., no screens or windows.
                   This option is useful if you are running an ARexx script
                   that starts Luminus, modifies one or more documents, and
                   exits without user intervention.

QUIET              Using this option tells Luminus not to present its initial
                   copyright banner.  This option would most likely be used in
                   conjunction with NOGUI.

Operations

This chapter deals with various aspects of Luminus, like its modes of oper-
ation, basic editing information and general behavior of the software.

Editing Modes

Currently, there are two editing modes available in Luminus.  The modes are
fairly versatile, and allow switching between them "on-the-fly."  Their
attributes and details are discussed below.

Page Mode

Page Mode is an editing mode that is used for editing static ANSI images of
one or more pages.  Subsequent pages in the document are generally images in
a later stage, much like a flipped-page cartoon is made up of a series of
static images that when moved through rapidly simulate animation.  This allows
page mode to have a crude, page-sized animation.

Cels edited on the page are directly overwritten, replacing the old cel on
that page.

You can have as many pages as can fit in memory in your documents.

When Page mode documents are saved, the cels are saved in displayed-order.

Animation Mode

Animation Mode is an editing mode that allows you to create fine-tuned anim-
ations using ANSI escape sequences for cursor positioning and screen control.

When you type characters in, or insert cels, everything is saved in the se-
quence in which it is entered.

There are no pages in this mode.  Overwritten cels are not replaced in the
document, but are remembered and simply hidden behind the newer cels.  A way
exists to edit existing cels, though, so if you do make a mistake, it is
possible to correct it without having to waste additional cels to "hide" it.

Drawing Modes

While Editing Modes affect the way cels are stored in the document and later
saved to disk files, Drawing Modes affect how they are created and placed into
the document.  There are two Drawing Modes available at this time.  (I have
two more under development right now.)  These are discussed below.

Text Mode

This mode is pretty much the "standard" drawing mode.  Typed text is placed
into the document (according to the Editing Mode), and cursor movements are
simply that.  You can change the colors and text attributes and all that
during your editing.

Attribute Mode

This mode acts basically the same as Text Drawing Mode as far as typing in
text is concerned.  Where this one differs is in the way cursor movement is
handled.  The cursor keys still move the cursor around the same as normal,
except that the cel at the destination position of the cursor is changed.  A
set of Attribute Mode Flags are available that determine how the cel is
changed.  Currently, there are three flags:

     Change foreground? - this flag, if set, means that the foreground color
          of the affected cel is changed to the current foreground color.

     Change background? - this flag, if set, means that the background color
          of the affected cel is changed to the current background color.

     Change attributes? - this flag, if set, means that the text attributes of
          the affected cel are changed to the current text attributes.

If in Animation Editing Mode, the cel isn't actually changed, but a copy is
made with the new colors and/or attributes and placed in that position.

Line Types

Luminus supports the use of several line types that assume an IBM-style font
is being used.  The line types are known as Single, Double, Single-Double
and Double-Single.  (Pretty descriptive, eh?)  The Single line type is a col-
lection of line pieces that are single width lines both horizontally and
vertically.  The Double line type is the same except that the line pieces are
double parallel lines.  The Single-Double and Double-Single line types use
combined single and double-parallel lines.  The first part of the their name
is the type of vertical line, the second part is the type of horizontal line.

Two additional line types are available that can be used with just about any
font.  They are Custom and Select.  The Custom line pieces are defined in the
Box & Line Settings panel.  This allows you to define the pieces used in all
parts of line drawing.  (See the Box & Line Settings panel for more infor-
mation on defining custom line pieces.)  The Select line type is a single
character that is used to draw all parts of a line, whether horizontal,
vertical, intersecting or whatever.  Generally, when the line should be drawn,
a requester is presented asking for the character to use for the line.  There
are some exceptions to this, such as ARexx commands for line or box drawing.

Cursor Directioning

This is an interesting little feature, I think.  Most text editors and word
processors (or just about any kind of editor) process input text from left to
right (or right to left, if the font is designed that way).  But since Luminus
is basically a ANSI text-based drawing program, it can come in handy to have
the cursor move in other directions during a drawing function or whatever.

So Luminus supports flexible cursor directions.  You can specify (separately)
the desired vertical and horizontal directions of the cursor.  The available
directions for movement are:

     Vertical dir.       Result
     ----------------------------------------------------------------------
     None                The cursor doesn't move vertically.

     Up                  The cursor moves upwards one character position.

     Down                The cursor moves downwards one character position.

     Horizontal dir.     Result
     -------------------------------------------------------------------------
     None                The cursor doesn't move horizontally.

     Left                The cursor move to the left one character position.

     Right               The cursor moves to the right one character position.

Vertical and horizontal directions can be combined to make angled cursor move-
ment.  And it's actually even possible to specify both as None and have the
cursor not move at all!

AppIcon, AppMenuItem & AppWindows

Luminus supports all three of Workbench library's App features.  Each
feature's implementation in Luminus will be discussed here.

AppIcon

By default, Luminus will display an AppIcon on the Workbench window upon
start-up.  This behavior can be changed via menu item or through the
Operations Settings panel and saved in the settings file.  Luminus' AppIcon
has two behaviors.

Should you double-click on it, Luminus' screen will be brought to the front,
and the current document's window will be brought to the front and activated.

You may also drop icons onto the AppIcon.  Luminus will attempt to open a new
document for each icon and load it.  These are usually icons for documents,
but Luminus will take anything and try to make sense of it.

AppMenuItem

This App feature places an item on the Tools menu in the Workbench's menu
structure.  Selecting this menu item will cause Luminus' screen to pop to the
front, and the current document's window to be brought to the front and acti-
vated.

AppWindow

Each document that Luminus opens up, it will attempt to attach an AppWindow.
The AppWindow enables you to drop icons into the document's window (only while
it is opened on the Workbench screen), which will tell Luminus to overlay the
files to the document.  Note that if multiple icons are dropped in one window,
Luminus will attempt to overlay all of them onto the document on which they
were dropped.

General Editing

This section covers the miscellaneous editing commands and keystrokes, such as
cursor keys with qualifiers, the Help key and the numeric keypad.

The numeric keypad

Just about all the programs I've used on the Amiga, if they've made use of the
numeric keypad, have used it in one mode only.  (The only exception to this
has been WordPerfectTM for the Amiga.)  It's either used just for numbers
(its default behavior), or for cursor movement (like SAS/C's editor), but
never for both.  Luminus doesn't suffer from this oversight.  The status line
of each document my reflect the current state of the numeric keypad.  If it is
in "number mode", 'Num' shows in the status line.  If it's in "cursor mode",
nothing shows.  You can switch between these modes by pressing they NumL key
(marked on the front of the '(' key on the numeric keypad) in combination with
either Shift key.

Number mode
In this mode, the keys act as they are labelled on the top, i.e., numbers, the
symbols '(', ')', '/', '*', '-', '+', '.', and the Enter key.

Cursor mode
In this mode, the keys act as key are labelled on their fronts, while the
Enter key works as in "number mode."  See the section below, Cursor keys, for
information on the behavior of the cursor keys.  The key marked 'Ins' (keypad
0) toggles Insert mode on and off.  The key marked 'Del' (keypad .) acts like
the Delete key (next to Help).  The '+' and '-' keys act normally.  The keys
marked '5', 'NumL' (execpt when Shifted), 'ScrL', and 'PrtSc' do nothing.

Help key

The Help key is active in Luminus.  Pressing it tells Luminus to execute the
AmigaGuide on-line help system.  Luminus' help system is context-sensitive, so
pressing the Help key within a subwindow will bring up the help file at the
appropriate place.

There is one exception:  pressing the Help key in the menu gives a brief
description of that menu item.

Cursor keys

The arrow keys (and their counterparts on the numeric keypad, when not
NumLocked), when unqualified, do normal cursor movement, i.e., left, right,
up, down.  When Shifted, the keys still behave as normal, but will extend an
existing block in the appropriate direction.  Following is a chart on the
behavior of the keys with and without qualifiers.

     Keystroke                What it does
     -------------------------------------------------------------------------
     Up arrow                 Moves up one line
     Down arrow               Moves down one line
     Left arrow               Moves left one column
     Right arrow              Moves right one column
     Home                     Move to the beginning of the line
     End                      Move to the end of the line
     PgUp                     Move up one windowful
     PgDn                     Move down one windowful
     Control + Up arrow       Moves to the top of the document
     Control + Down arrow     Moves to the bottom of the document
     Control + Left arrow     Move to the absolute beginning of line
     Control + Right arrow    Move to the absolute end of the line
     Control + Home           Move to the top-left corner of the document
     Control + End            Move to the bottom-right corner of the document
     Control + PgUp           Move to the top line of the document
     Control + PgDn           Move to the bottom line of the document
     Alt + Up arrow           Delete the current line, move all lower lines up
     Alt + Down arrow         Insert a blank line
     Alt + Left arrow         Delete the current column, move all right
                                   columns over
     Alt + Right arrow        Insert a blank column
     Alt + Home               Move to the top of the window
     Alt + End                Move to the bottom of the window
     Alt + PgUp               Move up one windowful, cursor doesn't move
     Alt + PgDn               Move down one windowful, cursor doesn't move

Error Codes

Standard AmigaDOS defines a set of general error codes that are normally
returned from a called task or process that indicate the state under which the
program exited.  The are normally 0 (normal exit, no errors), 5 (warning),
10 (error) and 20 (failure).  Luminus defines a set of specific error codes
that may be reeturned from the program itself to a Shell process, or from
ARexx commands to the ARexx script in the variable rc.

Following is Luminus' error code listing.  Several codes are referred to in
some chapters by a name.  This name is given in parentheses after the error
code's meaning.

NOTE      Luminus defines failure codes beginning at 50.  Code 0 indicates
          everything is okay and codes 1 through 49 are informational codes
          which are used internally; you will never see them.

Code      Meaning
----------------------------------------------------
0         Okay
50        General (undefined) failure
51        Unable to open file
52        Unable to save file
53        IFF error
54        Unable to open clipboard
55        Insufficient memory
56        Unable to lock public screen
59        Unable open window
60        Unable to lock directory
61        Unable to create port
62        Unable to create AppWindow
65        Wrong library version
68        Unable to create icon
69        Not enough screens
70        Unable to switch screens
71        Document in limbo
74        Unable to find cel
75        Invalid screen pointer
77        Invalid box dimensions
79        Invalid margins
80        No text
81        Out of dimension
82        Unable to open screen
83        Unable to open font
84        No such command
85        Invalid parameter (INVALID_PARAMETER)
87        Unable to open document
88        Command not available (COMMAND_NOT_AVAILABLE)
89        Unable to execute command
90        Unable to load settings
91        OPTIONS RESULTS not set in script (OPTIONS_RESULTS_NOT_SET)

Menus

This chapter deals with Luminus' menu structure and operation.

Project Menu

New

Selecting this menu item causes Luminus to open a new document, complete with
its own window.

Holding down either Shift key while selecting this item tells Luminus that you
want to specify the screen on which the new document is opened.  Please refer
to Select Public Screen under Requesters in the Control Panels & Windows
chapter.

Open...

This menu item lets you open up an existing document for editing.  The ASL
file requester is opened for you to select a file or files to open.  Multi-
selection is enabled in the file requester, so you can choose as many files
as you like to open, provided there is enough available memory for them all!

Holding down either Shift key while selecting this item tells Luminus that you
want to specify the screen on which the document(s) is (are) opened.  Please
refer to Select Public Screen under Requesters in the Control Panels & Windows
chapter.

Overlay...

This menu item allows you to choose a file or files to overlay onto the exist-
ing document using the ASL file requester.  Multi-selection is enabled in the
requester, and all files selected will be appended to the current document.

This item is only available in Animation Editing Mode.

Save

This menu item allows you to save the current document to disk.  If there is
no current filename of the filename is "Untitled", you will be prompted for
one via the ASL file requester.  Otherwise, the document is just saved.

Holding down either Shift key will bring up the Save Panel, so you may alter
the save parameters before saving the file.  You can have the Save Panel come
up automatically for every save attempt by enabling the Save Prompt gadget in
the File Settings Panel.

This item is ghosted if no changes have been made since the last save.

Save as...

This menu item allows you to save the current document to disk under a differ-
ent name than its current one.  An ASL file requester is presented for you to
choose the directory and filename.

Holding down either Shift key will bring up the Save Panel, so you may alter
the save parameters before saving the file.  You can have the Save Panel come
up automatically for every save attempt by enabling the Save Prompt gadget in
the File Settings Panel.

Close

Selecting this item causes the current document to close, shutting down its
window and freeing all memory associated with it.  If the document was
modified since its last save, you will prompted for verification to close the
document.

If the last document open is closed, Luminus will shut down as if you had
selected Quit.

About...

This menu item brings up an informational window, giving you the low-down on
Luminus.  It also informs you of the ARexx port name of the current document.

Help...

Selecting this item tells Luminus to activate its on-line-help feature.  In
order for on-line-help to work, the AmigaGuide file (a file of the same name
as the program ending with the extension '.guide') must be in either the same
directory as the program, or the logical directory HELP:.  Pressing the Help
key on the keyboard has the same effect.

Quit

You want to completely shut down Luminus.  This item causes that to happen, no
matter how many documents are open.  Holding either Shift key while selecting
this item will suppress the 'are you sure?' requester.

Luminus will normally inform you if any opened documents have been modified
since their last save, and give you a chance to save them.  Holding either Alt
key will suppress this requester.

Edit Menu

Cut

Cut grabs from the currently blocked area of the document, removing its cels
to the clipboard you have specified for the document.  Luminus will store the
data to the clipboard in IFF format, according to the type you specify, either
FTXT CHRS, which can usually be read by text editors and the console device,
and ANSI CEL, a compact proprietary format that Luminus uses.

The blocked data is removed from the document in the same manner as Erase.

This item is only enabled when a block is selected in the document.

Copy

Copy grabs from the currently blocked area of the document, duplicating its
cels to the clipboard you have specified for the document.  Luminus will store
the data to the clipboard in IFF format, according to the type you specify,
either FTXT CHRS, which can usually be read by text editors and the console
device, and ANSI CEL, a compact proprietary format that Luminus uses.

The blocked data is left in the document and the block is deselected when the
copy is complete.

This item is only enabled when a block is selected in the document.

Paste

Choosing this item will cause Luminus to grab whatever is in the specified
clipboard for the current document (each document may specify a different
clipboard unit number), and paste it at the cursor position.  Luminus under-
stands IFF clips of type FTXT CHRS and ANSI CEL.  No other types are
supported.

Erase

Selecting Erase will removed all blocked cels from the document without
pushing them onto the clipboard.  The rest of the document is left intact (see
Delete below).

This item is only enabled when a block is selected in the document.

Delete

Delete does somewhat the same as Erase, removing all blocked cels from the
document without pushing them onto the clipboard.  The difference is that
anything to the right of the deleted block is moved over to fill in the space
vacated by the removed cels.  Erase simply leaves the area blank, Delete
attempts to fill it in.

This item is only enabled when a block is selected in the document.

Clear

This sub-menu allows you to do global clears in the document.

     Current page
     This sub-item will remove all cels from the current page, rendering it
     blank.  You will be asked to verify your choice.

     This item is ghosted in Animation Editing Mode.

     Document
     This sub-item removes every cel from the entire document.  You must
     verify your choice.

Column

This sub-menu provides you with items for manipulating columns, i.e.,
inserting and deleting.

     Insert
     This sub-item causes Luminus to insert a blank column at the current
     cursor position for the entire height of the document.  All columns to
     the right are moved over.

     Note that any columns that are moved beyond the boundaries of the docu-
     ment are not lost, but may not be saved with the file, and are not
     displayed until they are moved back into the document's boundaries.

     Delete
     This sub-item causes the column at the cursor to be irretrievably removed
     from the document, and all columns to the right are moved over to fill
     its space.

Line

This sub-menu provides you with items for manipulating lines, i.e., inserting
and deleting.

     Insert
     This sub-item causes Luminus to insert a blank line at the current cursor
     position for the entire width of the document.  All lines below are moved
     up.

     Note that any lines that are moved beyond the boundaries of the document
     are not lost, but may not be saved with the file, and are not displayed
     until they are moved back into the document's boundaries.

     Delete
     This sub-item causes the column at the cursor to be irretrievably removed
     from the document, and all columns to the right are moved over to fill
     its space.

Document Menu

Use border?

This is a toggle item that determines if the current document's window will be
drawn with the standard Intuition border (and all appropriate gadgets,
including scroll bars).  When the state of this item is changed, the
document's window is closed and reopened accordingly.

Show status line?

This is another toggle item, which determines whether the document's status
line will be rendered.  If so, it is placed at the top or bottom according to
the Status line at top? option in the Document Settings panel.

Ruler

This sub-menu controls the ruler and its display aspects.

     Display?
     When this item is checked, two lines, one vertical, one horizontal, are
     displayed, intersecting at the current mouse position.  The ruler is
     automatically and temporarily disabled when the mouse pointer is outside
     the boundaries of the drawing area of the active document window.

     Hash marks?
     With this item checked, the ruler is displayed with vertical or horizon-
     tal hash marks along each of its beams, placed at character intervals so
     they would intersect the midpoint of each character row or column.  If
     the ruler Display? item is not checked, this item will be ghosted.

     Numbers?
     With this item checked, the ruler is displayed with position numbers
     drawn at a user-specified interval (which can be set in the Document
     Settings Panel).  Each number is drawn either above or to the left of its
     respective hash mark.  Should the ruler come close to the left or top
     drawing boundaries of the window, numbers may not be displayed that won't
     fit into the display wholly.  If the ruler Display? and Hash marks? items
     are not checked, this item will be ghosted.

Edit mode

This sub-menu's items are the available editing modes in Luminus.  Each mode
is discussed below.  For details on Luminus' editing modes, see the Operations
chapter.

     Page
     This sub-item causes Luminus to revert to Page Editing Mode.  (See Page
     under Editing Modes in the Operations chapter.)  Since an existing anim-
     ation can get severely damaged, i.e., certain portions of the animation
     may be lost, by switching to this mode, your choice is verified before
     any real action is taken.

     Animation
     This sub-item causes Luminus to revert to Animation Editing Mode.  (See
     Page under Editing Modes in the Operations chapter.)  Since switching to
     this mode makes no changes to the document's contents, as switching to
     Page Mode might do, no verification is necessary.

Draw mode

This sub-menu's items are the available drawing modes in Luminus.  Each mode
is discussed below.  For details on Luminus' drawing modes, see the Operations
chapter.

     Text
     This is the normal drawing mode.  Text is rendered normally and cursor
     movements are treated as only that.

     Attribute
     This mode is a unique drawing mode.  Text can entered as in Text Drawing
     Mode, but cursor movements are handled in an entirely different manner.
     Depending on the attribute mode flags set, moving the cursor over cels
     can change their colors or attributes.

Line type

This sub-menu contains the various line types with which Luminus may render
boxes and lines.  Each line type is briefly discusses below.  For details on
the line types, see the Operations chapter.

     Single
     This line type is a single vertical or horizontal line, including corners
     and intersecting pieces.  This type assumes an IBM-style font.

     Double
     This line type is a double vertical or horizontal line, including corners
     and intersecting pieces.  This type assumes an IBM-style font.

     Single-Double
     This line type is rendered using single vertical and double horizontal
     lines.  Corners and intersecting pieces are drawn with respect to these
     types.  This type assumes an IBM-style font.

     Double-Single
     This line type is rendered using double vertical and single horizontal
     lines.  Corners and intersecting pieces are drawn with respect to these
     types.  This type assumes an IBM-style font.

     Custom
     This line type's pieces are rendered according the ASCII codes set up in
     the Box & Line settings panel.  This type assumes no particular font, but
     may be set up according to any font.

     Select
     This line type's pieces are rendered using a single ASCII code, which is
     specified at the time of the line drawing.  This type assumes no part-
     icular font.

Attribute mode flags

This sub-menus contains some toggle-items that control how Attribute Drawing
Mode will affect existing character during cursor movement.  (See the
Attribute Mode under Drawing Modes in the Operations chapter for more infor-
mation.)

     Change foreground?
     If this item is checked, Attribute Drawing Mode will affect the fore-
     ground color of all cels the cursor passes over during cursor movement.

     Change background?
     If this item is checked, Attribute Drawing Mode will affect the back-
     ground color of all cels the cursor passes over during cursor movement.

     Change attribute?
     If this item is checked, Attribute Drawing Mode will affect the character
     attribute of all cels the cursor passes over during cursor movement.

Vertical movement

This sub-menu controls the vertical movement of the cursor during text entry.
This movement is in conjunction with the horizontal movement (above), thus
allowing such really cool effects as angled cursor movement.

     None
     When this item is enabled, the cursor makes no vertical movement during
     text entry.  This is the default behavior.

     Up
     This item causes the cursor to move upward after each character is
     entered.

     Down
     This item causes the cursor to move down after each character is entered.

Horizontal movement

This sub-menu controls the horizontal movement of the cursor during text
entry.  This movement is in conjunction with the vertical movement (above),
thus allowing such neat-o dog effects as angled cursor movement.

     None
     With this item checked, the cursor makes no horizontal movement after
     text entry.

     Left
     This item cause the cursor to move to the left after each character
     entered.

     Right
     This item causes the cursor to move to the right after each character
     entered.  This is the default behavior.

Text/Graphics Menu

Attribute

This sub-menu affects the current drawing colors and attributes.

     Foreground color...
     Background color...
     Selecting one of these two menu items brings up a requester that prompts
     for the desired color to which to change.  See Choose Color under
     Requesters in the Control Panels & Windows chapter for more information
     about the requester.

     Plain
     Bold
     Italics
     Underline
     Blink
     Inverse
     Concealed
     These items toggle the various text attributes on and off, with the
     exception of Plain, which clears all other attributes.  A checked item is
     enabled.

     At cursor
     This menu item grabs the colors and attributes of the cel underneath the
     cursor and makes them the current values.

Cycle colors

Color cycling is the ability for Luminus to change foreground and/or back-
ground colors 'on-the-fly', as you are entering text, making for some very
interesting (and psychedelic) effects.  Luminus cycles forward through the
available colors, looping around to the first color when it reaches the end of
the list.

     Foreground
     This item toggles the state of foreground color cycling.  A checked item
     indicates that cycling is enabled.  Luminus will affect the Bold
     attribute during color cycling, in order to take advantage of the full
     range of ANSI colors, shutting the attribute off or turning it on as
     needed.

     Background
     This item toggles the state of background color cycling.  A checked item
     indicates that cycling is enabled.  Background color cycling only cycles
     through the first eight background colors, keeping within the ANSI
     specification.

Text...

Selecting this menu item brings up the Text panel, which allows you to enter
multiple lines of text, which may be left-, center- or right-justified accord-
ing to any specified dimensions, and may optionally have a box or bevel box
rendered around it.  See the discussion of the Text Panel under Control Panels
in the Control Panels & Windows chapter.

Draw box

This item causes a box to be drawn using the currently selected block as its
dimensions.  The box is drawn using the current colors (including color
cycling) and attributes.

This item is ghosted if a block is not selected.

Draw bevel box

This sub-menu causes a bevelled box to be drawn using the currently selected
block as its dimensions.  The box is drawn using the current background color
(including color cycling) and attributes.  Its foreground color is rendered to
give it a raised or recessed appearance, according to the sub-item chosen.

     Raised
     This sub-item specifies that the bevel box should have a raised
     appearance.

     Recessed
     This sub-item specifies that the bevel box should have a recessed
     appearance.

Insert

This sub-menu allows you to insert ANSI codes into the document that are not
possible directly from the keyboard.

     Custom ANSI code...
     This sub-item brings up a string requester (see the Control Panels &
     Windows chapter) that allows you to enter the guts of an ANSI code.  As
     the requester indicates, do not type in the escape character and opening
     bracket ([), as these are assumed and added for you when the file is
     saved.  Custom codes are ignored during normal display.

     Clear screen...
     This sub-item presents a color requester (see the Control Panels &
     Windows chapter) from which you pick a background color with which to
     clear the screen.

Page Menu

This menu and its items are only available in Page Editing Mode.

New page

This sub-menu lets you add pages to your document, thus allowing a static
image multiple pages.  There is no limit (other than available memory) to the
number of pages you can add to the document.

     Append
     Selecting this item causes Luminus to create a new empty page at the end
     of the document.

     Insert
     This menu item inserts a new empty page at the current page, moving all
     subsequent pages back.

Delete page

This item allows you to delete an entire page of an image.  This data will be
irretrievably lost, so Luminus will verify your desire to delete the page.  If
there is only one page in the document, this item will be ghosted, as you
cannot delete the last remaining page (you may as well close the document!).

Previous page

This item moves to the previous page in the document.  If there is no previous
page, this item will be ghosted.

Next page

This menu item moves to the next page in the document.  If there is no next
page, this item will be ghosted.

Animation Menu

This menu and its items are only available in Animation Editing Mode.

Display...

Selecting this menu item tells Luminus to re-display the current animation
sequence from the first entered cel to the last.  You will be prompted for a
delay time.  Delay values are in 100ths of a second, i.e., a value of 100 is
1 second delay between each cel displayed.

Any input events (such as keystrokes, mouse-clicks, etc.) encountered during
the animation display are considered interruptions, and cause the animation to
stop its sequential display.  The finished image is then calculated and drawn
on the screen.  This is useful for interrupting long animation sequences, or
inadvertently long delay times.

Insert pause

This sub-menu allows you to insert a pause into the animation sequence (so
that you can stop and admire your work).  Two different types of pauses are
available.

     Key
     This flavor of pause waits for a keystroke or mouse-click before
     continuing with the animation sequence.  If the document's window is
     bordered, even clicking on the close gadget counts toward it.  Note that
     only one input event is consumed when this pause executes, and any events
     before or after are considered interruption events (as discussed above
     under the Display... menu item).

     Timed
     This pause, when executed, wait for a specified length of time before
     continuing with the animation sequence.  You are prompted for a delay
     time  Delay times are in 100ths of a second, i.e., 100 is a 1 second
     delay.

Edit cel...

This item brings up the Edit Cel panel.  From this panel you may edit
individual aspects of existing cels in the animation sequence.  See the
Control Panels & Windows chapter for details on the operation of the Edit Cel
panel.

Windows Menu

Attribute

Selecting this menu item tells Luminus to open up the Attributes interactive
support window.  (See the Control Panels & Windows chapter for details on this
type of window.)  If the window is already opened, but is partially or wholly
covered by other windows, it will be moved to the front.  If the window is
opened on another screen, it will be closed and reopened on the screen on
which the summoning window is opened.

This window provides a convenient method by which you may edit the current
colors and text attributes of your documents.  This window always reflects the
current settings of the currently active document.

Switches

Selecting this menu item tells Luminus to open up the Switches interactive
support window.  (See the Control Panels & Windows chapter for details on this
type of window.)  If the window is already opened, but is partially or wholly
covered by other windows, it will be moved to the front.  If the window is
opened on another screen, it will be closed and reopened on the screen on
which the summoning window is opened.

This window provides a convenient method by which you may edit the modes and
miscellaneous attributes of your documents.  This window always reflects the
current settings of the currently active document.

Character set

Selecting this menu item tells Luminus to open up the Character Set interact-
ive support window.  (See the Control Panels & Windows chapter for details on
this type of window.)  If the window is already opened, but is partially or
wholly covered by other windows, it will be moved to the front.  If the window
is opened on another screen, it will be closed and reopened on the screen on
which the summoning window is opened.

This window provides a convenient method by which you may enter character not
directly available from the keyboard, or characters for which you may not
remember the keystrokes, into your documents.

Refresh

This menu item causes Luminus to do a total refresh of the currently active
window.  Its border, gadgets, status line and other miscellaneous items, as
well as the actual display, are completely redrawn.  This item can come in
handy if one of your windows is graphically damaged, and the Amiga's display
refresh routines or Luminus' internal refresh routines don't catch it.

Jump screen...

This menu item brings up a scrolling list requester with all the available,
open public screens.  From this list you may select a public screen on which
you wish the current window to be reopened.  If you click the 'Move all
windows' checkbox so it is checked, then all windows, no matter what screen,
will be reopened on the desired screen.

Selecting this item while holding either Shift key will cause the current
window to reopen on the next screen in the public screen list, whichever that
may be.  No requester is presented.

To front

This item will move the current window in front of all other windows on the
screen.  It is available for when the document's window doesn't have a depth
gadget (which is the default) or it is obscured.

To back

This item will move the current window behind all other windows on the screen,
except backdrop windows (see your AmigaDOS manual for information on backdrop
windows).  It is available for when the document's window doesn't have a depth
gadget (which is the default) or it is obscured.

Zoom window

Selecting this menu item causes the window to behave as if its zoom gadget had
been selected, switching between its zoomed size and position and its regular
size and position.  It is available for when the document's window doesn't
have a zoom gadget (as when the window is rendered borderless) or it is
obscured.

Settings Menu

Create icons?

This item's state determines whether document's will be saved with icons or
not.  It is a global flag and affects all documents opened in this invocation
of Luminus.

Use AppIcon?

This item's state determines whether Luminus' AppIcon will be presented on the
Workbench window or not.  It is a global flag and affects all documents opened
in this invocation of Luminus.  See the Operations chapter form more infor-
mation on the behavior of Luminus's AppIcon.

Use preset color

This sub-menu allows you to choose from predefined color sets.  These color
sets are only available if you are using a custom screen in Luminus, and will
only affect that screen.  This entire sub-menu is disabled if no custom screen
is being used.

     A2024
     Selecting this sub-item changes the custom screen colors to a color set
     optimized for the A2024 monitor.  This color set assumes an 8-color
     screen.  A screen of fewer colors will not look right, and a screen of
     more colors will only have the first 16 changed.

     Amiga
     Selecting this sub-item changes the custom screen colors to the standard
     Amiga-style colors.  This color set assumes an 8-color screen.  A screen
     of fewer colors will not look right, and a screen of more colors will
     only have the first 16 changed.

     ANSI
     Selecting this sub-item changes the custom screen colors to the standard
     ANSI colors.  This color set assumes a 16-color screen.  A screen of
     fewer colors will not look right, and a screen of more colors will only
     have the first 16 changed.

     EGA
     Selecting this sub-item changes the custom screen colors to the standard
     EGA colors.  This color set assumes a 16-color screen.  A screen of fewer
     colors will not look right, and a screen of more colors will only have
     the first 16 changed.

     From Workbench
     Selecting this sub-item grabs the current colors from the Workbench
     screen and plugs them into the custom screen.

Display...

Selecting this menu item brings up the Display Settings panel, from which you
can edit aspects of Luminus regarding the display, such as screen mode, dim-
ensions, depth, and other things.  See the Display Settings Panel under
Control Panels in the Control Panels & Windows chapter.

If the screen mode, dimensions, depth, or font are changed in the panel,
Luminus will attempt to close and re-open its custom screen.  Any document
windows on this screen are temporarily closed, and after the screen is re-
opened, Luminus will attempt to re-open those windows.  Make sure any visitor
windows are closed.

Operations...

Selecting this menu item brings up the Operations Settings panel, from which
you can edit the operational settings of the program.  See the Operations
Settings Panel under Control Panels in the Control Panels & Windows chapter.

File...

Selecting this menu item brings up the File Settings panel, from which you can
edit the file settings of the program.  See the File Settings Panel under
Control Panels in the Control Panels & Windows chapter.

Document...

Selecting this menu item brings up the Document Settings panel, from which you
can edit the document settings of the program.  See the Document Settings
Panel under Control Panels in the Control Panels & Windows chapter.

Boxes & lines...

Selecting this menu item brings up the Box & Line Settings panel, from which
you can edit the box and line settings of the program.  See the Box & Line
Settings Panel under Control Panels in the Control Panels & Windows chapter.

Restore defaults

This menu item tells Luminus to disregard the currently loaded settings and
revert to its internal defaults.  These are the same defaults used if no
settings file is located upon program start-up.

Save settings

Selecting this menu item saves the current settings to disk.  The settings
file will be saved in the directory from which it was loaded.  If the file
wasn't loaded, it will be saved into the program's directory.  If the file
can't be saved there, it will saved in the ENVARC: and ENV: directories.

Save settings as...

This menu item prompts for a path and file name for the settings file, and
saves the current settings to disk.

Load settings...

This menu item brings up an ASL requester for you to select a settings file to
be loaded.

Tools Menu

Shell window...

Selecting this menu item causes Luminus to attempt to bring up a shell window,
using the Console Specification.  The Console Specification may be changed in
the Operations Settings Panel.

Execute script...

This menu item brings up a string requester in which you input the name of the
AmigaDOS script to be executed.  If no path is entered, the S: directory is
assumed.

ARexx script...

This menu item brings up a string requester in which you input the name of the
ARexx script to be executed.  If no path is entered, the REXX: directory is
assumed.

Control Panels & Windows

The purpose of this chapter is to explain the operation of various windows
that may pop up during certain activities in Luminus.  The general purpose of
these windows is examined, followed by a description of each window's gadgets
and their purpose.  There are three different types of windows in Luminus, not
counting document windows.

The first kind are called interactive support windows.  What this means is
that, unlike other windows, this window does not block input into the document
window from which it was summoned, but remains open in conjunction with all
document windows, and reflects the current settings of the active document.
As the active document is changed, usually by clicking in its window, all
interactive support windows are updated to reflect the settings of that newly
active document.  Interactive support windows' positions are saved in the
settings file.

The second type of window is the control panel.  These are windows that open
up, usually with several gadgets, that allow you to change, control, and in
some cases, 'fine-tune' the action that you have chosen.  Input to the
document window that summoned the control panel is blocked until the window is
closed and action is taken or cancelled.

The final type of window is the requester, of which there are two sub-types.
The first is the standard informational/query requester.  These are basically
the same as standard Intuition requesters.  They provide you with some
(essential) information or prompt you for a response, and have one or more
button gadgets at the bottom of the window to respond to the query.  The
second sub-type are specialized, each kind asking for information that cannot
be gathered using a few sentences and some buttons.  These are discussed in
detail below.

Interactive support windows

Attributes Window

The Attributes window allows you to control current drawing colors and
attributes as an alternative to using the menu system.  The following gadgets
are available in the Attributes window:

Foreground
This palette gadget reflects the current foreground color of the active
document.  Clicking on a color will change the active foreground color of that
document to the color chosen.  This gadget only allows access to the first
eight colors of the screen palette.  This is due the way ANSI foreground
colors are displayed.  To access the bright equivalents, simply click the Bold
gadget so it is checked.

Background
This palette gadget reflects the current background color of the active
document.  Clicking on a color will change the active background color of that
document to the color chosen.  This gadget only allows access to the first
eight colors of the screen palette.  This is due to the fact that the ANSI
specification only supports the eight dark colors for background display.

Cycle?
A checkbox gadget labelled 'Cycle?' is located beneath each palette gadget.
Each corresponds to the color cycling facility of the fore/background colors.
If the box is checked, color cycling is enabled.  Enabling color cycling
causes Luminus to move through the available spectrum of colors, circling back
around to the beginning when the end is reached.  Colors are cycled during
text-entry, whether interactive or ARexx-induced, during attribute drawing,
and is respected by the box and line drawing routines.

Plain
Pressing this button causes the currently set attributes to be cleared.  It is
basically provided as a convenience to having to deselect each attribute.

Bold/Italics/Underline/Blink/Inverse/Concealed
These checkboxes control the various attributes available in the ANSI
specification for text display.  A checked box indicates an active attribute.

NOTE      Some attributes may not be displayable on some computers.  For
          instance, the ANSI blinking attribute cannot be displayed on the
          Amiga, while underline and italics are normally not displayed on
          MS-DOS machine standard text displays.

Switches window

The Switches window allows you to control current editing and drawing modes,
line types and cursor movement as an alternative to using the menu system.
The following gadgets are available in the Switches window:

Edit mode
This cycle gadget allows you to choose from the available editing modes, which
are currently Page and Animation.  Switching from Animation mode to Page mode
can ruin a perfectly good animation, so your choice is verified before any
real action is taken.  Please see the discussion of Editing Modes in the Operations chapter.

Draw mode
This cycle gadget allows you to choose from the available drawing modes, which
are currently Text and Attribute.  Please see the discussion of Drawing Modes
in the Operations chapter.

Line type
This cycle gadget allows you to choose from the available line types.  Please
see the discussion of Line Types in the Operations chapter.

Vertical
This cycle gadget selects the vertical direction the cursor will move during
text entry.  Please see the discussion of Cursor Directioning in the
Operations chapter.

Horizontal
This cycle gadget selects the horizontal direction the cursor will move during
text entry.  Please see the discussion of Cursor Directioning in the
Operations chapter.

Change fgnd.
This checkbox gadget's state determines whether foreground colors will be
affected during Attribute mode drawing.  Please see the discussion of
Attribute Mode under Editing Modes in the Operations chapter.

Change bgnd.
This checkbox gadget's state determines whether background colors will be
affected during Attribute mode drawing.  Please see the discussion of
Attribute Mode under Editing Modes in the Operations chapter.

Change attr.
This checkbox gadget's state determines whether character attributes will be
affected during Attribute mode drawing.  Please see the discussion of
Attribute Mode under Editing Modes in the Operations chapter.

Character Set window

The Character Set window allows you to view and access the entire character
set for the font you have chosen for text editing.  This font is distinctly
difference from the screen font.  Program-related stuff is displayed in the
screen font, while the actual document text is displayed in the text font,
which is shown here.

Since many of the characters in a font are not accessible from the keyboard,
this window allows you to simply click on one of those characters and insert
it in the document at the cursor position.  A scroll bar is located at the far
right of the window, allowing you to peruse the available characters.

At the far left, there is a gap between the window's edge and the first column
of characters.  This space is provided for the current row marker.  This
marker is a dark red (in the ANSI color set) box positioned on the current
row.  Note that the current row is an absolute position, and may not be
visible if the scroll bar is used to scroll through the character set.
Clicking the mouse in the area to the left of a row of characters will cause
that to become the current row.

From any active document window, the eight characters in the current row may
be accessed by pressing any of the functions keys, F1 through F8.  Pressing
function keys F9 or F10 will decrement or increment, respectively, the current
row.

Control Panels

Save Panel

This panel allows you to specify the save parameters of a file before actually
saving it.

Save type
This cycle gadget allows you to change the type of file that will be saved.
The choices available are ANSI, IFF, and ASCII.  Note that the ASCII type is
not available when saving a file in Animation Editing Mode.

The ANSI type indicates that Luminus will save the file in standard ASCII
format with embedded ANSI codes for color, cursor movement, etc., as appro-
priate.

The IFF type indicates that the file will be saved in IFF format, as specified
by (the late) Commodore and Electronic Arts.  There are two different IFF
formats that Luminus understands.  See the 'IFF type' gadget below for more
details.

The ASCII type indicates that the file will be saved in standard ASCII format.
ANSI codes will not be saved with the file.  Again, this type is not available
in Animation Editing Mode.

IFF type
This cycle gadget allows you to choose from the IFF formats that Luminus
understands.  The IFF formats currently supported are FTXT CHRS and ANSI CEL.
See the Miscellaneous chapter for a further discussion of the IFF formats.

Line length
Specifies the maximum line length of a single line.  Luminus will not exceed
this value when saving to the file.  Some BBS software only allow a message's
lines to be a certain length, and since each character of an ANSI code
generally counts toward this, Luminus will start a new line if the ANSI code
would extend beyond this value.  This prevents ANSI codes from being obliter-
ated by a BBS's display routines.  This gadget is ghosted (not available) in
IFF save mode.

Video preparation
You may want the screen cleared before your animation in drawn, or the cursor
to be placed at the top-left corner of the screen.  This gadget allows you to
pick from certain types of codes that may be saved with your file before the
actual animation.

The video prep 'None' indicates that no codes should be saved first.  The v.p.
'Home' will place a code that positions the cursor at the top-left corner
('home' position).  The v.p. 'Clear screen' places a clear screen code before
the animation.

End-of-line type
Since Amigas, DOS machines, Macintoshes and UN*X machines handle newlines
differently, you can indicate that type of newline that will be saved in the
file.  The available types are 'CR only', 'CR + LF', and 'LF only'.

Use alt. escape?
This checkbox indicates whether you would like ANSI codes, which begin with
an escape character (ASCII code 27), saved with an alternate escape character,
which some BBS software use instead of the escape character.  The string
gadget next to the checkbox is where you indicate the alternate escape char-
acter.  These gadgets are only available in ANSI save mode.

Filter solid spaces?
This checkbox tells Luminus whether or not to treat solid spaces (ASCII code
160) as normal spaces or leave them as they are.

Save
This button tells Luminus that you are satisfied with the current settings and
want to proceed with the save operation.

Cancel
This button tells Luminus that you've changed your mind and don't want to save
the file after all.  Clicking on the window's close gadget is equivalent to
clicking the Cancel button.

Edit Cel Panel

This panel allows you to edit individual aspects of a cel.  It provides finer
control and the ability to edit existing cels in an animation sequence.  Note
that when this window is first summoned, the cel being editing is the topmost
available cel in the animation sequence at that cursor position.  There may be
cels hidden beneath it.  See the description below of the Prev and Next
buttons for information on how to get to those cels.

This panel is only available in Animation Editing Mode.

Character
This string gadget shows the character at the current position.  This gadget's
character is shown in the screen font, as opposed to the text font, so the
character may look different.  Next to the string gadget is a display box that
shows the actual character, given colors and attributes in the text font.

Foreground
Background
These two palette gadgets allow you to change the foreground and background
colors of the cel.

Plain
Bold
Italics
Underline
Blink
Inverse
Concealed
The Plain button and all the attribute checkboxes here are the same func-
tionally as the corresponding gadgets in the Attributes interactive support
window.  (See that window's description above for more details.)

Change
When you edit the colors and attributes of the cel in this window, you are
only affecting a copy of the cel contents.  Clicking on this button makes the
changes take effect.

Prev
Next
Clicking on one of these two buttons causes Luminus to search further through
the animation sequence for underlying cels at the cursor position.  Next moves
deeper into the layer, Prev shallower.

Done
Clicking on this button tells Luminus that you are done editing cels.  The
window will close, and any changes made to the animation will take effect.

Text Panel

This panel window comes up when you select 'Text...' from the Text/Graphics
menu.  It allows you to input one or more lines of text that may be justified
in some manner and/or outlined.  The following sections provide detail on the
Text panel's gadgets.

Text
This scrolling list gadget allows you to enter the text that you wish to have
displayed.  Click on any line of text to edit it.  When the panel is first
opened, there will be no text in this list.  You can enter new text by click-
ing on the 'Add' gadget (see below).

The string input gadget at the bottom of the list is where you actually enter
the text.  Press Enter when you are finished with that line, and the text will
be placed in the list.

Add
Clicking on this button creates a new blank line at the bottom of the list of
text and activates the string gadget.

Delete
Clicking this button causes the currently selected line of text to be deleted
from the list.  Once deleted, the test is irretrievably gone.  If this list is
empty, this button will be ghosted.

Clear
Clicking on this button will clear the entire list of text.  You will be asked
to confirm this, since once the text is gone, you can't get it back (except by
retyping all of it!).

Line type
This cycle gadget allows you to select the type of line that you would like to
have surrounding your text.  See Line Types in the Operations chapter for more
detail on the available line types.  If you don't want a line, click this
gadget 'til it reads 'None'.

Bevel
If you would like the line around your text to have a bevelled appearance, use
this cycle gadget to select the bevel type.  The two types available are
'Raised' and 'Recessed'.  If you want a normal line, select a bevel type of
'None'.  This gadget is ghosted if the line type is set to 'None'.

Justification
If you would like your text justified in the document, use this cycle gadget
to specify the type of justification.  The available types are 'None', 'Left',
'Center', and 'Right'.  All the justification types obey the margin values on
the Left and Right Margin gadgets (discussed below), except for 'None', which
places the text at the current cursor position.

Left margin
Right margin
These two integer gadgets let you specify the margin values to use when using
justification.  They default to the left and right edges of the document, but
you can change them to have text placed according to different settings.  The
margin values are bounds-checked against the document, and the left margin
cannot exceed the right margin value.

For example, you have an ANSI image that takes up the left side of an
80-column wide document.  If you want your text centered on the right hand
side, you would set the justification to 'Center' and the margins to 41 for
the left, and 80 for the right.

These gadgets are ghosted if the justification is set to 'None'.

Okay
When you click this button, Luminus will first check to see that the text you
specified, taking into account line type, justification and margin values,
will fit into the visible portion of the document.  (The 'visible portion' is
the total document size, not the part that is only displayed in the window.
Luminus preserves cels that extend beyond the boundaries of the document's
specified width and height.)  If your specified text would go beyond the
boundaries, you have the option of returning to the Text panel to make changes
or to just tell Luminus to put it in the document anyway.  This button is
ghosted if the text list is empty.

Cancel
Clicking this button will abort the Text panel and return you to your document
with no changes made.

Display Settings Panel

This panel deals with the basic Intuition display aspects of Luminus, such as
screenmode, colors, etc.  Each of the gadgets used in this panel are discussed
below.

Screenmode list
This scrolling list gadget presents the available screenmodes with which you
may open a custom screen.  Simply click on the desired mode for the custom
screen.  The standard dimensions for that mode will be plugged into the Width,
Height and Depth gadgets (discussed below).  The selected screenmode is only
valid if the Custom Screen? checkbox is checked.

Custom screen?
This checkbox determines whether or not Luminus will attempt to open a custom
screen of type PUBLICSCREEN upon start-up.  All documents, unless otherwise
specified, will open on this screen.  This is the default behavior.

Width
Height
Depth
These two integer gadgets and slider gadget control the width, height and
depth of the custom screen.  The width and height are bounds-checked with the
dimensions in the display database.  These gadgets are ghosted if Custom
screen? is not checked.

Shanghai windows?
Pop public screen?
These two checkboxes apply to the public screen attributes of the custom
screen.  They control the global public screen flags in Intuition.  Shanghai
windows?, if checked, tells Intuition that the default public screen will grab
any windows that don't have a specific screen destination and have them open
on itself.  Pop public screen?, if checked, tells Intuition that if any window
opens up on the default public screen, that it should move itself to the front
of the display.  These gadgets are ghosted if Custom screen? is not checked.

Name
This string gadget specifies the name of the custom public screen which
Luminus will attempt to open.  This name is used as identification for other
windows, possibly from other programs, so they may open on it.  This gadget is
ghosted if Custom screen? is not checked.

Text font
This display gadget shows the currently selected text display font, which is
used in all of Luminus' document windows.  The accompanying button, when
clicked, will bring up the ASL font requester, from which you may choose a new
font.  This font must be a monospaced font.  The font type is checked upon
return from the font requester, and if a proportional font is selected, it
will be ignored, and the old font will remain in place.

Screen font
This display gadget shows the currently selected screen font, which will be
used on the custom screen which Luminus will attempt to open, if specified.
The accompanying button, when clicked, will bring up the ASL font requester,
from which you may choose a new font.  This setting is ignored if Custom
screen? is not checked.

Public screen
This string gadget lets you specify the name of the public screen on which
Luminus will attempt to open its documents.  This can be overridden (see New
and Open in the Menus chapter).

Colors
This set of gadgets affects the color settings of the custom screen as well as
the pens that will be used when drawing certain things, such as the cursor,
blocked text and the status line.

The first gadget is a cycle gadget.  This tells what item will be affected by
any color changes.  The first item, 'None', indicates that no item will be
changed, and using the accompanying palette gadget and red, green and blue
slider will only affect the palette.  The subsequent items are 'Status line
foreground', 'Status line background', 'Block foreground' and 'Block back-
ground'.  Clicking to one of these items changes the palette gadget and
sliders to reflect that setting's current pen.

Selecting a color from the palette gadget makes that color available for
editing with the sliders.  If the cycle gadget indicates anything other than
'None', the color selected becomes the current pen for that setting as well.

The sliders allow you to change the red, green and blue content of a color.
Changes made are immediately apparent, but don't take effect unless the 'Use'
button is selected.

Use
When you click this button, Luminus checks to see if the screenmode, width,
height, depth or screen font have changed.  If any of them differ from the
current setting, Luminus will close its custom screen (if opened), and attempt
to reopen it (if set).  Should the text font differ from the current setting,
all document windows will be immediately refreshed to reflect the new font.

Cancel
Clicking this button will tell Luminus to ignore any and all changes made to
the display settings in the Display Settings panel, and will exit out of the
panel.

Operations Settings Panel

This panel lets you set the options regarding the general operations of
Luminus.

ARexx port base name
This string gadget allows you to enter the base name that will be used to name
the ARexx port of a document.  This name is suffixed with a numeric value to
give a unique derived port name  The default base name is 'LUMINUS'.

Status line format
This gadget contains a string with printf()-style formatting codes which
control how the status line is displayed.  Using these codes, you can custom-
ize the status line to look whichever way that floats your boat.  The follow-
ing codes are supported.

     Code      Meaning
     -------------------------------------------------------------------------
     %B        Block mode indicator ('Block' or nothing)
     %c        Column number
     %C        Caps Lock indicator ('Caps' or nothing)
     %D        Drawing mode indicator (verbose text; this code also reflects
               the current colors and text style)
     %E        Editing mode indicator (verbose text)
     %f        Filename of document
     %F        Complete path and filename of document
     %H        Horizontal direction indicator (verbose text)
     %I        Insert mode indicator ('Ins' or nothing)
     %l        Current line
     %L        Total number of cels in document
     %m        modified flag ('*' (asterisk) or ' ' (space) for modified or
               not, respectively)
     %n        Current cel or page number (this code's value depends on the
               current editing mode of the document)
     %N        Num Lock indicator ('Num' or nothing; see the Operations
               chapter for information on the NumLock key)
     %P        ARexx port name of document
     %V        Vertical direction indicator (verbose text)
     %Y        Line type indicator (verbose text)

These codes can be combined with regular text for a completely custom-made
status line.

Clipboard unit
This is the clipboard unit number that each document will use by default when
accessing the Clipboard.

Console specification
This string gadget allows you to specify the attributes of any console window
that might be opened up, such as selecting Shell window from the Tools menu.
Please refer to your AmigaDOS manual for more information on the console.

Use AppIcon?
Having this checkbox checked tells Luminus to place its AppIcon on the
Workbench screen.  You can use the AppIcon to easily load documents or return
to Luminus without having to flip through screens.  Please see AppIcon,
AppWindows & AppMenuItem in the Operations chapter.

Show status line?
This checkbox determines whether Luminus' documents will display a status line
in their windows by default.  This behavior can be controlled in each indivi-
dual document as well.

Status line at top?
This checkbox determines whether the status line (if displayed) will be at the
top or bottom of the window.  This is a global flag and applies to all
document windows.

Open attributes window?
Open switches window?
Open character set window?
These three checkboxes tell Luminus whether or not to open the respective
interactive support windows upon start-up.  See Interactive Support Windows
above.

Beep on error?
This checkbox tells Luminus to execute a DisplayBeep() (an Intuition function
that flashes the screen and sounds a (pitiful) tone) when an error occurs.

Ask before quitting?
This checkbox tells Luminus whether or not to confirm a quit action.  This
flags only applies when quitting using the Quit menu item.  If a document is
closed using the Close item, and it's the last document, Luminus will shut
down automagically without confirmation.

Use
Clicking this button puts the current display settings into effect.

Cancel
Clicking this button, on the other hand, exits this panel and puts all changed
settings into the bit-bucket (it ignores them).

Document Settings Panel

This control panel lets you control the settings that apply to Luminus'
documents.

Width
Height
These two integer gadgets let you specify the maximum displayable dimensions
of your documents.  These settings only affect what Luminus will display in
the document's window.  Cels that extend beyond these boundaries are
preserved.

Pages
This is the default number of pages a document will support upon initial open.
The actual number of pages can be changed from the Page menu.  This setting
only applies in Page Editing Mode, since animation sequences do not have
pages.

Foreground/Background
Cycle?
The cycle gadget of this group of gadgets controls which (foreground or back-
ground) will be affected by the palette gadget and Cycle? checkbox.  Choose a
color from the palette gadget to make that color current for the setting shown
in the cycle gadget.  Click on the checkbox to set or unset default color
cycling for the appropriate setting.

Edit mode
This cycle gadget sets the default editing mode of each document upon initial
open.  The currently available modes are 'Page' and 'Animation'.  The default
is 'Animation'.

Draw mode
This cycle gadget sets the default drawing mode of each document upon initial
open.  The currently available modes are 'Text' and 'Attribute'.  The default
is 'Text'.

Vertical direction
Horizontal direction
These two cycle gadgets set the default vertical and horizontal cursor
movement upon initial open.  You can choose from 'None', 'Up' and 'Down' for
vertical, and 'None', 'Left' and 'Right' for horizontal.  The defaults are
'None' for vertical and 'Right' for horizontal.

Borderless?
This checkbox determines whether Luminus' document windows will be opened with
a standard Intuition window border, complete with close gadget; title/drag
bar; zoom, depth and sizing gadgets; and vertical and horizontal scrollers.
The default is a borderless window.

Destructive backspace?
This setting determines whether the backspace key, when pressed, will delete
the cel onto which it moves.  See the Operation chapter for information on the
behavior of 'editing keys'.

Show ruler?
This setting determines whether the Ruler will be displayed by default in the
documents' windows.  The ruler is a pair of lines that intersect at the mouse
pointer.  By default, the ruler is not shown.

Show ruler hashes?
This setting determines whether the Ruler (if displayed) will have hash marks
drawn perpendicular to its edges at character width/height intervals.  The
hash marks are centered on the character position.  By default, hash marks are
not shown in the 68000/010 version, and are shown in the 68020+ versions.

Show ruler numbers?
This setting determines whether the Ruler (if displayed with hash marks on)
will have position numbers displayed adjacent to the hash marks.  The numbers
are displayed either to the left or above the hash marks, as appropriate.  By
default, numbers are not shown in the 68000/010 version, and are shown in the
68020+ versions.

Interval
This setting controls the interval at which the Ruler's numbers (if shown) are
drawn.  The numbers will start at this number, and are displayed in this inc-
rement.  For example, a setting of 10 will display every tenth ruler number
starting at 10.  The default value is 5.

Use
Clicking this button enacts the settings.

Cancel
Clicking this button ignores any changed settings in this panel and returns
you to the document.

File Settings Panel

This control panel affects the settings concerning how Luminus saves and loads
its files.

Save type
This cycle gadget allows you to set the type of file which will be saved when
you select Save or Save as from the Project menu.  The currently available
types are 'ANSI' and 'IFF'.  The default is 'ANSI'.

IFF type
If you elect to save file as type IFF, this cycle gadget lets you determine
which IFF format will be used.  The available formats are ANSI CEL, which is a
proprietary IFF format Luminus uses, or FTXT CHRS, which most IFF-compliant
word processors, as well as the Amiga's standard clipboard, understand.

Line length
This integer gadget determines the maximum length of a saved line before a
CR(/LF) is appended.  This allows Luminus to save documents so that lines will
not extend beyond some BBS software's maximum line lengths.

Video preparation
This cycle gadget lets you choose the type of video preparation that will
precede your file when it is saved.  The available types are 'None', 'Home
cursor', and 'Clear screen'.  'None' will not put anything before your data,
obviously.  'Home' will put an ANSI code to place the cursor at the top left
corner of the screen.  'Clear' will place in ANSI code that will clear the
screen before the file is drawn.

End-of-line type
This cycle gadget allows you to choose the type of EOL that will be saved with
your documents.  The avail able types are 'CR only', 'LF only', and 'CR + LF'.
The default is 'CR + LF'.

Use alt. escape?
Some BBS software, instead of using the standard escape character (ASCII code
27), use an alternate character, such as '@' or '`', for their ANSI escape
sequences.  Checking this box tells Luminus to use an alternate character when
saving files.  The string gadget next to it is where you input the character
to use.

Filter solid spaces?
Checking this checkbox tells Luminus to convert incoming or outgoing solid,
or "hard", spaces (ASCII code 160) to normal spaces.

Prompt on save?
Checking this gadget sets the flag that causes the Save panel (see above) to
pop up before a file is saved.  This allows you to change the save attributes
for each file without having to change the defaults.

Filter stray escapes?
ANSI codes, by definition, always begin with the character sequence "esc[",
where 'esc' stands for the ASCII escape character, code 27.  If Luminus should
encounter an "stray" escape character, i.e., one not belonging to a valid ANSI
sequence, this flag determines how it handles them.  If the flag is on, these
escapes will be filtered out of the file.  If it is off, they will remain as
part of the file, but will never be displayed.

I/O Buffer size
This integer gadget allows you to set the size of the buffer Luminus will use
for input and output.  This buffer speeds disk access and generally makes
loading and saving files quicker.  As a rule of thumb, the larger the buffer,
the quicker the file access; but you must be careful not to make the buffer
too large.  Note that this value is in kilobytes (KB), not bytes.

Timed backups
Interval
These two gadgets affect whether Luminus will execute a timed backup during
your editing sessions.  The checkbox turns the feature on, and the integer
gadget sets the amount of time (in minutes) that must pass before Luminus does
an automatic backup.

Directory
This is the directory in which Luminus will saved your backed up files.  This
directory applies to timed backups (above) as well as file backups (below).
If this is blank, the file's current directory is assumed.

Extension
This is the extension that will be appended to any files that Luminus backs
up, either via timed backup or through the Save original? flag (below).  You
do not have to add a period at the beginning of the extension; this will be
done for you.  If this is blank, no extension is added.

For example, Luminus backs up the file 'Logon.ansi', which you are editing.
You have the backup extension set at "backup".  The file will be saved into
the backup directory as 'Logon.ansi.backup'.

NOTE      Luminus will attempt to handle backups intelligently.  If the backup
          directory AND extension are both blank, the resulting path and
          filename would overwrite the original file, which defeats the
          purpose of the backup.  So if this case is detected, Luminus will
          add just the '.' (period) to the end of the filename to create a
          (possibly) unique filename, preventing an overwrite.  This is not
          possible with a filename that is the maximum length AmigaDOS allows.

Save original?
Setting this flags tells Luminus to preserve the original file when doing a
normal Save (Save as is not affected, since it allows you to explicitly
overwrite a file).  The file will be backed up into the specified directory,
using the specified extension.

Use
Click this button to make the changes you've made in this panel take effect.

Cancel
Clicking on this button aborts the panel and ignores any changes made therein.

Box & Line Settings Panel

This panel controls the settings concerning boxes and lines used in Luminus.

Line type
This cycle gadget allows you to set the default line type that will be used by
each document.

Box codes
These are the unlabeled boxes that take up most of the panel's real estate.
Each box corresponds to a part of a whole box, like so:

     +-----+ +-----+ +-----+ +-----+
     |  1  | |  2  | |  3  | |  4  |
     +-----+ +-----+ +-----+ +-----+

     +-----+         +-----+ +-----+
     |  5  |         |  6  | |  7  |
     +-----+         +-----+ +-----+

     +-----+ +-----+ +-----+ +-----+
     |  8  | |  9  | |  10 | |  11 |
     +-----+ +-----+ +-----+ +-----+

     +-----+ +-----+ +-----+ +-----+
     |  12 | |  13 | |  14 | |  15 |
     +-----+ +-----+ +-----+ +-----+

These gadgets allow you to enter the specific characters to use for each of
the box parts when drawing a box using the Custom line type.  The box numbers
are as follows:

     Number    Box part type
     --------------------------------------------------------------
        1      Upper-left corner
        2      Upper cross-beam
        3      Upper intersection
        4      Upper-right corner
        5      Left cross-beam
        6      Middle vertical cross-beam
        7      Right cross-beam
        8      Left intersection
        9      Middle horizontal cross-beam
       10      Middle intersection
       11      Right intersection
       12      Lower-left corner
       13      Lower cross-beam
       14      Lower intersection
       15      Lower-right corner

Use
Clicking on this button makes any changes made in this panel take effect.

Cancel
Click this button to abort the panel and ignore any changes made in it.

Requesters

Select Public Screen

This requester presents you with a scrolling list of all the currently opened
public screens.  From this list you may select a screen name and click the Use
button, or double-click the desired screen name.  Selecting Cancel or the
window's close gadget backs out of the requester with no action being taken.

If the Select Public Screen requester is called as a result of a screen jump
request, an additional gadget is available.  This is the Move all windows
gadget.  If this checkbox is checked when a public screen is chosen, then all
windows, not just the initiating window, will be affected.  This gadget is not
available if the requester is called from a New or Open Document request.

Choose Color

This requester presents you with a palette gadget from which to choose the
desired color, such as changing the foreground or background color.  Click
Use to make the change take effect, Cancel to back out.

String/Integer Input

This requester presents a string or integer gadget, with appropriate prompt-
ing, for user input.  Clicking the Use button or pressing carriage return from
the gadget effect the change, which clicking the close gadget or the Cancel
button back out with no action taken.

ARexx

This chapter discusses the ARexxTM commands available to you via Luminus'
ARexx interface.

Each document in Luminus has its own ARexx port, and may receive any command,
including commands that affect global settings.  The port name for any
document can be found by selecting the About item in the Project menu.

Some commands return results in the ARexx variable result, so you must be sure
to set OPTIONS RESULTS in your scripts.  If you do not, you will get an
OPTIONS_RESULTS_NOT_SET returned in rc, and you don't want that, now do you?

Some command are also only available in certain editing or drawing modes, or
when a block is selected, so please be sure to read the command's description.
Commands used while not in a certain mode usually return
COMMAND_NOT_AVAILABLE in rc.

Command Conventions

The following convention is used for each ARexx command discussed in this
chapter:

Command

   Synopsis  Arguments and options for the command.  The command name is shown
             first, followed by any required and/or optional parameters.
             Parameters in all lower-case, such as

                    SaveSettings file

             are substituted with something, like a filename.  Some parameters
             can be supplied multiple times, such as filenames in the Open
             command.  These parameters are followed by ellipses, like so:

                    Open file...

             If the parameter has square brackets around it, like this

                    Save [file]

             then it is optional.  Parameter with no brackets, like the first
             two above, are required, and must be supplied for the command to
             work as documented.  Keywords, which must be supplied as typed
             (except for case), are shown in all capitals, like this:

                    Ruler ON|OFF

             Also, the vertical bar that separates ON and OFF in the above
             command means that you can choose from any of the items there for
             that parameter.  So the above command could be Ruler ON, or Ruler
             OFF.  Simple, eh?

    Purpose  A brief description of the command.

Description  A detailed explanation of the command and its options, with
             examples as necessary.  If a command is usable in a certain mode,
             this is discussed here as well.  Some commands return results in
             result; the format is also described here.

   See Also  One or more references to other ARexx commands or sections in
             the manual for further explanation.

ARexx Commands

Luminus' supported ARexx commands are discussed below.

ActivateWindow

   Synopsis  ActivateWindow

    Purpose  Make this document's window active.

Description  This command causes the window associated with the document from
             whose ARexx port this command is received to become the input
             focus, or active window.

   See Also  None

AtCursor

   Synopsis  AtCursor

    Purpose  Grab the attributes at the current cursor position.

Description  AtCursor grabs the foreground and background colors and character
             attributes at the cursor position.  This command obeys the
             current Attribute Mode flags, so if a particular flag is not set,
             such as foreground color, that attribute will be ignored.  This
             way you can grab only the attributes you want.

   See Also  AttrMode

Attribute

   Synopsis  Attribute [PLAIN] [BOLD] [ITALICS] [UNDERLINE] [BLINK] [INVERSE]
                       [CONCEALED]

    Purpose  Inquire about or change the current attributes.

Description  Specify any of the parameters to toggle that state of that
             attribute.  The PLAIN parameter is a switch (as opposed to the
             others, which are toggles).  Using plain in combination with the
             other parameters allows you to completely reset the attributes
             without having to check on their current state and toggle the
             appropriate ones on or off.  For example, the current attributes
             are BOLD and UNDERLINE.  You want to change them to ITALICS.
             Simply issue the following command:

                    Attribute PLAIN ITALICS

             This will turn off all the attributes, and then turn on italics.

             Issuing this command without any of the parameters specified
             returns the currently set attributes as a text string in result.
             For example, if Italics and underlining were active, Attribute
             (with no parameters) would return:

                    "ITALICS UNDERLINE"

   See Also  None

AttrMode

   Synopsis  AttrMode [[NO]FORE[GROUND]] [[NO]BACK[GROUND]] [[NO]ATTR[IBUTE]]

    Purpose  Change the attribute mode flags.

Description  This command sets the Attribute mode flags.  These flags affect
             what attributes of cels are affected during Attribute Mode
             Drawing, as well as filtering which attributes are taken upon
             execution of the AtCursor command.

             Specifying any of the parameters prefixed with NO shuts that
             attribute off.  Otherwise, it is turned on.

             AttrMode returns the current Attribute mode flags in result as
             follows:

                    "foregnd-flag backgnd-flag attr-flag"

             where each -flag is either ON or OFF.

   See Also  DrawMode, AtCursor

BackgroundPen

   Synopsis  BackgroundPen [pen] [[NO]CYCLE]

    Purpose  Change the background drawing pen.

Description  This command changes the background color used for text and
             drawing.  The pen parameter accepts a color register number as
             its argument, starting at pen 0 to the maximum pen usable on the
             screen.  If the CYCLE keyword is supplied, the background color
             cycling flag is turned on.  NOCYCLE turns it off.

             BackgroundPen returns the current background pen and cycle flag
             in result as follows:

                    "pen-number cycle-flag"

             where pen-number is the numeric color register, and cycle-flag
             is either CYCLE or NOCYCLE.

   See Also  TextPen

BevelBox

   Synopsis  BevelBox left top width height bevel [line-type [character]]

    Purpose  Draw a box with a beveled appearance.

Description  The first five parameters are required, and specify the dim-
             ensions of the box to be drawn, and the bevel type.  Valid bevel
             types are RAISED and RECESSED.  The line-type parameter is the
             line type with which to draw the box.  Valid line types are
             SINGLE, DOUBLE, SINGLEDOUBLE, DOUBLESINGLE, CUSTOM and SELECT.
             If the SELECT line type is used, you must specify the character
             to use in character.

   See Also  Box, TextBox

Border

   Synopsis  Border [ON|OFF]

    Purpose  Turn on or off the document window's border.

Description  This command tells Luminus to open the document's window with or
             without a standard Intuition window border, complete with close
             gadget, title/drag bar, zoom, depth and sizing gadgets, and
             vertical and horizontal scrollers.  If the current state of the
             window differs from the desired one, the window will be closed
             and reopened in the requested state.  The parameters are quite
             obvious, I hope.

             Border returns the current state (ON or OFF) in result.

   See Also  None

Box

   Synopsis  Box left top width height [line-type [character]]

    Purpose  Draw a box.

Description  The first four parameters are required, and specify the dim-
             ensions of the box to be drawn.  The line-type parameter is the
             line type with which to draw the box.  Valid line types are
             SINGLE, DOUBLE, SINGLEDOUBLE, DOUBLESINGLE, CUSTOM and SELECT.
             If the SELECT line type is used, you must specify the character
             to use in character.

   See Also  BevelBox, TextBox

BoxLineSettings

   Synopsis  BoxLineSettings

    Purpose  Bring up the Box & Line Settings panel.

Description  Issuing this command brings up the Box & Line Settings panel.

   See Also  DisplaySettings, OpsSettings, FileSettings, DocumentSettings

ChangeWindow

   Synopsis  ChangeWindow left top width height

    Purpose  Change the current window's size and position.

Description  This command's parameters any value of zero or greater for left
             or top, and any positive value greater than or equal to 100 for
             width, and 75 for height.  The window, if its ultimate size and
             position would extend beyond the screen's boundaries, will first
             be moved and then resized to fit into the screen.

   See Also  ZoomWindow, UnZoomWindow, MoveWindow, SizeWindow

Clear

   Synopsis  Clear PAGE|DOCUMENT [FORCE]

    Purpose  Clear part or all of the current document.

Description  This command will clear larger portions of the document than are
             normally handles by Cut, Erase and their ilk.  The first para-
             meter can be either PAGE or DOCUMENT.  Specifying PAGE (which is
             only available in Page Editing mode), clears the current page.
             If this parameter is used in any other mode, INVALID_PARAMETER is
             returned in rc.  If DOCUMENT is specified, the entire document is
             cleared.  The second parameter, FORCE, suppressed the 'are you
             sure?' requester that normally comes up.

   See Also  None

Close

   Synopsis  Close [FORCE]

    Purpose  Close the current document.

Description  This command tells Luminus to shut the current document's window
             and free all associated memory for that document.  The FORCE
             parameter tells Luminus to suppress the requester that would
             appear if you had made changes to the document since its last
             save.

   See Also  None

CloseAttributes

   Synopsis  CloseAttributes

    Purpose  Close the Attributes interactive support window.

Description  This command closes the Attributes interactive support window if
             it is open.  If it isn't, nothing happens.

   See Also  OpenAttributes, OpenCharSet, CloseCharSet, OpenSwitches,
             CloseSwitches

CloseCharSet

   Synopsis  CloseCharSet

    Purpose  Close the Character Set interactive support window.

Description  This command closes the Character Set interactive support window
             if it is open.  If it isn't, nothing happens.

   See Also  OpenAttributes, CloseAttributes, OpenCharSet, OpenSwitches,
             CloseSwitches

CloseSwitches

   Synopsis  CloseSwitches

    Purpose  Close the Switches interactive support window.

Description  This command closes the Switches interactive support window if it
             is open.  If it isn't, nothing happens.

   See Also  OpenAttributes, CloseAttributes, OpenCharSet, CloseCharSet,
             OpenSwitches

CmdShell

   Synopsis  CmdShell [console-specification] [STARTUP[=]startup-file]

    Purpose  Start an AmigaDOS shell process.

Description  This command starts a new AmigaDOS shell process.  If the
             console-specification is provided, that will be used, otherwise
             the console specification in the Operations Settings panel is
             used.  You can specify a start-up file using the STARTUP para-
             meter.  If this is not provided, 's:Shell-Startup' is assumed.

   See Also  None

Column

   Synopsis  Column INSERT|DELETE

    Purpose  Insert or delete columns.

Description  Using the INSERT switch, you can insert a blank column at the
             cursor position, moving all columns on the right over to the
             right to accommodate the new column.  Columns that get moved
             outside the bounds of the document are not lost.

             The DELETE switch eliminates the column under the cursor and
             moves everything to the right over to fill its space.

   See Also  Line

Copy

   Synopsis  Copy

    Purpose  Copy blocked text to the clipboard.

Description  Copy, as opposed to Cut, grabs the currently blocked text and
             puts it in the clipboard, but does not remove it from the
             document.  The block is deselected upon completion of the copy.
             The selected clipboard unit for the current document is used.

             COMMAND_NOT_AVAILABLE is returned in rc if this command is used
             when no block is active.

   See Also  Cut, Paste, Erase, Delete

CreateIcons

   Synopsis  CreateIcons [ON|OFF]

    Purpose  Inquire about or alter the CreateIcons flag.

Description  If you specify either the ON or OFF parameter with this command,
             the CreateIcons flag will be changed to that state.

             This command returns the current state in result.

   See Also  None

Cursor

   Synopsis  Cursor UP|DOWN|LEFT|RIGHT [amount] [SHIFT] [ALT] [CONTROL]

    Purpose  Move the cursor around.

Description  The first parameter specifies the direction in which to move the
             cursor.  If the amount parameter is specified, the cursor will be
             moved that many positions in the specified direction.  Any of the
             switches, SHIFT, ALT or CONTROL, alter the effects of the cursor
             key just as if you had the appropriate key pressed.  See the
             Operations chapter on the effects of qualifier keys on cursor
             movement.

   See Also  Position

Cut

   Synopsis  Cut

    Purpose  Remove blocked text to the clipboard.

Description  This command grabs the currently blocked text (cels), puts them
             in the clipboard, and removes them from the document.  The
             selected clipboard unit for the current document is used.

             COMMAND_NOT_AVAILABLE is returned in rc if this command is used
             when no block is active.

   See Also  Copy, Paste, Erase, Delete

Delete

   Synopsis  Delete

    Purpose  Deletes a block from the current document.

Description  This command acts like Cut, removing blocked text from the
             document, except that it does not copy anything to the clipboard;
             the text is just removed.  Note that this command differs from
             Erase only in that it creates a "vacuum" that pulls anything to
             the right of the block in to fill the vacated space, whereas
             Erase leaves empty space where the removed text was previously.

             COMMAND_NOT_AVAILABLE is returned in rc if this command is used
             when no block is active.

   See Also  Cut, Erase

DeletePage

   Synopsis  DeletePage [FORCE]

    Purpose  Remove a page from the document.

Description  This command completely removes the current page from the
             document.  You will be prompted for confirmation of this.  Using
             the FORCE parameter suppresses this requester.

             This command is only available in Page Editing Mode.  Issuing it
             in any other mode results in a COMMAND_NOT_AVAILABLE error being
             returned in rc.

   See Also  NewPage

DisplaySettings

   Synopsis  DisplaySettings

    Purpose  Bring up the Display Settings panel.

Description  Issuing this command brings up the Display Settings panel.

   See Also  OpsSettings, FileSettings, DocumentSettings, BoxLineSettings

DocumentSettings

   Synopsis  DocumentSettings

    Purpose  Bring up the Document Settings panel.

Description  Issuing this command brings up the Document Settings panel.

   See Also  DisplaySettings, OpsSettings, FileSettings, BoxLineSettings

DrawMode

   Synopsis  DrawMode [TEXT|ATTR]

    Purpose  Change the current Drawing Mode.

Description  This command changes to the desired Drawing Mode.  Currently,
             TEXT and ATTR modes are the only ones available.  Future versions
             of Luminus may support additional modes.  See the Operations
             chapter for details on each of the Drawing Modes.

             DrawMode returns the current Drawing Mode in result.

   See Also  EditMode

EditCel

   Synopsis  EditCel [CHAR[ACTER][=]c] [ASCII[=]num] [FORE[GROUND][=]pen]
                     [BACK[GROUND][=]pen] [PLAIN] [BOLD] [ITALICS] [UNDERLINE]
                     [BLINK] [INVERSE] [CONCEALED]

    Purpose  Change the parts of a cel.

Description  Using this command, you can change the attributes of the cel over
             which the cursor is lying.  Underlying cels are not affected.

             The CHARACTER parameter lets you specify a new character to place
             in the cel.  This is a single character.  If you wish to specify
             the character using its ASCII code, use the ASCII parameter
             instead.

             The FOREGROUND and BACKGROUND parameters accept color register
             values as their arguments.  This is the color register to which
             you wish to change the foreground or background color.

             The rest of the parameters affect the text attributes of the
             cel's character.  The PLAIN parameter is a switch.  Specifying it
             resets all of the text attributes.  The others are toggles.  So
             for example, if Bold is on in the current cel, and you enter

                    EditCel BOLD

             the Bold attribute will be toggled to off.  Using PLAIN in
             combination with the others allows you to set all new attributes
             without having to worry which ones to toggle on or off to get the
             desired settings.

             EditCel returns the attributes of the cel in result as follows:

                    "character foregnd backgnd attributes..."

             where character is the character in the cel, foregnd is the
             foreground pen value, backgnd is the background pen value, and
             attributes... are the text names of whichever attributes are set.

             This command is only available in Animation Editing Mode.  Its
             use in any other mode causes a COMMAND_NOT_AVAILABLE to be
             returned in rc.

   See Also  None

EditMode

   Synopsis  EditMode [PAGE|ANIM] [FORCE]

    Purpose  Change the current Editing Mode.

Description  This command changes to the desired Editing Mode.  Currently,
             PAGE and ANIM modes are the only ones available.  Future versions
             of Luminus may support additional modes.  See the Operations
             chapter for details on each of the Editing Modes.

             When switching from ANIM mode to PAGE, you may lose some cels,
             potentially ruining your image.  You are presented with a
             requester that allows you to abort.  Using the FORCE parameter
             suppresses this requester.

             EditMode returns the current Editing Mode in result.

   See Also  DrawMode

Erase

   Synopsis  Erase

    Purpose  Erase a block from the current document.

Description  This command acts like Cut, removing blocked text from the
             document, except that it does not copy anything to the clipboard;
             the text is just removed.  Note that this command differs from
             Delete only in that it leaves empty space where the removed text
             was previously, whereas Delete creates a "vacuum" that pulls
             anything to the right of the block in to fill the vacated space.

             COMMAND_NOT_AVAILABLE is returned in rc if this command is used
             when no block is active.

   See Also  Cut, Delete

ExecuteScript

   Synopsis  ExecuteScript AmigaDOS-script

    Purpose  Execute an AmigaDOS script.

Description  This command allows you to asynchronously execute an AmigaDOS
             script.

   See Also  Rx

FileSettings

   Synopsis  FileSettings

    Purpose  Bring up the File Settings panel.

Description  Issuing this command brings up the File Settings panel.

   See Also  DisplaySettings, OpsSettings, DocumentSettings, BoxLineSettings

Font

   Synopsis  Font [fontname size]

    Purpose  Change the display's font and point-size.

Description  This command only changes the font used for the images; it does
             not change the screen's font.  The fontname parameter is the
             filename of the font.  You must include the '.font' extension.
             The size parameter is the desired point size (height) of the font
             that you want.

             This command returns the font name and size in result.

   See Also  None

GetCel

   Synopsis  GetCel

    Purpose  Get the attributes of the cel under the cursor.

Description  GetCel returns the attributes of the cel located directly under-
             neath the cursor in result as follows:

                    "character foregnd backgnd attributes..."

             where character is the character in the cel, foregnd is the
             foreground pen value, backgnd is the background pen value, and
             attributes... are the text names of whichever attributes are set.
             This command returns the same result as EditCel, but is included
             since EditCel is only available in Animation Editing Mode.

   See Also  GetLine

GetColumn

   Synopsis  GetColumn

    Purpose  Get the current column.

Description  This command returns the current cursor column in the ARexx
             variable result.

   See Also  GetLine

GetLine

   Synopsis  GetLine

    Purpose  Get the current line.

Description  This command returns the current cursor line in the ARexx
             variable result.

   See Also  GetColumn

GotoColumn

   Synopsis  GotoColumn column

    Purpose  Move to a specific column.

Description  The column parameter specifies the absolute column number to
             which Luminus should move the cursor.

   See Also  GotoLine

GotoLine

   Synopsis  GotoLine line

    Purpose  Move to a specific line.

Description  The line parameter specifies the absolute line number to which
             Luminus should move the cursor.

   See Also  GotoColumn

HorizDir

   Synopsis  HorizDir [NONE|LEFT|RIGHT]

    Purpose  Change the horizontal cursor direction.

Description  This command allows you to set the horizontal direction of the
             cursor.  HorizDir returns the current horizontal direction in
             result.

   See Also  VertDir

Insert

   Synopsis  Insert CODE[=]code|CLEARSCREEN [COLOR[=]num]

    Purpose  Insert a code into the animation.

Description  Use this command to insert non-typeable codes into your anim-
             ation.  If it is a custom ANSI code, use the CODE parameter.  Do
             not enter the escape character and opening bracket ([) for the
             code.  This is automatically done, since all ANSI codes begin
             with them.  If you want a clear screen code, use CLEARSCREEN.  If
             you don't specify a color, via COLOR, the current background
             color is used.  The num parameter is the color register number.

             This command is only available in Animation Editing Mode.  If it
             is issued in any other editing mode, a COMMAND_NOT_AVAILABLE
             error is returned in rc.

   See Also  None

JumpScreen

   Synopsis  JumpScreen [screen-name|NEXT] [ALL]

    Purpose  Jump the current window to a new screen.

Description  The JumpScreen command allows you to move an existing document's
             window to another screen.  The first parameter is either a
             screen-name or the keyword NEXT.  The screen-name must match an
             existing public screen's name exactly, and the destination screen
             must be a public screen.  Using NEXT will move to the next screen
             in Intuition's public screen list.

             The keyword ALL indicates that all document windows should be
             moved to the desired screen.

             If there are no public screens available, or the screen-name
             specified doesn't exist or can't be locked, the command drops
             result.  Otherwise, the screen on which the window is opened is
             returned.

   See Also  None

Line

   Synopsis  Line INSERT|DELETE

    Purpose  Insert or delete lines.

Description  Using the INSERT switch, you can insert a blank line at the
             cursor position, moving all lines below down to accommodate the
             new line.  Lines that get moved outside the bounds of the
             document are not lost.

             The DELETE switch eliminates the line under the cursor and moves
             everything below up to fill its space.

   See Also  Column

LineType

   Synopsis  LineType [SINGLE|DOUBLE|SINGLEDOUBLE|DOUBLESINGLE|CUSTOM|SELECT]

    Purpose  Change the current line type.

Description  This command changes to the desired line type.  The first four
             line types assumed an IBM-style font.  The line type CUSTOM
             allows for any font that may have complex box parts.  See the
             Operations chapter for details on each of the line types.

             LineType returns the current line type in result.

   See Also  None

LoadSettings

   Synopsis  LoadSettings file

    Purpose  Load a file of saved settings.

Description  The file parameter specifies the settings file to load.  You can
             specify a path with the filename.

   See Also  SaveSettings

LockGUI

   Synopsis  LockGUI

    Purpose  Locks the user interface, disabling display updates.

Description  Issue this command when you want to keep Luminus from updating
             its displays.  All window redrawing (with the exception of
             Intuition-mandated refreshes) is disabled, as well as menu
             updates.  You may still access the menus, but checkmarked items,
             for instance, may not reflect their proper state.  This is useful
             if you are going to issue a lot of display-intensive commands and
             don't want the system bogged down doing refreshes.  Updates do
             not get queued during a LockGUI.

   See Also  UnlockGUI

MoveWindow

   Synopsis  MoveWindow left top

    Purpose  Move the current window to a new position.

Description  This command's parameters accept any zero or positive coordinate
             values to which to move the current window.  This command does
             not affect the window's size, and will always keep the window
             within the screen's borders.

   See Also  ZoomWindow, UnZoomWindow, SizeWindow, ChangeWindow

New

   Synopsis  New [PORTNAME[=]ARexx-port] [SCREEN[=]public-screen]

    Purpose  Open a new, blank document.

Description  This command opens a new empty document and its accompanying
             window.  If the PORTNAME parameter is specified, the document's
             ARexx port will have the name given, instead of using the
             standard naming convention, which is to use the base name
             specified in the Operations Settings panel plus a unique numeric
             identifier.  For example, If the base name is 'LUMINUS', and you
             have two documents opened, with ARexx ports called 'LUMINUS.0'
             and 'LUMINUS.1', the next document will be called 'LUMINUS.2'.
             Using PORTNAME, you can say:

                    New PORTNAME THIRDDOC

             which will open the new document with an ARexx port named
             'MYDOC'.  If the portname specified cannot be opened, the
             document will open without an ARexx port.  The portname used will
             be returned in result, or if no port was opened, 'Untitled' will
             be returned.

             Using the SCREEN parameter, you can specify the public screen on
             which to open the document.  If the public screen specified is
             not available, or no public screen is specified, the name
             specified in the Public Screen setting in the Display Settings
             panel will be used.  If that doesn't work, the default public
             screen will be used.

             If New cannot open a new document, result will be dropped; other-
             wise, the name of the ARexx port is returned.

   See Also  Open

NewPage

   Synopsis  NewPage APPEND|INSERT

    Purpose  Add a new page to the document.

Description  NewPage adds a new, blank page to the document.  If you specify
             APPEND, the new page is placed at the end of the document, after
             all existing pages.  If INSERT is used, the new page is inserted
             at the current page, moving all subsequent pages back one to
             accommodate.

             This command may only be issued in Page Editing Mode.  If it is
             used in any other mode, a COMMAND_NOT_AVAILABLE error is returned
             in rc.

   See Also  DeletePage

NextPage

   Synopsis  NextPage

    Purpose  Move to the next page in the document.

Description  Issuing this command moves to the next page in the document, if
             there is one.  If there isn't, nothing happens.

   See Also  PreviousPage

Open

   Synopsis  Open file... [PORTNAME[=]ARexx-port] [SCREEN[=]public-screen]

    Purpose  Open one or more files.

Description  The parameter file... specifies the file (with optional path) to
             open.  You can specify more than one file to open.  Standard
             AmigaDOS pattern-matching can be used for filenames.  For
             example:

                    Open Work:Pictures/ANSI/#?.ans

             will open all files ending in '.ans' in the directory
             "Work:Pictures/ANSI".

             Each file will be opened in a separate document and window.  Open
             will return in result the names of each file (and path) opened,
             separated by a vertical bar ('|').

             See the description of New for details on the parameters PORTNAME
             and SCREEN.

             This command returns the ARexx port names in result.

   See Also  New

OpenAttributes

   Synopsis  OpenAttributes

    Purpose  Open the Attributes interactive support window.

Description  Issuing this command tells Luminus to open the Attributes
             interactive support window on the screen of the current document.
             If the window is already open on that screen, it is moved to the
             front.  If it open on another screen, it will close and reopen on
             the appropriate screen.

   See Also  CloseAttributes, OpenCharSet, CloseCharSet, OpenSwitches,
             CloseSwitches

OpenCharSet

   Synopsis  OpenCharSet

    Purpose  Open the Character Set interactive support window.

Description  Issuing this command tells Luminus to open the Character Set
             interactive support window on the screen of the current document.
             If the window is already open on that screen, it is moved to the
             front.  If it open on another screen, it will close and reopen on
             the appropriate screen.

   See Also  OpenAttributes, CloseAttributes, CloseCharSet, OpenSwitches,
             CloseSwitches

OpenSwitches

   Synopsis  OpenSwitches

    Purpose  Open the Switches interactive support window.

Description  Issuing this command tells Luminus to open the Switches inter-
             active support window on the screen of the current document.  If
             the window is already open on that screen, it is moved to the
             front.  If it open on another screen, it will close and reopen on
             the appropriate screen.

   See Also  OpenAttributes, CloseAttributes, OpenCharSet, CloseCharSet,
             CloseSwitches

OpsSettings

   Synopsis  OpsSettings

    Purpose  Bring up the Operations Settings panel.

Description  Issuing this command brings up the Operations Settings panel.

   See Also  DisplaySettings, FileSettings, DocumentSettings, BoxLineSettings

Overlay

   Synopsis  Overlay file...

    Purpose  Append one or more files onto the current document.

Description  This command attempts to append the contents of file... onto the
             current document.  The file... parameter accepts multiple
             filenames.  AmigaDOS pattern-matching can also be used.  For
             example:

                    Overlay Work:Pictures/ANSI/#?.ans

             will overlay all files ending in '.ans' in the directory
             "Work:Pictures/ANSI" onto the current document.

             All files that were overlaid, completely or partially, are
             returned in result.

   See Also  Open

Paste

   Synopsis  Paste

    Purpose  Paste text from the clipboard into the current document.

Description  This command grabs any text available from the clipboard and
             places it in the current document, using the current cursor
             position as its anchor point (top-left corner).  The selected
             clipboard unit for the current document is used.

             Paste will only grab chunks of types FTXT CHRS or ANSI CEL from
             the clipboard; no other IFF form is supported.

             COMMAND_NOT_AVAILABLE is returned in rc if this command is used
             when no block is active.

   See Also  Cut, Copy, Erase, Delete

Pause

   Synopsis  Pause KEY|TIMED[=]val

    Purpose  Insert a pause in the animation.

Description  This command allows you to insert a pause into the current
             animation.  The type of pause is specified by this command's
             parameters.  If a key-released pause is desired, use KEY.  If you
             want to use a pause that only stops for a length of time, use
             TIMED with the number of clock-ticks in val (there are 50
             clock-ticks per second).

   See Also  Insert

Position

   Synopsis  Position SOD|EOD|SOV|EOV

    Purpose  Position the cursor at a predetermined point in the document.

Description  Using the Position command, you can place the cursor at any of
             the "framing points" of the document, namely the start or end of
             the document or view.  The parameters SOD or EOD move the cursor
             to the start or end of the document, respectively.  The para-
             meters SOV or EOV move the cursor to the start or end of the
             "view" (the portion of the document currently visible in the
             document's window), respectively.

   See Also  Cursor

PresetColor

   Synopsis  PresetColor A2024|AMIGA|ANSI|EGA|FROMWB

    Purpose  Load a predefined color set in the custom screen's color
             registers.

Description  Specify one of the parameters above to load that color set into
             the custom screen registers.  This command only affects Luminus'
             own custom screen.  If this command is issued without Luminus
             having opened its own screen, a COMMAND_NOT_AVAILABLE error is
             returned.

   See Also  None

PreviousPage

   Synopsis  PreviousPage

    Purpose  Move to a previous page in the document.

Description  This command moves to the previous page in the document, if there
             is one.  If there isn't, nothing happens.

             This command is only available in Page Editing Mode.  A
             COMMAND_NOT_AVAILABLE is returned in rc if used in any other
             mode.

   See Also  NextPage

Quit

   Synopsis  Quit [FORCE]

    Purpose  Shutdown Luminus.

Description  This command tells Luminus to close all open documents and
             shutdown, including closing its custom screen, if opened.  The
             FORCE parameter tells Luminus to suppress the requester that
             would appear if you had made changes to any documents since their
             last save.  Otherwise, a requester will appear for each document
             that has modifications.

   See Also  None

RedoDisplay

   Synopsis  RedoDisplay

    Purpose  Tell Luminus to do an entire refresh of the display.

Description  This command causes Luminus to do an entire forced refresh of the
             current document window.  Some document information is recom-
             piled, the animation is redrawn, and Intuition is requested to
             update the window's imagery.

   See Also  None

Redraw

   Synopsis  Redraw speed

    Purpose  Redraw the current ANSI animation.

Description  This command causes the current animation to be redrawn from the
             first cel to the last as input into the document.  The speed
             parameter is the delay factor used in drawing the animation.
             This value is how long Luminus waits between each cel.  The
             higher the value, the longer the delay between cels, the slower
             the animation is drawn.  A value of 50 is equal to a 1 second
             pause.

   See Also  None

RestoreDefaults

   Synopsis  RestoreDefaults

    Purpose  Reset settings to internal defaults.

Description  This command will discard the current settings and return Luminus
             to its internally stored settings.

   See Also  None

Ruler

   Synopsis  Ruler [ON|OFF] [[NO]HASHES] [[NO]NUMBERS] [INTERVAL[=]num]

    Purpose  Change the attributes of the Ruler.

Description  This command's various parameters affect the state and attributes
             of the Ruler.  The Ruler is normally a pair of lines, one
             vertical, one horizontal, that intersect in the document's window
             at the mouse pointer.  The parameter ON|OFF lets you turn on or
             off the Ruler.  The second parameter, HASHES, turns on the hash
             marks that indicate character positions along the ruler's edges.
             NOHASHES shuts them off.  NUMBERS turns on hash numbering, which
             places a position number at intervals next to hash marks.  The
             interval can be controlled using the INTERVAL parameter.
             NONUMBERS turns numbering off.  Ruler returns the current state
             of the ruler in result as follows:

                    "state hash-state number-state interval"

             where state is either ON or OFF, hash-state is HASHES or
             NOHASHES, number-state is NUMBERS or NONUMBERS and interval is
             the current interval value.

   See Also  None

Rx

   Synopsis  Rx ARexx-script

    Purpose  Start an ARexx script.

Description  This command allows you to asynchronously start another ARexx
             script.

   See Also  ExecuteScript

Save

   Synopsis  Save [file] [MODE[=]mode] [LINE[=]num] [VIDEO[=]prep] [EOL[=]eol]
                  [ALTESC[=]code]

    Purpose  Save the current document to disk.

Description  This command saves the current document's contents to a file.
             The file parameter is the filename under which you wish to save
             it, with optional pathname.  If you want to change the way the
             file is saved without resetting your File Settings, some
             additional parameters are available.

             MODE lets you change the file format by which your file will be
             saved.  The available modes are ASCII (only in Page Editing
             mode), ANSI, and IFF.

             The LINE parameter lets you set the maximum line length that will
             be saved before a newline is placed.  This parameter is ignore if
             saving in IFF mode.

             The VIDEO parameter lets you specify the type of preparation code
             that will be prepended to the file during its save.  Available
             preps are NONE, HOME, CLEAR.

             The EOL parameter lets you set the type of newline that will be
             used.  Available types are CR (carriage-return only), LF (line-
             feed only), and CRLF (carriage-return and linefeed).

             The ALTESC parameter tells Luminus to use an alternate escape
             character instead of ASCII code 27.  The character to be used is
             specified after ALTESC.

   See Also  None

SaveSettings

   Synopsis  SaveSettings [file]

    Purpose  Save the current settings.

Description  If the file parameter is specified, the current settings will be
             saved to that file.  A path can be specified with the filename.
             If the file parameter is omitted, the settings will be saved
             using the last known filename.  If no filename is used,
             'Luminus.prefs' will be used.

   See Also  LoadSettings

SizeWindow

   Synopsis  SizeWindow width height

    Purpose  Change the current window's size

Description  This command's parameters accept any positive value greater than
             or equal to 100 for width, and 75 for height.  This command does
             not affect the window's position and will not size the window
             larger than would fit on the current screen.

   See Also  ZoomWindow, UnZoomWindow, MoveWindow, ChangeWindow

StatusLine

   Synopsis  StatusLine [ON|OFF] [TOP|BOTTOM]

    Purpose  Change the state and/or position of the status line.

Description  This command tells Luminus how and whether or not to display the
             status lines in the documents' windows.  The parameter ON or OFF
             turns on or off the status line in the current document only.
             The parameter TOP (or BOTTOM) sets the global flags in Luminus
             for where the status line should be displayed in all document
             windows.

             StatusLine return the current state of the status line in result
             as follows:

                    "state position"

             where state is either ON or OFF, and position is either TOP or
             BOTTOM.

   See Also  None

Text

   Synopsis  Text text

    Purpose  Place text into the document.

Description  The text parameter can be any ASCII characters starting at the
             first non-whitespace character after the command until the end of
             the line.  Strings which contain spaces do not have to be sur-
             rounded by quotes, and quotes are treated as literal text as
             well.  The Text command obeys the current directional settings.

   See Also  None

TextBox

   Synopsis  TextBox text [LINETYPE[=]type] [SELECT[=]character]
                     [BEVEL[=]bevel] [JUST[IFICATION][=]justification]
                     [LEFT[MARGIN][=]num] [RIGHT[MARGIN][=]num]

    Purpose  Place outlined/justified text in the document.

Description  The first parameter, text, is a quoted text string to place.  It
             may contain multiple lines, which should be separated by ASCII
             code 10 (hex 0x0A, a linefeed).  Be default, the text is left-
             justified using the current cursor position as the origin.  This
             behavior can be modified (see below).

             The LINETYPE parameter lets you specify the type of line that
             should be used for a box drawn around the text.  The line-types
             available are:  NONE, SINGLE, DOUBLE, SINGLEDOUBLE, DOUBLESINGLE,
             CUSTOM, and SELECT.  If you use the SELECT type, specify the
             character to be used by using the SELECT parameter.

             If you want the box to have a bevelled appearance, use the BEVEL
             parameter.  Valid bevel values are NONE, RAISED and RECESSED.

             If the text should be justified, use JUSTIFICATION.  Valid
             justification values are NONE, LEFT, CENTER and RIGHT.  If you
             use justification, you should specify left and right margin
             values, using LEFTMARGIN and RIGHTMARGIN.  If either of these
             parameters is missing, defaults values are used:  1 for the left
             margin, the maximum document width for the right margin.  Note
             that when justification is used, the current column position is
             ignored and not used, while the line position is.

   See Also  Box, BevelBox

TextPen

   Synopsis  TextPen [pen] [[NO]CYCLE]

    Purpose  Change the text drawing pen.

Description  This command changes the foreground color used for text and
             drawing.  The pen parameter accepts a color register number as
             its argument, starting at pen 0 to the maximum pen usable on the
             screen.  If the CYCLE keyword is supplied, the background color
             cycling flag is turned on.  NOCYCLE turns it off.

             TextPen returns the current foreground pen and cycle flag in
             result as follows:

                    "pen-number cycle-flag"

             where pen-number is the numeric color register, and cycle-flag is
             either CYCLE or NOCYCLE.

   See Also  BackgroundPen

UnlockGUI

   Synopsis  UnlockGUI

    Purpose  Unlocks the user interface, (re)enabling display updates

Description  This command is the counterpart to the LockGUI command.  It
             clears the display-locking flag, allowing Luminus to update its
             displays when called-for.  When the UnlockGUI command is issued,
             display will not immediately be refreshed and updated.  To get
             the displays up-to-date, issue a RedoDisplay command immediately
             after issuing the UnlockGUI.

   See Also  LockGUI

UnZoomWindow

   Synopsis  UnZoomWindow

    Purpose  Restore a window to its original size and position.

Description  This will cause the current window to return to its original size
             and position, becoming "unzoomed."  If the window is already
             unzoomed, nothing will happen.

   See Also  ZoomWindow

UseAppIcon

   Synopsis  UseAppIcon [ON|OFF]

    Purpose  Inquire about or alter the state of Luminus' AppIcon.

Description  If you specify either the ON or OFF parameter with this command,
             the AppIcon flag will be changed to that state.

             This command returns the current state in result.

   See Also  None

VertDir

   Synopsis  VertDir [NONE|UP|DOWN]

    Purpose  Change the vertical cursor direction.

Description  This command allows you to set the vertical direction of the
             cursor.  VertDir returns the current vertical direction in
             result.

   See Also  HorizDir

WindowToBack

   Synopsis  WindowToBack

    Purpose  Move the current window to the back.

Description  This command moves the currently active document's window behind
             all other windows on its screen (except for backdrop windows).

   See Also  WindowToFront, ZoomWindow, UnZoomWindow

WindowToFront

   Synopsis  WindowToFront

    Purpose  Move the current window to the front.

Description  This command moves the currently active document's window to the
             front of whatever screen it's on, and pops the screen to the
             front of the display.

   See Also  WindowToBack, ZoomWindow, UnZoomWindow

ZoomWindow

   Synopsis  ZoomWindow

    Purpose  Resize a window to its "zoomed" size and position.

Description  Every Intuition window has two different sets of the position and
             size values.  When a window opens initially, it's said to be in
             its "unzoomed" state.  Clicking its zoom gadget causes it to
             revert to its "zoomed" state, which is generally smaller and off
             to the side somewhere.  Luminus's document windows default to a
             "zoomed" size of about 100 x 75 pixels in the upper-left corner
             of the screen.

             Issuing this command will cause the window to revert to its
             "zoomed" state.  If the window is already zoomed, nothing will
             happen.

   See Also  UnZoomWindow

Command Summary

This sections provides a sort of quick-reference of all of Luminus' ARexx
commands.

ActivateWindow
AtCursor
Attribute [PLAIN] [BOLD] [ITALICS] [UNDERLINE] [BLINK] [INVERSE] [CONCEALED]
AttrMode [FORE[GROUND]] [BACK[GROUND]] [ATTR[IBUTE]]
BackgroundPen [pen] [[NO]CYCLE]
Border [ON|OFF]
Box left top width height [line-type [ascii-code]]
BoxLineSettings
ChangeWindow left top width height
Clear PAGE|DOCUMENT [FORCE]
Close [FORCE]
CloseAttributes
CloseCharSet
CloseSwitches
CmdShell [console-specification] [STARTUP[=]startup-file]
Column INSERT|DELETE
Copy
CreateIcons ON|OFF
Cursor UP|DOWN|LEFT|RIGHT [amount] [SHIFT] [ALT] [CONTROL]
Cut
Delete
DeletePage [FORCE]
DisplaySettings
DocumentSettings
DrawMode [TEXT|ATTR]
EditCel [CHAR[ACTER][=]c] [ASCII[=]num] [FORE[GROUND][=]pen]
        [BACK[GROUND][=]pen] [PLAIN] [BOLD] [ITALICS] [UNDERLINE] [BLINK]
        [INVERSE] [CONCEALED]
EditMode [PAGE|ANIM] [FORCE]
Erase
ExecuteScript AmigaDOS-script
FileSettings
Font [fontname size]
GetCel
GetColumn
GetLine
GotoColumn column
GotoLine line
HorizDir [NONE|LEFT|RIGHT]
Insert CODE[=]code|CLEARSCREEN [COLOR=num]
JumpScreen screen-name|NEXT [ALL]
Line INSERT|DELETE
LineType [SINGLE|DOUBLE|SINGLEDOUBLE|DOUBLESINGLE|CUSTOM|SELECT]
LoadSettings file
LockGUI
MoveWindow left top
New [PORTNAME[=]ARexx-port] [SCREEN[=]public-screen]
NewPage APPEND|INSERT
NextPage
Open file... [PORTNAME[=]ARexx-port] [SCREEN[=]public-screen]
OpenAttributes
OpenCharSet
OpenSwitches
OpsSettings
Overlay file...
Paste
Pause KEY|TIMED[=]val
Position SOD|EOD|SOV|EOV
PresetColor A2024|AMIGA|ANSI|EGA|FROMWB
PreviousPage
Quit [FORCE]
RedoDisplay
Redraw speed
RestoreDefaults
Ruler [ON|OFF} [[NO]HASHES] [[NO]NUMBERS] [INTERVAL[=]num]
Rx ARexx-script
Save [file] [MODE[=]mode] [LINE[=]num] [VIDEO[=]prep] [EOL[=]eol]
     [ALTESC[=]code]
SaveSettings [file]
SizeWindow width height
StatusLine [ON|OFF] [TOP|BOTTOM]
Text text
TextBox text [LINETYPE[=]type] [SELECT[=]character] [BEVEL[=]bevel]
        [JUST[IFICATION][=]justification] [LEFT[MARGIN][=]num]
        [RIGHT[MARGIN][=]num]
TextPen [pen] [[NO]CYCLE]
UnlockGUI
UnZoomWindow
UseAppIcon [ON|OFF]
VertDir [NONE|UP|DOWN]
WindowToBack
WindowToFront
ZoomWindow

Miscellaneous

This chapter basically covers, well, miscellaneous things that usually can't
be place anywhere else, plus just some tidbits of information.

Caveats

The Amiga supports multiple menu selections during one menu event.  If you are
not familiar with this, what it does is allow you to click with the left mouse
button on several menu items without having to re-access the menu with the
right mouse button.  Luminus is designed to respond to these "chained" menu
events.  Certain menu items allow you to close and re-open windows, such as
screen jumping and changing the screen mode of the custom screen.  When the
window that generated the menu events is closed, its menu structure is temp-
orarily "lost", and any chained menu selections with it.  So beware when
multi-selecting an item that may close your window.

The Future

The following items are on my to-do list for future versions of Luminus.  If
you think of an item that is not in this list, please feel free to drop me an
e-mail or postcard.

- Scan modules.  These would be mini-scripts that could instruct Luminus on
  how to "redesign" an animation.

- Line drawing mode.

- Fonts.  Possibly an internal-format font set for large lettering, and sup-
  port for drawing Amiga bitmapped fonts.

- Undo and Redo.