@DATABASE ToolType V1.00
$VER: Pure Basic - ToolType library V1.00 (26.09.1999) (c) Fantaisie Software
@NODE MAIN "ToolType V1.00"

  @{b}Pure Basic - ToolType V1.00@{ub}

    The 'Tooltypes' are located in a workbench icon. It's some
    strings you can easely write and read to store, for example,
    your program configuration. This is very useful because you
    don't need to create a separate file and the user can modify
    it himslef via the menu 'Icon/Information' of the Workbench
    screen.

  @{b}Commands summary:@{ub}

    @{" FreeToolType          " LINK FreeToolType}
    @{" GetNextToolTypeString " LINK GetNextToolTypeString}
    @{" GetNumberOfToolTypes  " LINK GetNumberOfToolTypes}
    @{" GetToolTypeValue      " LINK GetToolTypeValue}
    @{" InitToolType          " LINK InitToolType}
    @{" MatchToolType         " LINK MatchToolType}
    @{" MatchToolTypeString   " LINK MatchToolTypeString}
    @{" ReadToolTypeDiskInfo  " LINK ReadToolTypeDiskInfo}
    @{" WriteToolTypeDiskInfo " LINK WriteToolTypeDiskInfo}

    @{" ToolType Demo " LINK PureBasic:Examples/Sources/ToolType.pb/Main}
@ENDNODE


