
ZapButtons - MultiMedia extensions to Zap
-----------------------------------------

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

(The GPL is supplied as !Buttons.Copying. Source should be available from
wherever you got ZapButtons or Zap; if you have difficulty, get in touch with
the maintainer, below.)


     ZapButtons is a modeless extension to Zap which provides toolbars attached
to Zap's editing windows. Please note that the method for configuring panes of
Buttons has changed since the last version: the option that needs to be ticked
is Display->Buttons from the window menu, or Options->Display->Buttons from the
iconbar. These optins can be saved for all future windows in the usual way, ie.
Window menu->Misc->Set default options->This mode, then 
Window menu->Misc->Set default options->Save defaults.

     Where a mode does not support buttons bars (thus the Display->Buttons menu
entry is greyed out), you can add a set of buttons by providing three files in
your ZapUser; this is slightly involved - see the Technical section of this
document.

     ZapButtons now provides a Persistent option - normally the buttons bars
disappear when the input focus is transferred to a different window; when
this option is ticked the buttons will remain attached. This option may be
set independantly for each mode.


Installation
------------

To install, copy the !Buttons aplication into the !Zap.Modules directory. Zap
will then need to be restarted.

Note that many modes will normally have their buttons option turned off by
default. This can be reconfigured as required from the 'Options' in Zap's icon
bar menu.


Technical
---------

Buttons are enabled by setting b12 of w_info. When Zap created an editing
window, it check if this bit is set, and if so executed the command
BUTTONS_START. This causes ZapButtons to be loaded, and a pane attached to the
window.

To provide a button bar, a few files must be provided. ZapButtons expects to
find files called Templates, Sprites, Scripts and possibly Menus in a directory
Zap<mode>:Buttons. Thus in your mode's !StartUp file you should set the variable
Zap<mode>$Path to point to a list of directories to be checked for buttons bars.
I recommend that this search path includes ZapUser:Modules.<mode> so that users
can arrange for alternative button bars to be used.

The Templates file contains the window definition for the buttons bar. Up to 4
buttons bars may be provided, defined by templates called buttons0 .. buttons3 -
the names are case sensitive. The command BUTTONS_CHANGE is used to swap between
them.

The Sprites file contains the sprites to be used by the buttons bars.

The Menus file gives a menu to be used on the Button bar, in the standard Zap
format. The initial menu used has a handle of 0. If this file is not present,
ZapButtons will use the mode's mode menu instead.


Scripts
-------

The format of the command scripts files is as follows:

Sections begin with "<BUTTONSn>" or "(BUTTONSn)" where n is the number of the
button bar concerned.

Each section consists of a series of entries, one for each icon in the
relevant button bar's template.  These are in the same order as the icons
are stored in the template file.

An entry begins with a series of lines of Zap commands.  These may be in the
form of a colon-separated list.

If a line is prefixed by a '%' then the window the button bar is attached
to is not given the input focus before the line of commands is executed
(this normally happens automatically).

If Zap doesn't have the input focus then the commands are normally executed
on the window the button bar is attached to, using the most recent cursor
position in the document for any insertions/deletions.  However this depends
to some extent on whether the commands involved require this information. If
they don't then there are circumstances when the commands may be issued on
other windows, (see E-Command for details of the circumstances) so only use
'%'s if you're sure you know what you're doing, and then with caution.

Any lines prefixed by a '$' are not 'learned' by Zap.

If more than one prefix is present on a line, then any '%'s must precede
any '$'s.

Lastly there is a section of interactive help.  This is is a line prefixed
with a '|' character. This line has any leading spaces stripped from it and
is then fed to providers of interactive help upon request.

The section is terminated by a single '-' character on a line.


Extension calls
---------------

ZapButtons provides some functions through the interface provided by 
Zap_CallExtension. The calls are:

Buttons_Create		&200	
Creates a new buttons bar and attaches it to the window.
	=>	R0 = pane number to attach
		R8


Buttons_Delete		&201
Deletes the current buttons bar from the window and forgets all about it.
	=>	R8

	
Buttons_Open		&202
Makes the current buttons bar visible.
	=>	R8

	
Buttons_Close		&203
Hides the current buttons bar (without forgetting about it - state such as pane
offset from main window is preserved).
	=>	R8

	
Buttons_GetPaneHandle	&204
Returns the Wimp window handle of the pane attached to a window, or 0 if no
pane is currently attached.
	=>	R8
	<=	R0 = handle / 0

	
Buttons_GetPaneWindow	&205
Returns the Zap window pointer given a pane window handle, or 0 if the handle
is not recognised.
	=>	R0 = pane window handle
	<=	R8 / 0
		R9 preserved (ie. NOT the file)

Buttons_FlagsToggle	&206
Executes the zap command BUTTONS_FLAGSTOGGLE.
	=>	R0 = _pointer to_ word in same format as WFLAGS_TOGGLE
		R8


Changelog
---------

2.00 30-Jan-03		Created
2.01 09-Feb-03		Added extension calls
2.02 20-Oct-03		Added the Persistent option

Christian Ludlam	christian@zap.tartarus.org
