home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD1.iso / FileMover / HF-OM1.DMS / in.adf / OpusSDK.lha / SDK / docs / popup.doc < prev    next >
Encoding:
Text File  |  1996-08-31  |  5.3 KB  |  135 lines
  1. dopus5.library/DoPopUpMenu                         dopus5.library/DoPopUpMenu
  2.  
  3.     NAME
  4.         DoPopUpMenu - display a popup menu
  5.  
  6.     SYNOPSIS
  7.         DoPopUpMenu(window, menu, itemptr, button)
  8.                       A0     A1      A2      D0
  9.  
  10.         USHORT DoPopUpMenu(struct Window *, PopUpMenu *, PopUpItem **, USHORT);
  11.  
  12.     FUNCTION
  13.         This routine displays a popup menu. The PopUpMenu structure must be
  14.         initialised as follows:
  15.  
  16.             item_list - a list of the menu items
  17.  
  18.             locale    - a pointer to an initialised DOpusLocale structure
  19.  
  20.             flags     - menu flags. Currently supported flags are:
  21.  
  22.                             POPUPMF_HELP    - menu supports help via the user
  23.                                               pressing the help key
  24.  
  25.                             POPUPMF_REFRESH - the callback function supplied
  26.                                               should be used to refresh the
  27.                                               parent window
  28.  
  29.                             POPUPMF_ABOVE   - the popup menu should open
  30.                                               above the parent window, instead
  31.                                               of over the current mouse
  32.                                               position
  33.  
  34.             callback  - pointer to your refresh callback function, or NULL
  35.  
  36.         The callback function is a function that you define to handle the
  37.         situation when the parent window needs to be refreshed. If the parent
  38.         window is simplerefresh, you should provide this function. The function
  39.         has the following prototype:
  40.  
  41.             void __asm refresh_callback(    register __d0 ULONG type,
  42.                                             register __a0 struct Window *window,
  43.                                             register __a1 ULONG userdata )
  44.  
  45.         The routine will be called whenever the parent window needs to be
  46.         refreshed. 'type' is the IDCMP message type; usually
  47.         IDCMP_REFRESHWINDOW. 'window' is a pointer to the parent window, and
  48.         'userdata' is the userdata field of the PopUpMenu structure.
  49.  
  50.         The 'item_list' parameter is a MinList containing the items of the
  51.         popup menu. Each node on this list is a PopUpItem structure, which is
  52.         defined as follows :
  53.  
  54.             item_name - pointer to item name
  55.  
  56.             id        - item ID
  57.  
  58.             flags     - item flags. Currently supported flags are:
  59.  
  60.                             POPUPF_LOCALE   - signifies that 'item_name' is
  61.                                               not a pointer to a string, but
  62.                                               is a locale ID representing a
  63.                                               string in the supplied locale.
  64.  
  65.                             POPUPF_CHECKIT  - item can be checked, much like
  66.                                               CHECKIT in Intuition menus
  67.  
  68.                             POPUPF_CHECKED  - item starts out checked, much
  69.                                               like CHECKED in Intuition menus
  70.  
  71.                             POPUPF_SUB      - item has sub-items
  72.  
  73.                             POPUPF_DISABLED - item is disabled
  74.  
  75.             data      - unless POPUPF_SUB is set, this is a userdata field
  76.                         that can be set to anything. If POPUPF_SUB is set, this
  77.                         field must point to an initialised MinList containing
  78.                         the PopUpItem structures for the sub-menu. You can
  79.                         have up to four levels of sub-menus.
  80.  
  81.         Set 'item_name' to the special value POPUP_BARLABEL to produce a
  82.         separator bar in the menu.
  83.  
  84.     INPUTS
  85.         window  - Parent window to open menu over
  86.         menu    - PopUpMenu to open
  87.         itemptr - Pointer to location to receive a pointer to the selected
  88.                   item
  89.         button  - The code of the mouse button pressed to generate this menu.
  90.                   This is used to control which mouse button release will
  91.                   remove the menu (eg, if you pass SELECTDOWN for the 'button'
  92.                   value, the menu will be removed on a SELECTUP event)
  93.  
  94.     RESULT
  95.         Returns -1 if no item was selected. If an item was selected,
  96.         the item ID is returned, and the address of the PopUpItem structure
  97.         is stored in 'itemptr'. If the user pressed the help key over an item
  98.         and the POPUPMF_HELP flag is set, the POPUP_HELPFLAG flag will be
  99.         set in the returned item ID.
  100.  
  101.     SEE ALSO
  102.         GetPopUpItem()
  103.  
  104. dopus5.library/GetPopUpItem                       dopus5.library/GetPopUpItem
  105.  
  106.     NAME
  107.         GetPopUpItem - find a PopUpItem by ID
  108.  
  109.     SYNOPSIS
  110.         GetPopUpItem(menu, id)
  111.                       A0   D0
  112.  
  113.         PopUpItem *GetPopUpItem(PopUpMenu *, USHORT);
  114.  
  115.     FUNCTION
  116.         This searches the supplied menu for a PopUpItem with the specified ID,
  117.         and returns a pointer to it.
  118.  
  119.     INPUTS
  120.         menu - PopUpMenu to search
  121.         id   - ID to search for
  122.  
  123.     RESULT
  124.         Returns a pointer to the PopUpItem if found, or else NULL. This routine
  125.         supports one level of sub-menus, and will not find an item that is
  126.         more than one sub-menu deep.
  127.  
  128.     NOTES
  129.         This routine is useful in allowing you to find an item to set the state
  130.         of the POPUPF_CHECKED and POPUPF_DISABLED flags.
  131.  
  132.     SEE ALSO
  133.         DoPopUpMenu()
  134.  
  135.