home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 420.lha / PopMenuPackage / popmenu_pak.doc < prev    next >
Encoding:
Text File  |  1990-10-01  |  12.2 KB  |  427 lines
  1. TABLE OF CONTENTS
  2.  
  3. popmenu_pak/BuildPMenu
  4. popmenu_pak/CountPMenuItems
  5. popmenu_pak/FreePMenu
  6. popmenu_pak/GetPItem
  7. popmenu_pak/GetPItemNum
  8. popmenu_pak/HandlePMenu
  9. popmenu_pak/InitPMenu
  10. popmenu_pak/RefreshPMenu
  11. popmenu_pak/RemovePMenu
  12. popmenu_pak/SetActiveItem
  13. popmenu_pak/SetPMenuColor
  14. popmenu_pak/SetPMenuText
  15.  
  16.  
  17. popmenu_pak/BuildPMenu                                 popmenu_pak/BuildPMenu
  18.  
  19.    NAME
  20.       BuildPMenu  - Allocate a PMenu structure and setup its data
  21.  
  22.    SYNOPSIS
  23.       pmenu = BuildPMenu(first_item, flags, active, title, id);
  24.  
  25.    PROTOTYPE
  26.       struct PMenu *BuildPMenu(struct PMenuItem *, USHORT, SHORT, UBYTE *,
  27.                                USHORT);
  28.  
  29.    FUNCTION
  30.       BuildPMenu allocates and sets up a PMenu structure and necessary
  31.       support structures, such as the PMenu Gadget, IntuiText, and Border.
  32.       If a title is supplied, the PMenu always displays the title in the
  33.       menu select box, otherwise the last selected menu item is displayed.
  34.       The specified ID is used to compare with that of the ID found when
  35.       a GADGETDOWN message is received from the application program. The
  36.       active menu item number is a number from 1 up to the number of items
  37.       in the PMenuItem list, optionally passed as the first parameter. This
  38.       tells InitPMenu() which menu item to display when the menu is first
  39.       initialized (of course, this has no effect if a title is used). Note
  40.       that the first item need not be passed to this function. If you are
  41.       dynamically allocating your PMenuItems, then they can be added manually
  42.       later, with an assignment such as: "pmenu->FirstPItem = first_item".
  43.  
  44.    INPUTS
  45.       first_item -- pointer to a prepared PMenuItem structure, initialized
  46.                     with the following data:
  47.                     ------------------------
  48.          NextPItem      - pointer to next PMenuItem
  49.          Flags          - flags defining rendering of item
  50.          MutualExclude  - items of a LIST menu deselected when this one is
  51.          ItemFill       - pointer to item IntuiText or imagery (text only)
  52.          SelectFill     - pointer to selected item or imagery (not supported)
  53.       flags      -- flags defining type and rendering of menu:
  54.                      LISTPMENU - not supported
  55.                      COMMPMENU - normal command-type menu
  56.                      SHADOWED  - draw a shadow around the menu button
  57.                      TITLED    - if title is to be used later, but isn't
  58.                                  passed with this call
  59.       active     -- number (1-n) of active item (0 = first one too)
  60.       title      -- pointer to UBYTE constant title (or NULL)
  61.       id         -- PMenu ID, used to decide which PMenu was selected
  62.  
  63.    RETURNS
  64.       Returns a pointer to the allocated PMenu is successful, otherwise NULL.
  65.  
  66.    BUGS
  67.       None.
  68.  
  69.    SEE ALSO
  70.       InitPMenu(), FreePMenu()
  71.  
  72.  
  73. popmenu_pak/CountPMenuItems                       popmenu_pak/CountPMenuItems
  74.  
  75.    NAME
  76.       CountPMenuItems - count the number of menu items within a PopMenu
  77.  
  78.    SYNOPSIS
  79.       items = CountPMenuItems(pmenu);
  80.  
  81.    PROTOTYPE
  82.       int CountPMenuItems(struct PMenu *);
  83.  
  84.    FUNCTION
  85.       CountPMenuItems traverses the PopMenu PMenuItem list, and counts all
  86.       of the items in the list. This is useful to the application program
  87.       if it needs to know how many items are in a PMenu for window size
  88.       adjusting purposes.
  89.  
  90.    INPUTS
  91.       pmenu -- pointer to a prepared PMenu structure
  92.  
  93.    RETURNS
  94.       The number of items in the PMenu Item list, or zero if no items have
  95.       been assigned yet.
  96.  
  97.    BUGS
  98.       None.
  99.  
  100.    SEE ALSO
  101.  
  102.  
  103. popmenu_pak/FreePMenu                                   popmenu_pak/FreePMenu
  104.  
  105.    NAME
  106.       FreePMenu - removes and deallocates a PopMenu
  107.  
  108.    SYNOPSIS
  109.       FreePMenu(pmenu);
  110.  
  111.    PROTOTYPE
  112.       void FreePMenu(struct PMenu *);
  113.  
  114.    FUNCTION
  115.       FreePMenu first calls RemovePMenu() to remove the specified PopMenu
  116.       from its window. It then deallocates all memory used by the PopMenu,
  117.       that was allocated by BuildPMenu(). FreePMenu() can be called after
  118.       RemovePMenu() without screwing up anything.
  119.  
  120.    INPUTS
  121.       pmenu -- pointer to the prepared PMenu to deallocate
  122.  
  123.    RETURNS
  124.       None.
  125.  
  126.    BUGS
  127.       None.
  128.  
  129.    SEE ALSO
  130.       BuildPMenu(), RemovePMenu()
  131.  
  132.  
  133. popmenu_pak/GetPItem                                     popmenu_pak/GetPItem
  134.  
  135.    NAME
  136.       GetPItem - return a pointer to the numbered PMenuItem
  137.  
  138.    SYNOPSIS
  139.       pmenuitem = GetPItem(pmenu, item_number);
  140.  
  141.    PROTOTYPE
  142.       struct PMenuItem *GetPItem(struct PMenu *, SHORT);
  143.  
  144.    FUNCTION
  145.       GetPItem searches the specified PMenu's item list until it gets to the
  146.       specified item number, then returns the PMenuItem's pointer.
  147.  
  148.    INPUTS
  149.       pmenu       -- pointer to a prepared PMenu structure
  150.       item_number -- item number of PMenuItem pointer to return
  151.  
  152.    RETURNS
  153.       Pointer to the specified PMenuItem if that item number exists,
  154.       otherwise NULL.
  155.  
  156.    BUGS
  157.       None.
  158.  
  159.    SEE ALSO
  160.       GetPItemNum()
  161.  
  162.  
  163. popmenu_pak/GetPItemNum                               popmenu_pak/GetPItemNum
  164.  
  165.    NAME
  166.       GetPItemNum - find the specified PMenuItem's item number
  167.  
  168.    SYNOPSIS
  169.       item_number = GetPItemNum(pmenu, item);
  170.  
  171.    PROTOTYPE
  172.       SHORT GetPItemNum(struct PMenu *, struct PMenuItem *);
  173.  
  174.    FUNCTION
  175.       GetPItemNum returns the item number of the specfied PMenuItem within
  176.       the specified PMenu.
  177.  
  178.    INPUTS
  179.       pmenu -- pointer to a prepared PMenu structure
  180.       item --  pointer to an existing PMenuItem
  181.  
  182.    RETURNS
  183.       The item number of the PMenuItem, if it is within the PMenu, otherwise
  184.       NULL.
  185.  
  186.    BUGS
  187.       None.
  188.  
  189.    SEE ALSO
  190.       GetPItem()
  191.  
  192.  
  193. popmenu_pak/HandlePMenu                               popmenu_pak/HandlePMenu
  194.  
  195.    NAME
  196.       HandlePMenu - draw the PMenu and get an item from the user
  197.  
  198.    SYNOPSIS
  199.       item_number = HandlePMenu(pmenu);
  200.  
  201.    PROTOTYPE
  202.       USHORT HandlePMenu(struct PMenu *);
  203.  
  204.    FUNCTION
  205.       HandlePMenu opens and draws the specified PMenu's items. Then it goes
  206.       into a mode where it waits for a MOUSEBUTTON:SELECTUP event, waiting
  207.       for the user to lift up on the left mouse button. During this time it
  208.       tracks the mouse over the menu items, highlighted enabled menu items.
  209.       When the mouse button is released, HandlePMenu() returns the item
  210.       number of the item the mouse was over when the button was released. If
  211.       the mouse was outside the window, then 0 is returned. This function is
  212.       called by the host application program when it receives a GADGETDOWN
  213.       event, and the ID number of the selected Gadget and the ID of a PMenu
  214.       are the same. The host casts the pointer of the Gadget's UserData field
  215.       to type (struct PMenu *), and passes this to HandlePMenu().
  216.       NOTE: If you have several overlapping, call WindowToFront() on the
  217.       window containing the selected PMenu before calling HandlePMenu(). This
  218.       makes sure the window is front (and has no possibly-wreckable clipping
  219.       rectangles) and won't get messed up by the BitMap operations done by
  220.       HandlePMenu().
  221.  
  222.    INPUTS
  223.       pmenu -- pointer to an initialized PMenu structure.
  224.  
  225.    RETURNS
  226.       Item number of selected item (1-n), or NULL if none selected.
  227.  
  228.    BUGS
  229.       No layer locking or menu clip-recting is done on the menu drawing or
  230.       un-drawing. The menu is rendered directly in the window's BitMap,
  231.       after a backup of the menu area is saved.
  232.  
  233.    SEE ALSO
  234.  
  235.  
  236. popmenu_pak/InitPMenu                                   popmenu_pak/InitPMenu
  237.  
  238.    NAME
  239.       InitPMenu - attach a PMenu to a window
  240.  
  241.    SYNOPSIS
  242.       success = InitPMenu(window, pmenu, x, y);
  243.  
  244.    PROTOTYPE
  245.       int InitPMenu(struct Window *, struct PMenu *, SHORT, SHORT);
  246.  
  247.    FUNCTION
  248.       InitPMenu computes the size of the specified PopMenu and then attaches
  249.       it to the specified window at the specified location, displaying the
  250.       application-specified title (set with BuildPMenu() or SetPMenuText())
  251.       or default menu item name. If negative values are used for the x or y
  252.       position of the menu, then they will be offsets from the right or
  253.       bottom border of the window (such as GRELRIGHT or GRELBOTTOM for
  254.       Gadgets). Be careful, as you might not know how wide the menu will be.
  255.       If you specify a -1 for the x or y coordinates (or both), then the
  256.       menu will be located relative to the right or bottom borders, based
  257.       on the computed width/height of the PopMenu, plus 5 pixels. For
  258.       example, to place a PopMenu just inside the right border of the window,
  259.       pass a -1 for the x coordinate.
  260.  
  261.    INPUTS
  262.       window -- pointer to a standard open window
  263.       pmenu  -- pointer to a previously initialized PMenu structure
  264.       x      -- x-coordinate of upper-left corner of menu activation gadget
  265.       y      -- y-coordinate of upper-left corner of menu activation gadget
  266.  
  267.    RETURNS
  268.       TRUE if successful, NULL otherwise (only if a Window or PMenu pointer
  269.       was not passed).
  270.  
  271.    BUGS
  272.       None.
  273.  
  274.    SEE ALSO
  275.       BuildPMenu(), HandlePMenu()
  276.  
  277.  
  278. popmenu_pak/RefreshPMenu                             popmenu_pak/RefreshPMenu
  279.  
  280.    NAME
  281.       RefreshPMenu - redraws a PopMenu
  282.  
  283.    SYNOPSIS
  284.       RefreshPMenu(pmenu);
  285.  
  286.    PROTOTYPE
  287.       void RefreshPMenu(struct PMenu *);
  288.  
  289.    FUNCTION
  290.       RefreshPMenu redraws the PopMenu selection box and updates the title
  291.       in the box for an initialized PopMenu. This is useful if your window
  292.       imagery/gadgetry has been trashed by some graphics operation.
  293.       InitPMenu() calls RefreshPMenu() for you.
  294.  
  295.    INPUTS
  296.       pmenu -- pointer to an initialied PMenu structure
  297.  
  298.    RETURNS
  299.       None.
  300.  
  301.    BUGS
  302.       None.
  303.  
  304.    SEE ALSO
  305.       BuildPMenu(), InitPMenu()
  306.  
  307.  
  308. popmenu_pak/RemovePMenu                               popmenu_pak/RemovePMenu
  309.  
  310.    NAME
  311.       RemovePMenu - removes a PMenu from its window
  312.  
  313.    SYNOPSIS
  314.       RemovePMenu(pmenu);
  315.  
  316.    PROTOTYPE
  317.       void RemovePMenu(struct PMenu *);
  318.  
  319.    FUNCTION
  320.       RemovePMenu removes the specified PopMenu imagery from its window, but
  321.       does not deallocate the PopMenu data. RemovePMenu() is called by
  322.       FreePMenu().
  323.  
  324.    INPUTS
  325.       pmenu -- pointer to the PMenu to remove
  326.  
  327.    RETURNS
  328.       None.
  329.  
  330.    BUGS
  331.       None.
  332.  
  333.    SEE ALSO
  334.       InitPMenu(), FreePMenu()
  335.  
  336.  
  337. popmenu_pak/SetActiveItem                           popmenu_pak/SetActiveItem
  338.  
  339.    NAME
  340.       SetActiveItem - set a new active menu item for a PopMenu
  341.  
  342.    SYNOPSIS
  343.       SetActiveItem(pmenu, item_number);
  344.  
  345.    PROTOTYPE
  346.       void SetActiveItem(struct PMenu *, SHORT);
  347.  
  348.    FUNCTION
  349.       SetActiveItem sets the specified item number as the current active
  350.       menu item, and draws the item text in the menu select box (unless the
  351.       menu has been set with a constant title). This only works for menus
  352.       of type COMMPMENU.
  353.  
  354.    INPUTS
  355.       pmenu       -- pointer to the PMenu to affect
  356.       item_number -- item number (1-n) of item to make current
  357.  
  358.    RETURNS
  359.       None.
  360.  
  361.    BUGS
  362.       None.
  363.  
  364.    SEE ALSO
  365.  
  366.  
  367. popmenu_pak/SetPMenuColor                           popmenu_pak/SetPMenuColor
  368.  
  369.    NAME
  370.       SetPMenuColor - set the drawing colors of a PopMenu
  371.  
  372.    SYNOPSIS
  373.       SetPMenuColor(pmenu, frontpen, backpen);
  374.  
  375.    PROTOTYPE
  376.       void SetPMenuColor(struct PMenu *, USHORT, USHORT);
  377.  
  378.    FUNCTION
  379.       SetPMenuColor sets the rendering colors of the specified PopMenu to
  380.       the specified colors. The frontpen is used as the menu border and
  381.       title text color, and the backpen is used for the filled areas within
  382.       the menu select box and expanded menu list.
  383.  
  384.    INPUTS
  385.       pmenu    -- pointer to the initialized PopMenu to affect
  386.       frontpen -- color of the PopMenu border and title text
  387.       backpen  -- color of the PopMenu filled areas
  388.  
  389.    RETURNS
  390.       None.
  391.  
  392.    BUGS
  393.       None.
  394.  
  395.    SEE ALSO
  396.       SetPMenuText()
  397.  
  398.  
  399. popmenu_pak/SetPMenuText                             popmenu_pak/SetPMenuText
  400.  
  401.    NAME
  402.       SetPMenuText - set the new constant text for a TITLED PopMenu
  403.  
  404.    SYNOPSIS
  405.       SetPMenuText(pmenu, text);
  406.  
  407.    PROTOTYPE
  408.       void SetPMenuText(struct PMenu *, UBYTE *);
  409.  
  410.    FUNCTION
  411.       SetPMenuText sets new constant text for a PopMenu with constant
  412.       titling (TITLED bit set).
  413.  
  414.    INPUTS
  415.       pmenu -- pointer to the initialized PMenu to affect
  416.       text  -- UBYTE pointer to the text to render into the menu select box
  417.  
  418.    RETURNS
  419.       None.
  420.  
  421.    BUGS
  422.       None.
  423.  
  424.    SEE ALSO
  425.       SetPMenuColor()
  426.  
  427.