@database "icon"
@master "ADCD_v1.2:Inc&AD2.1/Includes/doc/icon.doc"

@Node Main "icon.doc"
@TOC 2.1Includes_Autodocs/Autodocs

@{" AddFreeList() " Link "AddFreeList()"}         @{" FreeDiskObject() " Link "FreeDiskObject()"}      @{" GetDiskObjectNew() " Link "GetDiskObjectNew()"}
@{" BumpRevision() " Link "BumpRevision()"}        @{" FreeFreeList() " Link "FreeFreeList()"}        @{" MatchToolValue() " Link "MatchToolValue()"}
@{" DeleteDiskObject() " Link "DeleteDiskObject()"}    @{" GetDefDiskObject() " Link "GetDefDiskObject()"}    @{" PutDefDiskObject() " Link "PutDefDiskObject()"}
@{" FindToolType() " Link "FindToolType()"}        @{" GetDiskObject() " Link "GetDiskObject()"}       @{" PutDiskObject() " Link "PutDiskObject()"}

@EndNode

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

NAME
    AddFreeList - add memory to a free list.

SYNOPSIS
    status = AddFreeList(free, mem, len)
     D0                  A0    A1   A2

    BOOL AddFreeList(struct @{"FreeList" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 80} *, APTR, ULONG);

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

INPUTS
    free -- a pointer to a @{"FreeList" Link "ADCD_v1.2:Inc&AD2.1/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

RESULTS
    status -- TRUE if the call succeeded else FALSE;

SEE ALSO
    @{"AllocEntry()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/exec/AllocEntry()"}, @{"FreeEntry()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/exec/FreeEntry()"}, @{"FreeFreeList()" Link "FreeFreeList()"}

BUGS
    None

@EndNode

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

NAME
    BumpRevision - reformat a name for a second copy.

SYNOPSIS
    result = BumpRevision(newbuf, oldname)
     D0                    A0      A1

    char *BumpRevision(char *, char *);

FUNCTION
    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).

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

RESULTS
    result - a pointer to newbuf

EXAMPLE
    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"

SEE ALSO

BUGS
    None

@EndNode

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

NAME
    DeleteDiskObject - Delete a Workbench disk object from disk.     (V37)

SYNOPSIS
    result = DeleteDiskObject(name)
     D0                      A0

    BOOL DeleteDiskObject(char *);

FUNCTION
    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 "ADCD_v1.2:Inc&AD2.1/Autodocs/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.

INPUTS
    name -- name of the object (char *)

RESULTS
    result -- TRUE if it worked, false if not.

EXAMPLE
    error=NULL;

    *Check if you have the right library version*

    if (((struct @{"Library" Link "ADCD_v1.2:Inc&AD2.1/Includes/exec/libraries.h/Main" 32} *)IconBase)->lib_Version > 36)
    {
            if (!DeleteDiskObject(name)) error=IoErr();
    }
    else
    {
            * Delete name plus ".info" *
    }

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

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

BUGS
    None

@EndNode

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

NAME
    FindToolType - find the value of a ToolType variable.

SYNOPSIS
    value = FindToolType(toolTypeArray, typeName)
     D0                      A0           A1

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

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

INPUTS
    toolTypeArray - an array of strings (char **).
    typeName - the name of the tooltype entry (char *).

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

EXAMPLE
    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

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

BUGS
    None

@EndNode

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

NAME
    FreeDiskObject - free all memory in a Workbench disk object.

SYNOPSIS
    FreeDiskObject(diskobj)
                    A0

    void FreeDiskObject(struct @{"DiskObject" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 59} *);

FUNCTION
    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 "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 59} allocated via @{"GetDiskObject()" Link "GetDiskObject()"}.

INPUTS
    diskobj -- a pointer to a @{"DiskObject" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 59} structure

RESULTS
    None

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

BUGS
    None

@EndNode

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

NAME
    FreeFreeList - free all memory in a free list.

SYNOPSIS
    FreeFreeList(free)
                 A0

    void FreeFreeList(struct @{"FreeList" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 80} *);

FUNCTION
    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 "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 80} is a list of @{"MemList" Link "ADCD_v1.2:Inc&AD2.1/Includes/exec/memory.h/Main" 55} structures.  See the
    @{"MemList" Link "ADCD_v1.2:Inc&AD2.1/Includes/exec/memory.h/Main" 55} and @{"MemEntry" Link "ADCD_v1.2:Inc&AD2.1/Includes/exec/memory.h/Main" 39} documentation for more information.

    If the @{"FreeList" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 80} itself is in the free list, it must be
    in the first @{"MemList" Link "ADCD_v1.2:Inc&AD2.1/Includes/exec/memory.h/Main" 55} in the @{"FreeList" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 80}.

INPUTS
    free -- a pointer to a @{"FreeList" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 80} structure

RESULTS
    None

SEE ALSO
    @{"AllocEntry()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/exec/AllocEntry()"}, @{"FreeEntry()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/exec/FreeEntry()"}, @{"AddFreeList()" Link "AddFreeList()"}

BUGS
    None

