@database "icon"

@Node Main "icon.doc"
@toc "Includes_&_Autodocs/Main"
    @{" AddFreeList() " Link "AddFreeList()"}
    @{" BumpRevision() " Link "BumpRevision()"}
    @{" DeleteDiskObject() " Link "DeleteDiskObject()"}
    @{" FindToolType() " Link "FindToolType()"}
    @{" FreeDiskObject() " Link "FreeDiskObject()"}
    @{" FreeFreeList() " Link "FreeFreeList()"}
    @{" GetDefDiskObject() " Link "GetDefDiskObject()"}
    @{" GetDiskObject() " Link "GetDiskObject()"}
    @{" GetDiskObjectNew() " Link "GetDiskObjectNew()"}
    @{" MatchToolValue() " Link "MatchToolValue()"}
    @{" PutDefDiskObject() " Link "PutDefDiskObject()"}
    @{" PutDiskObject() " Link "PutDiskObject()"}
@EndNode

@Node "AddFreeList()" "icon.library/AddFreeList"

@{b}   NAME@{ub}
       AddFreeList - add memory to a free list.

@{b}   SYNOPSIS@{ub}
       status = AddFreeList(free, mem, len)
         D0                  A0    A1   A2

	@{"BOOL" Link "includes/exec/types.h/Main" 68} AddFreeList(struct @{"FreeList" Link "includes/workbench/workbench.h/Main" 80} *, @{"APTR" Link "includes/exec/types.h/Main" 33}, ULONG);

@{b}   FUNCTION@{ub}
	This routine adds the specified memory to the free list.
	The free list will be extended (if required).  If there
	is not enough memory to complete the call, a null is returned.

	Note that AddFreeList does NOT allocate the requested memory.
	It only records the memory in the free list.

@{b}   INPUTS@{ub}
	free -- a pointer to a @{"FreeList" Link "includes/workbench/workbench.h/Main" 80} structure
	mem -- the base of the memory to be recorded
	len -- the length of the memory to be recorded

@{b}   RESULTS@{ub}
	status -- TRUE if the call succeeded else FALSE;

@{b}   SEE ALSO@{ub}
	@{"AllocEntry()" Link "exec/AllocEntry()"}, @{"FreeEntry()" Link "exec/FreeEntry()"}, @{"FreeFreeList()" Link "FreeFreeList()"}

@{b}   BUGS@{ub}
	None

@EndNode

@Node "BumpRevision()" "icon.library/BumpRevision"

@{b}   NAME@{ub}
       BumpRevision - reformat a name for a second copy.

@{b}   SYNOPSIS@{ub}
       result = BumpRevision(newbuf, oldname)
         D0                    A0      A1

	char *BumpRevision(char *, char *);

@{b}   FUNCTION@{ub}
	BumpRevision takes a name and turns it into a "copy_of_name".
	It knows how to deal with copies of copies.  The routine
	will truncate the new name to the maximum dos name size
	(currently 30 characters).

@{b}   INPUTS@{ub}
	newbuf - the new buffer that will receive the name
		 (it must be at least 31 characters long).
	oldname - the original name

@{b}   RESULTS@{ub}
	result - a pointer to newbuf

@{b}   EXAMPLE@{ub}
	oldname				 newbuf
	-------				 ------
	"foo"				 "copy_of_foo"
	"copy_of_foo"			 "copy_2_of_foo"
	"copy_2_of_foo"			 "copy_3_of_foo"
	"copy_199_of_foo"		 "copy_200_of_foo"
	"copy foo"			 "copy_of_copy foo"
	"copy_0_of_foo"			 "copy_1_of_foo"
	"012345678901234567890123456789" "copy_of_0123456789012345678901"

@{b}   SEE ALSO@{ub}

@{b}   BUGS@{ub}
	None

@EndNode

@Node "DeleteDiskObject()" "icon.library/DeleteDiskObject"

@{b}   NAME@{ub}
       DeleteDiskObject - Delete a Workbench disk object from disk.     (V37)

@{b}   SYNOPSIS@{ub}
       result = DeleteDiskObject(name)
         D0                      A0

	@{"BOOL" Link "includes/exec/types.h/Main" 68} DeleteDiskObject(char *);

