Reflective Images Tooltypes Library
===================================

By Stephen McNamara, inspired by the collection of tooltype functions by
Mark Tiffany.

(c)1994 Reflective Images

This library contains commands to allow the reading, comparing and setting
of tooltypes in a .info file.  All tooltype names are case insignificant
but as a general sort of rule they should really be completely uppercase.

This library attempts to open the system Icon.library, if the opening of
this library fails ALL commands in this library will be unusable.  Almost
every function in this library relies on the Icon.library completely.

Command list:
			GetIconObject filename$
			PutIconObject filename$
			FreeIconObject
			FindToolValue tooltype$
			FindToolNumber toolnum#
			MatchToolValue tooltype$,value$
			PutToolValue tooltype$,value$
			NewToolType tooltype$,value$
			ClearToolTypes


Statement/Function: GetIconObject
------------------------------------------------------------------------
Modes  : Amiga
Syntax : GetIconObject filename$
	 suc.l=GetIconObject (filename$)

  This command reads in a .info file from disk.  The filename given will
have '.info' added to the end of it and will be loaded into memory (chip or
fast depending on what is available for allocation) as a diskobject.
Please refer to the Amiga hardware includes for information about the
diskobject structure (or see your Blitz Basic Amigalibs resident file).

  If used as a function, this command will return either FALSE for failure
or the address of the allocated diskobject in memory.


Statement/Function: PutIconObject
------------------------------------------------------------------------
Modes  : Amiga
Syntax : PutIconObject filename$
	 suc.l=PutIconObject (filename$)

  This command takes a diskobject structure reserved and initialised by
GetIconObject and saves it out to disk as a .info file for the specified
file.  All current tooltypes and values will be saved with the file.


Statement/Function: FreeIconObject
------------------------------------------------------------------------
Modes  : Amiga
Syntax : FreeIconObject
	 suc.l=FreeIconObject

  This command will free up the diskobject that is currently being used.
It will not save out any tooltype changes and will free up the memory
without ANY changes being made to the .info file loaded from disk.


Function: FindToolValue
------------------------------------------------------------------------
Modes  : Amiga
Syntax : toolval$=FindToolValue(tooltype$)

  This function returns the value of the selected tooltype.  The return
value is a string, and is the part of the tooltype string after the "=" in
the tooltype entry.  The tooltype$ string that you pass can be in either
lower case or uppercase since all testing in done in uppercase, although as
a general rule, all tooltypes should be in uppercase.
  This function will return a null string if the named tooltype was not
found in the list of tooltypes for the file.  If the selected tooltype did
not have an actual value (e.g. DONOTWAIT) then this function will return
the string "!!".


Function: FindToolNumber
------------------------------------------------------------------------
Modes  : Amiga
Syntax : toolval$=FindToolNumber(tooltype$)

  This command will return the FULL tooltype string in the selected
tooltype position.  If the tooltype number does not exist then "" will be
returned.

  Example:	tooltypes: "DONOTWAIT"
			   "CLOCKX=157"

	FindToolNumber(0) will return "DONOTWAIT"
	FindToolNumber(1) will return "CLOCKX"
	FindToolNumber(49) will return ""


Function: MatchToolValue
------------------------------------------------------------------------
Modes  : Amiga
Syntax : suc.l=MatchToolValue(tooltype$,value$)

  This command searchs the current list of tooltypes for the selected
tooltype and, if found, attempts to match the values of it with the given
value.  This command uses the operating system call MatchToolType(), it
is able to cope with a tool having more than one value,

  		e.g. LANGUAGE=ENGLISH|FRENCH
			(the | is used to show OR, thus this tooltype
			 means that LANGUAGE equals ENGLISH or FRECH)
		When using match toolvalue with this tooltype, TRUE will be
		returned when you use value$="ENGLISH" or "FRENCH" but not
		(I think) both.

  You should note that for this command, the case of VALUE$ is
insignificant.


Statement/Function: SetToolValue
------------------------------------------------------------------------
Modes  : Amiga
Syntax : SetToolValue tooltype$,value$
	 suc.l=SetToolValue (tooltype$,value$)

  This command will attempt to set a tooltype that is currently defined to
the specified value.  When used as a function, this command will return
TRUE for success or FALSE for failure, possible failures include: no icon
file loaded and tooltype not found.  When used, this command attempts to
allocate memory to store the new tooltype information in, it does not
attempt to free up the old memory allocated to the tooltype.  This means
that you should keep alterations of tooltypes to a minimum.  The best way
to manage tooltypes is:

		1. Open the icon
		2. Read the tooltypes
		3. Close the icon
		4. ... do your program ...
		5. Open the icon
		6. Alter the tooltypes
		7. Save the icon

  Using this series of events, you'll keep memory usage (which will be
fairly small anyway...) to the very minimum.


Statement/Function: NewToolType
------------------------------------------------------------------------
Modes  : Amiga
Syntax : NewToolType tooltype$,value$
	 suc.l=NewToolType (tooltype$,value$)

  This command allocates a new tooltype in the currently loaded .info file
and sets its value.  No check is done to see is the tooltype already
exists and the new tooltype is added to the end of the current list of
tooltypes.


Statement: ClearToolTypes
------------------------------------------------------------------------
Modes  : Amiga
Syntax : ClearToolTypes

  This command is used to clear all the tooltype information from the
currently loaded .info file.  It does not attempt, though, to free up all
the memory reserved to store tooltype names and values, you should
therefore not used this command too many times in a row.  Once you have
used this command, any attempt to read tooltype values will fail.

>>END