Method XbpToolBarButton():addItem() Foundation

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.
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" 

  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 ) 

// Process notifications sent when an 
// item is selected on a tool bar button's 
// drop-down menu 
PROCEDURE HandleItemClick( oMenu ) 
      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." ) 


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.