GEMScript commands in jinnee:
=============================


REMARKS:
-------

"Returns" in the following text always means the result string,
i.e. msg[5 + 6] with GS_ACK. This corresponds to the actual returns 
of functions in Scripter.

"errno" specifies what the commands return in msg[7] (GSACK_OK 0 or 
GSACK_ERROR 2). This value can be interrogated in Scripter with errno.
Return 1 (GSACK_UNKNOWN - command unknown) is however intercepted by 
Scripter directly and the script will be terminated.

If nothing is specified for errno then basically GSACK_OK will be 
returned.

For simpler evaluation, the return with "boolean" commands for "FALSE"
is a null-pointer or an empty string. Due to this one can include the 
commands very easily in "if" queries in Scripter. This is because 
"if (string)" returns (TRUE) for any string, and only for null-pointers 
or empty strings not (FALSE).

In the following documentation the "FALSE-returns" are identified by "".
Instead of an empty string there may be a null-pointer instead.


COMMANDS:
---------


 Macro <app> <cmd> ...

Actually only meant for non-application-specific recording. jinnee
sends <cmd> ... to application <app>. <app> will be launched if 
necessary (if installed).

Return: Error-string on error (errno = 2). Otherwise the Return + errno 
of the application <app> called with the command <cmd> will be returned.

 Close [<dir>]

Closes the directory window <dir> or the topped window if <dir> is 
absent.

Return:
"1" - OK, window was closed
"" - No matching window open

 Open <dir>

Opens a directory window with path <dir>

Return:
"1" - OK, window was opened
"" - Error

errno:
GSACK_ERROR for missing <dir>

 Config <line>

Interprets <line> as a line from the INF file. Warning: In many cases 
the "feedback" is missing here, i.e. the result is mostly not visible 
immediately.

Return:
"1" - OK, <line> interpreted without errors
"" - Error

errno:
GSACK_ERROR for missing <line>

 Quit

Terminates jinnee (without query) if that is possible at the time.

Return:
"" - Termination is not possible at present
Otherwise nothing, but a GS_QUIT command will come.

 Shutdown

Executes a Shutdown if that is possible at the time.

Return: As for Quit

 GetFront

Returns the path of the topped directory window.

Return:
Path of the topped window or NULL

 ToFront <dir>

Searches for a directory window with path <dir> among the opened windows 
and tops this, if present.

Return:
"1" - Corresponding window found and topped
"" - Error, nothing topped

 SelectAll [<dir>]

Selects all objects in directory window with path <dir>. If <dir> is 
not specified all objects on the desktop will be selected.

Return:
Nothing

 DeselectAll [<dir>]

As SelectAll, except that all affected objects will be deselected.

Return:
Nothing

 Up [<dir>]

Steps up one level to the parent directory in window <dir>, or closes it 
if it already displaying the root directory. If <dir> is not specified 
then this will be applied to the top directory window.

Return:
"1" - OK
"" - Error

 Exec <prg> [<cmdline> [<startpath>]]

Starts the program <prg> with (optional) command line <cmdline>. The 
current path will be set to <startpath> if necessary.

Return:
Nothing

 Activate <prg>

Tops application <prg>

Return:
"1" - OK, found and topped
"" - Error, <prg> not found

errno:
GSACK_ERROR for missing <prg>

 cp [-b] [-r] [-k|j] [-d|s] [-i|o] [-f] [-a] [-p] [-t] <Dest.path> [<File1> ...]

Copies file via the jinnee routines. (Warning: Wildcards are not 
permitted as yet! This works only for existing objects - just as for
Drag&Drop operations directly in jinnee.)

