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

       Version: 1.30 (17th Feb 2009)
        Author: Paul Vigay <nospam@vigay.com>
Available from: http://www.vigay.com/software/nextbar.html


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 188K)
		* Supports Acorn's interactive help.
		* Print/Snapshot any open window.
		* Save data direct from other applications into a chosen directory.
		* Grab video files from YouTube.


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)
				
	Add to iconbar		If this option is turned on, NeXTBar will automatically add the
	                        specified application or directory to the iconbar via the 
	                        'addtinydir' command. This allows you to link files, directories
	                        and applications to the iconbar.
				
	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 on 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
				
	Auto-save in directory	If you assign a directory to a button, by toggling this option
	                        you can directly save data or copy files into the specified
	                        directory. This is handy if you want to save or copy a file and
	                        you don't have a suitable destination directory window open.
	                        Simply drag onto your favourite directory button on NeXTBar.
	                        
	then open		when used in conjunction with the auto-save option above, this
	                        option will tell NeXTBar to automatically open the directory 
	                        that you've just saved data into.
				
	'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). You can also
launch applications/data via the Apps sub-menu or perform a web based search using a variety of
popular search engines.

If you click MENU anywhere EXCEPT over a button you will be shown the main menu, consisting of
seven options;

	Info		Move right to see the version details of NeXTBar
	Help...		Display this !Help file.
	Stats      >    Displays statistics for NeXTBar.
	Choices...	Open the choices window (below)
	Apps >		Display sub-menus of applications available.
	Web Search >	Initiate a web search using popular search engines.
	Search...	Search for NeXTBar button data/applications.
	Close Files...  Runs my !CloseFiles utility, which is now included as a NeXTBar plugin.
	Quit/		Quit NeXTBar
  	  Unregister	(see below)


Printing any open window
~~~~~~~~~~~~~~~~~~~~~~~~  	  
From NeXTBar version 1.20 is the ability to print (or save) any RISC OS window currently open.

Just hit the 'print' button and, after a brief pause, you'll be greeted with a standard RISC OS
dialogue window, from where you can either save the window as a sprite or print to the current
printer driver.

If the current application (with the caret) claims the print key, you can alternatively press
both ALT keys for one second to achieve the same result.

A couple of additional options are available (saved along with the main
NeXTBar choices) which allow you to include the window borders or auto-increment the filename.

Auto-incrementing the filename will automatically add an increasing number each time you save,
so that you can save a series of window or screenshots without having to change the filenames
each time.

If you have a printer driver loaded, simply press return or click 'Print' to print the window.

N.B. The window printed will be the one underneath the mouse pointer, and you should make sure
no other windows are partly obscuring it, otherwise your print may be incorrect.

Note also that the page is printed from a sprite, so will not be as good quality as if you'd
printed direct from the application. However, some applications (such as GhostScript) don't have
a printing capability, so this is the next best thing. :-)


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).
	
	24 hour time		Displays the time in 24 hour clock format.
				
	Anonymous Web Searching Pass all web searches through an anonymiser so that your web
	                        browsing cannot be traced.
	                        The parameters of the anonymiser can be edited by changing the
	                        values at the top of the !NeXTBar.Resources.Messages file.
	                        
	Extract video files	If this option is on, you can save an HTML web page directly
	                        from a web browser to a NeXTBar button and NeXTBar will scan the
	                        HTML source code looking for any YouTube video files. If one is
	                        detected, NeXTBar will automatically launch a browser to
	                        download the actual video file. This can be saved and then
	                        dragged onto Murnong for subsequent processing.
	                        (see http://www.users.on.net/~belles/software/murnong/)
	                        (added at v1.21)

        Save dirs		Click on the 'date' icon in order to step through the available
                                date formats for the name of sub-directories created if you have
                                the 'Create dated sub-dir' option enabled on your directory
                                button.
                                
	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.
				
	Single click		Make buttons activate on a single click instead of a
	                        double-click.

	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.
	
	Logging                 If this option is on, NeXTBar will diagnose a diagnostic log
	                        file. This may be useful to diagnose problems, if instructed by
	                        Paul.
                                In normal use it should be turned OFF.

        Save/Print
        ~~~~~~~~~~
	Disable			Disable/Enable the Save/Print features.
	
        Borders                 If on, NeXTBar will include the window borders when grabbing/
                                printing windows.
                                
        Titlebar                If on, NeXTBar will include the window title bar when grabbing/
                                printing windows.
                                
        Auto-increment          If on, NeXTBar will automatically increment the filename when
                                grabbing windows.
                                
        Debugging               If on, debugging information will be generated when you do a
                                print out.
                                In normal use it should be turned OFF.

				
	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.
				
	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:-
				
        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.

	Auto Hide               If on, NeXTBar will automatically disappear when you move the
	                        pointer out of it. It will re-appear when you move the pointer
	                        back to position X - where X is the side of NeXTBar closest to
	                        the nearest screen edge.
	                        For example, if NeXTBar was positioned to the right of the
	                        screen, it will reappear when the pointer crosses the RIGHT edge
	                        of where NeXTBar was before it closed.
	                        It's designed this way because generally NeXTBar would be
	                        positioned against the edge of the desktop, meaning it would
	                        automatically re-appear when the pointer touches the edge of the
	                        desktop on which NeXTBar was positioned.
	                        The sensitivity (in pixels) can be set by advanced users by
	                        editing the 'autohidesens' variable in the
	                        !NeXTBar.data.choices file.
	                        N.B. Moving the pointer to the bottom left hand corner of the
	                        screen and pressing CTRL will always re-open the bar, which is
	                        handy if it's auto closed and you can't remember the position.
	                        
	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).
				
	or use max XX 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.

	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.
	                        
	Open/Close delay        Sets whether or not there is a short delay when opening or
	                        closing the NeXTBar (only works when 'Auto Hide' is turned on).
	                        The actual delay is determined by the values set within the
	                        !NeXTBar.data.choices file 'opendelay' and 'closedelay' values.
	                        
	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.data.choices file -
	                        but the normal user shouldn't need to change this.
			
	Passwords
	~~~~~~~~~
	Use password		Click on the 'Enable' 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.
				
				
	Open data directory     Clicking on this icon will open NeXTBar's internal data
	                        directory. From here you can manually edit the various options
	                        files within NeXTBar.

	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.data.choices 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.

- Startup 'obey' file
  You can create an optional 'start' file and place it inside !NeXTBar.data and NeXTBar will
  execute each line of it after initialisation. This allows you to add an additional obey file
  of commands that NeXTBar will run AFTER initialising all its buttons and auto-loading
  applications.
  
- You can customise the search engines, or add new ones (up to 25 in total) by editing the
  !NeXTBar.Resources.Engines file in a text editor.
		
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 nospam@vigay.com
   (you can click on the relevant button in the 'Info' window)

2. Go my RISC OS Software page on the internet at
   http://www.vigay.com/software/

3. Write to me at:-

	"Digital Phenomena Ltd."
	PO Box 813,
	Portsmouth,
	Hampshire,
	PO1 9EY.
	England


Paul Vigay, 13th Apr 2001 - 2009
