ToolMaker v0.04 (22nd Apr 2008)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

BETA QUALITY - SUITABLE FOR COMMENTS AND SUGGESTIONS!!


Purpose
~~~~~~~
To automatically create and customise toolsprite icons.

One of the beauties of RISC OS is the fact the entire desktop can be customised with your own
icons and colours. However, until now it's always been quite intricate and time consuming to 
actually change all the desktop icons, because a complete set needs to be created in a pixel
editing package such as !Paint.

ToolMaker takes a different approach to the problem. It keeps a database of icon definitions, in
the form of a series of 'Logo like' text file which define each icon. ToolMaker can then
automatically create an entire set with any colours you like, simply by recreating a new set of
icons based upon the definitions provided.

The benefit of this is that once you've defined a set of sprites you can simply create them any
colour you require without having to go back and re-edit all the sprites by hand.


Licence
~~~~~~~
ToolMaker is Shareware. It's fully functional but if you find it useful, please consider sending
a donation of 10.00 to:-

	Digital Phenomena Ltd
	PO Box 813,
	Portsmouth,
	Hampshire,
	PO1 9EY
	England
	
Please make cheques payable to "Digital Phenomena Limited"


Use
~~~
ToolMaker is a complex tool, but intended to make things as easy as possible. However, it's 
still a "work in progress" application, so please feel free to offer feedback.

There are several sets of data that ToolMaker uses to construct your set of replacement tool 
sprites.

These are stored in various directories inside !ToolMaker, such as:-

	ToolDefns	The actual tool definitions, stored in their own directory structure.
	                (see below)
	                
	Schemes		Various colour schemes
	                (see below)
	                
	Profiles	Sets of user choices
	
	Resources	Internal files required for ToolMaker (do not edit)
	
	Docs		Various documentation and notes files (incomplete!)
	
	
Load ToolMaker by double-clicking on its icon. Its icon will appear on the bar. Clicking
SELECT on this will toggle the main window open or closed.

