!Help file for !NeXTBar - Licence and Usage Instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

       Version: 1.07 (15th Feb 2002)
        Author: Paul Vigay <paul@vigay.com>
Available from: http://www.vigay.com/shareware/


Purpose
~~~~~~~
A multi-purpose application launcher and desktop tidy-upper.


Status
~~~~~~
NeXTBar is Shareware. If you find NeXTBar useful you can register by
sending me 12.00ukp. In return you will receive a registration code
which will unlock the features which are disabled in the free 'demo'
version. Cheques should be payable to "Paul Vigay" and posted to the
address given below (contacting me). Alternatively, you can pay by
credit card via a secure link from the web page above.


Distribution Licence
~~~~~~~~~~~~~~~~~~~~
This product cannot be used, bundled or supplied with any other product,
compilation of products or collection of software, either in part or in full,
without the express written consent of the author. This includes (but is not
limited to) PD compilation discs, magazine cover discs, software collections, 
commercial software or any other form of media or third-party distributor.

It may not be added to, uploaded or stored on any third-party web site other
than that owned or managed by the author.

If supplied (with the author's permission) by any third-party, all files must 
remain intact and cannot be altered, modified or changed (with the exception
of any 'user choices' saved/created by the software itself).
This licence does not allow any third-party to disassemble, reverse-engineer
or otherwise examine the program code.

The author of this work reserves the right to change any or all of the terms
of this licence without prior notice to third-parties.

If you have obtained this software from an authorised distributor, it is
worth checking the authors web site to see if a newer version is available.
If you would like permission to distribute this software, please contact the
author via any of the methods indicated below.


What is it?
~~~~~~~~~~~
NextBar places a NeXT style bar down the right-side of the screen, which
contains a number of buttons which can be assigned different applications.
To load an application simply, double-click on the relevant button. It also
has some other features:-

		* Up to 55 buttons per 'page' (depending on screen size)
		* Nine pages, easily switched via coloured tabs or CTRL-
		  function keys (1-9)
		* Controllable via a menu or bar.
		* Selectable bar size, small or large.
		* Vertical or Horizontal configuration.
		* Password protection to stop unauthorised people editing
		  the buttons or hotkeys.
		* Optional display of free memory.
		* Optional display of time or date.
		* Ability to lock screen position of bar.
		* Each application can be set to be 'seen' or even loaded
		  automatically when NextBar starts up.
		* Each application can be assigned a 'hotkey' to simplify
		  application launching.
		* Relatively compact (only 156K)
		* Supports Acorn's interactive help.


How to use it
~~~~~~~~~~~~~
The first time you run NeXTBar it will put a blank bar down the right-hand
side of the screen. It should scale automatically to the size of the screen
mode you are using. The number of buttons will be automatically calculated 
in order to provide the optimum display for your particular screen mode.

At the top of the bar you will see nine coloured buttons. Clicking on each of
these will display a different bar. The currently selected bar is indicated
by a small coloured indicator immediately below the buttons.
NB. You can also change bar by pressing CTRL and a function key from 1-9 to
change to the specified page.
NB2. If you hold SHIFT down whilst clicking on the coloured buttons, you can
'name' the different bars. This will be used to create meaningful sub-menus
when selecting different bars using the menu navigation. (added at v0.04)

The rest of the buttons indicate which applications or files you have linked
to. Just double-click on a button to launch that particular file or
application. Holding SHIFT down acts the same as in normal filer windows - ie
it will open directories or load files into a text editor.
If a button is assigned a web URL, NeXTBar will launch the required URL in
a web browser window.

To add a new application or file, just drag the icon you require from the
filer window and drop it onto the chosen button. This will open the
'Application Options' window:-


Copying/Moving buttons
~~~~~~~~~~~~~~~~~~~~~~
(added at version 1.05)
You can copy a button by dragging it to a new position. Whilst the drag
operation is in process you can still press the 1-9 hotkeys in order to
change the destination bar.
Hold SHIFT down when you do the initial drag to MOVE a button rather than
copy it. The hotkeys still work in order to change the bar during the drag
and you don't need to keep SHIFT held down (only required for initial drag).

N.B. No overwrite warning is given, so be aware that copying/moving to a
button already in use will replace the function already assigned to that
button.


Application Options
~~~~~~~~~~~~~~~~~~~
When you drag a file or application (or even a URL from a web browser) to a
NeXTBar button, you will be given a number of options that you can set. 
These are:-

	'See' on loading	If this option is turned on, NeXTBar will
				'filer_boot' the specified application each
				time you load NeXTBar. This is only relevant
				to applications dragged to NeXTBar. This
				option will be ignored for ordinary files.
				
	Auto-load		If this option is turned on, NeXTBar will
				automatically load the specified application
				(or open it, if a directory) when you load
				NeXTBar. This is handy if you want to add
				NeXTBar to you Boot sequence and want it to
				load various applications each time you start
				up your machine.
				N.B. This control is overruled by the 'Disable
				autoload' option in the main choices (below)
				
	Insert text at caret	If you assign a plain text file to a button
				you can have the option of either loading the
				file into a text editor when you double-click
				ont the button, or actually insert the text
				of the file into the current document at the
				caret position.
				This option will only work if NeXTBar detects
				a text file, and was added at version 1.03
				
	'Hot' key		You can enter any key from A-Z in here (case
				insensitive) to assign a hotkey to the 
				specified file or application. This allows you
				to load it simply by pressing CTRL and the
				character you enter.
				To remove a hotkey, simply delete the value
				entered (leave blank).
				NB. Hotkeys can be globally turned on or off
				from the main choices (below)
				NB2. Note that due to the way RISC OS handles
				internal key numbers, CTRL A-I is the same
				as CTRL 1-9, so pressing CTRL 1 will also
				activate anything defined as CTRL-A.
				
	Button Name		By default, NeXTBar will automatically extract
				the 'leaf name' (ie. the filename excluding
				the full filepath) from the file or
				application you dragged to the button.
				Normally you can simply leave as this, but
				you may wish to manually edit it, especially
				in the case of web URLs which often just
				resort to 'index.html'. This name is the name
				displayed on the NeXTBar button. It can be
				up to 12 characters long.

	Button sprite		By default this is blank and NeXTBar will
	                        use the default application sprite to put on
	                        buttons.
	                        However, if you enter a sprite name in here
	                        it will take precedence and allow you to 
	                        change the sprite on each button.

	                        N.B.The sprite name should exist in the
	                        wimpsprite pool. Also, if you use a sprite
	                        which is bigger than the button, you may end
	                        up with bits which overflow the button and
	                        aren't redrawn properly (although NeXTBar will
	                        still function normally).
	                        
	Path			Displays the full pathname of whatever you
				dragged to the button. You would not normally
				change this. However, the icon is writable
				just in case. Be careful if you do manually
				edit the value though, as you may get 'file
				not found' errors if NeXTBar can't find the
				file.
				Just above the actual filepath is a red
				description of what you are editing. This will
				usually be a file, application or URL.
				
	Cancel			Cancel adding/editing the button and close
				the Application Options window.
				
	Update			This will save the information and assign
				the file or application to the button.
				
