home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / TRSICAT.LZX / CATS_CD2_TRSI / Inc&AD2.1 / Text_Autodocs / icon.doc < prev    next >
Encoding:
Text File  |  1992-09-11  |  13.2 KB  |  497 lines
  1. TABLE OF CONTENTS
  2.  
  3. icon.library/AddFreeList
  4. icon.library/BumpRevision
  5. icon.library/DeleteDiskObject
  6. icon.library/FindToolType
  7. icon.library/FreeDiskObject
  8. icon.library/FreeFreeList
  9. icon.library/GetDefDiskObject
  10. icon.library/GetDiskObject
  11. icon.library/GetDiskObjectNew
  12. icon.library/MatchToolValue
  13. icon.library/PutDefDiskObject
  14. icon.library/PutDiskObject
  15. icon.library/AddFreeList                             icon.library/AddFreeList
  16.  
  17.    NAME
  18.        AddFreeList - add memory to a free list.
  19.  
  20.    SYNOPSIS
  21.        status = AddFreeList(free, mem, len)
  22.          D0                  A0    A1   A2
  23.  
  24.     BOOL AddFreeList(struct FreeList *, APTR, ULONG);
  25.  
  26.    FUNCTION
  27.     This routine adds the specified memory to the free list.
  28.     The free list will be extended (if required).  If there
  29.     is not enough memory to complete the call, a null is returned.
  30.  
  31.     Note that AddFreeList does NOT allocate the requested memory.
  32.     It only records the memory in the free list.
  33.  
  34.    INPUTS
  35.     free -- a pointer to a FreeList structure
  36.     mem -- the base of the memory to be recorded
  37.     len -- the length of the memory to be recorded
  38.  
  39.    RESULTS
  40.     status -- TRUE if the call succeeded else FALSE;
  41.  
  42.    SEE ALSO
  43.     AllocEntry(), FreeEntry(), FreeFreeList()
  44.  
  45.    BUGS
  46.     None
  47.  
  48. icon.library/BumpRevision                           icon.library/BumpRevision
  49.  
  50.    NAME
  51.        BumpRevision - reformat a name for a second copy.
  52.  
  53.    SYNOPSIS
  54.        result = BumpRevision(newbuf, oldname)
  55.          D0                    A0      A1
  56.  
  57.     char *BumpRevision(char *, char *);
  58.  
  59.    FUNCTION
  60.     BumpRevision takes a name and turns it into a "copy_of_name".
  61.     It knows how to deal with copies of copies.  The routine
  62.     will truncate the new name to the maximum dos name size
  63.     (currently 30 characters).
  64.  
  65.    INPUTS
  66.     newbuf - the new buffer that will receive the name
  67.          (it must be at least 31 characters long).
  68.     oldname - the original name
  69.  
  70.    RESULTS
  71.     result - a pointer to newbuf
  72.  
  73.    EXAMPLE
  74.     oldname                 newbuf
  75.     -------                 ------
  76.     "foo"                 "copy_of_foo"
  77.     "copy_of_foo"             "copy_2_of_foo"
  78.     "copy_2_of_foo"             "copy_3_of_foo"
  79.     "copy_199_of_foo"         "copy_200_of_foo"
  80.     "copy foo"             "copy_of_copy foo"
  81.     "copy_0_of_foo"             "copy_1_of_foo"
  82.     "012345678901234567890123456789" "copy_of_0123456789012345678901"
  83.  
  84.    SEE ALSO
  85.  
  86.    BUGS
  87.     None
  88.  
  89. icon.library/DeleteDiskObject                   icon.library/DeleteDiskObject
  90.  
  91.    NAME
  92.        DeleteDiskObject - Delete a Workbench disk object from disk.     (V37)
  93.  
  94.    SYNOPSIS
  95.        result = DeleteDiskObject(name)
  96.          D0                      A0
  97.  
  98.     BOOL DeleteDiskObject(char *);
  99.  
  100.    FUNCTION
  101.     This routine will try to delete a Workbench disk object from disk.
  102.     The name parameter will have a ".info" postpended to it, and the
  103.     info file of that name will be deleted.  If the call fails,
  104.     it will return zero.  The reason for the failure may be obtained
  105.     via IoErr().
  106.  
  107.     This call also updates the Workbench screen if needed.
  108.  
  109.     Using this routine protects you from any future changes to
  110.     the way icons are stored within the system.
  111.  
  112.    INPUTS
  113.     name -- name of the object (char *)
  114.  
  115.    RESULTS
  116.     result -- TRUE if it worked, false if not.
  117.  
  118.    EXAMPLE
  119.  
  120.     error=NULL;
  121.  
  122.     *Check if you have the right library version*
  123.  
  124.     if (((struct Library *)IconBase)->lib_Version > 36)
  125.     {
  126.         if (!DeleteDiskObject(name)) error=IoErr();
  127.     }
  128.     else
  129.     {
  130.         * Delete name plus ".info" *
  131.     }
  132.  
  133.     if (error)
  134.     {
  135.         * Do error routine...*
  136.     }
  137.  
  138.    SEE ALSO
  139.     PutDiskObject(), GetDiskObject(), FreeDiskObject()
  140.  
  141.    BUGS
  142.     None
  143.  
  144. icon.library/FindToolType                           icon.library/FindToolType
  145.  
  146.    NAME
  147.        FindToolType - find the value of a ToolType variable.
  148.  
  149.    SYNOPSIS
  150.        value = FindToolType(toolTypeArray, typeName)
  151.          D0                      A0           A1
  152.  
  153.     char *FindToolType(char **, char *);
  154.  
  155.    FUNCTION
  156.     This function searches a tool type array for a given entry,
  157.     and returns a pointer to that entry.  This is useful for
  158.     finding standard tool type variables.  The returned
  159.     value is not a new copy of the string but is only
  160.     a pointer to the part of the string after typeName.
  161.  
  162.    INPUTS
  163.     toolTypeArray - an array of strings (char **).
  164.     typeName - the name of the tooltype entry (char *).
  165.  
  166.    RESULTS
  167.     value - a pointer to a string that is the value bound to typeName,
  168.         or NULL if typeName is not in the toolTypeArray.
  169.  
  170.    EXAMPLE
  171.     Assume the tool type array has two strings in it:
  172.         "FILETYPE=text"
  173.         "TEMPDIR=:t"
  174.  
  175.     FindToolType( toolTypeArray, "FILETYPE" ) returns "text"
  176.     FindToolType( toolTypeArray, "filetype" ) returns "text"
  177.     FindToolType( toolTypeArray, "TEMPDIR" )  returns ":t"
  178.     FindToolType( toolTypeArray, "MAXSIZE" )  returns NULL
  179.  
  180.    SEE ALSO
  181.     MatchToolValue()
  182.  
  183.    BUGS
  184.     None
  185.  
  186. icon.library/FreeDiskObject                       icon.library/FreeDiskObject
  187.  
  188.    NAME
  189.        FreeDiskObject - free all memory in a Workbench disk object.
  190.  
  191.    SYNOPSIS
  192.        FreeDiskObject(diskobj)
  193.                         A0
  194.  
  195.     void FreeDiskObject(struct DiskObject *);
  196.  
  197.    FUNCTION
  198.     This routine frees all memory in a Workbench disk object, and the
  199.     object itself.  It is implemented via FreeFreeList().
  200.  
  201.     GetDiskObject() takes care of all the initialization required
  202.     to set up the object's free list.  This procedure may ONLY
  203.     be called on a DiskObject allocated via GetDiskObject().
  204.  
  205.    INPUTS
  206.     diskobj -- a pointer to a DiskObject structure
  207.  
  208.    RESULTS
  209.     None
  210.  
  211.    SEE ALSO
  212.     GetDiskObject(), PutDiskObject(), DeleteDiskObject(), FreeFreeList()
  213.  
  214.    BUGS
  215.     None
  216.  
  217. icon.library/FreeFreeList                           icon.library/FreeFreeList
  218.  
  219.    NAME
  220.        FreeFreeList - free all memory in a free list.
  221.  
  222.    SYNOPSIS
  223.        FreeFreeList(free)
  224.                      A0
  225.  
  226.     void FreeFreeList(struct FreeList *);
  227.  
  228.    FUNCTION
  229.     This routine frees all memory in a free list, and the
  230.     free list itself.  It is useful for easily getting
  231.     rid of all memory in a series of structures.  There is
  232.     a free list in a Workbench object, and this contains
  233.     all the memory associated with that object.
  234.  
  235.     A FreeList is a list of MemList structures.  See the
  236.     MemList and MemEntry documentation for more information.
  237.  
  238.     If the FreeList itself is in the free list, it must be
  239.     in the first MemList in the FreeList.
  240.  
  241.    INPUTS
  242.     free -- a pointer to a FreeList structure
  243.  
  244.    RESULTS
  245.     None
  246.  
  247.    SEE ALSO
  248.     AllocEntry(), FreeEntry(), AddFreeList()
  249.  
  250.    BUGS
  251.     None
  252.  
  253. icon.library/GetDefDiskObject                   icon.library/GetDefDiskObject
  254.  
  255.    NAME
  256.     GetDefDiskObject - read default wb disk object from disk.       (V36)
  257.  
  258.    SYNOPSIS
  259.     diskobj = GetDefDiskObject(def_type)
  260.          D0                          D0
  261.  
  262.     struct DiskObject *GetDefDiskObject(LONG);
  263.  
  264.    FUNCTION
  265.     This routine reads in a default Workbench disk object from disk.
  266.     The valid def_types can be found in workbench/workbench.h and
  267.     currently include WBDISK thru WBGARBAGE.  If the call fails,
  268.     it will return zero.  The reason for the failure may be obtained
  269.     via IoErr().
  270.  
  271.     Using this routine protects you from any future changes to
  272.     the way default icons are stored within the system.
  273.  
  274.    INPUTS
  275.     def_type - default icon type (WBDISK thru WBKICK).  Note that the
  276.            define 'WBDEVICE' is not currently supported.
  277.  
  278.    RESULTS
  279.     diskobj -- the default Workbench disk object in question
  280.  
  281.    SEE ALSO
  282.     PutDefDiskObject
  283.  
  284.    BUGS
  285.     None
  286.  
  287. icon.library/GetDiskObject                         icon.library/GetDiskObject
  288.  
  289.    NAME
  290.        GetDiskObject - read in a Workbench disk object from disk.
  291.  
  292.    SYNOPSIS
  293.        diskobj = GetDiskObject(name)
  294.          D0                      A0
  295.  
  296.     struct DiskObject *GetDiskObject(char *);
  297.  
  298.    FUNCTION
  299.     This routine reads in a Workbench disk object in from disk.  The
  300.     name parameter will have a ".info" postpended to it, and the
  301.     info file of that name will be read.  If the call fails,
  302.     it will return zero.  The reason for the failure may be obtained
  303.     via IoErr().
  304.  
  305.     Using this routine protects you from any future changes to
  306.     the way icons are stored within the system.
  307.  
  308.     A FreeList structure is allocated just after the DiskObject
  309.     structure; FreeDiskObject makes use of this to get rid of the
  310.     memory that was allocated.
  311.  
  312.    INPUTS
  313.     name -- name of the object (char *) or NULL if you just want a
  314.         DiskObject structure allocated for you (useful when
  315.         calling AddAppIcon in workbench.library).
  316.  
  317.    RESULTS
  318.     diskobj -- the Workbench disk object in question
  319.  
  320.    SEE ALSO
  321.     GetDiskObjectNew(), PutDiskObject(), DeleteDiskObject(),
  322.     FreeDiskObject()
  323.  
  324.    BUGS
  325.     None
  326.  
  327. icon.library/GetDiskObjectNew                   icon.library/GetDiskObjectNew
  328.  
  329.    NAME
  330.        GetDiskObjectNew - read in a Workbench disk object from disk.    (V36)
  331.  
  332.    SYNOPSIS
  333.        diskobj = GetDiskObjectNew(name)
  334.          D0                      A0
  335.  
  336.     struct DiskObject *GetDiskObjectNew(char *);
  337.  
  338.    FUNCTION
  339.     This routine reads in a Workbench disk object in from disk.  The
  340.     name parameter will have a ".info" postpended to it, and the
  341.     info file of that name will be read.  If the call fails,
  342.     it will return zero.  The reason for the failure may be obtained
  343.     via IoErr().
  344.  
  345.     Using this routine protects you from any future changes to
  346.     the way icons are stored within the system.
  347.  
  348.     A FreeList structure is allocated just after the DiskObject
  349.     structure; FreeDiskObject makes use of this to get rid of the
  350.     memory that was allocated.
  351.  
  352.     This call is functionally identical to GetDiskObject with one exception.
  353.     If its call to GetDiskObject fails, this function calls GetDefDiskObject.
  354.     This is useful when there is no .info file for the icon you are trying
  355.     to get a disk object for.  Applications that use workbench application
  356.     windows MUST use this call if they want to handle the user dropping an
  357.     icon (that doesn't have a .info file) on their window.  The V2.0
  358.     icon editor program is an example of a workbench application window
  359.     that uses this call.
  360.  
  361.    INPUTS
  362.     name -- name of the object (char *) or NULL if you just want a
  363.         DiskObject structure allocated for you (useful when
  364.         calling AddAppIcon in workbench.library).
  365.  
  366.    RESULTS
  367.     diskobj -- the Workbench disk object in question
  368.  
  369.    SEE ALSO
  370.     FreeDiskObject(), GetDiskObject(), PutDiskObject(), DeleteDiskObject()
  371.  
  372.    BUGS
  373.     None
  374.  
  375. icon.library/MatchToolValue                       icon.library/MatchToolValue
  376.  
  377.    NAME
  378.        MatchToolValue - check a tool type variable for a particular value.
  379.  
  380.    SYNOPSIS
  381.        result = MatchToolValue(typeString, value)
  382.          D0                        A0        A1
  383.  
  384.     BOOL MatchToolValue(char *, char *);
  385.  
  386.    FUNCTION
  387.     MatchToolValue is useful for parsing a tool type value for
  388.     a known value.  It knows how to parse the syntax for a tool
  389.     type value (in particular, it knows that '|' separates
  390.     alternate values).  Note that the parsing is case insensitve.
  391.  
  392.    INPUTS
  393.     typeString - a ToolType value (as returned by FindToolType)
  394.     value - you are interested if value appears in typeString
  395.  
  396.    RESULTS
  397.     result - TRUE if the value was in typeString else FALSE.
  398.  
  399.    EXAMPLE
  400.     Assume there are two type strings:
  401.         type1 = "text"
  402.         type2 = "a|b|c"
  403.  
  404.     MatchToolValue( type1, "text" ) returns TRUE
  405.     MatchToolValue( type1, "TEXT" ) returns TRUE
  406.     MatchToolValue( type1, "data" ) returns FALSE
  407.     MatchToolValue( type2, "a" ) returns TRUE
  408.     MatchToolValue( type2, "b" ) returns TRUE
  409.     MatchToolValue( type2, "d" ) returns FALSE
  410.     MatchToolValue( type2, "a|b" ) returns FALSE
  411.  
  412.    SEE ALSO
  413.     FindToolType()
  414.  
  415.    BUGS
  416.     None
  417.  
  418. icon.library/PutDefDiskObject                   icon.library/PutDefDiskObject
  419.  
  420.    NAME
  421.     PutDefDiskObject - write disk object as the default for its type.  (V36)
  422.  
  423.    SYNOPSIS
  424.        status = PutDefDiskObject(diskobj)
  425.          D0                        A0
  426.  
  427.     BOOL PutDefDiskObject(struct DiskObject *);
  428.  
  429.    FUNCTION
  430.     This routine writes out a DiskObject structure, and its
  431.     associated information.  If the call fails, a zero will
  432.     be returned.  The reason for the failure may be obtained
  433.     via IoErr().
  434.  
  435.     Note that this function calls PutDiskObject internally which means
  436.     that this call (if sucessful) notifies workbench than an icon has
  437.     been created/modified.
  438.  
  439.     Using this routine protects you from any future changes to
  440.     the way default icons are stored within the system.
  441.  
  442.    INPUTS
  443.     diskobj -- a pointer to a DiskObject
  444.  
  445.    RESULTS
  446.     status -- TRUE if the call succeeded else FALSE
  447.  
  448.    SEE ALSO
  449.     GetDefDiskObject
  450.  
  451.    BUGS
  452.     None
  453.  
  454. icon.library/PutDiskObject                         icon.library/PutDiskObject
  455.  
  456.    NAME
  457.        PutDiskObject - write out a DiskObject to disk.
  458.  
  459.    SYNOPSIS
  460.        status = PutDiskObject(name, diskobj)
  461.          D0                    A0      A1
  462.  
  463.     BOOL PutDiskObject(char *, struct DiskObject *);
  464.  
  465.    FUNCTION
  466.     This routine writes out a DiskObject structure, and its
  467.     associated information.  The file name of the info
  468.     file will be the name parameter with a
  469.     ".info" postpended to it.  If the call fails, a zero will
  470.     be returned.  The reason for the failure may be obtained
  471.     via IoErr().
  472.  
  473.     As of release V2.0, PutDiskObject (if sucessful) notifies workbench
  474.     han an icon has been created/modified.
  475.  
  476.     Using this routine protects you from any future changes to
  477.     the way icons are stored within the system.
  478.  
  479.    INPUTS
  480.     name -- name of the object (pointer to a character string)
  481.     diskobj -- a pointer to a DiskObject
  482.  
  483.    RESULTS
  484.     status -- TRUE if the call succeeded else FALSE
  485.  
  486.    NOTES
  487.     It is recommended that if you wish to copy an icon from one place
  488.     to another than you use GetDiskObject() and PutDiskObject()
  489.     and do not copy them directly.
  490.  
  491.    SEE ALSO
  492.     GetDiskObject(), FreeDiskObject(), DeleteDiskObject()
  493.  
  494.    BUGS
  495.     None
  496.  
  497.