Logo2
Logo
bigstockphoto_Businesswoman_Sit_With_Noteboo_227734
 

ARexx

The Directory Opus 5 ARexx port name is DOPUS.x, where x is
the invocation count of the program (the first and most often used
one is DOPUS.1). Since ARexx scripts launched from Directory
Opus do not automatically inherit the command address, you may
want to use the {Qp} command sequence in Opus functions (this is
described elsewhere in the manual).
If a command returns a value or information, the data will
generally be returned in the RESULT variable. The only
exceptions to this are the dopus getstring and lister getstring
commands (see below) which return information in the special
DOPUSRC variable. Error codes are returned in the RC variable.
The ARexx command set is very comprehensive and flexible.
Almost complete control of listers in name mode is offered, along
with the ability to launch functions and commands. You can add
your own commands to Opus via ARexx scripts which are loaded
automatically - the commands appear identical to the built-in
functions. You can even replace the default commands with your
own.
There is also a powerful custom handler ability. This allows your
ARexx program to receive messages from Opus for a variety of
user actions, including lister and icon events. See the section on
Custom Handlers on page 241 for more information.

ARexx Commands
For simplicity, the Directory Opus 5 command set is arranged in a
hierarchical structure, with only three main (or base) commands:-
dopus, lister and command.
dopus
The first base command is dopus. This is a general purpose
command, and allows you to perform functions not falling into the
other categories.
dopus addappicon <port> <label> <id> [pos <x> <y>]
[icon<filename>] [quotes] [info] [snap] [close]
[local] [locked] [menu <stem>] [base <base>]
This command allows you to add your own AppIcons to the
DOpus (and optionally the Workbench) screen from ARexx.
You can specify an icon image to use, the label of the icon and
the position on the screen, as well as several other
parameters. You can also specify the items for the pop-up
menu for the new icon. Opus sends messages to the message
port you specify - see the example scripts provided for more
information on how to receive and process these messages.
The parameters for "addappicon" are:-
port - the name of the port messages are sent to
label - the icon label (text displayed under the icon)
id - your own ID for the icon; this is returned in
messages
pos - position for the icon (xy coordinates)
icon - optional pathname of icon file to use
(without the .info suffix)
quotes - specify this keyword if you want filenames
quoted when sent to the message port
info - if you want Information to work on this icon
snap - if you want Snapshot to work on this icon
close - if you want Close instead of Open in
the pop-up menu

local - if you want the icon to be local to Opus
(and not appear on Workbench)
locked - the icon will start out locked in position,
unable to be moved
menu - name of a stem variable containing
your own menu items
base - allows you to specify the base ID of
messages sent from the pop-up menu
The menu parameter allows you to specify your own items
for the icon's pop-up menu. The stem variable must be in the
following format:
stem.COUNT - number of items
stem.0 - item 1
stem.1 - item 2
etc.
If you specify "---" as an item, a separator bar will appear.
When you receive a message that the user has selected one of
these menu items, the message will contain the ID of the item.
This is the value corresponding to the item's position in the
stem array (eg 0 for item 1, 1 for item 2, etc). If the base field is
specified, the value given for the base will be added to this
ID.
This command returns an appicon handle in RESULT if it is
successful. This same handle can be passed to dopus
setappicon to modify the icon, and must be passed to dopus
remappicon to remove the appicon when you are finished. If
you do not specify an icon file to use then the system's default
"tool" icon will be used for the image.
Messages from the appicon are sent to the port you specified.
The messages are structured in much the same way as
messages sent from listers, so there's no reason you shouldn't
be able to use the same code for both. For more information,
see the Custom Handlers section on page 241.

dopus addtrap [abort |<command>] <handler> [port
<portname>]
This command allows your script to trap the progress bar's
abort button or any Opus internal command. Specify the
abort keyword to trap the abort message, or the name of the
internal command you wish to trap. handler is the name of
your custom handler message port. If you pass the name of a
message port with the optional port keyword, the message
will be sent to that port instead of your usual handler port.
This can be very useful when used with abort if your handler
is busy doing something synchronously when the abort is
pressed. If the abort port is on a separate process, it may be
able to interrupt the main handler process using signals for
instance. The dopus remtrap command is used to remove
trapped functions. See the Custom Handlers section on page
241 for more information on the messages sent.

dopus back
This command moves the Directory Opus 5 window (and
screen) to the rear of the display.

dopus command <name> program <scriptname> [desc
<description>] [template <template>] [source] [dest]
This command provides the ability to add new internal
commands to Directory Opus, or to replace existing
commands. It is generally called from within the init function
of an Opus ARexx module and the program parameter will be
the name of that module. The program field is mandatory,
and Opus will run the script name you provide here
whenever this function is invoked. See ARexx modules and
the example script on page 248 for more information.

dopus error <code>
This command is used to retrieve meaningful error messages
when passed an Opus ARexx error code. For example,
> dopus error 1
--> File rejected by filters
> dopus error 10
--> Invalid lister handle

dopus front
This command moves the Directory Opus 5 window (and
screen) to the front of the display.

dopus getfiletype <filename> [id]
This command allows you to query a file to see if it is
recognised by Directory Opus 5. <filename> is the name of the
file, including the full path. By default, if the file is
recognised the Filetype description string will be returned in
RESULT. If you specify the id keyword, the Filetype ID will
be returned instead. For example,
> dopus getfiletype ram:testfile.lha
--> LHA Archive
> dopus getfiletype ram:picture.jpg id
--> JPEG

dopus getstring <text> [secure] [<length>] [<default]>
[<buttons>]
This command allows you to prompt the user to input a text
string. <text> is a string of text to be displayed in the
requester, and should be surrounded by quotes if it contains
spaces. The secure keyword causes the string to be displayed
as asterisks, which can be useful for passwords. <length> is
the maximum length of the string to accept and defaults to 80
if not specified. <default> is the default value of the string;
that is, the text you wish to initially appear in the field.
<buttons> are the buttons you wish the requester to have;
each button should be separated by a vertical bar character. If
the buttons parameter is omitted the requester will have a
single button marked 'OK'. For example,
> dopus getstring '"Please enter some text" 40 ""Okay|Cancel'
This would display a requester with the string "Please enter
some text", a maximum input length of 40 characters, no default
text, and buttons labelled Okay and Cancel.
The string (if any) is returned in RESULT. The cardinal
number of the selected button is returned in the special
variable DOPUSRC. In the above example, if the user clicked
Okay, DOPUSRC would contain 1, and if the user clicked
Cancel it would contain 0. This command and the lister
getstring command are the only ones that use the DOPUSRC
variable currently, but this may change in the future.
+Please note that previous versions of Opus 5 did not clear
RESULT if an empty string was entered. Make sure that this
change does not affect your scripts.

dopus read <filename>
dopus read <handle> <filename>
dopus read <handle> quit
The read command is provided to allow you greater control
over the Opus text viewer. They basically allow you to open
a viewer and view multiple files in it one by one before
closing it again. You use the viewer handle in much the same
way as you would a lister handle. For example,
> dopus read ram:file1.txt
--> 121839492
> dopus read 121839492 ram:file2.txt
--> 121839492
> dopus read 121839492 quit
--> 0

dopus remappicon <handle>
Removes an appicon that was added previously with the dopus
addappicon command.

dopus remtrap [abort | <command>] <handler>
Disables the trapping of the progress bar's abort button or the
specified Opus internal command as initiated with the dopus
addtrap command. If you specify "*" as the command, all
traps added for this handler will be removed. handler is the
name of the message port as specified inthe dopus addtrap
command.