The grey numbers in the bottom left hand corner are internal information
relevant to NeXTBar and can be ignored. However, for more advanced (or
curious) users, they indicate the reference of the actual button you are
editing in the form page no./button no. Note that both references start from
0, so the top button on page 1 will be shown as 0,0 and the fifth button on
page 8 will be shown as 7,4.


The Main Choices
~~~~~~~~~~~~~~~~
Clicking MENU over a button will give you the option to either edit the
contents of the button (described above) or to erase the contents of the
button (ie. make it blank again).
If you click MENU anywhere EXCEPT over a button you will be shown the main
menu, consisting of four options;

	Info		Move right to see the version details of NeXTBar
	Choices...	Open the choices window (below)
	Help		Display this !Help file.
	Quit/		Quit NeXTBar
  	  Unregister	(see below)


Unregistering
~~~~~~~~~~~~~
If you hold the CTRL key down while opening the main menu, the 'Quit' option
will be replaced a the 'Unregister' option. Selecting this from the main
menu will unregister NeXTBar and also delete the choices file from within the
application. This is mainly to avoid manually opening the application 
directory if I release a version with an updated choices file (which would 
require this file deleting).
N.B. Selecting 'Unregister' does NOT delete your application data file or
screen position. If you wish to pass an unregistered copy of NeXTBar on to a
friend, you should manually delete ALL files in the !NeXTBar.data directory.

	
The Choices Window
~~~~~~~~~~~~~~~~~~
The main choices window contains a number of options which allow you to
customise the look and behaviour of NeXTBar to suit your own preferences.
These will now be described in turn:-

	Include free memory	If on, NeXTBar will display a 'free memory'
				indicator at the bottom (or right, if horiz.)
				of the bar.
				
	Include time		If on, NeXTBar will display the current time
				at the bottom (or right, if horiz.) of the
				bar. If required you can change this to the
				date....
				
	...or date		Displays the current day and date instead
				of the time (above).
				
	Allow 'Hot' keys	Enables the hotkey feature whereby each button
				can be assigned a hotkey from A-Z in order to
				launch the file/application simply by pressing
				CTRL and the key.
				However, you may find this interferes with
				other applications, or just don't require it,
				thus the ability to disable it. If turned off
				NeXTBar will ignore all hotkeys.
				
	Use 'Shift-CTRL'	This assigns an alternative method to activate
				function keys. Instead of pressing CTRL and
				the function key, you need to press SHIFT and
				CTRL. This allows for clashes with other
				applications which also activate via CTRL-
				function keys.
				N.B. This only affects changing bar via the
				function keys. It does not affect the CTRL-key
				assigned to individual buttons.
				
	Disable autoload	If on, NeXTBar will NOT load ANY applications
				when it is started up, even though some
				buttons may be set to autoload. This feature
				was mainly put in for debugging purposes (as
				I didn't want multiple copies of things
				loading each time I ran NeXTBar) but I thought
				I'd leave it in, in case people found it
				handy.
	
	Single click		Make buttons activate on a single click
	                        instead of a double-click.
	                        
				
	Positioning
	~~~~~~~~~~~
	Include titlebar	Allows you to turn the title bar on or off
				This may be preferential when using the bar
				in its horizontal orientation, as it saves
				screen space.
				N.B. If the title bar is off you won't be
				able to move the bar around until you turn
				it back on again.
				
	Lock position		If on, NeXTBar will lock the position of the
				bar and won't allow you to drag it to a new
				position, irrespective of whether the title
				bar is on or off (see above).
				
	Auto-expand		If on, NeXTBar will automatically expand to
				fill either the full height or width of the
				screen mode you are currently in. If off,
				NeXTBar will create as many buttons as you
				specify to the right of this option:-
				
	or use max buttons	If you want a fixed size NeXTBar you can turn
				the above option off and specify how many 
				buttons you require. This can be any number
				between 1 and 55 (maximum).
				
				NOTE: If you change into a smaller screen
				mode, you may find that some buttons become
				inaccessible due to exceeding the maximum
				number of buttons allowed for the current
				screen mode. If this happens, either change
				back into a bigger screen mode, or bear this
				in mind when setting up your buttons.

        Disable copy/move       If this option is toggled ON, the copy/move
                                buttons by dragging them will be disabled.
                                This is useful for people who don't want to
                                accidentally move buttons around by accident.

	Small bar		If on, the bar will be rescaled to approx
	                        half size. This will occupy less screen space
	                        for those people who require a minimalist
	                        display.
	                        
	                        N.B. Whilst in this mode you cannot display
	                        free memory or clock display. Also, text
	                        labels are removed from the buttons for
	                        clarity.
	                        
	Orientation		You can choose from two options, simply by
				clicking on the Vertical/Horizontal icon.
				This is self-explanatory and will reset the
				orientation of the bar.
				
	Save position		Click once on this icon in order to save the
				current position of the bar. Next time you 
				load NeXTBar it will be drawn in the same
				position. If you wish to move it again, simply
				click on the 'save position' icon again.
				The actual screen coordinates of the position
				are saved within the file called
				!NeXTBar.data.position and are in plain text
				format. The current page is also saved.
				If you wish to reset the position, you can
				either manually reposition the bar, or you can
				delete this file, in which case NeXTBar will
				reset to default location.
			
	Put icon on iconbar	Some people expressed a wish to select apps
	                        from a menu structure (similar to !Menon) so
	                        I added this option at v0.04. There are three
	                        options (click SELECT to toggle between them).
	                        They are self-explanatory and allow you to
	                        either have just an icon, just the bar, or
	                        both.
	                        N.B. The position of the icon (left/right side
	                        of the iconbar) can be set manually by editing
	                        the !NeXTBar.Resources.Messages file - but
	                        the normal user shouldn't need to change this.
				
	Use password		Click on the 'Use password' icon to activate.
				If no password has been set (which will be
				the case if you're using NeXTBar for the first
				time), you will be prompted to enter a new
				password. Enter the password in the writable
				icon. You then need to enter the password 
				again, for confirmation.
				Once you have entered a password, you can
				toggle the 'Use password' icon on or off.
				If on, you won't be able to add or edit any
				buttons or use some of the choices options.
				The password is encrypted and saved within
				NeXTBar and will be needed if you want to edit
				any buttons or even if you wish to change
				the password again.
				To remove the password, simply change the 
				password to a blank (ie. empty) entry.
				
	Cancel			Cancel any alterations you may have made and
				go back to the options that were selected
				when you first opened the choices window.
				
	OK			Choose the new options and save for next time.
				Clicking OK will also redraw the bar to 
				reflect any changes.