@Node FreeToolType

    @{b}SYNTAX@{ub}
  FreeToolType(@{b}#Obj@{ub}.w)

    @{b}STATEMENT@{ub}
  This statement frees a ToolType Object that was initialized with
  ReadToolTypeDiskInfo(), but it doesn't care if the Object to free
  isn't initialized.

  @{b}#Obj@{ub}
  The Object to free.
@EndNode


@Node GetNextToolTypeString

    @{b}SYNTAX@{ub}
  @{b}String@{ub}$ = GetNextToolTypeString(@{b}#Obj@{ub}.w)

    @{b}FUNCTION@{ub}
  This function returns the next ToolType and all associated values
  as a string.

  After the last ToolType is reached the next ToolType that will be
  returned is the first one. To find out how many ToolType strings
  exist, use the Returnvalue from the function GetNumberOfToolTypes().

  A ToolType is in length restricted to 128 bytes by the OS.

  @{b}#Obj@{ub}
  Object to use.

  @{b}String@{ub}
  The returned string holds the ToolType and all associated values like
  this  "AMIGA=1200|4000".
@EndNode


@Node GetNumberOfToolTypes

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.w = GetNumberOfToolTypes(@{b}#Obj@{ub}.w)

    @{b}FUNCTION@{ub}
  This function returns the number of ToolTypes that are present
  in the icon's .info file, this should be used to easily fetch
  the right number of ToolType strings.

  @{b}#Obj@{ub}
  Object to use.

  @{b}Result@{ub}
  Any positive value is the number of ToolTypes there is in the
  icon's .info file, but if it's instead  -1  this indicate that
  no ToolType at all is present in icon's .info file.
@EndNode


@Node GetToolTypeValue

    @{b}SYNTAX@{ub}
  @{b}String@{ub}$ = GetToolTypeValue(@{b}#Obj@{ub}.w,@{b}ToolName@{ub}$)

    @{b}FUNCTION@{ub}
  This function returns the associated values, to the specified ToolType,
  as a string.

  @{b}#Obj@{ub}
  Object to use.

  @{b}String@{ub}
  The returned string holds the Tool value like this "1200|4000", but
  if the ToolType was not present in icon's .info file the string
  will be empty.
@EndNode


@Node InitToolType

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.l = InitToolType(@{b}Objects@{ub}.l,@{b}*WBStartup@{ub})

    @{b}FUNCTION@{ub}
  This function set up some basic stuff to handle ToolTypes.

  This is the Init routine and should always be called before any
  other ToolType function. At the moment it could only be called
  once, so if there is a failure with this call the program should
  always @{b}quit@{ub}.

  @{b}Objects@{ub}
  This parameter specifies how many ToolType Objects are needed.
  Each Object can hold data about one .info file.

  Maximum number of Objects is 2046.

  @{b}*WBStartup@{ub}
  This is a pointer to a WBStartupMessage, this Message is passed to
  the program from WorkBench, *WBStartup is the Returnvalue from the
  function WBStartup() that catches the Message.

  With this approach Object 0 is always automatically initialized from
  the .info file of the double clicked icon and the current directory
  is also set to the directory of this icon.

  If this parameter isn't a pointer, but instead zero, none of the above
  actions have taken place.

  @{b}Result@{ub}
  If some error has occurred then result is FALSE and there is no point
  in calling any other ToolType functions.  Should Always Be Ckecked.
@EndNode


@Node MatchToolType

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.w = MatchToolType(@{b}#Obj@{ub}.w,@{b}ToolName@{ub}$,@{b}Value@{ub}$)

    @{b}FUNCTION@{ub}
  This function checks if ToolType is present and if it's set to
  the specified value.

  None of the ToolTypes need to be read into Pure Basic strings for
  this function, it's convenient when ToolTypes only need to be
  examined.

  @{b}ToolName@{ub}
  This is the ToolType to look out for.

  @{b}Value@{ub}
  This is the value to look out for, could be a zerostring.

  @{b}Result@{ub}
  If this is -1 the ToolType is not present in icon's .info file, if
  it's instead 0 the ToolType is found but it's not set to the specified
  value and finally if it's 1 then the ToolType is found and have one
  value that is the same as third parameter.
@EndNode


@Node MatchToolTypeString

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.w = MatchToolTypeString(@{b}String@{ub}$,@{b}ToolName@{ub}$,@{b}Value@{ub}$)

    @{b}FUNCTION@{ub}
  This function checks if a Pure Basic string holds a specific
  ToolType and a matching value.

  @{b}String@{ub}
  This is the string to examine.

  @{b}ToolName@{ub}
  This is the ToolType to check for.

  @{b}Value@{ub}
  This is the value to check for, could be a zerostring.

  @{b}Result@{ub}
  If this is -1 the ToolType is not present in Pure Basic string, if
  it's instead 0 the ToolType is found but it's not set to the specified
  value and finally if it's 1 then the ToolType is found and have one
  value that is the same as third parameter.
@EndNode


@Node ReadToolTypeDiskInfo

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.l = ReadToolTypeDiskInfo(@{b}#Obj@{ub}.w,@{b}IconName@{ub}$)

    @{b}FUNCTION@{ub}
  This function reads the icon's .info file that is specified by name
  and initializes the ToolType Object.

  If the Object is already initialized this function doesn't care and
  just creates a new Object without deleting the old one - then
  there is no possibile way to preform any actions on the old Object.

  Maximum number of ToolTypes that could be handled is 32767,
  restricted by this Pure Basic Lib.

  @{b}#Obj@{ub}
  Object to use.

  @{b}IconName@{ub}
  The icon's name: ".info" is automatically added to the end of name.

  @{b}Result@{ub}
  If this is set to FALSE the icon's .info file couldn't be read.
@EndNode


@Node WriteToolTypeDiskInfo

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.w = WriteToolTypeDiskInfo(@{b}#Obj@{ub}.w,@{b}Array()@{ub},@{b}IconName@{ub}$)

    @{b}FUNCTION@{ub}
  This function writes the icon's .info file back to disk.

  @{b}#Obj@{ub}
  Object to use.

  @{b}Array()@{ub}
  This array hold the strings that contain the new ToolTypes
  to be written.

  The new ToolTypes have priority over old ToolTypes, so if only
  one ToolType is added then all ToolTypes must first be read
  into Pure Basic strings with the function GetNextToolTypeString().

  Maximum number of ToolTypes that could be handled is 32767,
  restricted by this Pure Basic Lib.

  @{b}IconName@{ub}
  The icon's name: ".info" is automatically added to the end of name.

  @{b}Result@{ub}
  If this is TRUE then the writing was succesful.
@EndNode