
                              SEEKER MACROS
                              -------------

Seeker Macros enable you to set up Seeker to perform repetetive or complex
tasks. They can be run using the standard Macro playback [m] or attached
to a button for continuous use. Although there are some limitations when
using Macros, these limitations are minor and with a little forethought
they can be overcome.

Several example macros (with comments) have been supplied to give you an
insight on ways that macros can be implemented.

Some Seeker functions are disabled during Macro recording and playback. These
functions include the Seeker Editor and Auto Launching. These functions are
disabled to eliminate any problems that may be caused due to changing
button commands and file positions. Macro recording is also disabled
during recording or playback. You can however launch macros from within other
macros.

Other Functions that are disabled or modified during macro recording
or playback:
Auto Scrolling - Disabled (when drag selecting files/dir's).
Hot Keys - Disabled.
Paths used in List Boxes are limited to 80 characters.
Slider Movement - This relies on multiple LClicks rather than a single
                  LClick and HOLD.

CREATING A MACRO SCRIPT
-----------------------
The simplest and easiest way to create a macro script is to record it. This
is achieved with an LClick on the [M] button and selecting RECORD when
prompted (Keyboard: M ). Enter a name for your macro and Seeker will begin
recording it. MACRO will be displayed in the top centre of the Seeker
display - this obviously indicates you are recording.

When Seeker begins to record a macro it will first set the List Box sorting
to the default (ALPHA Dir's, Files). It will then check the file & directory
protection and Hidden switches ( [F], [D] & [H] ) and store them in the
first line of the macro with the macro identifier MACRO#. Following this
Seeker will store the current paths for each List Box. It will also change to
the Bank Number of Button Row 1. That Bank Number will also be stored. All of
this is to ensure that the Macro playback starts with File and Directory
protection, Hidden Display, Paths and Button Bank all set correctly. Seeker
will then begin recording all mouse clicks and keyboard input.

Once you have completed your recording press ESCape. 'Macro Completed' will
be displayed.

NOTES: 1. Internal buttons will act normally when recording, however,
          USER buttons will NOT launch.
       2. Always keep in mind that what is displayed in the List Boxes
          while recording, may and probably will be different during
          macro playback.
       3. The NAME (select files by name) button is very useful for
          processing files. (See DEMO6.MAC for an example of this)
       
The recorded macro script is a simple text file. This allows you to edit
your macro (or create one from scratch) in a standard text editor. The macro
command language is outlined below. 

MACRO PLAYBACK
--------------
To playback a macro script LClick on the [M] button and select PLAYBACK when
prompted (Keyboard: m). Enter the name of the macro and it will start to
playback. Alternately, if you have installed a Macro into a Button, click on
the Button containing your Macro.

When your macro begins to playback, Seeker will first set the File, Dir and
Hidden switches to their recorded state. Seeker will also deselect all files
and directories that may be highlighted. This initial startup procedure can
be turned off if required (see below - MACRO#).

'Macro Completed' will be displayed on completion of the Macro.
If you wish to terminate your macro before it has completed you can press the
ESCape key if Seeker is still active. If you have launched an external program
press CTRL C which will cause the Macro to terminate when Seeker becomes
active again.

If your macro includes an external launch, and the external program generates
an error, your macro will halt. 

NOTE:
 When an external program completes, Seeker checks the exit status of the
 program when it has completed. If the program does not exit cleanly,
 Seeker Commander will advise you: 'Error or Abnormal Exit' and pause.
 Unfortunately there are quite a few programs out there that do not exit
 legally. In effect these programs exit as though there has been an error,
 even though there was no error within the program.
 If you launch an external program that generates a 'false' error, you can
 override the error checking and consequently the Macro halting by using
 the error override switch. By appending ~ to the command switches for your
 button, Seeker will ignore any error generated by that button and continue.
 It should be remebered however, that if a REAL error is encountered when
 launching that button, it will also be ignored.


INSTALLING A MACRO INTO A BUTTON
--------------------------------
Installing a macro into a Button is quite simple. If you wish to insert
a macro into a Button using the Seeker Editor, use the command switch #M
This indicates that this button is a macro and will be treated as such.
Rapid Insertion is also possible, however, you must name your macro with
the extention .MAC (MY_MACRO.MAC not just MY_MACRO). This will ensure the
#M switch is appended. If your macro does not end in .MAC the default command
switches (#A&L!) will be appended, which will generate an error on playback.

Regardless of how you install your macro button, the Path to it will be
ignored. ALL macros MUST reside in the SEEKER\MACROS directory.

MACRO COMMANDS
--------------
Although all macro commands are available to the user, some of them are
generated internally when recording and are not easily implemented by the
user. It is recommended (until you are conversant with the MACRO commands)
that you record your macro and edit it if required rather than create it
from scratch.

Any command that uses text (MSG# for example) must enclose the text in
inverted commas if the text contains spaces. eg...
   MSG#"This is a Message" - CORRECT
   "MSG#This is a Message  - ACCEPTABLE
   MSG#This is a Message   - INCORRECT
In addition, the text and command cannot exceed 80 characters.

MACRO#???      INITIALISER. ALL macros MUST begin with the Initialiser
               on the very FIRST line.
               ?:  File Protection Switch - 0=OFF 1=ON
               ?:  Dir  Protection Switch - 0=OFF 1=ON
               ?:  Hidden Files Displayed - 0=NO  1=YES
               If these initialiser switches (??? - 0's or 1's) are omitted,
               Seeker will not deselect any files or dir's that are selected
               or reset the File, Dir or Hidden Switches. This allows you to
               select files etc and use your macro to process them.

LCLK#x,y!z     LEFT MOUSE BUTTON CLICK  - INTERNAL
RCLK#x,y!z     RIGHT MOUSE BUTTON CLICK - INTERNAL
               x=Horizontal Position
               y=Vertical Position
               z=Qualifying Keys Used (See below for description)

REQ#?          REQUESTER RESPONSE - INTERNAL
               When recording a macro, any button requester that is
               generated will have your response recorded.
               3 Response Requester
               ?: 0 = Bottom Button
               ?: 1 = Left Button
               ?: 2 = Right Button
               2 Response Requester
               ?: 0 = Left Button
               ?: 1 = Right Button

;              COMMENT
               Anything following ; will be ignored.
               This allows you to comment on the commands (See DEMO MAC's)

TEXT#?         TEXT INPUT
               ? = Text to supply
               ?: TEXT = Use text supplied by GTEXT# command
               When recording a macro, any prompt that requires text will
               have the text you input recorded (See DEMO MAC's)
               Some commands REQUIRE the TEXT# command. If it is not present
               an error will be generated.
               The TEXT# command can also utilise the text retrieved with
               the GTEXT# command. By using the TEXT# command thus:
               TEXT#TEXT (see GTEXT# below or DEMO_11.MAC for an example).
               NOTES:
                1. If a command requires the TEXT# command, the TEXT# command
                   must be on the following line. 
                2. The actual text attached to this command cannot exceed
                   75 characters. (Keep this in mind when setting a new path)

GTEXT#???      GET TEXT FROM USER
               ??? = Question text for user
               When a macro is playing back and text is required, normally
               the TEXT# command will supply that text (see above).
               By using the GTEXT# command, Seeker will prompt the user for
               the required text.
               The GTEXT# command can also be used to get text before
               it is required. By doing this, the text entered can be used
               by the TEXT#, IF#, MSG# or WAIT# commands later in the script.
               The text entered will be valid until the GTEXT# command is
               used again. Although the text retreived by GTEXT can be up
               to 80 characters it will not be stored if it exceeds 13
               characters.
               (See DEMO_11.MAC for an example)

PATH#?         NEW PATH
               ?: L = Left List Box
               ?: R = Right List Box
               PATH# will look on the next line for the TEXT# command
               which should contain the new path. If the next line is
               a comment( ; ) line the path will not change. Anything on
               the next line other than a comment, TEXT# or GTEXT# will
               generate an error.

SIDE#?         ACTIVATE LIST BOX
               ?: L = Left List Box
               ?: R = Right List Box
               Similar to the PATH# command, however no new path is required
               or used. This command will activate a List Box.

BUTN#Butn,Bank BUTTON ACTIVATE
               (Button Number,Bank Number)
               This command will activate a specific Button from a specific
               Bank. If Button Number is 0 Seeker will just change Banks.
               The ,Bank number is not required if you do not wish to change
               to a different bank. eg...
               BUTN#0,1 - Switch to Bank 1. Don't activate any button
               BUTN#3   - Activate Button number 3 from the currently active
                          bank. (See DEMO8.MAC for an example)

WAIT#????,??   WAIT FOR ???? milliseconds,?? text
               The WAIT# command is used to pause your macro for a specified
               time. By supplying the optional text WAIT# can be used to
               display a message while it is paused. If you wish to use
               the TEXT supplied by the GTEXT# command in your wait message
               use %T within your text (see MSG# command below)
               The wait command can be used to slow your macro down, giving
               you the opportunity to abort if required (fast macros may not
               pick up an ESCape key press).
               While Recording press w or W to initiate a pause.
               WAIT#2000 - Pause for 2 sec's ('Paused...' will be displayed)
               WAIT#2000,"Hello User" - Pause 2 sec's ('Hello User' diplayed)

MSG#??         DISPLAY A MESSAGE
               ? = Message_Text
               The MSG# command will display the text supplied and wait for
               a key press or mouse click.
               If you use the @ within your message it will be converted
               into a 'Titled Message'. A Titled Message will put the first
               'section' of text within a highlight bar. The rest of the text
               will be below the title.
               If you wish to use the TEXT supplied by the GTEXT# command
               use %T within your message.
               MSG#"Hello there"                         - CORRECT
               MSG#" Title @ Message "                   - TITLED MESSAGE
               MSG#"Hello User@Press a key to continue"  - TITLED MESSAGE
               MSG#"Text entered at Requester was: %T"   - Use supplied TEXT

SDOS#????      SEND DOS COMMAND
               This command allows you to issue a DOS command. The command
               should be entered directly after the SDOS#.
               If you follow your command with Seeker command #switches they
               will be acted on accordingly. (See DEMO4.MAC) 

SMAC#?         SEND MACRO COMMAND
               ? = new_macro_name (eg..MYMACRO.MAC)
               ? = ASK
               This command allows you to launch a new macro from a macro
               that is already playing back. By using SMAC you can chain
               a series of macros together. (See DEMO5.MAC)
               When the SMAC command is used, macro playback will terminate
               and the new macro will take over. This means that SMAC will
               be the last command acted on within your macro.
               If you use the ASK switch instead of a macro name you will
               be prompted for the new macro to playback.
               NOTE: If you relaunch the same macro that is running - it will
                     cause an endless loop.
                     This potential error condition has been left available
                     to you. It is recommended that you use the WAIT# command
                     to allow the opportunity to abort the loop when required.
                     (See DEMO7.MAC for an example)

GOTO#?         GOTO
               ? = LABEL to jump to
               ?: ASK = Prompt Uer for Label to GOTO
               The GOTO# command allows you to jump to a specific line in
               your macro. (See DEMO8.MAC or DEMO_11.MAC for examples)
               eg...
               MY_LABEL:           <- The Label Name
               GOTO#MY_LABEL       <- The Goto Label command
               GOTO#ASK            <- Prompt User for Label to jump to

?:             LABEL
               ? = Label_Name
               The colon signifies that this line is a GOTO label.
               If a label has been jumped to with the GOTO command it's
               condition is true otherwise it's condition is false.
               This means that if you follow the label with the IF# command
               it will be true after a GOTO jump, but false if it was not
               reached because of a GOTO. Any other command following the
               LABEL other than the IF# command will set its condition to
               false. (See DEMO8.MAC or DEMO_11.MAC for examples)
               eg...
               MY_LABEL:           <- The Label Name
               GOTO#MY_LABEL       <- The Goto Label command

ASK#????       ASK USER FOR REPSONSE
               ? = Question text for user       
               The ASK# command will prompt the user for an ABORT/CONFIRM
               response. ASK# is used in conjunction with IF#, ELSE#, ENDIF#.
               If the user selects ABORT at the requester the result will
               be 0. If the user selects CONFIRM the result will be 1.

IF#?           TEST FOR ACTION
               ?: 0 = If ASK# returned ABORT then do the following..
               ?: 1 = If ASK# returned CONFIRM then do the following..
               ?: Filename = If this filename exists in the currently
                             Active List Box then do the following..
               ?: TEXT     = Use the text supplied by the GTEXT command.
                             TEXT will be searched for in the currently
                             Active List Box.
               The IF# command is used in conjunction with the ENDIF#
               command and the optional ELSE# command.
               (See DEMO_09.MAC for a basic example)
               (See DEMO_10.MAC for a simple example)
               (See DEMO_11.MAC for a complex example)

ELSE#          ALTERNATE ACTION
               When using the IF# command, if the response is not true
               then perform the following instead. The ELSE# command is
               optional.
               (See DEMO_09.MAC for a basic example)
               (See DEMO_10.MAC for a simple example)
               (See DEMO_11.MAC for a complex example)

ENDIF#         END OF TEST
               Any IF# command MUST be completed with ENDIF#. This is where
               the MACRO will resume once the IF# test has been completed.
               (See DEMO_09.MAC for a basic example)
               (See DEMO_10.MAC for a simple example)
               (See DEMO_11.MAC for a complex example)

ENDMACRO       END OF MACRO SCRIPT
               You *MUST* finish your Macro with ENDMACRO.
               Although some commands make the ENDMACRO command inoperative,
               it is much better to include ENDMACRO at the end of EVERY
               macro script.
               
               
QUALIFYING KEYS
---------------
When a Left or Right Mouse Button click is recorded, any qualifying keys that
are also pressed when the mouse is clicked are also recorded. These keys are
assigned numbers. The following table lists the numbers for each combination
of qualifying keys:

0  = No Qualifying keys (Just a Click)
1  = Right Shift
2  = Left Shift
3  = Left & Right Shift
4  = Ctrl
5  = Ctrl - Right Shift
6  = Ctrl - Left Shift
7  = Ctrl - Left & Right Shift
8  = Alt
9  = Alt - Right Shift
10 = Alt - Left Shift
11 = Alt - Left & Right Shift
12 = Alt - Ctrl
13 = Alt - Ctrl - Right Shift
14 = Alt - Ctrl - Left Shift
15 = Alt - Ctrl - Left & Right Shift