dopus request <text> <buttons>
This command allows you to request a choice from the user.
<text> is a string of text to be displayed in the requester.
<buttons> are the buttons you wish the requester to have;
each button should be separated by a vertical bar character.
For example,
> dopus request '"Please choose an option" "
Option 1|Option 2|Option 3"' (all one line)
This would display a requester with the string "Please choose
an option", and three buttons labelled Option 1, Option 2 and
Option 3.
The cardinal number of the selected button is returned in RC.
The last button supplied (Option 3 in this case) is designated a
Cancel button, and so returns the value 0. Therefore, the values
returned by this example are 1, 2 and 0 respectively.

dopus screen
This command returns information about the Opus screen in
the following format:-
<name> <width> <height> <depth> <barheight>
If Opus is iconifiedit does not have a screen. In this case RC
will be set to 5. You can use this to find out whether or not
Opus is currently iconified. Here is an example of the output:
> dopus screen
--> DOPUS.1 640 512 2 10
The barheight value is useful if you intend to open listers or
other windows just below the screen title bar.

dopus send <port name> <string>
This command does nothing to DOpus itself, but instead
makes it easy for you to send a string (or any length) to
another ARexx task (via a message). The string is supplied in
Arg0 of the message sent to the named port.

dopus setappicon <handle> <item>
This allows you to do things to AppIcons added with the
dopus addappicon command. Valid <item> fields are :-
text <text>
Changes the icon label.
busy [on |off]
Make icon busy or non-busy.
locked [on |off]
Make icon locked or unlocked.
If an icon is busy, it is unselectable by the user. It will not
respond to double-clicks, pop-up menu events,
drag'n'drops, etc. The icon image is ghosted when it is
busy. When an icon is locked, its position can not be
changed and it can not be moved manually by the user, nor
will a CleanUp will not affect it.

dopus version
The version command returns a string in the format <version>
<revision> and is useful in ARexx scripts for determining if
certain features exist.

lister

The next base command, lister, allows you to control listers and
entries within listers.

lister add <handle> <name> <size> <type><seconds>
<protect> <comment>
This command adds an entry to the specified lister. <name> is
the full name of the entry; <size> is the size of the entry; <type>
is the type of the entry (less than 0 for a file, greater then 0 for a
directory); <seconds> is the datestamp of the entry in seconds
from 1/1/78; <protect> is the protection bits of the file (in ascii
format); <comment> is the comment of the entry (if any). Valid
entry types are:-
0 device
1 plain directory
-1 plain file
2 directory in assign colour
-2 file in device colour
3 directory in bold (link)
-3 file in bold (link)
4 directory in assign colour and bold
-4 file in device colour and bold
+ After a 'lister add' command, the display is not updated
until you execute a 'lister refresh' command.
For example,
> lister add 121132636 '"My file!"' 12839 -1 540093905
prwed my comment

lister addstem <handle> <stem>
This command adds files to a lister via a stem variable. It is
more powerful than the lister add command and should be
used in preference. The fields of the stem variable are very
similar to those returned by a lister query <handle> entry stem
command (in fact, you could pass the result the query
directly to an addstem to add an identical entry to another
lister.) The fields that are used are :-
name - name of entry
size - file size
type - type of entry (same as for lister add)
protstring - protection bits (ASCII string, eg "rwed")
protect - protection value (number, used if
protstring is not given)
comment - file comment
datestring - creation date and time (ASCII string)
date - number of seconds since 1/1/78 (used
if datestring is not given)
filetype - ascii string for file type display
selected - 0 or 1
version - version number
revision - revision number
verdate - version date string
userdata - user data (value, not a string)
display - custom display string
menu - custom pop-up menu
base - base ID for pop-up menu
Not all of these fields are required. As a bare minimum you
should specify either the name or the display field.
The display string allows you to specify a completely custom
string to display for the entry. None of the other information
will be displayed if this string is supplied. The maximum
length is 256 characters.
The userdata field allows you to specify your own ID value (or
any other value) to be associated with this entry. Its main
usage is with the custom pop-up menu and custom handlers.
The menu field allows you to specify a stem variable
containing custom items for the pop-up menu that appears
when the user presses the right button on this entry. Its
format is the same as for AppIcon pop-up menus;
stem.COUNT - number of entries
stem.BASE - base ID
stem.0 - entry 1
stem.1 - entry 2
If count is set to 0, right-button pop-ups will be disabled for
this file. If this field is not specified, the default pop-up menu
will be displayed. If you specify "---" as an item, a separator
bar will appear. When you receive a message that the user has
selected one of these menu items, the message will contain
the ID of the item. This is the value corresponding to the
item's position in the stem array (eg 0 for item 1, 1 for item 2,
etc). If the base field is specified, the value given for the base
will be added to this ID.
See the Custom Handlers section later in this chapter for more
information on the messages sent.

lister copy <handle> <destination>
This command copies the contents of one lister to another lister.
Unlike most commands, the display of the destination lister is
refreshed immediately. For example,
> lister copy 121132636 121963868

lister clear <handle>
This command clears the contents of the specified lister. The
display will not be updated until you execute a lister refresh
command.
+  In previous versions of Opus 5, this command also cleared
the custom handler name. This is no longer the case.

lister clear <handle> <item> <value>
This command clears a particular item of information in the
specified lister. <handle> is the handle of the lister in question;
<item> can be one of the following keywords:-
abort
This clears the abort flag in the specified lister.
> lister clear 121132636 abort
flags <flags>
Clears sort/display flags for this lister. The display is not
updated unless you execute a lister refresh command. See
the lister query section for the keywords to use. For
example,
> lister clear 121132636 flags reverse
progress
This turns the progress indicator off in the specified lister.
> lister clear 121132636 progress

lister close [all |<handle>]
This command closes the specified lister or all listers if the all
keyword is supplied in place of a lister handle. Any function
that is currently taking place will be aborted. <handle> is the
lister handle that was returned when you created this lister
with the lister new command. For example,
> lister close 121132636

lister empty <handle>
This command will display an empty cache in the specified
lister (unlike lister clear which clears the contents of the
current cache). If no empty caches are available (and a new
one can not be created), the existing cache will be cleared. If
the lister has a custom handler attached, it will receive an
inactive message.
+ Note that previous versions of Opus 5 did not send the 'inactive'
message to the custom handler when this command was used.

lister getstring <handle> <text> [secure] [<length>]
[<default]> [<buttons>]
This command is identical to the dopus getstring command
except that it takes a lister handle as an additional parameter
and the requester will be centred over that lister.
<text> is a string of text to be displayed in the requester, and
should be surrounded by quotes if it contains spaces. The
secure keyword causes the string to be displayed as asterisks,
which can be useful for passwords. <length> is the maximum
length of the string to accept and defaults to 80 if not specified.
<default> is the default value of the string; that is, the text you
wish to initially appear in the field. <buttons> are the buttons
you wish the requester to have; each button should be
separated by a vertical bar character. If the buttons parameter
is omitted the requester will have a single button marked 'OK'.
For example,
> lister getstring 121132636 '"Please enter some text"
40 "" Okay|Cancel'
This would display a requester over the lister with the string
"Please enter some text", a maximum input length of 40
characters, no default text, and buttons labelled Okay and
Cancel.
The string (if any) is returned in RESULT. The cardinal
number of the selected button is returned in the special
variable DOPUSRC. In the above example, if the user clicked
Okay, DOPUSRC would contain 1, and if the user clicked
Cancel it would contain 0. This command and the dopus
getstring command are the only ones that use the DOPUSRC
variable currently, but this may change in the future.

lister new [<x/y/w/h>] [toolbar <toolbar>] [<path>]
This command creates a new lister. You may optionally
specify the position and size of the new lister. The default
position is -1/-1 causes the lister to open under the mouse
pointer. A custom toolbar for the lister can be specified with
the toolbar keyword; toolbar files are expected to be found in
the DOpus5:Buttons directory if the full path is not given. You
may also specify a path to read when the lister opens. For
example,
> lister new
> lister new 100/50/400/300
> lister new ram:
> lister new 80/30/200/200 dh0:work
> lister new toolbar custom_toolbar work:
--> 121132636
If the lister opens successfully, its handle is returned in the
RESULT variable. You must save the value of this handle if
you wish to do anything further with this lister. In the above
example, a handle of 121132636 was returned. This will be
used for further examples below.