Miscellaneous Hints 'n' Tips
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Clicking on NeXTBar (but not on an actual button) with SELECT will bring
  NeXTBar to the front. Clicking with ADJUST will put NeXTBar to the back.

- Icon colours of free memory/time/date icons
  Advanced users can change the font and/or background colours of the free
  memory and time/data indicators by editing the values in the
  !NeXTBar.Resources.Messages file.
  The value consists of an eight-bit hexadecimal value with the upper 4 bits
  signifying the background colour and the lower 4 bits setting the font
  colour. These range from 0-F for the 16 default wimp desktop colours.
  
- Data formats
  Although you should NOT edit the internal datafiles by hand, NeXTBar stores
  its data in plain text format. The button definitions are stored in
  !NeXTBar.data.appdata and consist of two lines for each entry;
  The first line contains the options set in the Application Options and the
  second line contains the actual filename of the file/application.
  Do not change these by hand, but I've opted to store in plain text format
  so that advanced users can do a search/replace should they change the name
  of their hard drive, or want to move 'everything' on to a new filing system.

		
Comments
~~~~~~~~
If you find any bugs, or have any ideas for future versions or
enhancements, please feel free to contact me.
Also, if you feel that there is something lacking or not explained well
enough in these instructions, please advise me so that I can improve
future documentation.