The main window comprises various options, such as:-

	Base tool icon set	Lets you choose one of the sets of toolsprites contained within
				the ToolDefns directory.
				
	Colour Scheme		Lets you choose a colour scheme. The new colour scheme is active
	                        as soon as you select it from the menu.
	                        
	Colours			Currently 16 or 256 colours are selectable from a menu.
	                        This determines how many colours your new tool sprites will have
	                        If you're using a 16 colour mode, you can optionally edit the
	                        colour mappings by clicking on the icon next to the colour
	                        selector.
	                        
	Debug			Normally turned off. You can turn this on to provide additional
	                        debugging information in case anything goes wrong.
	                        Clicking on 'View log' will open the log, if available.
	                        
	Profiles
	
	This section allows you to store different sets of choices, so you can store multiple
	combinations of choices.
	Either select a new profile from the menu (stored in the Profiles directory) or enter a
	new name in the writable icon and then click 'Save Profile' to create a new profile with
	the current settings.
	I hope to add an option to delete profiles in the near future. Keep an eye on the web
	site for updates and development schedule.
	
	Selecting a new profile from the menu DOES automatically load the profile, so be careful
	as any changes you've made recently will be overwritten.
	
	MiscSetup icon		Clicking on the MiscSetup icon will automatically load my 
	                        MiscSetup boot plugin, without double-clicking on !Boot.
	
	Cancel			Close the current window (doesn't currently cancel anything)
	
	Create ToolSprites	Create your new set of toolsprites. This will generate a new
	                        set of toolsprites and store them inside !ToolMaker, called
	                        "ToolSprites"


Colour Mappings
~~~~~~~~~~~~~~~
With 16 colour sprites you can edit the colour mappings within ToolMaker itself (as opposed to 
editing colour mapping files, for 256 colours). By clicking on the various colour icons you can
change which colour appears as which other colour.
If you want to use colours other than the 16 standard wimp colours, you'll need to create your
sprites in a 256 colour mode and edit the relevant colour scheme mapping files.
Clicking on the 'Reset to default' will reset them all to the default - or re-select a colour
scheme from the menu above.
Clicking 'Cancel' in this window will revert back to the previous colour arrangement.


The Tool Sprite Definition files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ToolDefns' directory inside ToolMaker contains a number of directories, one for each set of
toolsprite definitions. There are currently two, as examples:-

	dacha		A set of sprites based on those designed by Dacha (David Barrow)
	iyonix		A set of default Castle icons
	minitools	My personal favourite, which are slightly smaller than the default ones.
	ROS4		A set of RISC OS 4.03 icons
	sky		Some blue icons converted from a 32K colour set.
	
	
If you want to create your own sets, just create a new directory with the name you want to call
your new set (which will appear on the base tool icon set menu (see above).

Inside these directories is contained a complete set of text files defining each icon in the 
toolsprite set. These should be plain text files, saved with the same filename as the sprite
they represent.

Each file contains a number of commands in a Logo like script language, which instructs 
ToolMaker how to 'draw' the relevant sprites. Each command is on a new line and the following
commands are currently defined:-
Each command is followed by a single space and then one or more parameters.

	#	Any line starting with a hash (#) is a comment, and ignored.
	
	s	Icon size. This should be the first command in a file (and only occur once)
		It's followed by two parameters, separated by a comma. This defines the width
		and height of the sprite respectively.
		
	mask	Create a mask for the current sprite (useful if you want a sprite with a mask
	        but don't actually require any transparent pixels, where 'x' is inappropriate.
		
	c	Set colour for future commands. This command is followed by a single parameter,
	        the colour to use for all future commands - until you issue another c command.
	        
	x	Set transparency for pixel x,y (effectively same as 'p' but transparent)
	        
	m	Move to absolute location.
	        This moves the 'pen' to an absolute coordinate within the sprite, starting from
	        0,0 which is the bottom left hand corner.
	        Coordinates run from 0 to 1 less than the total width or height.
	        
	f	Fill relative in the current colour.
		This will fill a rectangle relative to the last position. For instance, if a
		"f 5,5" command follows a "m 6,6" command, it will move to coordinates 6,6 and
		then plot a rectangle 5 pixels wide by 5 pixels high.
		
	d	Draw to absolute location in the current colour.
		This will draw a straight line from the current pen location to new absolute
		coordinates.
		eg. m 3,4	will move to X coordinate 3 and Y coordinate 4
		    d 7,8	will draw a line to X coordinate 7 and Y coordinate 8
		  
	dt	Draw dots to absolute location in the current colour.
	        This command is the same as the 'd' command (above) but will draw a dotted line
	        instead (including both end points)
		  
	p	Plot pixel in current colour.
		This will plot a single pixel in the current colour at absolute x,y coordinates.
		
	r	Draw relative rectangle outline in current colour.
		This is similar to the f command except it will just draw a rectangle outline.
		
	e	Draw outline ellipse
		This shape is slighly more complex because it requires two previous 'm' commands
		(move) in order to set it up correctly.
		Basically, the procedure is;
			Move to the centre
			Move to the outermost (left/right)point at the same point as the centre.
			Plot the highest or lowest point (via the 'e' command)
		This is explained on page 127 of the BBC BASIC Guide.
		
	ef	Draw filled ellipse
		This works in exactly the same way as the outline ellipse (above) but will plot
		a filled ellipse.
		
	t	Draw filled triangle
		Again, this is done by defining three points (like ellipses, above) and thus
		has two m commands to move to two of the points, followed by a t command,
		defining the third point.
		N.B. There is no unfilled triangle, because that would effectively just be
		three lines (m, m, d)
		(see page 124 of BBC BASIC Guide)
		

A specific 'circle' command is not provided because a circle is just a regular ellipse, so can
be constructed using the e/ef commands.
		
By stringing the commands above together, you can define how your individual sprites will be
drawn. Although time consuming the first time you do it, you only need to do it once, and
ToolMaker can use the set in order to quickly and easily redefine the colours, whereas normally
you'd have to individually create a new set of icons if you want to change the colour scheme.


Quick way of creating tool sprite definitions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There's a quick way of quickly converting an existing set of sprites into a ToolMaker script.
Open the main window, then open your existing set of toolsprites into !Paint.
Then, save the sprite you require by dragging and dropping into the main ToolMaker window.
ToolMaker will then analyse the sprites contents and open a dialogue box containing the sprite
name, ready for dragging into your tool definition directory.

This will literally convert the entire sprite to individual plot commands (p) so is very
inefficient, expecially as you can put a border around a tool sprite by using a single
rectangle (r) command. However, it can provide a 'quick and dirty' way of converting complex
sprites. However, I'd recommend taking the time to learn how to use the script language and
optimising your own tool sprite definitions.

The minitools set of icons was defined by me, individually optimised using the script language
above, whereas the Iyonix tool set was created by ToolMaker using the quick method described
here. You can compare the text files to spot the difference.


Colour Schemes
~~~~~~~~~~~~~~
ToolMaker is incomplete in this department so far, as you can only edit the first 16 colours
from the colour mappings window (which is ok if you're using 16 colour sprites) but not much
good if you want to edit 256 colour sprites.

The directory 'Schemes' inside ToolMaker contains a number of colour translation tables, again
consisting of plain text files.

Each file should consist of the letter c followed immediately by the numbers 0 - 255 (each on
a new line) followed by a colon (:) and another number. This replaces the first colour with
the second colour (using the standard 256 colour !Paint palette colours).

For example, to replace colour 6 with colour 87 you simply edit the relevant line as follows

c6:87

Save each set of colour definitions with a different filename and each can be selectively loaded
from the relevant menu in the main ToolMaker window.

Feel free to examine the supplied files to see how it works. It becomes fairly easy once you get
the hang of it. :-)


Limitations
~~~~~~~~~~~
Probably several, as it's still under development!


Known Bugs
~~~~~~~~~~
Quite a few probably, but no show stopper ones (hopefully) as I've tested it reasonably well
myself.


To Do list
~~~~~~~~~~
 - Add an option to delete profiles.

 - Work out a better way of defining colour schemes.


History
~~~~~~~
There follows a concise list of changes between each version, in reverse date order so that the
latest changes are listed first.

 v0.04 (22nd Apr 2008) BETA TEST 3
        a) Bug fix: Correctly read colours when importing 16 colour sprites.
        b) Allowed sprites to be dragged to iconbar as well as main window in order to import.
        c) Bug fix: Correctly convert transparent/masked pixels when importing sprite data.
        d) Further optimised sprite import routine to add lines for repeated similar colours.
        e) Automatically reload colour scheme when creating toolsprites (saves remembering to 
           manually reload colours if you've edited the colour translation table).
        f) Automatically convert 32K and 16M colour sprites into 256 colour palette when
           importing sprites.
        g) Tested for A9 Home compatibility (added 'mask' command)
        
 v0.03 (18th Apr 2008) BETA TEST 2
        a) Redesigned templates slightly to make a less cluttered display, and remove colour
           translation icons if using more than 16 colours.
        b) Added open log button (if logging enabled)
        
 v0.02 (17th Apr 2008) BETA TEST 1
        a) Added support for transparencies ('x' command)
        b) Added support for dotted lines ('dt' command)
        c) Added support for outline ellipses ('e' command) and filled ellipses ('ef' command)
        d) Added support for triangles ('t' command)
        e) Optimised sprite import routine to only detect colour changes, rather than colour of
           every pixel.
        f) Bug fix: Correct conversion error in colour translations.
        g) Added additional set of tool sprite definitions, based on Dacha's design.
        
 v0.01 (16th Apr 2008) ALPHA TEST 1
        a) First release version, proof of concept only!

2008 Paul Vigay
