Method XbpToolBar():addItem() Foundation
Adds a tool bar item (button) to the XbpToolBar object.
:addItem( [<cCaption>], [<xImage>], [<xDisabledImage>], [<xHotImage>], [<cDLL>], [<nStyle>], [<cKey>] ) => <oButton>
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>:
|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.|
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.
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>.
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.