home *** CD-ROM | disk | FTP | other *** search
/ DOpus Plus / DOpus Plus.iso / SDK / docs / icon.doc < prev    next >
Encoding:
Text File  |  1998-10-26  |  7.8 KB  |  265 lines
  1. dopus5.library/FreeCachedDiskObject       dopus5.library/FreeCachedDiskObject
  2.  
  3.     NAME
  4.         FreeCachedDiskObject - free a cached icon
  5.  
  6.     SYNOPSIS
  7.         FreeCachedDiskObject(icon)
  8.                               A0
  9.  
  10.         void FreeCachedDiskObject(struct DiskObject *);
  11.  
  12.     FUNCTION
  13.         This function frees a cached icon obtained via a call to
  14.         GetCachedDiskObject() or a similar function.
  15.  
  16.     INPUTS
  17.         icon - icon to free
  18.  
  19.     RESULT
  20.         The usage count of the cached icon is decremented. When the usage
  21.         count reaches zero, the icon is flushed from the cache.
  22.  
  23.     NOTES
  24.         You can pass a normal, uncached icon to this routine, in which case
  25.         it just passes the call through to FreeDiskObject().
  26.  
  27.     SEE ALSO
  28.         GetCachedDiskObject(), icon.library/FreeDiskObject()
  29.  
  30. dopus5.library/GetCachedDefDiskObject   dopus5.library/GetCachedDefDiskObject
  31.  
  32.     NAME
  33.         GetCachedDefDiskObject - GetDefDiskObject() with image caching
  34.  
  35.     SYNOPSIS
  36.         GetCachedDefDiskObject(type)
  37.                                 D0
  38.  
  39.         struct DiskObject *GetCachedDefDiskObject(long);
  40.  
  41.     FUNCTION
  42.         This routine returns one of a number of default icons. The main
  43.         advantage this has over the icon.library GetDefDiskObject() call is
  44.         that the image data of the icons is cached. This can save a huge
  45.         amount of chip memory if multiple copies of the same icon are
  46.         required (compare the chip memory used when you open a large drawer
  47.         in Workbench with the same drawer in Opus).
  48.  
  49.     INPUTS
  50.         type - type of icon to create
  51.  
  52.     RESULT
  53.         Returns a pointer to the icon or NULL for failure.
  54.  
  55.     SEE ALSO
  56.         FreeCachedDiskObject(), icon.library/GetDefDiskObject()
  57.  
  58. dopus5.library/GetCachedDiskObject         dopus5.library/GetCachedDiskObject
  59.  
  60.     NAME
  61.         GetCachedDiskObject - get an icon from disk with image caching
  62.  
  63.     SYNOPSIS
  64.         GetCachedDiskObject(name,flags)
  65.                              A0    D0
  66.  
  67.         struct DiskObject *GetCachedDiskObject(char *,long);
  68.  
  69.     FUNCTION
  70.         This routine loads an icon from disk, and caches the image data. If
  71.         the same icon is loaded again, the cached image data is used instead
  72.         of loading a new copy. This can save valuable chip memory, especially as
  73.         the cache is system wide.
  74.  
  75.     INPUTS
  76.         name - name of icon to load (without the .info suffix)
  77.         flags - set to 0 for now
  78.  
  79.     RESULT
  80.         Returns a pointer to the icon if successful, otherwise NULL.
  81.  
  82.     NOTES
  83.         You should not use this routine if you want to modify the image data.
  84.         Only the image data is cached, however, so you can modify any of the
  85.         other fields of the icon.
  86.  
  87.         Also, this routine is slightly slower than a normal call to
  88.         GetDiskObject(), and while the icon is loading requires slightly more
  89.         memory (the whole icon is loaded, then if the image is found in the
  90.         cache the new copy is discarded).
  91.  
  92.     SEE ALSO
  93.         FreeCachedDiskObject(), icon.library/GetDiskObject
  94.  
  95. dopus5.library/GetCachedDiskObjectNew   dopus5.library/GetCachedDiskObjectNew
  96.  
  97.     NAME
  98.         GetCachedDiskObjectNew - get icon with default fallback
  99.  
  100.     SYNOPSIS
  101.         GetCachedDiskObjectNew(name,flags)
  102.                                 A0    D0
  103.  
  104.         struct DiskObject *GetCachedDiskObjectNew(char *,long);
  105.  
  106.     FUNCTION
  107.         This routine attempts to load the icon in the same way as the
  108.         GetCachedDiskObject() routine. If no icon is found for the supplied
  109.         filename, the object in question is examined, and a default icon is
  110.         returned. This routine will return WBPROJECT, WBDRAWER, WBTOOL or
  111.         WBDISK icons, depending on the name passed in.
  112.  
  113.     INPUTS
  114.         name - name of object to load icon for (no .info suffix)
  115.         flags - set to 1 for now
  116.  
  117.     RESULT
  118.         Returns a pointer to the icon if successful, otherwise NULL.
  119.  
  120.     SEE ALSO
  121.         GetCachedDiskObject(), FreeCachedDiskObject(),
  122.         icon.library/GetDiskObjectNew()
  123.  
  124. dopus5.library/GetIconFlags                       dopus5.library/GetIconFlags
  125.  
  126.     NAME
  127.         GetIconFlags - get special Opus icon flags
  128.  
  129.     SYNOPSIS
  130.         GetIconFlags(icon)
  131.                       A0
  132.  
  133.         ULONG GetIconFlags(struct DiskObject *);
  134.  
  135.     FUNCTION
  136.         Opus stores additional information in icons to control some of the
  137.         enhanced features. This routine returns the special flags set for the
  138.         icon you supply.
  139.  
  140.     INPUTS
  141.         icon - icon to retrieve flags for
  142.  
  143.     RESULT
  144.         Returns ULONG containing the flags set. Current flags in use are :
  145.  
  146.             ICONF_POSITION_OK   - an Opus-specific position is available
  147.             ICONF_NO_BORDER     - icon has no border
  148.             ICONF_NO_LABEL      - icon has no label
  149.  
  150.     SEE ALSO
  151.         SetIconFlags(), GetIconPosition()
  152.  
  153. dopus5.library/GetIconPosition                 dopus5.library/GetIconPosition
  154.  
  155.     NAME
  156.         GetIconPosition - get Opus-specific icon position
  157.  
  158.     SYNOPSIS
  159.         GetIconPosition(icon, xptr, yptr)
  160.                          A0    A1    A2
  161.  
  162.         void GetIconPosition(struct DiskObject *, short *, short *);
  163.  
  164.     FUNCTION
  165.         Opus keeps a separate record from Workbench of icon positions. This
  166.         function allows you to retrieve the Opus-specific position of the
  167.         icon (the normal Workbench position is in do_CurrentX/do_CurrentY).
  168.  
  169.     INPUTS
  170.         icon - icon to retrieve position for
  171.         xptr - pointer to short to receive x position
  172.         yptr - pointer to short to receive y position
  173.  
  174.     RESULT
  175.         Stores the position in the two variables provided.
  176.  
  177.     NOTES
  178.         You should call GetIconFlags() first to check that an Opus-specific
  179.         position is available for this icon.
  180.  
  181.     SEE ALSO
  182.         SetIconPosition(), GetIconFlags()
  183.  
  184. dopus5.library/SetIconFlags                       dopus5.library/SetIconFlags
  185.  
  186.     NAME
  187.         SetIconFlags - set Opus flags in an icon
  188.  
  189.     SYNOPSIS
  190.         SetIconFlags(icon, flags);
  191.                       A0     D0
  192.  
  193.         void SetIconFlags(struct DiskObject *, ULONG);
  194.  
  195.     FUNCTION
  196.         This routine allows you to set the special Opus flags in an icon.
  197.  
  198.     INPUTS
  199.         icon - icon to set flags for
  200.         flags - new flags for the icon
  201.  
  202.     RESULT
  203.         The flags in the icon are set. See GetIconFlags() for a description
  204.         of the available flags.
  205.  
  206.     SEE ALSO
  207.         GetIconFlags()
  208.  
  209. dopus5.library/SetIconPosition                 dopus5.library/SetIconPosition
  210.  
  211.     NAME
  212.         SetIconPosition - set Opus position for an icon
  213.  
  214.     SYNOPSIS
  215.         SetIconPosition(icon, x, y)
  216.                          A0  D0 D1
  217.  
  218.         void SetIconPosition(struct DiskObject *, short, short);
  219.  
  220.     FUNCTION
  221.         This routine allows you to set the Opus-specific position for an
  222.         icon.
  223.  
  224.     INPUTS
  225.         icon - icon to set position for
  226.         x - new x position of icon
  227.         y - new y position of icon
  228.  
  229.     RESULT
  230.         The position is set in the icon.
  231.  
  232.     NOTES
  233.         You should also call SetIconFlags() on the icon to set the
  234.         ICONF_POSITION_OK flag.
  235.  
  236.     SEE ALSO
  237.         GetIconPosition(), SetIconFlags()
  238.  
  239. dopus5.library/CopyFileIcon                       dopus5.library/CopyFileIcon
  240.  
  241.     NAME
  242.         CopyFileIcon - copy icon from one file to another
  243.  
  244.     SYNOPSIS
  245.         CopyFileIcon(source, dest)
  246.                          A0     A1
  247.  
  248.         void CopyFileIcon(char *, char *);
  249.  
  250.     FUNCTION
  251.         This routine copies the icon from the specified source object to a
  252.         new icon for the destination object.
  253.  
  254.     INPUTS
  255.         source - source icon (without .info)
  256.         dest - destination icon (without .info)
  257.  
  258.     RESULT
  259.         The icon is copied. If an icon already exists for the source, it is
  260.         NOT overwritten. No error code is available for this function.
  261.  
  262.     NOTES
  263.         If the specified source file has no icon, a default icon is created.
  264.  
  265.