home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / inc&ad2.0 / text_autodocs / wb.doc < prev   
Text File  |  1992-09-01  |  11KB  |  345 lines
  1. TABLE OF CONTENTS
  2.  
  3. workbench.library/AddAppIconA
  4. workbench.library/AddAppMenuItemA
  5. workbench.library/AddAppWindowA
  6. workbench.library/RemoveAppIcon
  7. workbench.library/RemoveAppMenuItem
  8. workbench.library/RemoveAppWindow
  9. workbench.library/AddAppIconA                   workbench.library/AddAppIconA
  10.  
  11.    NAME
  12.     AddAppIcon - add an icon to workbench's list of appicons.        (V36)
  13.  
  14.    SYNOPSIS
  15.     AppIcon = AddAppIconA(id, userdata, text, msgport,
  16.        D0              D0     D1      A0     A1
  17.  
  18.                     lock, diskobj, taglist)
  19.                      A2      A3      A4
  20.  
  21.     struct AppIcon *AddAppIconA(ULONG, ULONG, char *,
  22.         struct MsgPort *, struct FileLock *, struct DiskObject *,
  23.         struct TagItem *);
  24.  
  25.     Alternate, varargs version:
  26.     struct AppIcon *AddAppIcon(ULONG, ULONG, char *,
  27.             struct MsgPort *, struct FileLock *,
  28.             struct DiskObject *,
  29.             tag1, data1,
  30.             tag2, data2,
  31.             ...
  32.             TAG_END );
  33.  
  34.    FUNCTION
  35.     Attempt to add an icon to workbench's list of appicons.  If
  36.     successful, the icon is displayed on the workbench (the same
  37.     place disk icons are displayed).
  38.     This call is provided to allow applications to be notified when
  39.     a graphical object (non neccessarely associated with a file)
  40.     gets 'manipulated'. (explained later).
  41.     The notification consists of an AppMessage (found in workbench.h/i)
  42.     of type 'MTYPE_APPICON' arriving at the message port you specified.
  43.     The types of 'manipulation' that can occur are:
  44.     1. Double-clicking on the icon.  am_NumArgs will be zero and
  45.        am_ArgList will be NULL.
  46.     2. Dropping an icon or icons on your appicon.  am_NumArgs will
  47.           be the number of icons droppped on your app icon plus one.
  48.           am_ArgList will be an array of ptrs to WBArg structures.
  49.           Refer to the 'WBStartup Message' section of the RKM for more info.
  50.     3. Dropping your appicon on another icon.  NOT SUPPORTED.
  51.  
  52.    INPUTS
  53.     id - this variable is strictly for your own use and is ignored by
  54.          workbench.  Typical uses in C are in switch and case statements,
  55.          and in assembly language table lookup.
  56.     userdata - this variable is strictly for your own use and is ignored
  57.            by workbench.
  58.     text - name of icon (char *)
  59.     lock - NULL    (Currently unused)
  60.     msgport - pointer to message port workbench will use to send you an
  61.           AppMessage message of type 'MTYPE_APPICON' when your icon
  62.           gets 'manipulted' (explained above).
  63.     diskobj - pointer to a DiskObject structure filled in as follows:
  64.         do_Magic - NULL
  65.         do_Version - NULL
  66.         do_Gadget - a gadget structure filled in as follows:
  67.         NextGadget - NULL
  68.         LeftEdge - NULL
  69.         TopEdge - NULL
  70.         Width - width of icon hit-box
  71.         Height - height of icon hit-box
  72.         Flags - NULL or GADGHIMAGE
  73.         Activation - NULL
  74.         GadgetType - NULL
  75.         GadgetRender - pointer to Image structure filled in as follows:
  76.             LeftEdge - NULL
  77.             TopEdge - NULL
  78.             Width - width of image (must be <= Width of hit box)
  79.             Height - height of image (must be <= Height of hit box)
  80.             Depth - # of bit-planes in image
  81.             ImageData - pointer to actual word aligned bits (CHIP MEM)
  82.             PlanePick - Plane mask ((1 << depth) - 1)
  83.             PlaneOnOff - 0
  84.             NextImage - NULL
  85.         SelectRender - pointer to alternate Image struct or NULL
  86.         GadgetText - NULL
  87.         MutualExclude - NULL
  88.         SpecialInfo - NULL
  89.         GadgetID - NULL
  90.         UserData - NULL
  91.         do_Type - NULL
  92.         do_DefaultTool - NULL
  93.         do_ToolTypes - NULL
  94.         do_CurrentX - NO_ICON_POSITION (recommended)
  95.         do_CurrentY - NO_ICON_POSITION (recommended)
  96.         do_DrawerData - NULL
  97.         do_ToolWindow - NULL
  98.         do_StackSize - NULL
  99.  
  100.     (an easy way to create one of these (a DiskObject) is to create an icon
  101.         with the V2.0 icon editor and save it out.  Your application can then
  102.         call GetDiskObject on it and pass that to AddAppIcon.)
  103.  
  104.     taglist - ptr to a list of tag items.  Must be NULL for V2.0.
  105.  
  106.    RESULTS
  107.     AppIcon - a pointer to an appicon structure which you pass to
  108.           RemoveAppIcon when you want to remove the icon
  109.           from workbench's list of appicons.  NULL
  110.           if workbench was unable to add your icon; typically
  111.           happens when workbench is not running or under low
  112.           memory conditions.
  113.  
  114.    EXAMPLE
  115.     You could design a print-spooler icon and add it to the workbench.
  116.     Any file dropped on the print spooler would be printed.  If the
  117.     user double-clicked (opended) your printer-spooler icon, you could
  118.     open a window showing the status of the print spool, allow changes
  119.     to print priorities, allow deletions, etc.  If you registered this
  120.     window as an 'appwindow' (explained in workbench.library AddAppWindow)
  121.     files could also be dropped in the window and added to the spool.
  122.  
  123.    SEE ALSO
  124.     RemoveAppIcon()
  125.  
  126.    BUGS
  127.     Currently Info cannot be obtained on appicons.
  128.  
  129. workbench.library/AddAppMenuItemA           workbench.library/AddAppMenuItemA
  130.  
  131.    NAME
  132.     AddAppMenuItem - add a menuitem to workbench's list              (V36)
  133.                         of appmenuitems.
  134.  
  135.    SYNOPSIS
  136.     AppMenuItem = AddAppMenuItemA(id, userdata, text, msgport, taglist)
  137.     D0                  D0     D1      A0     A1       A2
  138.  
  139.     struct AppMenuItem *AddAppMenuItemA(ULONG, ULONG, char *,
  140.                         struct MsgPort *,
  141.                         struct TagItem *);
  142.  
  143.     Alternate, varargs version:
  144.     struct AppMenuItem *AddAppMenuItem(ULONG, ULONG, char *,
  145.                     struct MsgPort *,
  146.                     tag1, data1,
  147.                     tag2, data2,
  148.                     ...
  149.                     TAG_END );
  150.  
  151.    FUNCTION
  152.     Attempt to add the text as a menuitem to workbench's list
  153.     of appmenuitems (the 'Tools' menu strip).
  154.  
  155.    INPUTS
  156.     id - this variable is strictly for your own use and is ignored by
  157.          workbench.  Typical uses in C are in switch and case statements,
  158.          and in assembly language table lookup.
  159.     userdata - this variable is strictly for your own use and is ignored
  160.            by workbench.
  161.     text - text for the menuitem (char *)
  162.     msgport - pointer to message port workbench will use to send you an
  163.           AppMessage message of type 'MTYPE_APPMENUITEM' when your
  164.           menuitem gets selected.
  165.     taglist - ptr to a list of tag items.  Must be NULL for V2.0.
  166.  
  167.    RESULTS
  168.     AppMenuItem - a pointer to an appmenuitem structure which you pass to
  169.               RemoveAppMenuItem when you want to remove the menuitem
  170.               from workbench's list of appmenuitems.  NULL if
  171.               workbench was unable to add your menuitem; typically
  172.               happens when workbench is not running or under low
  173.               memory conditions.
  174.  
  175.    SEE ALSO
  176.     RemoveAppMenuItem()
  177.  
  178.    BUGS
  179.     Currently does not limit the system to 63 menu items...
  180.     Any menu items after the 63rd will not be selectable.
  181.  
  182. workbench.library/AddAppWindowA               workbench.library/AddAppWindowA
  183.  
  184.    NAME
  185.     AddAppWindow - add a window to workbench's list of appwindows.  (V36)
  186.  
  187.    SYNOPSIS
  188.     AppWindow = AddAppWindowA(id, userdata, window, msgport, taglist)
  189.     D0              D0     D1       A0      A1       A2
  190.  
  191.     struct AppWindow *AddAppWindowA(ULONG, ULONG, struct Window *,
  192.                     struct MsgPort *, struct TagItem *);
  193.  
  194.     Alternate, varargs version:
  195.     struct AppWindow *AddAppWindow(ULONG, ULONG, struct Window *,
  196.                     struct MsgPort *
  197.                     tag1, data1,
  198.                     tag2, data2,
  199.                     ...
  200.                     TAG_END );
  201.  
  202.    FUNCTION
  203.     Attempt to add the window to workbench's list of appwindows.
  204.     Normally non-workbench windows (those not opened by workbench)
  205.     cannot have icons dropped in them.  This call is provided to
  206.     allow applications to be notified when an icon or icons get
  207.     dropped inside a window that they have registered with workbench.
  208.     The notification consists of an AppMessage (found in workbench.h/i)
  209.     of type 'MTYPE_APPWINDOW' arriving at the message port you specified.
  210.     What you do with the list of icons (pointed to by am_ArgList) is
  211.     up to you, but generally you would want to call GetDiskObjectNew on
  212.     them.
  213.  
  214.    INPUTS
  215.     id - this variable is strictly for your own use and is ignored by
  216.          workbench.  Typical uses in C are in switch and case statements,
  217.          and in assembly language table lookup.
  218.     userdata - this variable is strictly for your own use and is ignored
  219.            by workbench.
  220.     window - pointer to window to add.
  221.     msgport - pointer to message port workbench will use to send you an
  222.           AppMessage message of type 'MTYPE_APPWINDOW' when your
  223.           window gets an icon or icons dropped in it.
  224.     taglist - ptr to a list of tag items.  Must be NULL for V2.0.
  225.  
  226.    RESULTS
  227.     AppWindow - a pointer to an appwindow structure which you pass to
  228.             RemoveAppWindow when you want to remove the window
  229.             from workbench's list of appwindows.  NULL
  230.             if workbench was unable to add your window; typically
  231.             happens when workbench is not running or under low
  232.             memory conditions.
  233.  
  234.    SEE ALSO
  235.     RemoveAppWindow()
  236.  
  237.    NOTES
  238.        The V2.0 icon editor is an example of an app window.  Note that app
  239.        window applications generally want to call GetDiskObjectNew
  240.        (as opposed to GetDiskObject) to get the disk object for the icon
  241.        dropped in the window.
  242.  
  243.    BUGS
  244.     None
  245.  
  246. workbench.library/RemoveAppIcon               workbench.library/RemoveAppIcon
  247.  
  248.    NAME
  249.     RemoveAppIcon - remove an icon from workbench's list            (V36)
  250.                          of appicons.
  251.  
  252.    SYNOPSIS
  253.     error = RemoveAppIcon(AppIcon)
  254.          D0                     A0
  255.     BOOL RemoveAppIcon(struct AppIcon *);
  256.  
  257.    FUNCTION
  258.     Attempt to remove an appicon from workbench's list of appicons.
  259.  
  260.    INPUTS
  261.     AppIcon - pointer to an AppIcon structure returned by AddAppIcon.
  262.  
  263.    RESULTS
  264.     error - Currently always TRUE...
  265.  
  266.    NOTES
  267.     As with anything that deals with async operation, you will need to
  268.     do a final check for messages on your App message port for messages
  269.     that may have come in between the last time you checked and the
  270.     call to removed the App.
  271.  
  272.    SEE ALSO
  273.     AddAppIconA()
  274.  
  275.    BUGS
  276.     None
  277.  
  278. workbench.library/RemoveAppMenuItem       workbench.library/RemoveAppMenuItem
  279.  
  280.    NAME
  281.     RemoveAppMenuItem - remove a menuitem from workbench's list      (V36)
  282.                 of appmenuitems.
  283.  
  284.    SYNOPSIS
  285.     error = RemoveAppMenuItem(AppMenuItem)
  286.          D0                            A0
  287.     BOOL RemoveAppMenuItem(struct AppMenuItem *);
  288.  
  289.    FUNCTION
  290.     Attempt to remove an appmenuitem from workbench's list
  291.     of appmenuitems.
  292.  
  293.    INPUTS
  294.     AppMenuItem - pointer to an AppMenuItem structure returned by
  295.               AddAppMenuItem.
  296.  
  297.    RESULTS
  298.     error - Currently always TRUE...
  299.  
  300.    NOTES
  301.     As with anything that deals with async operation, you will need to
  302.     do a final check for messages on your App message port for messages
  303.     that may have come in between the last time you checked and the
  304.     call to removed the App.
  305.  
  306.    SEE ALSO
  307.     AddAppMenuItemA()
  308.  
  309.    BUGS
  310.     None
  311.  
  312. workbench.library/RemoveAppWindow           workbench.library/RemoveAppWindow
  313.  
  314.    NAME
  315.     RemoveAppWindow - remove a window from workbench's list         (V36)
  316.                           of appwindows.
  317.  
  318.    SYNOPSIS
  319.     error = RemoveAppWindow(AppWindow)
  320.          D0                       A0
  321.     BOOL RemoveAppWindow(struct AppWindow *);
  322.  
  323.    FUNCTION
  324.     Attempt to remove an appwindow from workbench's list of appwindows.
  325.  
  326.    INPUTS
  327.     AppWindow - pointer to an AppWindow structure returned by
  328.             AddAppWindow.
  329.  
  330.    RESULTS
  331.     error - Currently always TRUE...
  332.  
  333.    NOTES
  334.     As with anything that deals with async operation, you will need to
  335.     do a final check for messages on your App message port for messages
  336.     that may have come in between the last time you checked and the
  337.     call to removed the App.
  338.  
  339.    SEE ALSO
  340.     AddAppWindowA()
  341.  
  342.    BUGS
  343.     None
  344.  
  345.