Method XbpToolBarButton():addItem()

Adds an item to the menu of a drop-down tool bar button.

:addItem( [<cCaption>], [<cKey>] ) => <oMenu>

<cCaption> is a character string that specifies the caption to be displayed by the menu item after it is added to the tool bar button's menu. This parameter is optional.

<cKey>

Parameter <cKey> is an optional character string that specifies a key string to be assigned to the menu item to be added. If a key string is passed in parameter <cKey>, it can later be used to address the menu item, eg. for changing its caption string. Key strings must be unique within a tool bar button's drop-down menu. If a duplicate key string is passed in parameter <cKey>, a runtime error results.

The method :addItem() returns a reference to the XbpToolBarButtonMenuItem object added to the tool bar button's menu item array.

The method :addItem() is used to add a new menu item to a tool bar button's drop-down menu. tool bar buttons with a drop-down menu are defined by passing the XBPTOOLBAR_BUTTON_DROPDOWN style in the <nStyle> parameter to XbpToolBarButton:addItem(). Alternatively, the button's :style instance variable may be used to set this style.

The items added to a button's drop-down menu are displayed when the user selects the drop-down arrow next to the tool bar button's image. When a menu item is selected, a xbeTBAR_ButtonMenuClicknotification is sent to the XbpToolBar object that contains the tool button.

// 
// Example for using :addItem() to add menu items 
// to a tool bar button 
// 
#include "XBP.CH" 

PROCEDURE Main() 
  LOCAL oTBar 
  LOCAL oButton 

    // Create the XbpToolBar object 
    oTBar := XbpToolBar():new() 
    oTBar:create( ,, {0,SetAppWindow():ySize-40},; 
                     {SetAppWindow():xSize,40} ) 

    // Add a drop-down tool bar button to the 
    // tool bar object 
    oButton := oTBar:addItem( "Menu Button",,,,,XBPTOOLBAR_BUTTON_DROPDOWN ) 

    // Add items to the button's drop-down menu 
    oButton:addItem( "Item #1", "ITEM1" ) 
    oButton:addItem( "Item #2", "ITEM2" ) 
    oButton:addItem( "Item #3", "ITEM3" ) 

    // Assign a code block for processing 
    // "menu item selected" notifications 
    oTBar:ButtonMenuClick := {|oMenu| HandleItemClick(oMenu)} 

    SetAppFocus( SetAppWindow() ) 

    SetPos( 5,0 ) 
    WAIT 
RETURN 

// Process notifications sent when an 
// item is selected on a tool bar button's 
// drop-down menu 
PROCEDURE HandleItemClick( oMenu ) 
   DO CASE 
      CASE oMenu:Key == "ITEM1" 
         MsgBox( "Drop-down menu item #1 selected!" ) 
      CASE oMenu:Key == "ITEM2" 
         MsgBox( "You clicked on item #2." ) 
      CASE oMenu:Key == "ITEM3" 
         MsgBox( "This time, you picked item #3." ) 
   ENDCASE 
RETURN

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Method XbpToolBarButton():addItem() Foundation