of_addItems

Description

Adds a list of items (buttons or separators) to the toolbar in a single call. Items are passed as arrays.

Syntax

of_addItems(String name[], {String image[]}, {String toolTip[]}, {Integer position[]})

Parameter(s)

Name Type Description
name String Array The names of the items (buttons) to be added. The name is also the text displayed for a toolbar item when display text is enabled
image String Array The name of the image file to be displayed for the item. This parameter is optional and has no default value. The valid fileTypes are GIF, PNG, JPG, BMP, WMF and RLE
toolTip String Array The text to be used when displaying the item's toolTip. This parameter is optional and defaults to the item's name
position Integer Array Indicates which "side" of the toolbar to which the item is to be anchored. Values allowed for this parameter are LEFT (1) and RIGHT (2). This parameter is optional and the default value is LEFT

Return Value

Returns a long containing the total number of items that are part of the toolbar after the call is complete.

Usage

While the name parameter is NOT optional, it can contain empty values. When a name is empty, the program assigns the name using "ToolBarItem" + String(item), i.e. if the item is the 3rd item added the name will be "ToolBarItem_3".

The arrays must have the same number of elements. The controlling array is the name argument and the other arrays, if provided, must have the same number of elements.

If you want to include a separator as part of the list of items to add, you can use the ucsttoolbar.SEPARATOR constant in the name array at the position(s) you want the separator to occur.

"Update" is automatically disabled at the beginning of of_addItems and reset to its previous state at the end of the routine. The redraw of the toolbar is controlled by of_addItems based on this previous state. That way if the programmer has disabled update before the call, it will remain disabled and the programmer can still decide when to redraw the toolbar. Otherwise, if update is enabled before the call, it is disabled, the individual of_addItem calls are made and then the redraw happens just once.

Another consideration when using this method is that when using the RIGHT position, items are added from right-to-left, like a pop stack. When items are added using the LEFT position, they are added left-to-right.

Examples

uo_toolbar.of_addItems({ 'Open',                           'Save',                     &
                         uo_toolBar.SEPARATOR,             'Exit' },                   &
                       { 'Open.bmp',                       'Save.bmp',                 &
                         '',                               'powerOff.bmp' },           &
                       { uo_toolbar.LEFT,                   uo_toolBar.LEFT,           &
                         uo_toolBar.LEFT,                   uo_toolbar.RIGHT })

uo_toolbar.of_addItem('',         'Print.bmp')
uo_toolbar.of_addItem('Preview',  'Preview.bmp')

uo_toolbar.of_addSeparator()

uo_toolbar.of_addItem('Copy',       'Copy.png')
uo_toolbar.of_addItem('Cut',        'Cut.png')
uo_toolbar.of_addItem('Paste',      'Paste.bmp')
uo_toolbar.of_addItem('Clear',      'Clear!')

uo_toolbar.of_addSeparator(uo_toolbar.RIGHT)

uo_toolbar.of_addItem('Text Only',  '',        uo_toolbar.RIGHT)

uo_toolbar.of_addSeparator(uo_toolbar.RIGHT)

uo_toolbar.of_addItem('Text 4',     '',        'Text 4 ToolTip',     uo_toolbar.RIGHT)
uo_toolbar.of_addItem('Text 3',                uo_toolbar.RIGHT)
uo_toolbar.of_addItem('Text 2',     '',        uo_toolbar.RIGHT)
uo_toolbar.of_addItem('Text 1',     '',        uo_toolbar.RIGHT)


Doc_9.jpg

See Also

Last edited Sep 24, 2016 at 1:56 PM by cjharris02892, version 17