@{b}   FUNCTION@{ub}
	This routine will try to delete a Workbench disk object from disk.
	The name parameter will have a ".info" postpended to it, and the
	info file of that name will be deleted.  If the call fails,
	it will return zero.  The reason for the failure may be obtained
	via @{"IoErr()" Link "dos/IoErr()"}.

	This call also updates the Workbench screen if needed.

	Using this routine protects you from any future changes to
	the way icons are stored within the system.

@{b}   INPUTS@{ub}
	name -- name of the object (char *)

@{b}   RESULTS@{ub}
	result -- TRUE if it worked, false if not.

@{b}   EXAMPLE@{ub}

	error=NULL;

	/*Check if you have the right library version*/

	if (((struct @{"Library" Link "includes/exec/libraries.h/Main" 33} *)IconBase)->lib_Version > 36)
	{
		if (!DeleteDiskObject(name)) error=IoErr();
	}
	else
	{
		/* Delete name plus ".info" */
	}

	if (error)
	{
		/* Do error routine...*/
	}

@{b}   SEE ALSO@{ub}
	@{"PutDiskObject()" Link "PutDiskObject()"}, @{"GetDiskObject()" Link "GetDiskObject()"}, @{"FreeDiskObject()" Link "FreeDiskObject()"}

@{b}   BUGS@{ub}
	None

@EndNode

@Node "FindToolType()" "icon.library/FindToolType"

@{b}   NAME@{ub}
       FindToolType - find the value of a ToolType variable.

@{b}   SYNOPSIS@{ub}
       value = FindToolType(toolTypeArray, typeName)
         D0                      A0           A1

	char *FindToolType(char **, char *);

@{b}   FUNCTION@{ub}
	This function searches a tool type array for a given entry,
	and returns a pointer to that entry.  This is useful for
	finding standard tool type variables.  The returned
	value is not a new copy of the string but is only
	a pointer to the part of the string after typeName.

@{b}   INPUTS@{ub}
	toolTypeArray - an array of strings (char **).
	typeName - the name of the tooltype entry (char *).

@{b}   RESULTS@{ub}
	value - a pointer to a string that is the value bound to typeName,
		or NULL if typeName is not in the toolTypeArray.

@{b}   EXAMPLE@{ub}
	Assume the tool type array has two strings in it:
	    "FILETYPE=text"
	    "TEMPDIR=:t"

	FindToolType( toolTypeArray, "FILETYPE" ) returns "text"
	FindToolType( toolTypeArray, "filetype" ) returns "text"
	FindToolType( toolTypeArray, "TEMPDIR" )  returns ":t"
	FindToolType( toolTypeArray, "MAXSIZE" )  returns NULL

@{b}   SEE ALSO@{ub}
	@{"MatchToolValue()" Link "MatchToolValue()"}

@{b}   BUGS@{ub}
	None

@EndNode

@Node "FreeDiskObject()" "icon.library/FreeDiskObject"

@{b}   NAME@{ub}
       FreeDiskObject - free all memory in a Workbench disk object.

@{b}   SYNOPSIS@{ub}
       FreeDiskObject(diskobj)
                        A0

	void FreeDiskObject(struct @{"DiskObject" Link "includes/workbench/workbench.h/Main" 59} *);

@{b}   FUNCTION@{ub}
	This routine frees all memory in a Workbench disk object, and the
	object itself.  It is implemented via @{"FreeFreeList()" Link "FreeFreeList()"}.

	@{"GetDiskObject()" Link "GetDiskObject()"} takes care of all the initialization required
	to set up the object's free list.  This procedure may ONLY
	be called on a @{"DiskObject" Link "includes/workbench/workbench.h/Main" 59} allocated via @{"GetDiskObject()" Link "GetDiskObject()"}.

@{b}   INPUTS@{ub}
	diskobj -- a pointer to a @{"DiskObject" Link "includes/workbench/workbench.h/Main" 59} structure

@{b}   RESULTS@{ub}
	None

@{b}   SEE ALSO@{ub}
	@{"GetDiskObject()" Link "GetDiskObject()"}, @{"PutDiskObject()" Link "PutDiskObject()"}, @{"DeleteDiskObject()" Link "DeleteDiskObject()"}, @{"FreeFreeList()" Link "FreeFreeList()"}