Contacting the author
~~~~~~~~~~~~~~~~~~~~~
You can contact me in several ways:-

1. Email me at paul@vigay.com
   (you can click on my name in the 'Info' window)

2. Go my Acorn Shareware page on the internet at
   http://www.vigay.com/shareware/
   (this site is also mirrored at http://www.vigay.net)

3. Write to me at 104 Manners Road, Southsea, Hampshire, PO4 0BG, England


History
~~~~~~~
Changes made between versions:

v1.07 (7th Feb 2002)
        a) Bug fix: Autoload option occasionally didn't recognise the first
           mouse click on it, when it was previously ON.
        b) Added 'Disable copy/move' option to main choices which will
           disable the ability to drag buttons to new locations.

v1.06 (21st Oct 2001)
        a) Bug fix: Fixed application launching from Apps menu.
        
v1.05 (17th Oct 2001)
        a) Made dragging things to buttons more intelligent, in that only
           applications set the default 'See on loading' set to 'on' and
           normal files/directories default to 'off'.
        b) Bug fix: Prevented repeated jumping to the front when using
           virtual desktop managers, such as !WorkSpace.
        c) Added facility to copy/move buttons by dragging them to new
           positions (hold SHIFT down to move button).
        d) Amended interactive help to display bar names when moving pointer
           over the coloured bar selectors.
        e) Added facility to toggle between clock/date display by clicking on
           the clock/date icon on the bar.
        f) Added facility to use a user-defined wimpsprite on each button.
        g) Expanded data area to allow for up to 55 buttons on each bar
           (previously 25)