@EndNode

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

NAME
    GetDefDiskObject - read default wb disk object from disk.       (V36)

SYNOPSIS
    diskobj = GetDefDiskObject(def_type)
     D0                          D0

    struct @{"DiskObject" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 59} *GetDefDiskObject(LONG);

FUNCTION
    This routine reads in a default Workbench disk object from disk.
    The valid def_types can be found in @{"workbench/workbench.h" Link "ADCD_v1.2:Inc&AD2.1/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 "ADCD_v1.2:Inc&AD2.1/Autodocs/dos/IoErr()"}.

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

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

RESULTS
    diskobj -- the default Workbench disk object in question

SEE ALSO
    @{"PutDefDiskObject" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/icon/PutDefDiskObject()"}

BUGS
    None

@EndNode

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

NAME
    GetDiskObject - read in a Workbench disk object from disk.

SYNOPSIS
    diskobj = GetDiskObject(name)
     D0                      A0

    struct @{"DiskObject" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 59} *GetDiskObject(char *);

FUNCTION
    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 "ADCD_v1.2:Inc&AD2.1/Autodocs/dos/IoErr()"}.

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

    A @{"FreeList" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 80} structure is allocated just after the @{"DiskObject" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 59}
    structure; @{"FreeDiskObject" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/icon/FreeDiskObject()"} makes use of this to get rid of the
    memory that was allocated.

INPUTS
    name -- name of the object (char *) or NULL if you just want a
            @{"DiskObject" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 59} structure allocated for you (useful when
            calling AddAppIcon in workbench.library).

RESULTS
    diskobj -- the Workbench disk object in question

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

BUGS
    None

@EndNode

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

NAME
    GetDiskObjectNew - read in a Workbench disk object from disk.    (V36)

SYNOPSIS
    diskobj = GetDiskObjectNew(name)
     D0                      A0

    struct @{"DiskObject" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 59} *GetDiskObjectNew(char *);

FUNCTION
    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 "ADCD_v1.2:Inc&AD2.1/Autodocs/dos/IoErr()"}.

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

    A @{"FreeList" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 80} structure is allocated just after the @{"DiskObject" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 59}
    structure; @{"FreeDiskObject" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/icon/FreeDiskObject()"} makes use of this to get rid of the
    memory that was allocated.

    This call is functionally identical to @{"GetDiskObject" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/icon/GetDiskObject()"} with one
    exception.  If its call to @{"GetDiskObject" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/icon/GetDiskObject()"} fails, this function calls
    @{"GetDefDiskObject" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/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.

INPUTS
    name -- name of the object (char *) or NULL if you just want a
            @{"DiskObject" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 59} structure allocated for you (useful when
            calling AddAppIcon in workbench.library).

RESULTS
    diskobj -- the Workbench disk object in question

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

BUGS
    None

@EndNode

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

NAME
    MatchToolValue - check a tool type variable for a particular value.

SYNOPSIS
    result = MatchToolValue(typeString, value)
     D0                        A0        A1

    BOOL MatchToolValue(char *, char *);

FUNCTION
    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 insensitve.

INPUTS
    typeString - a ToolType value (as returned by FindToolType)
    value - you are interested if value appears in typeString

RESULTS
    result - TRUE if the value was in typeString else FALSE.

EXAMPLE
    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

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

BUGS
    None

@EndNode

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

NAME
    PutDefDiskObject - write disk object as the default for its type. (V36)

SYNOPSIS
    status = PutDefDiskObject(diskobj)
     D0                        A0

    BOOL PutDefDiskObject(struct @{"DiskObject" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 59} *);

FUNCTION
    This routine writes out a @{"DiskObject" Link "ADCD_v1.2:Inc&AD2.1/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 "ADCD_v1.2:Inc&AD2.1/Autodocs/dos/IoErr()"}.

    Note that this function calls @{"PutDiskObject" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/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.

INPUTS
    diskobj -- a pointer to a @{"DiskObject" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 59}

RESULTS
    status -- TRUE if the call succeeded else FALSE

SEE ALSO
    @{"GetDefDiskObject" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/icon/GetDefDiskObject()"}

BUGS
    None

@EndNode

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

NAME
    PutDiskObject - write out a @{"DiskObject" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 59} to disk.

SYNOPSIS
    status = PutDiskObject(name, diskobj)
     D0                    A0      A1

    BOOL PutDiskObject(char *, struct @{"DiskObject" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 59} *);

FUNCTION
    This routine writes out a @{"DiskObject" Link "ADCD_v1.2:Inc&AD2.1/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 "ADCD_v1.2:Inc&AD2.1/Autodocs/dos/IoErr()"}.

    As of release V2.0, PutDiskObject (if sucessful) 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.

INPUTS
    name -- name of the object (pointer to a character string)
    diskobj -- a pointer to a @{"DiskObject" Link "ADCD_v1.2:Inc&AD2.1/Includes/workbench/workbench.h/Main" 59}

RESULTS
    status -- TRUE if the call succeeded else FALSE

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

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

BUGS
    None

@EndNode