@{b}   BUGS@{ub}
	None

@EndNode

@Node "FreeFreeList()" "icon.library/FreeFreeList"

@{b}   NAME@{ub}
       FreeFreeList - free all memory in a free list.

@{b}   SYNOPSIS@{ub}
       FreeFreeList(free)
                     A0

	void FreeFreeList(struct @{"FreeList" Link "includes/workbench/workbench.h/Main" 80} *);

@{b}   FUNCTION@{ub}
	This routine frees all memory in a free list, and the
	free list itself.  It is useful for easily getting
	rid of all memory in a series of structures.  There is
	a free list in a Workbench object, and this contains
	all the memory associated with that object.

	A @{"FreeList" Link "includes/workbench/workbench.h/Main" 80} is a list of @{"MemList" Link "includes/exec/memory.h/Main" 55} structures.  See the
	@{"MemList" Link "includes/exec/memory.h/Main" 55} and @{"MemEntry" Link "includes/exec/memory.h/Main" 39} documentation for more information.

	If the @{"FreeList" Link "includes/workbench/workbench.h/Main" 80} itself is in the free list, it must be
	in the first @{"MemList" Link "includes/exec/memory.h/Main" 55} in the @{"FreeList" Link "includes/workbench/workbench.h/Main" 80}.

@{b}   INPUTS@{ub}
	free -- a pointer to a @{"FreeList" Link "includes/workbench/workbench.h/Main" 80} structure

@{b}   RESULTS@{ub}
	None

@{b}   SEE ALSO@{ub}
	@{"AllocEntry()" Link "exec/AllocEntry()"}, @{"FreeEntry()" Link "exec/FreeEntry()"}, @{"AddFreeList()" Link "AddFreeList()"}

@{b}   BUGS@{ub}
	None

@EndNode

@Node "GetDefDiskObject()" "icon.library/GetDefDiskObject"

@{b}   NAME@{ub}
	GetDefDiskObject - read default wb disk object from disk.       (V36)

@{b}   SYNOPSIS@{ub}
	diskobj = GetDefDiskObject(def_type)
         D0                          D0

	struct @{"DiskObject" Link "includes/workbench/workbench.h/Main" 59} *GetDefDiskObject(LONG);

@{b}   FUNCTION@{ub}
	This routine reads in a default Workbench disk object from disk.
	The valid def_types can be found in @{"workbench/workbench.h" Link "includes/workbench/workbench.h/Main" 0} and
	currently include WBDISK thru WBGARBAGE.  If the call fails,
	it will return zero.  The reason for the failure may be obtained
	via @{"IoErr()" Link "dos/IoErr()"}.

	Using this routine protects you from any future changes to
	the way default icons are stored within the system.

@{b}   INPUTS@{ub}
	def_type - default icon type (WBDISK thru WBKICK).  Note that the
		   define 'WBDEVICE' is not currently supported.

@{b}   RESULTS@{ub}
	diskobj -- the default Workbench disk object in question

@{b}   SEE ALSO@{ub}
	@{"PutDefDiskObject()" Link "PutDefDiskObject()"}

@{b}   BUGS@{ub}
	None

@EndNode

@Node "GetDiskObject()" "icon.library/GetDiskObject"

@{b}   NAME@{ub}
       GetDiskObject - read in a Workbench disk object from disk.

@{b}   SYNOPSIS@{ub}
       diskobj = GetDiskObject(name)
         D0                      A0

	struct @{"DiskObject" Link "includes/workbench/workbench.h/Main" 59} *GetDiskObject(char *);

@{b}   FUNCTION@{ub}
	This routine reads in a Workbench disk object in from disk.  The
	name parameter will have a ".info" postpended to it, and the
	info file of that name will be read.  If the call fails,
	it will return zero.  The reason for the failure may be obtained
	via @{"IoErr()" Link "dos/IoErr()"}.

	Using this routine protects you from any future changes to
	the way icons are stored within the system.

	A @{"FreeList" Link "includes/workbench/workbench.h/Main" 80} structure is allocated just after the @{"DiskObject" Link "includes/workbench/workbench.h/Main" 59}
	structure; @{"FreeDiskObject" Link "icon/FreeDiskObject()"} makes use of this to get rid of the
	memory that was allocated.