v1.04 (17th Jun 2001)
        a) Bug fix: Stopped hotkeys intercepting non ctrl-keys (ie. pressing
           backspace used to trigger CTRL-H etc).
        b) Made free mem and clock icons clickable so that you can click on
           them to make bar go to front/back.
        c) Added 'Single click' option so that you can decide whether you
           want the buttons to activate on a single or double-click.
           Thanks to Wim van Cappellen for suggesting this option.

v1.03 (8th Jun 2001)
        a) Correctly scaled sprites when 'small bar' is set and there are no
           pre-defined wimp sprites available.
        b) Communicate the full 'button file path' to !Help when the mouse
           pointer is over one of the buttons.
        c) Added facility to insert text files at the caret position.
        d) Tidy up: 'Autoload' window not opened on loading unless there
           are other things to load.
        e) Bug fix: Setting horizontal bar with free memory display and no
           clock/date display corrupted the bar redraw.
        f) Bug fix: NeXTBar window not put to the back when you click ADJUST
           to update the main choices.
        g) Bug fix: Correctly disallow ; characters in filenames and button
           names (this is because ; is used as an internal terminator for
           NeXTBar itself)
        h) Bug fix: Un-highlight any 'selected' buttons when you change bar.
           
v1.02 (25th May 2001)
        a) Bug fix (introduced in v1.01): Clicking adjust on the NeXTBar
           correctly puts the bar to the back.
           
v1.01 (24th May 2001)
        a) Bug fix: Occasionally allowed you to assign the same hotkey to
           different buttons. Now an error is correctly given.
        b) Amended button erasure confirmation message to contain correct
           button name, if unable to extract a valid leafname.
        c) Bug fix: Free memory/clock updated immediately when you OK the
           choices.
        d) Greyed out empty bars from the application menu.
        e) Changed NeXTBar bar title to display the title of the current
           bar.
        f) Tested working ok on RISC OS 3.11
        g) Bug fix: Clicking on title bar brings bar to front, even if
           'lock position' is turned on.

v1.00 (8th May 2001)
        a) Added 'Apps' menu in order to load applications via menu control
           as well as via the navigation bar.
        b) Added iconbar option to main choices window.
        c) Added 'Unregister' option.
        d) Bug fix: The erase menu option wasn't greyed out correctly on
           blank buttons greater than 6.
        e) Added 'Small' mode to display a minimalist bar.
        f) Bug fix: Allowed chars>127 to be used in filenames, thus allowing
           apps like !HTML to be assigned to a button correctly.
        
v0.03 (25th Apr 2001)
        a) Fixed minor bug in that URIs assigned to buttons were incorrectly
           assigned a filtype F91 instead of B28.
        b) Tidied a couple of icons so that unregistered users don't get the
           caret in the hotkey icon, even though it's greyed out.
        c) Fixed bug in maximum buttons error validation. (only allowed 20)
        d) Improved autoheight detection for changing into different screen
           modes. The bar shouldn't overlap the icon bar in any screen modes
           bigger than 640x480.
        e) Greyed out the 'erase' button option if menu clicked over empty
           buttons.
           
v0.02 (21st Apr 2001)
        a) Adjusted templates to work better with larger desktop fonts
        b) Added facility to adjust click on bar to 'put to back'.
        c) Added 'Help' option to main menu, which will load this !Help
           file.
           
v0.01 (16th Apr 2001)
        - First version (test)


Paul Vigay, 13th Apr 2001
