Method XbpToolBar():addItem()

Adds a tool bar item (button) to the XbpToolBar object.

:addItem( [<cCaption>], [<xImage>], [<xDisabledImage>], [<xHotImage>], 
          [<cDLL>], [<nStyle>], [<cKey>] ) => <oButton>

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

The parameter <xImage> specifies the image to be displayed by the tool bar item (button). The image may be specified by passing a numeric value with the resource id of a BITMAP resource. Also, an instance of the XbpBitmap or XbpIcon class may be used for other image file formats. Alternatively, a pre-defined system image may be specified. If an image is defined using parameter <xImage>, it is displayed alongside the caption string specified in parameter <cCaption>.

The parameter <xDisabledImage> specifies the image to be shown when the tool bar button is disabled. The image may be specified by passing a numeric value with the resource id of a BITMAP resource. Also, an instance of the XbpBitmap or XbpIcon class may be used for other image file formats. There are no pre-defined disabled versions of the system images that can be used with the <xDisabledImage> parameter. Parameter <xDisabledImage> is optional. If no disabled image is defined for a button, the system uses default imagery to draw the button if it is disabled.

A disabled image will not be displayed unless an image is assigned to parameter <xImage>. In addition, we recommend assigning custom images to all the buttons in a tool bar if the default imagery for disabled buttons should not be used. Display may be incorrect if custom images are assigned only to a subset of the tool bar buttons. Problems may result if custom disabled images are assigned to only a subset of the tool bar buttons defined.

<xHotImage> specifies the image to be displayed when the mouse pointer is positioned over the tool bar button. A button's hot image is only used if the XBPTOOLBAR_STYLE_FLAT style is used with the XbpToolBar object, see :style. Parameter <xHotImage> is optional. If no hot image is defined for a button, the system only draws a frame around the button when the mouse is positioned over it.

A hot image will not be displayed unless a standard image is assigned to parameter <xImage>. In addition, we recommend assigning custom hot images to all the buttons in a tool bar if the default imagery for hot buttons should not be used. Display may be incorrect if custom images are assigned only to a subset of the tool bar buttons.

<cDLL>

<cDLL> is an optional character string that can be used to specify the name of a Dynamic Link Library (DLL). This parameter is only used if resource identifiers are used with either the <xImage>, the <xDisabledImage> or <xHotImage> parameters. In this case, the XbpToolBar object attempts to load the image resource(s) from the DLL file passed in <cDLL> instead of the application's main module (.EXE). If no image is specified or if it is specified using an XbpBitmap or XbpIcon object, parameter <cDLL> is ignored.

Parameter <nStyle> is a numeric value that defines the style of the tool bar item to be added. This parameter is optional. If omitted, the default style for tool bar buttons is used.

<cKey>

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

The method :addItem() returns a reference to the XbpToolBarButton object added to the tool bar item array.

The method :addItem() is used to add a new tool bar button to the XbpToolBar object. A tool bar button is usually associated with one specific command or function that can be performed by the Xbase++ application.

Each tool bar button can optionally display its own caption string and image. Also, pre-defined tool bar button styles exist, which can be selected by specifying one of following constants in parameter <nStyle>:

Constant	Description
XBPTOOLBAR_BUTTON_DEFAULT *)	Default button style
XBPTOOLBAR_BUTTON_TOGGLE	Function represented by the button is a toggle of a certain kind. If it is depressed, the button remains depressed until it is pressed again.
XBPTOOLBAR_BUTTON_BUTTONGROUP	Button is part of a group of buttons which are mutually exclusive. Only one button can be selected in a button group. However, all of them can be unpressed.
XBPTOOLBAR_BUTTON_SEPARATOR	Button is a divider between other buttons. Separator buttons can be used to visually group tool bar buttons. Cannot display caption or image.
XBPTOOLBAR_BUTTON_PLACEHOLDER	Button serves as a place-holder, eg. for another Xbase Part. Buttons of this style can be used to reserve space for placing other objects in a tool bar object.
XBPTOOLBAR_BUTTON_DROPDOWN	Button displays a down-arrow next to its caption, which can be used to open a drop-down menu similar to an XbpCombobox.
Default button style

In addition to its caption string, a button added to an XbpToolBar object can also display an application-defined image. The image must be specified using parameter <xImage> when the button is added using :addItem(). The image may be defined in a BITMAP resource linked to the application, a Dynamic Link Library (DLL) or may be loaded from disk using an object of the XbpBitmap() or XbpIcon() class. Furthermore, alternate images can be specified using parameters <xDisabledImage> and/or <xHotImage>. These images are displayed when the button is disabled or when the mouse pointer is positioned over it, respectively. Note that the latter is only supported for XbpToolBar objects of the XBPTOOLBAR_STYLE_FLAT style. Note also that if images are specified for a tool bar button's hot or disabled states, they must be of the same size as the button's standard image. If no standard image is defined, both the disabled and the hot image will not be displayed.

Instances of the XbpToolBar class support loading pre-defined images representing standard operations such as opening or saving files or printing. To use one of the system images together with a toolbar button object, the image's identifier must be specified in parameter <xImage> when calling :addItem(). See method :loadImageSet() for further information on loading system images and using them with tool bar buttons.

After the XbpToolBar object is configured, the items defined in the internal array of tool bar buttons can be retrieved using method :getItem(). For easier access and better source code readability, a unique identifier may be assigned to each button added using method :addItem(). The key must be specified as a character string in parameter <cKey>.

// 
// Example for using :addItem() to add a button 
// to an XbpToolBar object 
// 
#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 new tool bar button and assign it 
    // a unique identifier 
    oTBar:addItem( ,,,,,, "TSTBUTTON" ) 

    // Use :getItem() to retrieve a reference 
    // to the button just added. Use this to 
    // change the caption text. 
    oButton := oTBar:getItem( "TSTBUTTON" ) 
    oButton:caption := "Button #1" 

    SetAppFocus( SetAppWindow() ) 

    SetPos( 5,0 ) 
    WAIT 
 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 XbpToolBar():addItem() Foundation