home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD1.iso / FileMover / HF-OM1.DMS / in.adf / OpusSDK.lha / SDK / docs / appicon.doc next >
Encoding:
Text File  |  1996-08-30  |  16.5 KB  |  480 lines
  1. dopus5.library/AppXXX routines                 dopus5.library/AppXXX routines
  2.  
  3.     The dopus5.library installs patches into the system when it loads to
  4.     intercept calls to the workbench.library AddAppXXX() functions. This
  5.     allows DOpus to show AppIcons, AppMenuItems, and support drag and drop
  6.     onto AppWindows.
  7.  
  8.     The emulation is transparent as far as a third-party application is
  9.     concerned, but it is possible to access additional features that DOpus
  10.     provides (especially for AppIcons). Obviously these are only available
  11.     through DOpus, and not through Workbench.
  12.  
  13.     Using tags with the AddAppIcon() function, it is possible to control
  14.     the DOpus-only features of AppIcons. Workbench ignores these tags, and
  15.     so if Workbench is running as well it will just see the plain AppIcon
  16.     itself.
  17.  
  18.     The tags are as follows :
  19.  
  20.         DAE_Local
  21.  
  22.         This tag causes the icon to only be added to DOpus. If Workbench is
  23.         running as well, it will not see this icon. Supplying this tag
  24.         is probably a good idea if your AppIcon depends on some of the other
  25.         DOpus-specific functions.
  26.  
  27.         DAE_Snapshot
  28.  
  29.         Indicates that this icon can support the Snapshot function. If this
  30.         tag is specified, the Snapshot item in the icon popup menu will be
  31.         enabled, and the Snapshot item in the main Icon menu will work.
  32.         Use of this tag generates AppSnapshotMsgs, see below for more
  33.         information.
  34.  
  35.         DAE_Close
  36.  
  37.         Turns the 'Open' item in the icon popup menu into a 'Close' item.
  38.         APPSNAPF_CLOSE will be set in the AppSnapshotMsg that is
  39.         generated.
  40.  
  41.         DAE_Info
  42.  
  43.         Indicates that this icon can support the Information function.
  44.         This is similar in operation to the DAE_Snapshot tag. The
  45.         APPSNAPF_INFO flag will be set in the AppSnapshotMsg.
  46.  
  47.         DAE_Menu
  48.  
  49.         This tag can be used several times for one icon. It allows you to
  50.         specify additional entries for the icon popup menu. ti_Data points
  51.         to a string that is displayed for the menu item. The order these
  52.         tags are supplied specifies the order they are displayed, and
  53.         also controls the ID that is returned in AppSnapshotMsgs.
  54.  
  55.         DAE_ToggleMenu
  56.  
  57.         Similar to DAE_Menu, this allows you to specify a menu item for
  58.         the icon popup menu. The only difference is that the menu item
  59.         is a toggle-select item (analagous to CHECKIT for Intuition menus).
  60.  
  61.         DAE_ToggleMenuSel
  62.  
  63.         The same as DAE_ToggleMenu, but specifies that the item is to be
  64.         selected by default (analagous to CHECKED for Intuition menus).
  65.  
  66.         DAE_MenuBase
  67.  
  68.         This tag allows you to specify a base ID for menu IDs that
  69.         are generated via the DAE_Menu, DAE_ToggleMenu and DAE_ToggleMenuSel
  70.         tags. Menu IDs usually start at 0 for the first menu and increase
  71.         from there. If you specify the DAE_MenuBase tag, the menu IDs will
  72.         start from your supplied value.
  73.  
  74.         DAE_Background
  75.  
  76.         This allows you to specify a pen to use to render the background
  77.         colour of the icon. If not supplied, the default is pen 0.
  78.  
  79.         DAE_Locked
  80.  
  81.         This tag specifies that the icon position is to be locked.
  82.         That is, the user will be unable to reposition the icon from the
  83.         initial coordinates. This flag can be changed later using the
  84.         ChangeAppIcon() function.
  85.  
  86.  
  87.     Using the new tags can cause special messages to be sent to your
  88.     message port. These are an extension of the normal AppMessages,
  89.     and can be identified by an am_Type of MTYPE_APPSNAPSHOT.
  90.  
  91.     The events you will get special messages for are :
  92.  
  93.         Snapshot
  94.  
  95.         If the DAE_Snapshot tag was specified and the user snapshots your
  96.         icon, you will receive a message containing the icon position
  97.         (AppSnapshotMsg->position_x and AppSnapshotMsg->position_y).
  98.         It is your responsibility to save these values, and use them
  99.         when adding the AppIcon in the future.
  100.  
  101.         If the APPSNAPF_WINDOW_POS flag is set in the AppSnapshotMsg->flags
  102.         field, the position in AppSnapshotMsg->window_pos is also valid.
  103.  
  104.         Un-Snapshot
  105.  
  106.         If the DAE_Snapshot tag was specified and the user unsnapshots
  107.         your icon, you will receive a message with the APPSNAPF_UNSNAPSHOT
  108.         flag set.
  109.  
  110.         Close
  111.  
  112.         If DAE_Close was specified, and the user selects the Close item
  113.         in the icon popup menu, you will receive a message with the
  114.         APPSNAPF_CLOSE flag set.
  115.  
  116.         Information
  117.  
  118.         You will receive a message with the APPSNAPF_INFO flag set if you
  119.         specified the DAE_Info tag, and the user selects Information on your
  120.         icon.
  121.  
  122.         Menu
  123.  
  124.         If menus were added with the DAE_Menu tags, you will receive a
  125.         message with the APPSNAPF_MENU flag set when the user selects one
  126.         of your menu items. The AppSnapshotMsg->id field contains the
  127.         item ID. If the user pressed the help key on one of the items,
  128.         the APPSNAPF_HELP flag will also be set.
  129.  
  130.     Directory Opus also sends additional information to AppWindows. If you
  131.     receive an AppMessage of type MTYPE_APPWINDOW, you should check to see
  132.     if it is an Opus message using the CheckAppMessage() function. If so,
  133.     the message is a DOpusAppMessage, which contains additional information.
  134.     The extra fields are :
  135.  
  136.         da_DropPos
  137.  
  138.         This field contains an array of Point structures. Each structure
  139.         gives the offset from the origin of each file in the message.
  140.         This allows you to maintain the relative positions of all icons
  141.         dropped in a multiple-file operation.
  142.  
  143.         da_DragOffset
  144.  
  145.         This Point structure gives you the offset of the primary icon
  146.         from the mouse pointer. That is, if the user clicked on the primary
  147.         icon in the top-left corner, this offset would be 0,0. If they
  148.         picked up the icon from the bottom-right corner, it might be 32,18.
  149.  
  150.         da_Flags
  151.  
  152.         The only flag supported so far is DAPPF_ICON_DROP. This indicates
  153.         that the files dropped were in fact icons (ie from an icon mode
  154.         lister).
  155.  
  156.     The da_DropPos and da_DragOffset fields enable you to calculate the
  157.     exact position that the user dropped the files on. Normal AppMessages
  158.     only provide the position of the mouse pointer, which is useless if you
  159.     want to maintain the relative and correct positions of the icons.
  160.  
  161. dopus5.library/AllocAppMessage                 dopus5.library/AllocAppMessage
  162.  
  163.     NAME
  164.         AllocAppMessage - allocate a DOpusAppMessage
  165.  
  166.     SYNOPSIS
  167.         AllocAppMessage(memory, port, count)
  168.                           A0     A1     D0
  169.  
  170.         DOpusAppMessage *AllocAppMessage(APTR, struct MsgPort *, short);
  171.  
  172.     FUNCTION
  173.         This function allows you to create a DOpusAppMessage (an extended
  174.         AppMessage) easily.
  175.  
  176.     INPUTS
  177.         memory - memory handle or NULL (see memory.doc)
  178.         port - address of reply port
  179.         count - number of arguments
  180.  
  181.     RESULT
  182.         Allocates a DOpusAppMessage, including space for count arguments
  183.         (both da_Msg.am_ArgList and da_DropPos will be initialised).
  184.  
  185.     NOTES
  186.         Unless you actually want to send an AppMessage to a DOpus window
  187.         with relative icon positions, you don't really need this function.
  188.         It does provide a convenient way to allocate an AppMessage, though,
  189.         and there's no reason you can't use DOpusAppMessages totally in
  190.         place of AppMessages if you want to.
  191.  
  192.     SEE ALSO
  193.         FreeAppMessage(), SetWBArg()
  194.  
  195. dopus5.library/AppWindowData                     dopus5.library/AppWindowData
  196.  
  197.     NAME
  198.         AppWindowData - extract data from an AppWindow
  199.  
  200.     SYNOPSIS
  201.         AppWindowData(appwindow, idptr, userdataptr)
  202.                          A0        A1       A2
  203.  
  204.         struct MsgPort *AppWindowData(APTR, ULONG *, ULONG *);
  205.  
  206.     FUNCTION
  207.         This function returns the ID, Userdata and Message port associated
  208.         with the specified AppWindow. These are the parameters that are
  209.         supplied in the call to AddAppWindow.
  210.  
  211.     INPUTS
  212.         appwindow - AppWindow handle
  213.         idptr - pointer to ULONG to contain the ID
  214.         userdataptr - pointer to ULONG to contain the Userdata
  215.  
  216.     RESULT
  217.         The AppWindow ID and Userdata are stored in the variables supplied,
  218.         and the address of the AppWindow's message port is returned.
  219.  
  220.     SEE ALSO
  221.         FindAppWindow(), workbench.library/AddAppWindow()
  222.  
  223. dopus5.library/ChangeAppIcon                     dopus5.library/ChangeAppIcon
  224.  
  225.     NAME
  226.         ChangeAppIcon - make changes to an AppIcon
  227.  
  228.     SYNOPSIS
  229.         ChangeAppIcon(icon, render, select, label, flags)
  230.                        A0     A1      A2      A3     D0
  231.  
  232.         void ChangeAppIcon
  233.              (APTR, struct Image *, struct Image *, char *,
  234.               ULONG);
  235.  
  236.     FUNCTION
  237.         This function allows you to make changes to an AppIcon that
  238.         was previously added to DOpus. It has no effect on the icon
  239.         on Workbench, so you should use the DAE_Local tag when adding
  240.         the icon if your program depends on this function.
  241.  
  242.         You are able to change both frames of the icon's image and the
  243.         icon's label. You can also lock or unlock the icon's position,
  244.         and make it busy.
  245.  
  246.     INPUTS
  247.         icon - icon to act on, as returned by AddAppIcon()
  248.         render - new main image for the icon
  249.         select - new select image for the icon
  250.         label - new label for the icon
  251.         flags - control flags. The available flags are :
  252.  
  253.                 CAIF_RENDER     - change the main image
  254.                 CAIF_SELECT     - change the select image
  255.                 CAIF_TITLE      - change the label
  256.                 CAIF_LOCKED     - change the 'locked' flag
  257.                 CAIF_SET        - use with CAIF_LOCKED
  258.                 CAIF_BUSY       - make icon busy
  259.                 CAIF_UNBUSY     - make icon unbusy
  260.  
  261.     NOTES
  262.         To lock an icon, pass CAIF_LOCKED|CAIF_SET. To unlock it, pass
  263.         CAIF_LOCKED by itself. The render, select and label parameters are
  264.         ignored unless their corresponding flags are set. You can specify
  265.         any combination of these flags at once. To reduce the visible
  266.         effects, you should make as many changes with the one call as
  267.         possible.
  268.  
  269.     SEE ALSO
  270.         SetAppIconMenuState(), workbench.library/AddAppIcon
  271.  
  272. dopus5.library/CheckAppMessage                 dopus5.library/CheckAppMessage
  273.  
  274.     NAME
  275.         CheckAppMessage - check if an AppMessage is from DOpus
  276.  
  277.     SYNOPSIS
  278.         CheckAppMessage(msg)
  279.                          A0
  280.  
  281.         BOOL CheckAppMessage(DOpusAppMessage *);
  282.  
  283.     FUNCTION
  284.         This function allows you to discover whether an AppMessage is
  285.         actually an extended DOpusAppMessage.
  286.  
  287.     INPUTS
  288.         msg - AppMessage to test
  289.  
  290.     RESULT
  291.         Returns TRUE if the message is a DOpusAppMessage.
  292.  
  293.     NOTES
  294.         You MUST only pass AppMessages (or DOpusAppMessages) to this
  295.         function. Passing other types of messages (eg IntuiMessages)
  296.         results in undefined behaviour.
  297.  
  298.     SEE ALSO
  299.         AllocAppMessage()
  300.  
  301. dopus5.library/FindAppWindow                     dopus5.library/FindAppWindow
  302.  
  303.     NAME
  304.         FindAppWindow - test to see if a window is an AppWindow
  305.  
  306.     SYNOPSIS
  307.         FindAppWindow(window)
  308.                         A0
  309.  
  310.         APTR FindAppWindow(struct Window *);
  311.  
  312.     FUNCTION
  313.         This routine allows you to discover whether a Window is in fact
  314.         an AppWindow.
  315.  
  316.     INPUTS
  317.         window - pointer to the window to test
  318.  
  319.     RESULT
  320.         Returns the AppWindow handle if it is an AppWindow, or NULL if not.
  321.  
  322.     NOTES
  323.         You should only use the returned value within a Forbid()/Permit(),
  324.         as the window in question could disappear at any time. Also note that
  325.         the system patches are not installed until the dopus5.library is
  326.         loaded. Any AppWindows added to the system before the patches are
  327.         installed are undetectable.
  328.  
  329.     SEE ALSO
  330.         AppWindowData(), workbench.library/AddAppWindow()
  331.  
  332. dopus5.library/FreeAppMessage                   dopus5.library/FreeAppMessage
  333.  
  334.     NAME
  335.         FreeAppMessage - frees a DOpusAppMessage
  336.  
  337.     SYNOPSIS
  338.         FreeAppMessage(msg)
  339.                         A0
  340.  
  341.         void FreeAppMessage(DOpusAppMessage *);
  342.  
  343.     FUNCTION
  344.         This function frees the supplied DOpusAppMessage. It is only
  345.         designed for messages allocated with AllocAppMessage.
  346.  
  347.     INPUTS
  348.         msg - message to free
  349.  
  350.     NOTES
  351.         You should not use this routine for AppMessages you receive
  352.         (ie are sent by another process). You should ReplyMsg() those
  353.         messages as normal. This function is used to free DOpusAppMessages
  354.         that YOU create, usually when they are replied to by another
  355.         task.
  356.  
  357.     SEE ALSO
  358.         AllocAppMessage()
  359.  
  360. dopus5.library/GetWBArgPath                       dopus5.library/GetWBArgPath
  361.  
  362.     NAME
  363.         GetWBArgPath - extract pathname from WBArg
  364.  
  365.     SYNOPSIS
  366.         GetWBArgPath(wbarg, buffer, size)
  367.                       A0      A1     D0
  368.  
  369.         BOOL GetWBArgPath(struct WBArg *, char *, long);
  370.  
  371.     FUNCTION
  372.         This function is provided as a convenient method of extracting
  373.         the pathname of a file/directory from a WBArg structure (usually
  374.         within an AppMessage).
  375.  
  376.     INPUTS
  377.         wbarg - pointer to the WBArg structure
  378.         buffer - buffer to write pathname to
  379.         size - size of buffer
  380.  
  381.     RESULT
  382.         The full path and name of the object referred to by the WBArg
  383.         structure is copied to the supplied buffer. This routine returns
  384.         TRUE if it was successful.
  385.  
  386. dopus5.library/ReplyAppMessage                 dopus5.library/ReplyAppMessage
  387.  
  388.     NAME
  389.         ReplyAppMessage - reply to an AppMessage
  390.  
  391.     SYNOPSIS
  392.         ReplyAppMessage(msg)
  393.                          A0
  394.  
  395.         void ReplyAppMessage(DOpusAppMessage *);
  396.  
  397.     FUNCTION
  398.         This function is the best way to reply to a DOpusAppMessage. Its
  399.         operation is quite straightforward - if the message has a reply
  400.         port set, it calls ReplyMsg() as normal. Otherwise, it calls
  401.         FreeAppMessage. This allows messages to be sent with no reply
  402.         needed. Directory Opus will never send an AppMessage without a
  403.         reply port, but you might want to use this routine among your
  404.         own processes.
  405.  
  406.     INPUTS
  407.         msg - message to reply to
  408.  
  409.     RESULT
  410.         The message is replied or freed.
  411.  
  412.     SEE ALSO
  413.         FreeAppMessage()
  414.  
  415. dopus5.library/SetAppIconMenuState         dopus5.library/SetAppIconMenuState
  416.  
  417.     NAME
  418.         SetAppIconMenuState - change the state of an icon popup menu
  419.  
  420.     SYNOPSIS
  421.         SetAppIconMenuState(icon, item, state)
  422.                              A0    D0     D1
  423.  
  424.         long SetAppIconMenuState(APTR, long, long);
  425.  
  426.     FUNCTION
  427.         This allows you to set the state of a toggle-select menu item in
  428.         the icon popup menu of AppIcons. These menu items would have been
  429.         added with the DAE_ToggleMenu and DAE_ToggleMenuSel tags.
  430.  
  431.     INPUTS
  432.         icon - icon to act on, as returned by AddAppIcon()
  433.         item - number of item to change (in the order they were added)
  434.         state - new state for the item (TRUE=selected)
  435.  
  436.     RESULT
  437.         Returns the old selection state of the item.
  438.  
  439.     NOTES
  440.         This routine uses 0 as a base ID for the menu items, even if you
  441.         specified a new base with DAE_MenuBase.
  442.  
  443.     SEE ALSO
  444.         ChangeAppIcon(), workbench.library/AddAppIcon
  445.  
  446. dopus5.library/SetWBArg                               dopus5.library/SetWBArg
  447.  
  448.     NAME
  449.         SetWBArg - fill out a WBArg entry in a DOpusAppMessage
  450.  
  451.     SYNOPSIS
  452.         SetWBArg(msg, item, lock, name, memory)
  453.                   A0   D0    D1    A1     A2
  454.  
  455.         BOOL SetWBArg(DOpusAppMessage *, short, BPTR, char *, APTR);
  456.  
  457.     FUNCTION
  458.         This routine makes it easy to initialise the WBArg structures
  459.         in an AppMessage (or a DOpusAppMessage).
  460.  
  461.     INPUTS
  462.         msg - AppMessage to initialise
  463.         item - item to initialise (starting at 0)
  464.         lock - lock on parent directory
  465.         name - name of file
  466.         memory - memory handle or NULL
  467.  
  468.     RESULT
  469.         The specified WBArg in the AppMessage is initialised with the
  470.         lock and name specified. This routine returns TRUE if it was
  471.         successful.
  472.  
  473.     NOTES
  474.         'lock' is the lock of the item's parent directory in the case of
  475.         files, or on the item itself in the case of directories. For files,
  476.         'name' is the name of the file. 'name' is null for directories.
  477.         The lock and name you supply are both copied, so they do not need
  478.         to remain valid once this call is complete.
  479.  
  480.