Home > Language Reference > Classes > Form

CmdBarAddButton Method

Inserts a new button to the command bar.

Syntax

Public Sub CmdBarAddButton(ByVal eBmpID As HbCmdBarButtons, ByRef objMenu As MenuItem, Optional ByRef sText As String = "", Optional ByVal iWhere As Integer = 255)

Remarks

The CmdBarAddButton method inserts a new button to the command bar. It should only be called when the command bar is about to be displayed, that is while handling a CmdBarOpen event.

The eBmpID parameter specifies the identifier of the bitmap used to draw the button. This can be either one of the predefined constants listed below, or the value returned by the ResID property of any Bitmap in your project.

For UI consistency, it is strongly advised to use one of those predefined bitmaps wherever possible, in the order listed above (for example, the hbCmdBarDelete bitmap, if used, should be the rightmost button). Note that due to Palm OS limitations, you cannot insert a dynamically created bitmap on the command bar ; bitmaps have to be created at design time in your project. Bitmaps for the buttons should be 16x13 pixels.

The objMenu parameter specifies the menu item whose event handler will be called if the user taps this button. This implies that you cannot insert a button whose action is not already provided by a menu item; this is consistent with the Palm OS UI guidelines.

The optional sText parameter specifies the text to be displayed on the left of the command bar when the user selects this button. If this parameter is omitted, the text of the corresponding menu item is used instead.

The optional iWhere paramater specifies where to insert the button. Buttons are numbered from 1 to 8, from right to left. If this parameter is 0, the button is inserted at the rightmost position. If it is 255 (or omitted), the button is inserted at the leftmost position. If it lies between 1 and 8 inclusive, it specifies the index where to insert the button.

The command bar can contain up to 8 buttons. However, it is advised not to add more than 4 buttons in order to make room for the predefined cut, copy and paste buttons and for the text which is displayed on the left when a button is selected.

System requirements