-b : Backup-mode (Warning: Won't work with Kobold -> use -j!)
-r : (Rename) Rename files (unfortunately won't work with Kobold!)
-k : Let Kobold perform the action if appropriate
-j : Let only jinnee routines perform the action
-d : Display dialog  ("Confirmation")
-s : (Silent) Do not display dialog
-i : Display indicator nevertheless
-o : Don't display indicator (off)
-f : Take "queued-up" files from the "Add" command (see below).
     One can still specify additional files ("<File1> ...") but 
     one does not have to, of course
-a : Copy asynchronously, i.e. the cp command returns immediately 
     while jinnee copies in the background
-p : (Replace All) On name collisions, replace all
     (Warning: Won't work with Kobold -> use -j!)
-t : (Trash) On name collisions use a replacement name
     (Warning: Won't work with Kobold -> use -j!)

One can also write several options one after the other following a 
"minus" character, e.g. "-jbs".

Warning: The destination path <Dest.path> must always be specified first 
(before the files to be copied).

Warning: In the files ("<File1> ...") there must be no empty parameters 
or parameters to be ignored (see GEMScript docs)!

Return:
"1" - OK, copying is taking or has taken place
"" - Error

errno:
GSACK_ERROR with incorrect parameters

 mv [-b] [-r] [-k|j] [-d|s] [-i|o] [-f] [-a] [-p] [-t] <Dest.path> [<File1> ...]

Moves files via the jinnee routines - similat to cp.

 rm [-k|j] [-d|s] [-i|o] [-f] [-a] [<File1> ...]

Deletes files via the jinnee routines - similar to cp/mv.

 Add <File1> ...

jinnee remembers the specified files for the running script. These can 
later be used with the option -f with cp, mv or rm. Following this the 
"store" will be empty once more.

This is useful for large copying action when otherwise the cp line 
would become too long (or obscure) in a script interpreter. Multiple 
cp commands would not necessarily provide a remedy as this might make 
the Copy dialog appear several times.

Return:
"1" - OK
"" - Error, (e.g. insufficient memory)

 Clear

Empties the store with the queued up files (Add).

Return:
Nothing

 eject [<dir>]

Ejects the medium in a drive. Only the drive is evaluated from <dir>.
If <dir> is missing then the normal jinnee routine will be called - 
the same one that can be reached from the menu entry too (i.e. an 
attempt will be made to eject the medium in the order: Selected drive, 
the drive of the topped window, or finally drive A:).

Return:
"1" - OK, (at least one) medium ejected
"" - No medium ejected

 finished

Returns whether an action started asynchronously (-a with cp, mv or rm)
has terminated.

Return:
"1" - Finished. No action still running
"" - Not finished, something is still running

 Exist <object>

Returns whether a file, a link or a folder named <object> exists.

Return:
"1" - Exists
"" - Does not exist

 FileExist <file>

Returns whether a file (or a link to a file) named <file> exists.

Return:
"1" - Exists
"" - Does not exist

 FolderExist <folder>

Returns whether a folder (or a folder link) named <folder> exists.

Return:
"1" - Exists
"" - Does not exist

 LinkExist <link>

Returns whether a link (file or folder) named <link> exists.

Return:
"1" - Exists
"" - Does not exist

 CheckApp <prg>

Checks whether application <prg> is running and attempts to launch it 
if it is not.

Return:
"1" - Found or launched
"" - Not running and also could not be launched (not found)

errno:
GSACK_ERROR for missing <prg>

 TestApp <prg>

Tests whether application <prg> is running.

Return:
"1" - Running
"" - Not running

errno:
GSACK_ERROR for missing <prg>

 LoadINF [<inf>]

Loads the INF file <inf> with the jinnee settings.
If <inf> is not specified, the file selector appears.

Return:
"1" - INF file loaded (or file selector, see below)
"" - Error during loading

Warning: On calling the file selector (i.e. without <inf>) the return 
is always "1", no matter whether the user has chosen OK or Cancel, or
even if there was an error during loading.

 SaveINF [<inf>]

Saves the current jinnee settings in the INF file <inf>.
If <inf> is not specified, the file selector appears.

Return:
Exactly as for LoadINF!

 NoteOpen [-i <ID>] [-l <width>] [-b <backcolor>] [-d] [-w|-o] [-a]
           [-px L|C|R] [-py T|C|B] [-x <pos>] [-y <pos>]
          {[-f <fntid>] [-p <point>] [-t <textcolor>] [-c]
          <Textline>}*

Places a note on the desktop.

-i:  <ID> = Four characters for ID (in case a given note is meant)

-l:  <width> = Line width of the note's border

-b:  <backcolor> = Background colour (-1 = light yellow, which jinnee
                   will find itself)

-d:  "don't save", i.e. the note will not be saved in  the JINNEE.NOT
     file.

-w:  "window", note is to be placed in a window.

-o:  "on desk", note is to be placed directly on the desktop.

-a:  "add" The lines should be added to an existing note.
     (Only sensible in conjunction with -i)

-px: "Pin" in X-direction when adapting size: L,C,R (or 0,1,2)

-py: "Pin" in Y-direction when adapting size: T,C,B (or 0,1,2)

-x:  X-position of the note
-y:  Y-position of the note 

     Normally these will be absolute pixel specifications that refer 
     to the "Pin" of the note.

     If the number is followed by a percent character ("%"), then the 
     note will be positioned on the desktop relative to a scale from
     0 - 10000 (not 100!). For this the pin is not the decisive factor 
     but the size of the note.

     If the number is followed by an asterisk ("*"), then the note will 
     be positioned on the desktop relative to a scale from 0 - 10000 and 
     with reference to the "Pin". So here it is not the size of the note  
     that is the decisive factor, but only the pin.

-f: <fntid> = Font-ID for the following text line(s)

-p: <point> = Point size  -"-    -"-

-t: <textcolor> = Colour  -"-    -"-    

-c: This line is to be output centred.


-f, -p, -t and -c can be placed before every line and may therefore 
appear several times.

-f, -p and -t also apply for all following lines, -c only for the 
current one.

If a note already exists with the same ID, then this will be "updated".
The  -f, -p, -t, -c  settings for the individual lines will not be 
altered during this if they are not specified.

Return:
"1" - OK
"" - Error, (e.g. insufficient memory)

 NoteClose -i <ID>

Deletes the specified note from the desktop.

Return:
"1" - OK
"" - Error (not found)

errno:
GSACK_ERROR if <ID> is missing

 NoteExist -i <ID>

Tests whether a specific note exists.

Return:
"1" - Yes, it exists
"" - No, it does not exist

errno:
GSACK_ERROR if <ID> is missing

 NotePad [-i <ID>] [-e]

Opens the notepad, optionally for a specified note.
It can also be edited directly (without a dialog).

-i : A specific note according to its ID
-e : Don't show (Edit) dialog, i.e. edit directly

Return:
Nothing

 ReRead [<dir>]

Makes jinnee read anew the contents of <dir>, so corresponds to "ESC" 
or SH_WDRAW or AV_PATH_UPDATE... ;-)
If <dir> is missing then all windows will be read anew.

Return:
Nothing

 Term <prg>

Sends AP_TERM to the program <prg> in the hope that this will then 
terminate... ;-)

Return:
"1" - AP_TERM sent
"" - Error (app not found)

errno:
GSACK_ERROR for missing <prg>

 EmptyTrash [-d|s] [-i|o]

Empties the recoverable wastebasket. Warning: Always asynchronous, 
i.e. after a reply to the command the wastebasket is not necessarily 
empty already. This can be interrogated however with the command 
"finished".
Options: see cp

Return:
Nothing

 GetIcon [-w] [-m] [-o] [-p] [-l <label>] [-t|-n|<name>]

Returns the icons.

-w: "Window" - Do not return any desktop icons
-m: "Mini" - Return mini icons (implies -w)
-o: "Open" - Flipped open icons (implies -m)
-p: "Prg" - Looks for program icons, attaces internally ".PRG" and ".APP"
-l: "Label" - Search for drive labels
-t: "Trash" - Return wastebasket icon
-n: "Notepad" - Return notepad icon

If the last character of <name> is a backslash then a search will be 
made for folder icons, otherwise for file icons. Drives are treated as
folders except that <name> consists of "Character + colon + Backslash", 
e.g. "C:\".

Return:
Address to following structure, where the address is specified as an 
ASCII string (ltoa); or "" if no icon was found or some other error 
has arisen (shortage of memory...).

typedef struct {
	int ob_type;	/* G_ICON or G_CICON */
	void *iconblk;	/* Pointer to ICONBLK or CICONBLK */
	char c;		/* Character that has to be inserted (for drives). 
	                  0 = none. */
} GS_GetIcon;

IMPORTANT: Before one returns GS_ACK, one _must_ copy out all the data!!! 
So everything from the GS_GetIcon structure, the ICONBLK (or CICONBLK) 
itself and also all of the icon data to which this points...


Every GEMScript client that has once sent jinnee an "GetIcon" command
and retains the communications channel (GS_REQUEST) to jinnee will get 
sent back the command "IconsChanged" for any alteration to jinnee's 
icons.

GetIcon can also be called without parameters, in which case though one 
will not get any icons returned, one will still be informed about any 
icon alterations.

 AppGetLongName

Returns the string "jinnee".

 GetApplication [ [-v] | [-e] | [-f] | [-d] | [-c] ] <file>

Returns the application(s) that are appropriate for opening a given 
file. There may be more than one!

-v[iewer]: The appropriate viewer will be returned (as with 
           Alternate + double-click).

-e[ditor]: The editor will be returned (as with Control + double-click).
           <file> is not normally taken into account.

-f[inder]: The search program will be returned.
           <file> will not be taken into account.

-d[iskformat]: The disk formatting program will be returned.
              <file> will not be taken into account.

-c[hangeRes]: The resolution changing program will be returned.
              <file> will not be taken into account.

Only one option (or none ;-)) may be specified at a time.

Return:
application(s) with path. (Or empty string or null-pointer if no 
application was found.)

errno:
GSACK_ERROR on error (e.g. memory shortage or specifying several 
options at the same time).

 QueryApplication [-Editor|-Viewer|-Finder|-Formatter|-ChangeRes]
[-Path <path>] [-Open <mask>] [-Show <mask>] [-Multiple
Never|Ask|Send|Start] [-ParaPass No|VA_START|Drag&Drop] [-StartPath
Progpath|Parapath|Windpath] [-Parallel 0|1] [-AVKbshift 0|1]
[-FollowLink 0|1] [-WDraw 0|1] [-Autostart 0|1] [-PropFont 0|1] [-Cmd
<cmdline>] [-SendCmd 0|1] [-NoParaNoCmd 0|1] [-Key <shortcut>]
[-PassSelected 0|1] [-ShiftWait 0|1]

Searches for an installed application. The parameters mirror all options 
that one can set in jinnee's "Applications" dialog for an installed 
application.

The function QueryApplication searches for an installed application 
that matches all the parameters passed (so the passed parameters have 
to be a portion of the actual parameters). If the specified parameters 
fit several applications, then only the first application found will 
be returned.

When searching for one of the special applications (Editor, Viewer, ...)
the corresponding parameter ("-Editor", ...) must be specified in order 
for the application to be found.

IMPORTANT: The individual parts of the parameter-list have to be 
separated from each other with NULLbytes.

A few examples of queries in a Scripter script:

QueryApplication("-Path", "intrface.prg");

	checks whether the program Interface is installed generally in 
	jinnee.

QueryApplication("-Path", "intrface.prg", "-PropFont", "0");

	checks whether the program Interface is installed in jinnee with the 
	"Prop. font" option switched off.


QueryApplication("-Editor");

	returns the installed Editor.

QueryApplication("-Path", "qed.app", "-Open", "*.inf,*.txt");

	checks whether qed is installed for opening "*.inf" and "*.txt".

Please note:

For the "-Path" parameter one can also specify just the filename in 
place of the complete path (the extender must however be given).

For "-Open" and "-Show", checks are made whether the individual parts 
of the matching pattern are present in the corresponding application that 
is being tested (their order is immaterial). This means that if, in the 
above example, qed was installed in jinnee for "*.txt,*.doc,*.inf", 
then it will still be found, as the partial strings "*.inf" and "*.txt" 
of the search string are present in the installed application.

For "-Key" the following applies for keyboard shortcuts:
"a" = Alternate
"s" = Shift
"l" = Left Shift-key
"r" = Right Shift-key
"c" = Control
These have to be in lower case letters and in this order; normal letter 
keys have to be written in capitals.
For instance, the shortcut Shift+Control+Alt+C will be: "ascC".

Return:
The complete parameter-list of the located application. (Can be reused as 
parameters for QueryApplication, CreateApplication or RemoveApplication).
If no suitable application was found, nothing will be returned.

errno:
GSACK_ERROR on error

 CreateApplication [-Editor|-Viewer|-Finder|-Formatter|-ChangeRes]
[-Path <path>] [-Open <mask>] [-Show <mask>] [-Multiple
Never|Ask|Send|Start] [-ParaPass No|VA_START|Drag&Drop] [-StartPath
Progpath|Parapath|Windpath] [-Parallel 0|1] [-AVKbshift 0|1]
[-FollowLink 0|1] [-WDraw 0|1] [-Autostart 0|1] [-PropFont 0|1] [-Cmd
<cmdline>] [-SendCmd 0|1] [-NoParaNoCmd 0|1] [-Key <shortcut>]
[-PassSelected 0|1] [-ShiftWait 0|1]

Installs a new application. Parameters as for QueryApplication. An 
application that is already present will NOT be replaced, but in general 
a NEW application will be created. Exception: The special applications
(Editor, Viewer, ...); there is always only one of these.

Missing parameters will be set to their default values (as if one were 
installing a new application in jinnee manually).

Return:
The complete parameter-list of the installed application.

errno:
GSACK_ERROR on error

 RemoveApplication [-Path <path>] [-Open <mask>] [-Show <mask>]
[-Multiple Never|Ask|Send|Start] [-ParaPass No|VA_START|Drag&Drop]
[-StartPath Progpath|Parapath|Windpath] [-Parallel 0|1] [-AVKbshift
0|1] [-FollowLink 0|1] [-WDraw 0|1] [-Autostart 0|1] [-PropFont 0|1]
[-Cmd <cmdline>] [-SendCmd 0|1] [-NoParaNoCmd 0|1] [-Key <shortcut>]
[-PassSelected 0|1] [-ShiftWait 0|1]

Remove installed application. Parameters as for QueryApplication.

Returns:
"1" - Application removed
""  - Application not removed (e.g. because not found)

errno:
GSACK_ERROR on error

 OptionHelp <page> [<option>]

For interactive Help systems: Opens the Settings dialog at the page
<page>. If <option> is specified then in addition the named option is 
emphasised in red. At present recognition occurs purely (automatically) 
from the object title actually displayed. For popups and groups of 
objects further possibilities would be sensible; perhaps this will 
come in the future.

The same function can also be called via VA_START, incidentally.
Command line format: "#OptionHelp <page>|<option>". (<option> can be 
omitted).

 TrashPath

Returns the wastebasket directory that is set in jinnee.
(Warning: May be an empty string if the user has not specified a 
directory.)

 Label <path>

Returns the drive label (established via Dreadlabel). For <path> one 
should always specify paths in the form "letter, colon, backslash".
In Scripter make sure that you use backslash quoting, such as, say:
jinnee.Label("C:\\");

errno:
GSACK_ERROR on error.

 CheckCommand <cmd>

Returns whether a command is understood. (See GEMScript docs 1.2)

 GetAllCommands

Returns all known commands. (See GEMScript docs 1.2)