@{b}   INPUTS@{ub}
	name -- name of the object (char *) or NULL if you just want a
		@{"DiskObject" Link "includes/workbench/workbench.h/Main" 59} structure allocated for you (useful when
		calling AddAppIcon in workbench.library).

@{b}   RESULTS@{ub}
	diskobj -- the Workbench disk object in question

@{b}   SEE ALSO@{ub}
	@{"GetDiskObjectNew()" Link "GetDiskObjectNew()"}, @{"PutDiskObject()" Link "PutDiskObject()"}, @{"DeleteDiskObject()" Link "DeleteDiskObject()"},
	@{"FreeDiskObject()" Link "FreeDiskObject()"}

@{b}   BUGS@{ub}
	None

@EndNode

@Node "GetDiskObjectNew()" "icon.library/GetDiskObjectNew"

@{b}   NAME@{ub}
       GetDiskObjectNew - read in a Workbench disk object from disk.    (V36)

@{b}   SYNOPSIS@{ub}
       diskobj = GetDiskObjectNew(name)
         D0                      A0

	struct @{"DiskObject" Link "includes/workbench/workbench.h/Main" 59} *GetDiskObjectNew(char *);

@{b}   FUNCTION@{ub}
	This routine reads in a Workbench disk object in from disk.  The
	name parameter will have a ".info" postpended to it, and the
	info file of that name will be read.  If the call fails,
	it will return zero.  The reason for the failure may be obtained
	via @{"IoErr()" Link "dos/IoErr()"}.

	Using this routine protects you from any future changes to
	the way icons are stored within the system.

	A @{"FreeList" Link "includes/workbench/workbench.h/Main" 80} structure is allocated just after the @{"DiskObject" Link "includes/workbench/workbench.h/Main" 59}
	structure; @{"FreeDiskObject" Link "icon/FreeDiskObject()"} makes use of this to get rid of the
	memory that was allocated.

	This call is functionally identical to @{"GetDiskObject" Link "icon/GetDiskObject()"} with one exception.
	If its call to @{"GetDiskObject" Link "icon/GetDiskObject()"} fails, this function calls @{"GetDefDiskObject" Link "icon/GetDefDiskObject()"}.
	This is useful when there is no .info file for the icon you are trying
	to get a disk object for.  Applications that use workbench application
	windows MUST use this call if they want to handle the user dropping an
	icon (that doesn't have a .info file) on their window.  The V2.0
	icon editor program is an example of a workbench application window
	that uses this call.

@{b}   INPUTS@{ub}
	name -- name of the object (char *) or NULL if you just want a
		@{"DiskObject" Link "includes/workbench/workbench.h/Main" 59} structure allocated for you (useful when
		calling AddAppIcon in workbench.library).

@{b}   RESULTS@{ub}
	diskobj -- the Workbench disk object in question

@{b}   SEE ALSO@{ub}
	@{"FreeDiskObject()" Link "FreeDiskObject()"}, @{"GetDiskObject()" Link "GetDiskObject()"}, @{"PutDiskObject()" Link "PutDiskObject()"}, @{"DeleteDiskObject()" Link "DeleteDiskObject()"}

@{b}   BUGS@{ub}
	None

@EndNode

@Node "MatchToolValue()" "icon.library/MatchToolValue"

@{b}   NAME@{ub}
       MatchToolValue - check a tool type variable for a particular value.

@{b}   SYNOPSIS@{ub}
       result = MatchToolValue(typeString, value)
         D0                        A0        A1

	@{"BOOL" Link "includes/exec/types.h/Main" 68} MatchToolValue(char *, char *);

@{b}   FUNCTION@{ub}
	MatchToolValue is useful for parsing a tool type value for
	a known value.  It knows how to parse the syntax for a tool
	type value (in particular, it knows that '|' separates
	alternate values).  Note that the parsing is case insensitive.

@{b}   INPUTS@{ub}
	typeString - a ToolType value (as returned by FindToolType)
	value - you are interested if value appears in typeString

@{b}   RESULTS@{ub}
	result - TRUE if the value was in typeString else FALSE.

@{b}   EXAMPLE@{ub}
	Assume there are two type strings:
	    type1 = "text"
	    type2 = "a|b|c"

	MatchToolValue( type1, "text" ) returns TRUE
	MatchToolValue( type1, "TEXT" ) returns TRUE
	MatchToolValue( type1, "data" ) returns FALSE
	MatchToolValue( type2, "a" ) returns TRUE
	MatchToolValue( type2, "b" ) returns TRUE
	MatchToolValue( type2, "d" ) returns FALSE
	MatchToolValue( type2, "a|b" ) returns FALSE

@{b}   SEE ALSO@{ub}
	@{"FindToolType()" Link "FindToolType()"}

@{b}   BUGS@{ub}
	None

@EndNode

@Node "PutDefDiskObject()" "icon.library/PutDefDiskObject"

@{b}   NAME@{ub}
	PutDefDiskObject - write disk object as the default for its type.  (V36)

@{b}   SYNOPSIS@{ub}
       status = PutDefDiskObject(diskobj)
         D0                        A0

	@{"BOOL" Link "includes/exec/types.h/Main" 68} PutDefDiskObject(struct @{"DiskObject" Link "includes/workbench/workbench.h/Main" 59} *);

@{b}   FUNCTION@{ub}
	This routine writes out a @{"DiskObject" Link "includes/workbench/workbench.h/Main" 59} structure, and its
	associated information.  If the call fails, a zero will
	be returned.  The reason for the failure may be obtained
	via @{"IoErr()" Link "dos/IoErr()"}.

	Note that this function calls @{"PutDiskObject" Link "icon/PutDiskObject()"} internally which means
	that this call (if sucessful) notifies workbench than an icon has
	been created/modified.

	Using this routine protects you from any future changes to
	the way default icons are stored within the system.

@{b}   INPUTS@{ub}
	diskobj -- a pointer to a @{"DiskObject" Link "includes/workbench/workbench.h/Main" 59}

@{b}   RESULTS@{ub}
	status -- TRUE if the call succeeded else FALSE

@{b}   SEE ALSO@{ub}
	@{"GetDefDiskObject()" Link "GetDefDiskObject()"}

@{b}   BUGS@{ub}
	None

@EndNode

@Node "PutDiskObject()" "icon.library/PutDiskObject"

@{b}   NAME@{ub}
       PutDiskObject - write out a @{"DiskObject" Link "includes/workbench/workbench.h/Main" 59} to disk.

@{b}   SYNOPSIS@{ub}
       status = PutDiskObject(name, diskobj)
         D0                    A0      A1

	@{"BOOL" Link "includes/exec/types.h/Main" 68} PutDiskObject(char *, struct @{"DiskObject" Link "includes/workbench/workbench.h/Main" 59} *);

@{b}   FUNCTION@{ub}
	This routine writes out a @{"DiskObject" Link "includes/workbench/workbench.h/Main" 59} structure, and its
	associated information.  The file name of the info
	file will be the name parameter with a
	".info" postpended to it.  If the call fails, a zero will
	be returned.  The reason for the failure may be obtained
	via @{"IoErr()" Link "dos/IoErr()"}.

	As of release V2.0, PutDiskObject (if successful) notifies workbench
	han an icon has been created/modified.

	Using this routine protects you from any future changes to
	the way icons are stored within the system.

@{b}   INPUTS@{ub}
	name -- name of the object (pointer to a character string)
	diskobj -- a pointer to a @{"DiskObject" Link "includes/workbench/workbench.h/Main" 59}

@{b}   RESULTS@{ub}
	status -- TRUE if the call succeeded else FALSE

@{b}   NOTES@{ub}
	It is recommended that if you wish to copy an icon from one place
	to another than you use @{"GetDiskObject()" Link "GetDiskObject()"} and PutDiskObject()
	and do not copy them directly.

@{b}   SEE ALSO@{ub}
	@{"GetDiskObject()" Link "GetDiskObject()"}, @{"FreeDiskObject()" Link "FreeDiskObject()"}, @{"DeleteDiskObject()" Link "DeleteDiskObject()"}

@{b}   BUGS@{ub}
	None

@EndNode

