| ***************************************************************
| *                     ZapBits extensions			*
| ***************************************************************

| Darren Salt:

TOICON
Sends the selected text to the next thing you click on (if it can accept the
input focus). Select "types" the text, Adjust causes a ^U to be typed first,
anything else cancels.
 
Up to 255 characters will be written, stopping at the first control
character.

SENDURL
Broadcasts the URL at the cursor position. URLs may be prefixed by "URL:",
enclosed in "" or <>, or unenclosed. Email addresses and URLs beginning with
"www." or "ftp." are recognised without requiring the protocol name prefix.
 
SENDURL tries to use AcornURI, falling back on the ANT protocol then on the
URI/URL variables (in which case the URL /may/ not be launched properly).

SENDURLSTRING <string>
Broadcasts the supplied URL in a similar manner to SENDURL.

@SENDURLSTRING <offset>
Returns either the URL at the supplied file offset, or a null string.

| Tim Tyler:

COMMANDIB
Executes a command string as if from the icon bar menu. This may be used when
wanting to set configuration options in mode menus or on button bars.

MENUFROMFILE <string>
This command reads a Zap-style menu file whose path is <string>, converts
this to a wimp menu and displays it on the screen with the pointer over the
middle of the first menu entry. The command was designed to be used from
button bars, but may prove useful elsewhere.

MODEMENU [<string>]
Used to provide access to the mode menu of a mode. The optional string may be
used to specify which mode's options are displayed by setting this to the
name of the mode.
 
Note that the MODE and MODEN commands perform a very similar function.
However, they get ticked in menus, change mode when clicked on, and MODE will
not take a string as an argument.
 
If no (or a null) string is provided then the mode of the current window is
set if there is one, otherwise, no submenu will be generated.
 
The command can be of use in menu files by using:

"Mode options" MODEMENU "ModeName"

EVENT <string>
Where <string> is [C/S]<interval> <command>

This initiates and terminates routines which regularly call specified Zap
commands.

Only a single Zap command with no arguments is permitted.

[C] cancels an event.
[S] sets a new event.

<interval> is in centiseconds.  Only one callback routine is currently
permitted at any one time.

Note that not all Zap commands take kindly to being called in such an
irregular manner.

TMT_IF <string>
Where <string> is <condition> THEN <commands>[ ELSE <commands>]

<condition> takes the form of anything that can be evaluated to a number by
the operating system's evaluation routines.  However before the evaluation
takes place, the following substitutions are made on the condition-string:

  "SHIFT"         : TRUE if SHIFT is currently being pressed / FALSE.
  "ALT"           : TRUE if ALT is currently being pressed / FALSE.
  "CTRL"          : TRUE if CTRL is currently being pressed / FALSE.
  "CONTROL"       : TRUE if CTRL is currently being pressed / FALSE.
  "SELECT"        : TRUE if the SELECT button is being pressed / FALSE.
  "ADJUST"        : TRUE if the ADJUST button is being pressed / FALSE.
  "MENU"          : TRUE if the MENU button is being pressed / FALSE.
  "BUTTONS"       : The state of the last pressed mouse buttons / FALSE.
  "MODE"          : The mode number of the current mode / TRUE if none.
  "TEXTMODENAME"  : Replaced by the name of the current mode *in quotes*.
  "INHTMLTAG"     : TRUE if the cursor in in an HTML tag / FALSE otherwise.
  "CURSORVAL"     : The ASCII value of the character under the cursor.
  "CURSORCHAR"    : The character under the cursor enclosed in quotes.
  "SELANYWHERE"   : TRUE if there is a selection anywhere in a Zap text.
  "SELHERE"       : TRUE if there is a selection in 'this' Zap text.
  "SELSIZE"       : The size of the current selection, or TRUE if none.
  "TICKED(<cmd>)" : TRUE if the Zap command <cmd> would be ticked in a menu.
  "GREYED(<cmd>)" : TRUE if the Zap command <cmd> would be grey if in a menu.
  "TRUE"          : -1
  "FALSE"         : 0

Note that these (and THEN and ELSE) are all CASE SENSITIVE.

TICKED and GREYED have the limitation that their parameter may not currently
be a Zap command which takes a string as its argument. They are also
currently sensitive to excess spaces - there should never be more than one
space in the expression, the one separating the Zap command from its
numerical argument. As an example, "GREYED(SAVESEL)" is equivalent to
"NOT(SELANYWHERE)".
 
If the condition is evaluated to a non-zero number, then the colon-separated
string of Zap commands after the 'THEN' is obeyed. If it is zero (FALSE) then
the commands after the 'ELSE' are executed (if this is present). If the
expression cannot be successfully evaluated then a warning is given
indicating where the problem lies.

MOUSETRAP
This command freezes the mouse pointer until all mouse buttons are released.
It was written to provide a 'lock' option on the 'drag' icons of button bars.

POWERSEARCH <string>
"POWERSEARCH <break><search string><break>[*][$][#/%]<Zap command(s)>"

This is a programmable search routine. It takes a search string and a
colon-separated string of Zap commands as parameters.

The search is performed in the currently selected region, and will only
operate if this is in the same window as that from which the command has been
issued.
 
The search string (which may be wildcarded) is delimited by a user-definable
character represented as <break> in the syntactic description.
 
If a '*' character is next in the string, the search is case sensitive.
If a '$' character follows, Zap's macros are used in the search.
If a '#' character comes next, then the region searched for is cut (deleted).

The cursor is positioned at the start of the found sequence, unless the next
parameter in the string is a '%' character. If this is the case then the
cursor is positioned at the end of the specified sequence.
 
'#' and '%' cannot be combined; if a '#' is present, no '%' is required.

Then the following colon-separated list of Zap commands is then executed.

This process continues until the search string is no longer found in the
selected region.
 
Because of the programmable nature of this command, it may get into infinite
loops if it is fed parameters in an unintelligent manner.
 
It can always be aborted at any point by pressing the <ESCAPE> key.

UPDATESTATUS
Executes the two internal Zap calls Zap_SaveWinStatus and Zap_NewWinStatus.
This refreshes the window's frame, and a number of other items.

