Click above to get retro games delivered to your door ever month!

MENU_ITEM()                                                         C_EXAM04
   Adds a text button to a menu.

   Syntax
         nButtonNum = MENU_ITEM(nMenuNum,nRow,nCol,nKeyCode,nKeyType,cLabel,
                                nUpdate,nNonSelect)

   Arguments
         nMenuNum    Sets the number of the menu to place the button on.
         nRow        Sets the row for the button.
         nCol        Sets the column for the button.
         nKeyCode    Sets the keyboard code that will select the button.
         nKeyType    Sets the keyboard code type specified above.
                     0 = ASCII character value is specified.
                     1 = IBM keyboard scan code is specified.
         cLabel      Sets the button text.
         nUpdate     Sets whether highlighting will change.
                     0 = Selecting button will not change currently
                         highlighted button.
                     1 = Selecting button will lowlight previously selected
                         button and highlight new button.
         nNonSelect  Sets whether the button is available for selection or
                     not.
                     0 = Button is available for selection.
                    -1 = Button cannot be selected.
                    -2 = Button is displayed only as a text description.

   Returns
         nButtonNum  Returns the number of the new button in the menu.

   Description
         MENU_ITEM() adds a button to a menu set with nMenuNum.

         nRow and nCol set the position of cLabel. The area defined will be a
         rectangular section surrounding the label. A button can be selected
         during a call to KEY_PRESS() or MENU_ONLY() by clicking the mouse
         within the area or, alternately, by hitting the key defined by
         nKeyCode and nKeyType. The button number will be returned directly
         from MENU_ONLY() or from KP_ITEM_NO() if the menu was displayed with
         MENU_WAKE().

         nKeyCode and nKeyType set the keyboard codes that will select a menu
         button.

         nKeyType sets the type of code that will select the menu item.
         Type 0 tells the menu system to look for an ASCII character value
         when a key is pressed, while type 1 looks for an IBM keyboard
         scan code. Each key on the keyboard has a unique number called a
         scan code. There are approximately 221 uniquely identifiable codes on
         the standard IBM keyboard. We use the scan codes because the function
         keys do not have an ASCII code. For example, F1 has a scan code of
         59, while the home key is 71.

         The actual code the menu system looks for when the keyboard key is
         pressed is set with nKeyCode. This code will be an ASCII value if
         the type is 0, or a scan code value if the type is 1.

         nUpdate sets whether the button text will highlight when the mouse
         cursor passes over the text. When the mouse passes over a menu
         item, if nUpdate is 0 the menu system will not change the currently
         highlighted button. If nUpdate is 1, the menu system will lowlight
         the previously selected button and highlight the new button.

         nNonSelect sets whether the button is available for selection or
         not. A 0 will make the button available for selection, while a -1
         will turn the button to the non select color and make it
         non-selectable. A -2 will allow the label to be printed on the
         menu, but it will not be selectable. The -2 flag allows you to
         place descriptive information on a menu that will not be selected
         by the mouse.