Custom tool buttons

To present a user-defined command to users, use a custom tool button. When a custom tool button is clicked, its associated script is executed. Custom tool buttons can be placed directly on a custom toolbar or in the drop-down menu of another tool button.

Tool buttons are represented by ToolItem objects in the ArcPad object model. A ToolItem object is also a collection of ToolItem objects (buttons in a drop-down menu). Tool buttons are represented by either TOOLBUTTON or MENUITEM elements in ArcPad XML. If a tool button is placed directly on a custom toolbar, it's represented by a TOOLBUTTON element. If it's placed on the drop-down menu of another tool button, it's represented by a MENUITEM element.

Attributes

The following tool button attributes are set at design time in ArcPad Studio in the Tool Properties dialog box. They cannot be changed at run time (some attributes have corresponding properties that can be accessed and changed at run time). Attributes beginning with the letters "on" are used to specify the script to run when an event occurs. These attributes are set on the Events page of the Tool Properties dialog box. Attributes are written to the customization file (.apa or arcpad.apx) in ArcPad XML format.

• name—Name of the tool button. Used to reference the tool button in scripts.
• caption—Text to the left of the tool button in the drop-down menu (for MENUITEM elements only).
• image—Bitmap displayed on the tool button.
• prompt—Status bar text for the tool button.
• promote—Specifies whether the menu item will be promoted to the top of the list when selected (for MENUITEM elements only).
• shortcut—Function key or action button shortcut for the tool button.
• tooltip— ToolTip that displays when the mouse pointer is over the tool (desktop only, for TOOLBUTTON elements only).
• onclick—Script that runs when an OnClick event occurs.
• onpointerdown—Script that runs when an OnPointerDown event occurs.
• onpointermove—Script that runs when an OnPointerMove event occurs.
• onpointerup—Script that runs when an OnPointerUp event occurs.

Events

Tool buttons generate two types of events: the OnClick event and OnPointer events (OnPointerDown, OnPointerMove, and OnPointerUp). You can specify a script to run whenever one of these types of events occurs. That is, for a given tool button, you can either handle the OnClick event or one or more of the OnPointer events. The following tool button events are available:

• OnClick—Occurs when the tool button is clicked.
• OnPointerDown—Occurs when the pointer is touched on the map view while the tool button is clicked.
• OnPointerMove—Occurs when the pointer is moving around while still touching the map view while the tool button is clicked.
• OnPointerUp—Occurs when the pointer is released from the map view while the tool button is clicked.

Properties

Tool button properties can be read and set at run time via scripts. The following tool button properties are available:

• Checked—Value that determines whether the tool button is displayed in an active state.
• Count—Number of tool item objects (tool buttons) on the tool button's drop-down menu.
• Enabled—Value that determines whether the tool button can respond to user-generated events.
• ID—Internal Windows identification of the tool button.
• Index—Index of the tool button.
• Name—Name of the tool button.
• Visible—Value that determines whether the tool button is visible.

Methods

Tool button methods can be called at run time via scripts. The following tool button methods are available:

• Click—Clicks the tool button as if it had been manually clicked.
• Item—Specified tool item object (tool button).

Reference a tool button

You can reference any tool button on a toolbar that is currently loaded, regardless of whether or not the toolbar or tool button is visible. You reference a tool button via its name or index. The two options for referencing a tool button are described in this section.

Direct reference

Direct reference involves referencing a tool button via its name or index and the Toolbar object that contains the tool button. For example, to reference a tool button with the name "tlbtnStatistics" that is the third tool button on a toolbar with the name "tlbTools", see the following sample code:

VBScript

Dim objToolBar
Set objToolbar = Application.ToolBars("tlbTools")
Dim objToolButton
Set objToolButton = objToolbar.Item("tlbtnStatistics")

JScript

var objToolbar = Application.ToolBars("tlbTools");
var objToolButton = objToolbar.Item("tlbtnStatistics");

Python

objToolbar = Application.ToolBars("tlbTools")
objToolButton = objToolbar.Item("tlbtnStatistics")

Or the following code:

VBScript

Dim objToolBar
Set objToolbar = Application.ToolBars("tlbTools")
Dim objToolButton
Set objToolButton = objToolbar.Item(1)

JScript

var objToolbar = Application.ToolBars("tlbTools");
var objToolButton = objToolbar.Item(1);

Python

objToolbar = Application.ToolBars("tlbTools")
objToolButton = objToolbar.Item(1)

Tool buttons that are present in a drop-down menu (menu items) are referenced the same way as tool buttons without drop-down menus; however, use the item's name, not the index, because the index of items in a drop-down menu changes as items are promoted to the top of the menu. For example, to reference a tool button with the name "tlbtnOption2" that is on a drop-down menu, see the following sample code:

VBScript

Dim objToolBar
Set objToolbar = Application.ToolBars("tlbTools")
Dim objToolButton
Set objToolButton = objToolbar.Item("tlbtnOption2")

JScript

var objToolbar = Application.ToolBars("tlbTools");
var objToolButton = objToolbar.Item("tlbtnOption2");

Python

objToolbar = Application.ToolBars("tlbTools")
objToolButton = objToolbar.Item("tlbtnOption2")

Event reference

Event reference involves referencing a tool button in an event handling script. For example, to reference a tool button in its OnClick event handler, see the following sample code:

VBScript

Dim objToolButton
Set objToolButton = ThisEvent.Object

JScript

var objToolButton = ThisEvent.Object;

Python

objToolButton = ThisEvent.Object

Click a tool button

To click a tool button, reference the tool button and call its Click method. For example, to click a tool button named "tlbtnStatistics" on a toolbar named "tlbTools", see the following sample code:

VBScript

Application.ToolBars("tlbTools").Item("tlbtnStatistics").Click

JScript

Application.ToolBars("tlbTools").Item("tlbtnStatistics").Click();

Python

Application.ToolBars("tlbTools").Item("tlbtnStatistics").Click()

Enable or disable a tool button

To enable or disable a tool button, reference the tool button and set its Enabled property to true or false, respectively. For example, to enable a tool button named "tlbtnStatistics" on a toolbar named "tlbTools", see the following sample code:

VBScript

Application.ToolBars("tlbTools").Item("tlbtnStatistics").Enabled = True

JScript

Application.ToolBars("tlbTools").Item("tlbtnStatistics").Enabled = true;

Python

Application.ToolBars("tlbTools").Item("tlbtnStatistics").Enabled = True

To disable the same tool button, see the following sample code:

VBScript

Application.ToolBars("tlbTools").Item("tlbtnStatistics").Enabled = False

JScript

Application.ToolBars("tlbTools").Item("tlbtnStatistics").Enabled = false;

Python

Application.ToolBars("tlbTools").Item("tlbtnStatistics").Enabled = False