lister query <handle> <item>
This command returns a particular item of information from
the specified lister. <handle> is the handle of the lister in
question. All information is returned in the RESULT variable,
unless an error occurs. <item> can be one of the following
keywords:-
all
This command returns the handles of all non-busy listers
(that is, any listers that are not performing a function at the
time). Note that this does not require a lister handle to
operate. This also supports the use of stem variables. For
example,
> lister query all
--> 121132636 121963868
abort
This returns a boolean value indicating the status of the
lister's abort flag. This query command is only valid if the
lister has a progress indicator open (as this is the only way
the user can abort a function anyway). This will return 1 if
the user has clicked the abort gadget, 0 if she has not. For
example,
> lister query 121132636 abort
--> 0
+ Note that in Opus 4, querying the abort flag would also
reset it. This is not the case in Opus 5; if you wish to reset the
state of the abort flag you must use the "lister clear" command.
busy
Returns a boolean value (0 or 1) indicating the lister busy
status. That is, if the lister is currently busy, it will return 1,
otherwise it will return 0. For example,
> lister query 121132636 busy
--> 1
dest
This command returns the handles of all destination listers
currently open. Note that this does not require a lister
handle to operate. This also supports the use of stem
variables. For example,
> lister query dest
--> 121963868
This command supports the stem and var keywords (see
lister query entry for more information.)
dirs <separator>
Returns the names of all directories in the lister. For
example,
> lister query 121132636 dirs
--> "Clipboards","ENV","T"
This command supports the stem and var keywords (see
lister query entry for more information.)
display
This returns a string indicating the current display items.
The string will consist of the same keywords as for sort, in
the order that they appear in the lister (if they appear at all).
For example,
> lister query 121132636 display
--> name size date protect comment
entries <separator>
Returns the names of all entries (that is, both files and
directories) in the lister. For example,
> lister query 121132636 entries
--> "Clipboards" "ENV" "T" "abc" "Disk.info"
This command supports the stem and var keywords (see
lister query entry for more information.) For example,
> lister query 121132636 entries stem files
This would return the following variables :-
files.count = 7
files.0 = Clipboards
files.1 = ENV
files.2 = T
files.3 = abc
etc.
entry <name>
Returns information about the specified entry. <name> is
the actual name of the entry to return information about.
You can supply #xxx for the name (where xxx is a number),
to specify the cardinal number of the desired entry. This
command can return information in two ways. The default
way is to return a string of information in either the
RESULT variable or another variable of your choice. The
information returned in this case is
<name> <size> <type> <selection> <seconds>
<protect> <comment>
where <name> is the full name of the entry, <size> is the
size of the entry, <type> is the type of the entry (<0 means a
file, >0 means a directory), <selection> indicates the
selection status of the entry (1 if the entry is selected, 0 if it
is not selected), <seconds> is the datestamp of the entry in
seconds from 1/1/78, <protect> is the protection bits of the
file (in ascii format); and <comment> is the comment of the
entry (if any). For example,
> lister query 121132636 entry ENV
--> ENV -1 2 0 543401724 ---- rwed
By default the string is returned in the RESULT variable. If
you wish to use another variable name, specify the var
keyword followed by the variable name. For example,
> lister query 121132636 entry ENV var my variable
The second, and more elegant method, returns information
about the entry in a stem variable. To use this second
method, you must specify the stem keyword followed by
the name of the stem variable you wish to use. For
example,
> lister query 121132636 entry ENV stem fileinfo
The specified stem variable will have several fields, each
containing information about the entry in question. These
fields are as follows:-
name - filename
size - file size
type - type (<0 = file, >0 = dir)
selected - 0 or 1
date - seconds since 1/1/78
protect - protection bits (long value)
datestring - datestamp in ascii form
protstring - protection bits in ascii form
comment - file comment (if any)
filetype - file type (if any)
version - version number
revision - revision number
verdate - version date (numerical dd.mm.yyformat)
datenum - file date in numerical dd.mm.yy format
time - file time in hh:mm:ss 24 hour format
Several other query commands in this section support the
var and stem keywords.
+ Note regarding the lister query files, dirs, entries, selfiles,
seldirs, and selentries commands. In previous versions of Opus
5, RESULT was not cleared if there were no entries to return.
This problem has been fixed. Also when using these commands
with the STEM keyword, the COUNT field will now be set to
zero in this case.
files <separator>
Returns the names of all files in the lister. The names are
returned as one long string, separated by spaces. You may
change the separation character by specifying it after the
files keyword. For example,
> lister query 121132636 files
--> "abc" "Disk.info" "readme" "zzz.zzz"
This command supports the stem and var keywords (see
lister query entry for more information.)
firstsel
Returns the name of the first selected entry in the lister. The
entry is not deselected, so if you don't deselect it yourself
this command will only ever return the one name. For
example,
> lister query 121132636 firstsel
--> "ENV"
flags
This returns a string indicating any sort or display flags that
are active for the lister. These flags are:-
reverse - sort in reverse order
noicons - filter icons
hidden - filter hidden bit
For example,
> lister query 121132636 flags
--> noicons
hide
This returns the current hide filter for this lister. For
example,
> lister query 121132636 hide
--> #?.o
handler
Returns the name of the current custom handler port. For
example,
> lister query 121132636 handler
--> ArcDir121132636
label
This command returns the label that appears beneath this
lister when it is iconified. By default, the label will be the
name of the current directory. This label can however be
changed by calling the lister set label command. For
example,
> lister query 121132636 label
--> Ram Disk
lock <type>
This command returns to current lock status of the lister
where <type> is either state or format. See the lister set lock
command.
mode
This returns the current mode for this lister and also the
word showall if the lister is in an icon mode and displaying
files without icons. The lister modes are:-
name - name mode
icon - workbench style icon mode
icon action - icon action mode
For example,
> lister query 121132636 mode
--> icon action showall
numdirs
Returns the number of directories in the lister. For example,
> lister query 121132636 numdirs
--> 3
numentries
Returns the total number of entries in the lister (files + dirs).
For example,
> lister query 121132636 numentries
--> 7
numfiles
Returns the number of files in the lister. For example,
> lister query 121132636 numfiles
--> 4
numselentries
Returns the number of selected entries in the lister.
numseldirs
Returns the number of selected directories in the lister.
numselfiles
Returns the number of selected files in the lister.
path
Returns a string indicating the current path visible in the
lister. For example,
> lister query 121132636 path
--> ram:
position
Returns the current position and size of the lister. The word
locked will also be returned if the lister is locked in
position. For example,
> lister query 121132636 position
--> 80/30/200/200 locked
selfiles <separator>
Returns the names of all selected files in the lister. This
command supports the stem and var keywords (see lister
query entry for more information.)
seldirs <separator>
Returns the names of all selected directories in the lister.
This command supports the stem and var keywords (see
lister query entry for more information.)
selentries <separator>
Returns the names of all selected entries (ie both files and
directories) in the lister. This command supports the stem
and var keywords (see lister query entry for more
information.)
separate
This returns a keyword indicating the current file
separation method in this lister. Valid methods are:-
mix - mix files and directories
dirsfirst - directories first
filesfirst - files first
For example,
> lister query 121132636 separate
--> dirsfirst
show
This returns the current show filter for this lister.
source
This command returns the handles of all source listers
currently open. Note that this does not require a lister
handle to operate. For example,
> lister query source
--> 121132636 128765412
This command supports the stem and var keywords (see
lister query entry for more information.) For example,
> lister query source stem sources.
This would return:-
sources.count = 2
sources.0 = 121132636
sources.1 = 128765412
sort
This returns a keyword indicating the current sort method
in this lister. Valid sort methods are:-
name - filename
size - file size
protect - protection bits
date - datestamp
comment - comment
filetype - file type
version - file version
For example,
> lister query 121132636 sort
--> name
toolbar
This returns the toolbar currently being used by this lister.
For example,
> lister query 121132636 toolbar
--> DOpus5:Buttons/toolbar
visible
Returns a boolean value indicating if the lister is currently
visible. For example,
> lister query 121132636 visible
--> 1
lister read <handle> <path> [force]
This command will read the given path into the specified lister.
By default a new cache is used to read the directory; if the force
keyword is specified, the current cache will be cleared and the
directory will be read into that. The old path is returned in
RESULT. For example,
> lister read 121132636 'dh0:test'
--> RamDisk:

lister refresh (all | <handle>) [full] [date]
This command refreshes the display of the specified lister or
all listers if the keyword all is given in place of a lister handle.
Unlike Opus 4, none of the lister modifying commands above
will actually refresh or update the lister display; hence, you
must use this command after making any changes (changing
sort method, adding files, etc) to have the changes display.
The optional full keyword causes the lister title and status
displayed to be refreshed as well. For example,
> lister refresh 121132636 full
If the date keyword is specified, the lister will update its
directory datestamp, which will stop it re-reading itself the
next time it is activated. If this keyword is specified, the lister
display itself is not refreshed.
>lister refresh 12113236 date

lister remove <handle> <name>
This command removes an entry from the specified lister.
<name> is either the name of the entry, or #xxx (where xxx is a
number) to specify the cardinal number of the entry. The
display is not updated until you execute a lister refresh
command. For example,
> lister remove 121132636 #5

lister request <handle> <text> <buttons>
This command is identical to the dopus request command
except that it takes an additional handle parameter and the
requester will be centred over that lister.
<text> is a string of text to be displayed in the requester.
<buttons> are the buttons you wish the requester to have; each
button should be separated by a vertical bar character. For
example,
> lister request 121132636 '"Please choose an option" "
Option 1|Option 2|Option 3"’
This would display a requester with the string "Please choose
an option", and three buttons labelled Option 1 to Option 3.
The cardinal number of the selected button is returned in RC.
The last button supplied (Option 3 in this case) is designated a
Cancel button, and so returns the value 0. Therefore, the values
returned by this example are 1, 2 and 0 respectively.

lister set <handle> <item> <value>
This command sets a particular item of information in the
specified lister. <handle> is the handle of the lister in question.
<item> can be one of the following keywords:-
busy <state> [wait]
Sets the busy status for this lister. You can specify 0 or off
to turn the busy pointer off, or 1 or on to turn it on. When
turning busy status on you can also provide the wait
keyword which will cause the command to be synchronous.
For example,
> lister set 121132636 busy on wait
> lister set 121132636 busy 0
case
This command turns on or off case sensitivity for this lister.
Since Amiga filenames are not case sensitive this setting
defaults to off. It may be useful for some custom handlers
to turn case sensitivity on however.
> lister set 121132636 case on
> lister set 121132636 case off
dest [lock]
Makes this lister the destination. If you specify the lock
keyword, it will be locked as a destination. For example,
> lister set 121132636 dest
display <items>
Sets the display items for this lister. The display will not be
updated until you execute a lister refresh command. See the
lister query section for the item keywords to use.
For example,
> lister set 121132636 display name date size protect
field [<number> <string>]
This allows you to set your own strings to be used in the
lister field titles. You can not change the nature of the
columns in the lister - this just allows you to change the
heading.
The <number> (0-9) specifies which string to replace;
counting from 0 they are:-
name, size, access, date, comment, type,
owner, group, net, version
Set to an empty string to restore the default. You will need
to do a lister refresh <handle> full to update the display once
you have changed the titles.
You can also do lister set <handle> field off to turn field titles
off altogether, and on to turn them back on again. Note that
if field titles have not been enabled in the configuration, an
ARexx script is unable to turn them on.
For example,
> lister set 121132636 field 0 FileName 4 Notes
flags <flags>
Sets sort/display flags for this lister. The display is not
updated unless you execute a lister refresh command. See
the lister query section for the keywords to use. For
example,
> lister set 121132636 flags reverse noicons
header <string>
This works just like lister set title except it changes the text
in the 'Files x/y Dirs x/y' bar. The old header string is
returned in RESULT. Set this to an empty string to restore
the default. If you wish to actually display an empty
header, set it to a - (hyphen character.)
handler <port name> [quotes] [fullpath]
Sets the custom handler port name for this lister. This is the
name of the message port to which messages from Opus
will be sent. If you specify the quotes flag, any filenames
sent in messages to the port will be enclosed in quotes (this
is a good idea as it allows you to support filenames
containing spaces). If you specify the fullpath flag, messages
will always contain the full path name of a file, irrespective
of whether it came from an Opus lister or not. (Usually, if
the file comes from a lister you will only get the filename
itself, plus the lister handle with which to find out the
path). For example,
> lister set 121132636 handler 'lhadir_handler' quotes
See Custom Handlers later in this chapter for more details.
hide <pattern>
Sets the hide pattern for this lister. The pattern is applied
immediately but the display is not updated until you
execute a lister refresh command. For example,
> lister set 121132636 hide '#?.info'
label
This command can be used to set the label that will be
displayed beneath the iconified lister. To remove a custom
label, simply use this command with no label specified. For
example,
> lister set 121132636 label Custom Lister
> lister set 121132636 label
lock <type>
The type parameter may currently be:-
state [on|off]
The state parameter allows you to lock the lister to its
current state so the user will be unable to change it until
you unlock it.
format [on |off]
The format parameter allows you to lock the lister to its
current display format. Currently this just prevents the
user bringing up the Format Edit Requester.
You can string these commands on the one line, for
example,
> lister set 121132636 lock state on format on
mode
This command sets the mode for this lister. See the lister
query section for the keywords to use. For example,
> lister set 121132636 mode name
> lister set 121132636 mode icon action showall
namelength
This command sets the maximum length allowed for
filenames in this lister. The minimum length is 30
characters which is also the default length. This command
will only be useful for writers of custom handlers. Note
that the internal Opus commands, for the most part, do not
currently support filenames longer than 30 characters. For
example,
> lister set 121132636 namelength 256
newprogress [name] [file] [info] [bar] [abort]
This turns the progress indicator on in the specified lister.
This is similar to the old lister set progress command, but
allows greater control over the information displayed.
name - allocates space for filename display
file - allocates space for file progress display
info - allocates space for information line
bar - allocates space for progress bar
abort - adds abort gadget
Progress windows that show both the bar graph and the file
progress will have the graph and file displays swapped
around. This means that instead of the graph showing the
percentage of files copies, and a 'xx%' display showing the
progress of that file, the graph shows the file progress and a
'xxx of yyy' display gives overall information.
> lister set 121132636 newprogress name file info bar abort
newprogress name <filename>
If the progress bar was opened with the name parameter,
this will set the current filename.
> lister set 121132636 newprogress name 'myfile.txt'
newprogress file <total> <count>
If the progress indicator was opened with the file but not
the bar parameter, this will set the total number of files and
the number of the current file. This is shown as 'xx%' in the
top right of the requester.
If the progress indicator was opened with both the file and
bar parameters, this will set the total number of bytes and
the current byte count. This is shown in the bar graph part
of the requester.
> lister set 121132636 newprogress file 12 4
newprogress info <text>
<text> is a text string to be displayed between the filename
and the bar graph of the progress indicator. For example,
> lister set 121132636 newprogress info "From 'T' to 'Ram:'"
newprogress bar <total> <count>
If the progress indicator was opened with the bar but not
the file parameter, this will set the total number of bytes
and the current byte count. This is shown in the bar graph
part of the requester.
If the progress indicator was opened with both the file and
bar parameters, this will set the total number of files and
the number of the current file. This is shown as 'xxx of yyy'
in the top right of the requester.
> lister set 121132636 newprogress bar 1024 100
newprogress title <text>
<text> is a text string to be displayed in the title bar of the
progress indicator. For example,
> lister set 121132636 newprogress title 'Copying...'
You can use the old 'lister set progress' commands on a
'newprogress' indicator, but obviously they can only change the
filename and bar count. Use 'lister clear progress' to remove
either the 'old' or 'new' progress indicators.
off
Turns this lister off (ie neither source nor destination). For
example,
> lister set 121132636 off
path <path string>
Sets the current path string in the lister. Note that this does
NOT cause the directory to be read, it merely changes the
displayed string. To read a new directory, use the lister
read command. For example,
> lister set 121132636 path 'dh0:work'
position <x/y/w/h>
This sets the current position and size of the lister if it has
not been locked. If the lister is visible the window will be
moved immediately. For example,
> lister set 121132636 position 20/20/400/300
progress <total> <text>
Please note that the 'lister set progress' commands have now
been superseded by the 'lister set newprogress' commands.
Please use those commands in any new scripts.
This turns the progress indicator on in the specified lister.
<total> specifies the total amount to be processed, and
controls the bar graph display. <text> is a text string to be
displayed in the title bar of the progress indicator. For
example,
> lister set 121132636 progress 38 'Archiving files...'
progress count <count>
This updates the bar graph display in the progress indicator
(which must have already been turned on); <count> is the
current progress count to be indicated by the bar graph.
For example,
> lister set 121132636 progress count 4
progress name <name>
This updates the filename display in the progress indicator.
The filename is displayed above the bar graph. For
example,
> lister set 121132636 progress name 'myfile.txt'
separate <method>
Sets the separation method for this lister. The list is
rearranged immediately, but the display will not be
updated until you execute a lister refresh command. See
the lister query section for the separation keywords
recognised. For example,
> lister set 121132636 separate mix
show <pattern>
Sets the show pattern for this lister. The pattern is applied
immediately but the display is not updated until you
execute a lister refresh command. For example,
> lister set 121132636 show '#?.c'
sort <method>
Sets the sort method for this lister. The list is resorted
immediately, but the display will not be updated until you
execute a lister refresh command. See the lister query section
for the sort method keywords available. For example,
> lister set 121132636 sort date
> lister set 121132636 sort filetype
source [lock]
Makes this lister the source. If you specify the lock
keyword, it will be locked as a source. For example,
> lister set 121132636 source lock
title <string>
Sets the title for this lister (the title displayed in the lister
title bar). The title bar display will not be updated until
you execute a lister refresh full command. The old title is
returned in RESULT. For example,
> lister set 121132636 title 'hello'
--> RESULT
> lister set 121132636 title
--> hello
toolbar
This command changes the toolbar that is used in this lister.
For example,
> lister set 121132636 toolbar Ram:custom_toolbar
visible <state>
Sets the visible status for this lister. By default, listers are
visible when they are created. If you set this state to 0 or
off, the lister will disappear from the display, until you
make it visible again. For example,
> lister set 121132636 visible off
> lister set 121132636 visible 1

