ToolBar.AppendItem Method (Typed)

Add a new toolbar button item to the end of the toolbar from the list of buttons available.

Namespace: XSharp.VO.SDK
Assembly: XSharp.VOGUIClasses (in XSharp.VOGUIClasses.dll) Version: 2.19

Syntax

 VIRTUAL METHOD AppendItem(
	nButtonID,
	nMenuItemID,
	oBmp,
	nPosition,
	cTitle,
	nImgCount,
	bState,
	bStyle,
	symTB
) AS USUAL CLIPPER

[ClipperCallingConventionAttribute(new string[] { ... })]
public virtual Usual AppendItem(
	Usual nButtonID = default,
	Usual nMenuItemID = default,
	Usual oBmp = default,
	Usual nPosition = default,
	Usual cTitle = default,
	Usual nImgCount = default,
	Usual bState = default,
	Usual bStyle = default,
	Usual symTB = default
)

Request Example View Source

Parameters

nButtonID (Optional): Type: Usual
The ID of the new toolbar button item. To add a gap between groups of buttons, append an item labeled IDT_SEPARATOR. To see the standard button items available, bring up the list in the Menu Editor. For custom toolbar buttons, append an item labeled IDT_CUSTOMBITMAP. (For example, for the first button, the <nButtonID> is IDT_CUSTOMBITMAP + 1; the second is IDT_CUSTOMBITMAP + 2, and so on.)
nMenuItemID (Optional): Type: Usual
The ID of the menu item corresponding to the new toolbar button item.
oBmp (Optional): Type: Usual
A bitmap object that contains one or more custom bitmaps. Each button in the bitmap must be a 16-color, 20 x 16 pixel bitmap. The first button in the bitmap must be drawn in pixel positions 1 and 20, the second in positions 21 and 40, the third in positions 41 and 60, and so on. (Effectively, this is a ribbon of buttons.) It is possible to have the custom buttons in individual bitmap resource files, and create a Bitmap object for each button. <nPosition> is set to 1 if you use this method. It is recommended to use a ribbon of buttons in one bitmap file, as this only uses one handle. The latter method will use a handle for each object created.
nPosition (Optional): Type: Usual
The position of a custom toolbar button in the bitmap. If a ribbon of buttons is used for <oBitmap>, then the first button is 1, the second is 2, and so on. If an individual bitmap is used or if not specified, <nPosition> is 1. The following figure illustrates a ribbon of buttons contained in one bitmap, showing the pixel positions and the <nPosition> for each:
cTitle (Optional): Type: Usual
The title of the toolbar button that is used if the button is displayed on the toolbar, in either of the TB_TEXTANDICON or TB_TEXTONLY styles. If not specified, the default is NULL_STRING.
nImgCount (Optional): Type: Usual
The number of buttons in the image passed in <oBmp>. The default is 1.
bState (Optional): Type: Usual
The initial state of the button—enabled or disabled. If enabled, the button can be selected by the user. If disabled, the button appears dimmed (grayed) and cannot be selected; it remains unavailable until it is enabled by the application. The default is enabled (TBSTATE_ENABLED).
bStyle (Optional): Type: Usual
An optional style flag for the toolbar item. By default the style is automatically derived from the other parameters. Passing a Windows API constant can, however, enforce a specific style. The default is TBSTYLE_BUTTON.
symTB (Optional): Type: Usual
Symbolic name representing the toolbar to be used. Defaults to the main toolbar.

Return Value

Type: Usual
TRUE if successful; otherwise, FALSE.

Remarks

Tip
Consult your Microsoft Win32 Software Development Kit documentation for detailed information about a particular Windows API constant.

Both the event triggered, when the button is clicked, and the description that shows up in the status bar are based on the properties of the associated menu. Thus, the toolbar controls the action of the application indirectly, through its associated menu. Specifying a toolbar by calling this method for each standard toolbar button might seem cumbersome. The recommended way to define the toolbar is to use the Menu Editor, which automatically generates code to lay out the toolbar. Note that the user can modify the set of button items on the toolbar with the configuration dialog. The program does not need to concern itself with what buttons exist, since the events come in as if they were menu selections. In order to reduce "visual noise" (undesirable blinking and flicker), the toolbar does not immediately reflect a button added with ToolBar:AppendItem(). Instead, you must call ToolBar:Update() to make all the new buttons show up at once. The ToolBar:Show() method automatically updates the display. For toolbars that are defined once and for all and attached to a window, there is no need for explicitly calling ToolBar:Update(), it is intended only for toolbars that change their button configuration on the fly.

Examples

The following example adds two custom bitmaps to the toolbar:

Copy

 1DEFINE BUTTON_ONE := 1
 2DEFINE BUTTON_TWO := 2
 3DEFINE FIRST_BUTTON := IDT_CUSTOMBITMAP + BUTTON_ONE
 4DEFINE SECOND_BUTTON := IDT_CUSTOMBITMAP + BUTTON_TWO
 5DEFINE MENUOPTIONONE := 3000
 6DEFINE MENUOPTIONTWO := 3001
 7LOCAL oBitmap AS Bitmap
 8// IDB_BUTTONS is the resource definition of the
 9// bitmap for 2 buttons
10oBitmap := Bitmap{IDT_BUTTONS}
11// The first AppendItem() method takes the first
12// button bitmap in the bitmap object, while the
13// the second one takes the second bitmap.
14SELF:ToolBar:AppendItem(FIRST_BUTTON,MENUOPTIONONE,;
15oBitmap,1,"Button One")
16SELF:ToolBar:AppendItem(SECOND_BUTTON,;
17MENUOPTIONTWO,oBitmap,2,"Button Two")

Reference

ToolBar Class

XSharp.VO.SDK Namespace