lister select <handle> <name> <state>
This command changes the selection status of an entry in
the specified lister. <name> is either the name of the entry,
or #xxx (where xxx is a number) to specify the cardinal
number of the entry. <state> is the desired selection status
(0 or off' for off, 1 or on for on). If <state> is not given then
the state of the entry is toggled. The display is not
refreshed until you execute a lister refresh command. The
previous selection state of the entry is returned in RESULT.
For example,
> lister select 121132636 ENV on
--> off

lister wait <handle> [quick]
This command causes the rexx script to wait for the specified
lister to finish whatever it is doing. Because Opus 5
multitasks, all rexx commands (like lister read, or lister new)
will return immediately, even if the lister has not completed
its task. This command will force the script to wait until the
lister goes non-busy. If the lister is not in a busy state when
this command is called, the program will wait for up to two
seconds for it to go busy, otherwise this call is aborted. If the
quick keyword is specified, the command will return
immediately if the lister is not busy, instead of waiting for
two seconds. It would be silly to do lister set busy 1 and then
lister wait. For example,
> lister read 121132636 'c:'
> lister wait 121132636

lister iconify (all | <handle>) <state>
This command causes either all listers or the specified lister to
become iconified if state is 1, on, or omitted altogether, and to
deiconify if state is 0 or off.
> lister iconify 121132636
> lister iconify all off

command
The third base command is command. This allows you to call the
internal commands of Directory Opus 5 from an ARexx script. The
commands execute exactly as if they had been run from a custom
button or menu.
command [wait] [source <handle>] [dest <handle>]
[original] command [arguments]
If the wait flag is specified, the command will be run
synchronously, otherwise it will return immediately. Ordinarily,
commands operate on the current source and destination listers -
the source and dest parameters allow you to specify alternative
listers to use.
The original flag allows you to run an original Opus internal
function if the command has been replaced in the command list by
an external module (external modules which add commands to
Opus override the internal list). This means you could have a
module that replaced some Opus commands, did something
special in some circumstances, and in others just called the original
Opus function.
The command parameter is the name of the command, and
arguments are any optional arguments for the command, as
normal. Some examples are:
> command all
> command wait copy
> command read s:startup-sequence
> command source 121132636 makedir name=MyDir noicon
> command original wait delete ram:#?

ARexx Error Codes
Lister handles are the actual address in memory of the lister
structure. Opus 5 will reject any non-valid handles with an RC of
10. All commands that return data return it in RESULT (with the
exception of dopus getstring and lister getstring) or a specified
stem variable; if an error occurs, the error code is returned in RC.
An RC of 0 generally indicates that everything is ok. Error codes
are:-
1 RXERR_FILE_REJECTED
The file you tried to add was rejected by the current lister filters.
+ Note that this is not an error, just a warning. The file is
still added, it will just not be visible until the filters are changed.
5 RXERR_INVALID_QUERY
RXERR_INVALID_SET
The query/set item you specified was invalid.
6 RXERR_INVALID_NAME
RXERR_INVALID_KEYWORD
The filename, or keyword you specified was invalid.
8 RXERR_INVALID_TRAP
The trap you tried to remove didn't exist.
10 RXERR_INVALID_HANDLE
The lister handle you gave was invalid.
12 RXERR_NO_TOOLBAR
The lister has no valid toolbar.
15 RXERR_NO_MEMORY
There wasn't enough memory to do what you wanted.
20 RXERR_NO_LISTER
A lister failed to open (usually because of low-memory).

Custom Handlers
The custom handler system allows you to specify the name of an
external public message port. This port will be sent messages
whenever certain things happen that you are interested in.
Messages that are sent are properly formatted ARexx messages. An
example code fragment to receive a message is:
call waitpkt(myportname) /* wait for messages to arrive */
packet=getpkt(myportname) /* get waiting message */
arg0=getarg(packet,0) /* get Argument 0 */
arg1=getarg(packet,1) /* get Argument 1 */
arg2=getarg(packet,2) /* get Argument 2, etc... */
call reply(packet,0) /* reply to the message */

Custom Handlers for Listers
A custom handler is "attached" to a lister by calling lister set
<handle> handler for that lister, giving the name of your message
port. Whenever something interesting happens to your lister, the
handler will be sent an ARexx message. The handler can be
implemented either as a rexx program or as a C program (in which
case it must interpret the rexx message itself). Unlike Opus 4,
messages sent to handlers do not cause Directory Opus 5 to "hang"
until they are replied (although you should try to reply to any
messages as soon as possible).
+ Note that custom handlers for listers are specific only to
the cache that is visible in the lister at the time the handler name
is set. The same handler port may be used set for multiple
caches, and indeed for multiple listers. Note also that message
port names are case-sensitive.
The rexx message identifies the type of event, the lister the event
happened to, and other pertinent data. The events that you will be
notified of are :-
doubleclick
This is a double-click event, and indicates that an item in the
lister has been double-clicked on by the user. The message
arguments are:-
Arg0 - "doubleclick" (a string indicating the event type)
Arg1 - <handle> (lister handle)
Arg2 - <name> (entry name)
Arg3 - undefined
Arg4 - undefined
Arg5 - <userdata> (if userdata was specified with the
lister addstem command)
Arg6 - <qualifiers> (string indicating qualifiers pressed
- shift, alt, and control keys)
drop
This is a drag'n'drop event, and indicates that one or more
entries have been dropped into a lister. The message
arguments are:-
Arg0 - "drop" (event type)
Arg1 - <handle> (destination lister handle)
Arg2 - <names> (filenames)
Arg3 - <handle> (source lister handle)
Arg4 - undefined
Arg5 - undefined
Arg6 - <qualifiers> (shift, alt, and control keys)
The filenames are separated by spaces (if there is more than
one), and will be within quotes if the quotes keyword was
specified for the lister set handler command. If the files
originated from another Opus 5 lister, Arg3 gives the handle of
that lister. If this is the case, and the fullpath option was not
specified in lister set handler, only the filenames (and not their
paths) are supplied in Arg2 (you can get the source path using
lister query). If Arg3 is null then the drop most likely
originated from Workbench, and the names in Arg2 include the
full paths.
dropfrom
This is exactly the same as the drop event, except that it
indicates a drop from a lister rather than a drop to one. The
message arguments are:-
Arg0 - "dropfrom" (event type)
Arg1 - <handle> (source lister handle)
Arg2 - <names> (filenames)
Arg3 - <handle> (destination lister handle)
Arg4 - undefined
Arg5 - undefined
Arg6 - <qualifiers> (shift, alt, and control keys)
Note that appicons can also receive dropfrom events but they
have slightly different arguments. They can be distinguished
by the word "icon" always present in Arg4. See below for more
information.
parent
This event will be received when the Parent Directory item is
chosen from the lister cache pop-up menu, or whenever the
user clicks on the border parent gadget or uses the parent hot
key, "/". The message arguments are:-
Arg0 - "parent" (event type)
Arg1 - <handle> (source lister handle)
Arg2 - <path> (path of lister)
Arg3 - undefined
Arg4 - undefined
Arg5 - undefined
Arg6 - <qualifiers> (only shift key)
root
A root event will be received when the Root Directory item is
chosen from the lister cache pop-up menu, or whenever the
user uses the root hot key, ":". The message arguments are:-
Arg0 - "root" (event type)
Arg1 - <handle> (source lister handle)
Arg2 - <path> (path of lister)
Arg3 - undefined
Arg4 - undefined
Arg5 - undefined
Arg6 - <qualifiers> (shift keys)
path
When the user enters a new path in the path gadget of a lister
you will receive this message. The arguments are:-
Arg0 - "path" (event type)
Arg1 - <handle> (lister handle)
Arg2 - <path> (path of lister)
reread
The reread event will be sent to your handler when the Re-read
Directory item is chosen from the lister cache pop-up menu. Its
arguments are:-
Arg0 - "reread" (event type)
Arg1 - <handle> (lister handle)
Arg2 - <path> (new path for lister)
active
This event indicates that a cache with a custom handler
attached has just become visible. The message arguments are:-
Arg0 - "active" (event type)
Arg1 - <handle> (lister handle)
Arg2 - <title> (cache title)
Arg3 - undefined
Arg4 - <path> (path of the lister)
Arg2 will contain the custom title of the cache that became
active, if it has been set with lister set title. If no custom title
has been defined, the path string of the cache is returned
instead (ie in this case Arg2 will be the same as Arg4).
inactive
This event indicates that the cache this custom handler is
attached to is no longer active (visible in the lister). The
message arguments are the same as for active above, except for
a different event type in Arg0. This message is caused by the
cache in the lister being changed (either by the user or under
rexx control), or even by the lister being closed. Note that you
may receive an active message for another cache with a custom
handler, or even for the same cache, immediately after
receiving an inactive message.

Trapped Functions
Messages for trapped commands are sent to the lister much like
the other messages. The arguments are :
Arg0 - <command> (name of the command, or "abort")
Arg1 - <handle> (source lister handle, if any)
Arg2 - <files> (selected files, if any)
Arg3 - <handle> (destination lister handle, if any)
Arg4 - <path> (source path; useful if there's no lister
associated with it)
Arg5 - <args>(user-supplied arguments to the function)
Arg7 - <path> (destination path; allows you to support
the Select Destination requester)

AddStem Pop-Ups
If you have added files to a lister with lister addstem and specified
your own pop-up menus for the files, you will receive messages
when these menus are chosen by the user. The arguments sent are:
Arg0 - "menu" (string identifies this as a menu event)
Arg1 - <handle> (lister handle)
Arg2 - <name> (entry name)
Arg3 - <id> (ID of the menu item + base ID if specified)
Arg4 - "file" (string identifying this as a "file" menu
event)
Arg5 - <userdata> (userdata specified via the lister
addstem command)

Custom Handlers for AppIcons
AppIcons added with the addappicon command will also cause
messages to be sent. All AppIcon messages have the same
arguments:-
Arg0 - <event> (string identifying the event)
Arg1 - <id> (ID specified in the addappicon command)
Arg2 - <data> (filenames/menu ID/other information)
Arg3 - <handle> (source lister handle - if applicable)
Arg4 - "icon" (string identifying this as an "icon" event)
These are the events that apply to AppIcons:
doubleclick
This event indicates that an icon has been double-clicked, or
has had Open selected from its menu.
dropfrom
This is a drag'n'drop event, and indicates that one or more
entries have been dropped on this appicon from a lister or
elsewhere. The names of the entries are available in Arg2.
snapshot
This event occurs when the Snapshot menu item is selected. The
current position of the icon is available in Arg2 (as an x,y
string). You are responsible for storing this position.
unsnapshot
This event occurs when the Un-Snapshot menu item is selected.
removed
This event warns that Opus has quit and the handler code
should now clean up and exit.
info
This event occurs when the Information menu item is selected.
close
This will occur when Close is selected from the pop-up menu.
menu
This event indicates that one of the user-supplied menu items
has been selected in the pop-up menu. The number of the
menu item will be returned in Arg2.
menuhelp
This event indicates that the help key was pressed while the
mouse pointer was over one of the user-supplied menu items.
The number of the menu item will be returned in Arg2.
Because of the multi-tasking nature of Opus 5, information custom
handlers receive can not be 100% relied on. For example, you may
receive an active message, but the cache that caused it may have
immediately gone inactive again. You should therefore check your
port is clear of all messages before processing any that have come
in, and you should also use the lister query command to make sure
that things are how you expect them. Also note that listers (unless
you have turned busy on) can be closed by the user at any time.
An inactive message is sent when the lister is closed. To check that
a lister is still open, use the lister query path command (or any other
query command). If the lister no longer exists, RC will contain the
error code XERR_INVALID_HANDLE (10). Be aware though
that while these possibilities exist, generally they will not cause a
problem. For the most part it will only be if the user is "playing
around" that weird situations will occur.

ARexx Modules
ARexx Modules are ARexx scripts which are installed in the
DOpus5:Modules directory. They must have the suffix .dopus5 to
work correctly.
Each ARexx Module can add new internal commands to Opus.
Once both Opus 5 and ARexx have been started on the computer,
the DOpus5:Modules directory will be scanned for ARexx
Modules and each will have its init function called. Every ARexx
Module must have an init function or else it will not work. This is
the function that adds the extra commands to Opus.
The scripts are called with 4 or more parameters. The first 4 are
always provided - the portname of Directory Opus 5 and the
function name, followed by the source and destination lister
handles. Any user-supplied arguments to the function will follow.
You can add as many commands as you like. To add commands,
use the dopus command command. The template is :
dopus command <name> program <scriptname>
[desc <description>] [template <template>]
[source] [dest]
command - the name of the command
scriptname - filename of the script (this has to be the name of
the script as it appears in the DOpus5:Modules
directory, without the .dopus5 suffix)
desc - optional command description (for the pop-up
command list in editors)
template - optional ReadArgs style command template
(you'll have to do parsing yourself!)
source - indicates that the command needs a source
directory
dest - indicates that the command needs a destination
directory
The program field is mandatory, and Opus will run the script name
you provide here whenever this function is invoked. The desc and
template fields are optional. If you specify the source or dest
keywords (or both), you will be passed the appropriate lister
handle(s) as an argument to the script. If these
flags are not set, the arguments will still be passed, but will be
zero. Any user-supplied arguments to the function will be at the
end of the command line; you are responsible for parsing these
yourself.
Here is a complete example of an ARexx Module:-
/* Example Directory Opus 5 ARexx Module */
parse arg portname function source dest arguments
address value portname
options results
/* Initialise */
if function='init' then do
dopus command "Test1" program "test-command" desc "'Test
command 1'" template "TEST/S"
dopus command "Test2" program "test-command" desc "'Test
command 2'" source
exit
end
/* Test function 1 */
if function='Test1' then do
dopus request "'Test command 1 received!'" "Ok"
exit
end
/* Test function 2 */
if function='Test2' then do
str="'Test command 2 received - source handle " || source
dopus request str "Ok"
exit
end

ARexx Commands

The ARexx command functions of Opus allow you to write custom scripts to control Opus behaviour or to create complete programs which complement Opus and use the Opus in-built features to perform a wide variety of external tasks. There are many such scripts and these are usually stored in the DOpus5:ARexx directory The excellentArcDir program which enables the display of archives is an example of the use of Opus ARexx capabilities. This and many other scripts have been extensively revised and have been supplied in the Magellan-II update installations.

The following is a summary of the changes for the ARexx command interface for Opus Magellan-II. For a full explanation of the Opus ARexx commands and interface, please refer to the ARexx tutorial and guide on the DOpus Plus CD or available from the GPSoftware web site.

New and Enhanced ARexx Commands

Many new ARexx commands have been added and others have been enhanced to support more functionality required by the OpusFTP system plus a number of third-party scripts developed by Opus users.

The changes are a follows:-

command

ARexx commands using the "command wait <cmd>" function now return a result code indicating success or failure.

doubleclick

The ARexx command command doubleclick was not sending doubleclick messages to the custom handler if the source Lister had one. This has been rectified.

dopus command

This command has been greatly expanded. It provides the ability to add new internal commands to Directory Opus, or to replace existing commands. It is generally called from within the init function of an Opus ARexx module and the program parameter will be the name of that module, without the ".dopus5" extension.

The new template is:-

dopus command <name> program <scriptname> [desc
<description>] [template <template>] [source] [dest]
[private] [help <help file>] [handler] [temp] [ext <menu
name> type <filetype>] [remove]


The program field is mandatory, and Opus will run the script name you provide here whenever this function is invoked.

Use the name parameter to specify what the command should be called, and, optionally, use the desc parameter to define a description which will appear in command lists.

Using the handler parameter will allow the item to be displayed only if a custom handler matching the program parameter is present for the Lister.

The remove flag allows you to remove any command specified with name.

temp will allow you to add a 'temporary' command, which does not have an external command file. This command will then do nothing unless it is trapped with the dopus addtrap command.

Use the remove flag of the dopus command to remove it when you are done. Using the private flag will stop the temporary command from being seen in the internal command list.

The template is not parsed for you in any way - it is simply shown to the user when they request a template for your command. It is up to your script to handle the argument string sent to it.

If you give the source or dest keyword (or both), your command will not run unless there is a Lister of the given type. When run, the Lister will automatically go busy, and the source or dest argument given to your script will contain the Lister's handle. (Each argument still exists when the relevant keyword is not given, but is always "0").

Note that the standard ARexx module example code parses the source Lister handle into a variable called source and the destination handle into dest. Be careful that when you specify the source keyword for dopus command that you put it in quotes ("source"), otherwise the contents of the source variable may be used in place of the actual word "source". Take similar precautions with the "dest" word.

You can specify a help file for the new command with the help parameter.

Wildcard Patterns

The dopus command now supports wildcards in the type field, allowing you to add menus to multiple filetypes at once.

For example,

  dopus command "Unpack" program "Unpacker"
    'source' ext 'Unpack..." type a*

This would add the Unpack... menu item to all filetypes with IDs starting with "a". Full wildcards are supported.

PopUpExtensions

You can add a command to the pop-up menu of icons of a given type, or to the Lister itself, by specifying a filetype name or ID for the type parameter and the string to appear as the menu item for the ext parameter.

To match more than one filetype you can specify the type parameter multiple times (but you can only have one ext ). You can also specify one of the following keywords for the type parameter: all, disk, drawer, tool, project, trash, baddisk, leftout, lister, lister2.

Specifying lister for the type parameter will add items to the Lister pop-up menu rather than the icon pop-up menu.

Specifying lister2 for the type parameter will add items to the pop-up menu available from the SRCE/DEST display in the Lister status bar.

If you add menus to a filetype at priority -124, they will only be shown if no other filetype matched. This allows you to have a "default filetype" with menus that will only be shown if no other filetype menus are displayed.

Commands which are intended for pop-up menus are unlikely to be of general use. You can use the private keyword to hide the command (it will not appear in any list shown to the user). (This is not restricted to PopUpExtensions.)

See ARexx help file and the example scripts for more information.

  dopus clear <item>

Lets you clear a setting (equivalent to doing dopus set with a null string). For item use

background [desktop|lister|req] sound <event>

  dopus desktoppopup

This function triggers the desktop popup menu at the current mouse position, and return a value indicating the user's selection.

The function is called with a single value - a flags parameter which indicates which items in the menu are to be disabled (by default, all are available). Add the flag values as appropriate.

   Add to disable   Item   Returns
    2   Create Left-Out  1
    4   Copy To Desktop  2
    8   Move To Desktop  3

The function returns 0 if the user cancels the operation.

  dopus getdesktop

The dopus getdesktop command now returns the full path of the desktop folder rather than the actual configured path (which could be an assign).

  dopus matchdesktop

This commandwill match a supplied path against the desktop folder for you. For example,

   dopus matchdesktop 'DOpus5:desktop'
    ---> 1

  dopus progress

Two new parameters, info2 and info3 have been added to the dopus progress and lister newprogress commands. With these Opus now supports three information lines in the progress requester.

  dopus query <item>

Dopus query is the partner of dopus set and lets you query the current settings of the various items.

  dopus query background [desktop |lister |req]

This new command lets you query the currently set background picture.

  dopus query sound <event>

This new command lets you query the sound events.

For example,

  dopus query sound Startup

  dopus read <pos>

 dopus read is mostly previous documented, however there are three new flags - hex, ansi, smart - which control the text viewer mode. For example,

   dopus read hex 's:startup-sequence'

There are actually three already existing undocumented commands to achieve the same effect:

   dopus hexread
   dopus ansiread
   dopus smartread

However, the flag for the dopus read command is more logical. The optional <pos> flag allows you to specify the position of the text viewer.

For example,

  dopus read pos 10/10/400/200 s:startup-sequence

  dopus refresh <item>

Lets you refresh the display of certain items:

   all - refresh the entire display of everything
   background- already documented
   icons - refresh icons in all Listers and on the desktop
   lister [full] - refresh Lister displays

The various refresh commands are needed after modifying some settings with the dopus set command.

  dopus refresh
  dopus refresh background

Setting the background picture with the dopus set background command does NOT refresh the display. The display will not be updated until you call the "dopus refresh background" command.

There is also a new keyword custom to both this command and dopus set background'. Using this keyword, you can change the background pictures internally without modifying the actual environment settings. You must use the custom keyword on both the set and refresh commands for this to work. As soon as you do a refresh without setting this keyword, the pictures will revert back to the environment settings.

  dopus set <item> <parameters>

Allows you to configure certain items of the DOpus environment. It is primarily used at this stage for the themes system.

Item may be one of:-

  background - This new ARexx command has been added to manipulate background pictures:

  dopus set background <file> [desktop|lister|req] [center|tile] [precision <precision>]

This sets a new background picture for the specified place (desktop, lister or requesters). Precision, if supplied, can be: none, gui, icon, image or exact.

There is also a new keyword custom to both this command and dopus refresh background. Using this keyword, you can change the background pictures internally without modifying the actual environment settings. You must use the custom keyword on both the set and refresh commands for this to work. As soon as you do a refresh without setting this keyword, the pictures will revert back to the environment settings.

sound - This is a new ARexx command to let you set the sound events.

The format is:

   dopus set sound <event> <file> <volume>

For example,

   dopus set sound "Open Lister"
   DOpus5:sounds/open_Lister.snd 64

palette - Configures the DOpus palette. Accepts a string of up to 16 hex values; the last 8 represent the Opus colours, and the first 8 represent the system colours when Opus is on its own screen.

For example,

   dopus set palette 0xffaabb 0x000055

pens <type> - Configures the pens numbers used for various things where <type> is a string signifying the pen set to alter, and is followed by a number of values which represent which of the pens to use. <type> can be:

   icons  <dfg><dbg><dstyle><wfg><wbg><wstyle>
   files  <fg> <bg>
   dirs   <fg> <bg>
   selfiles  <fg> <bg>
   seldirs  <fg> <bg>
   devices  <fg> <bg>
   assigns  <fg> <bg>
   source  <fg> <bg>
   dest   <fg> <bg>
   gauge  <normal> <full>
   user   <count>

The pen number is mapped in the following way:

   1-4   bottom four system colours
   5-8   top four system colours
   9-16   Opus user pens

font <type> - Configure the fonts where <type> is a string representing the font to be configured:-

   screen  Screen font when Opus is on it's own
   screen
   listers  Font used for file display in Listers
   iconsd  Icons on the desktop
   iconsw  Icons in windows

<type> is followed by the font name and size, eg

   dopus set font screen courier.font 13


dopus script

To trigger a script (either an internal script or a custom one), use this command:

  dopus script <name> <data>

  <name> is the name of the script (not case sensitive), and
  <data> is an optional string that is passed to the script
  function in the {Qa} parameter.

lister new

The lister new ARexx command now takes several new parameters:

   inactive  Don't activate the Lister when it opens.
   invisible  The Lister is created but not shown. Use lister set visible to make it visible.
   iconify   The Lister is opened iconified.
   fromicon Will open the new Lister using the size and
            position information from the specified
            directory's icon (only if a path is specified
            and an icon exists). For example, lister new
            fromicon sys:tools
   mode    Lets you specify the initial mode of the new Lister. For example, lister new icon
            or lister new action showall

lister clearcache

Will flush any caches that were created by your Lister, using your custom handler. No other caches will be affected.

lister findcache

Allows you to find a cached directory and display it in the Lister, for example,

lister findcache <handle> <path>

When it returns, RESULT is set to 0 if the path was not found, or 1 if it was found. If the path is found, it will be automatically displayed in the Lister and you don't need to do any more. If it is not found, you'll have to read the directory as normal.

lister query active

There commandreturns the handle of the currently active Lister (ie the window is active, the Lister is not necessarily source or destination).

lister query proc

The lister query <handle> proc ARexx command will return the process address of the Lister (returned in RESULT in decimal).

lister query window

The lister <handle> query window command gets the window pointer of a Lister. This is the address (in base 10) of the window structure, or 0 if the Lister has no window.

lister query title
lister query header

We have added these commands to complement the lister set commands.

We have also added lister set value and lister query value ARexx commands. These allow you to associate your own data with a Lister in the form of name/value pairs. The Lister will maintain the values until it is closed.

For example,

   lister set <handle> value MyName "Fred Bloggs"
   lister query <handle> value MyName
   lister clear <handle> value MyName

lister reload

To reload (or load for the first time) a file in a Lister.

The template for the command is:-

   lister reload <handle> <name>

This also has an update flag to make it update the Lister datestamp (to save unnecessary reloading)

lister reload <handle> <name> update

For example,

  lister reload 12381928 'filename.lha'

If the file previously existed in the Lister, the user data, user menus and version information of the file is preserved.

lister set
lister set handler

A new switch for the lister set handler ARexx command called 'leavegauge' causes the fuel gauge to remain if it was already there, and leave it absent if it was not.In contrast, the old 'gauge' switch will always add a fuel gauge and not providing either switch will always cause the Lister to have no fuel gauge.

Another new switch, 'synctraps' causes messages trapped by ARexx Lister handlers to be synchronous. This is extremely useful when writing scripts.By default (and for compatibility) handler messages remain asynchronous.

There is now a 'nopopups' keyword for the ' lister set handler' command to disable all file popups in that Lister. If you have added your own popup menu to an entry it will be shown even if the nopopups flag is set.

lister set newprogress

Two new parameters, 'info2' and ' info3' have been added to the newprogress command. With these Opus now supports three information lines in the progress requester.

lister set commentlength

This command complements the 'lister set namelength' command and allows you to set the maximum comment length allowed in a Lister. Note that this only affects the length displayed and does not affect the maximum comment length that can be saved to disk, which is fixed at 79 characters. Its prime purpose is to support ARexx scripts and custom handlers where you may wish to use the comment field for storage of text longer than 79 characters. The FTPBatch download system being developed by third party sources is an example of this.

ARexx Notes

For file Listers, the popup menu CopyTo has been expanded so you can now copy to ARexx scripts. To do this,

  Create an ARexx script in the DOpus5:system/CopyTo
  directory. Set the comment of the script file to be the name
  that you want displayed in the menu.   Then set the Script
  protection bit of the script file.

The ARexx script will be passed the name of the file that was selected and the Opus ARexx port name.

For example,

  > list DOpus5:system/copyto

  TestScript.dopus 5135 -s--rw-d Today 00:07:12 :Test ARexx Script

  > type DOpus5:system/copyto/testscript.dopus5

  /* A test of a CopyTo script */
  parse arg filename portname source options results
  str = "'File : "||filename||"'"
  dopus request str "Ok"

  See DOpus ARexx guide from the DOpus Plus CD or from
  our web site for more details.


ARexx Handlers

If the 'synctraps' flag is set, messages you get from trapped functions now have a new argument. Arg8 contains the address (in decimal) of the FunctionHandle structure for this function, for use with the Opus callback hooks. This handle is only valid until you have replied to the message.

The "drop" and "dropfrom" custom handler messages now contain the word "subdrop" in the qualifier argument field if the drop was into a sub-directory.

When adding files to a Lister via ARexx/callbacks, you can set the datestamp of the file automatically to the current date/time by passing in 0.

Free Space Gauges are turned off by default for custom handler Listers; if you specify the gauge keyword for the 'lister set <handle> handle' ARexx command you can enable them but remember that the user may still have turned them off in the environment

You can now add a trap for all internal commands using an asterisk *, for example

    dopus addtrap * myhandler

Drag and dropping onto sub-directories is disabled by default for custom handlers. You need to add the 'subdrop ' keyword to the 'lister set handler' command to enable dropping into sub-directories for your handler. Note that the user may still have sub-dropping turned off in the environment.

The "drop" message now contains the full destination path in Arg5. You can compare this against the path of the destination Lister (handle in Arg1) to see whether the drop was into a sub-directory or not.