Exercise 1: Creating a default configuration file for toolbars (tree inventory)
Creating a default configuration file that replaces existing toolbars with custom toolbars
In this exercise, you begin by creating a default configuration file. One of the functions of a default configuration file is to specify which toolbars are shown when ArcPad starts and which toolbars are hidden. For example, you may want to hide or expose one or more of the default toolbars, and include a combination of built-in and custom tools that run your scripts. This exercise introduces the basic techniques for creating custom toolbars, and adding built-in and custom tools.
Creating a default configuration project
- Start ArcPad Studio. The ArcPad Studio dialog box appears. See the following screen shot:
- Click the New default configuration project radio button, then click OK. A new
configuration file is created with the <ArcPad> root element
and the <CONFIG> child element in the ArcPad Studio configuration window.
If in a previous session of ArcPad Studio you selected the Do not show this dialog again check box on the previous ArcPad Studio dialog box, you can create a default configuration file by clicking the New Configuration button on the toolbar. The configuration file (like all customization files) displays in a tree view. ArcPad Extensible Markup Language (XML) elements and attributes show as branches in the tree. You can modify the customization files by working in the tree view. See the following screen shot:Tip:
- If you only see an <ArcPad> element, but no <CONFIG> element after this step, you need to install the Microsoft XML Parser. You must do this before you can continue with the tutorial. See the ArcPad Install guide (located on your local drive where ArcPad is installed, for example, \\Program Files\ArcGIS\ArcPad\Help) for more information on installing the Microsoft XML Parser.
- Click the Toggle between source and tree view button on the toolbar to switch between tree and source view.
- Double-click the <CONFIG> element in the tree view to set the configuration file's properties. The Configuration Properties dialog box appears. On the dialog box, retain the Scale Bar tab's check box settings. Click OK on the dialog box. See the following screen shot:
- The <STATUSBAR> element is added as a child element to the <CONFIG> element in the tree view. Review the attributes of the <STATUSBAR> element by clicking the plus sign node to expand the branch. Leave all of the <STATUSBAR> attributes with the default settings of true. See the following screen shot:
- Click the Save button on the toolbar to save the configuration file (continue to save your work periodically while editing). The Save As dialog box appears.
- Type ArcPad.apx in the File name text box. The configuration file must be called ArcPad.apx and be saved in the \My Documents\My ArcPad folder for ArcPad to automatically load this file at startup.
- Click the Save button.
Hiding default toolbars
- Click the Toolbars button on the toolbar. The Toolbars dialog box appears without a defined toolbar.
- Click Add. See the following screen shot:
Creating a custom toolbar
- After you click Add on the Toolbars dialog box, the Toolbar properties dialog box appears. The Commands column on the right is empty. You will add built-in and custom tools to this column.
- Type tlbCustomToolBar1 in the Name text box.
- Type Tools in the Caption text box.
- Leave the Image text box empty (this toolbar will not have an image).
- Leave the Visible check box selected (you want this toolbar to show when ArcPad starts). See the following screen shot:
Adding built-in tools to the toolbar
While still on the Toolbar dialog box, select the following under the Command column on the left:
- Select openmap. Click Add.
- Select modezoomin. Click Add.
- Select modezoomout. Click Add.
- Select modepan. Click Add.
- Select modeidentify. Click Add.
- Select exit. Click Add. Leave the Toolbar dialog box open to add a custom tool. See the following screen shot:
Adding custom tools to the toolbar
- In addition to the built-in tools, you want to add a custom tool that calls a script to automate the process of adding a new tree to the Trees layer. Click the Add Custom button. The Tools Properties dialog box appears.
- Type tlAddTree in the Name text box.
- Type Add Tree in the Tooltip text box.
- Type Add a new tree to the Trees layer in the Prompt text box.
- You will now select the image for this new tool. Click the Browse button to navigate to the Tutorial folder under the ArcPad\Developer\Samples\Tutorial folder and select the tree.bmp file.
- Click Open. The image name appears in the Image text box.
- Click OK on the Tool Properties dialog box. See the following screen shot:
- On the Toolbar dialog box, click the Move Up or Move Down buttons to move your user-defined custom command, tlAddTree, so that it is at the end of the group of built-in commands (or to wherever you choose to place it). To move a command, select it until it is highlighted, then click Move Up or Move Down. If your control is already at the end of the Command List, move the custom tool up and down to test this feature (you can place the tool in any location on the toolbar). See the following screen shot:
- Click OK on the Toolbar dialog box to keep the selected commands.
- Click OK on the Toolbars dialog box.
- Click the Save button on the toolbar to save the configuration file.
Writing a script for the custom tool
Determine how you want this custom tool to work. You want the user to click the tool, click the map location where the new tree will be added, then add the tree's attribute information into your custom edit form. To accomplish this, you need to attach a script to the custom tool you just created.
You decide that the script will be called when the tool fires an OnPointerUp event and will do the following:
- Make sure the Trees layer is in the current map.
- Make the Trees layer editable if it is not already editable.
- Get the coordinates of the map location clicked by the user.
- Add a new tree (point feature) to the Trees layer at those coordinates, which automatically displays the custom data entry form that you create in the next exercise.
- Return the custom tool to its original state (not selected state).
- Click the Edit Script button on the toolbar. A new VBScript source code file named Config1.vbs is created. If you want to save this as a JScript source code file, click the File menu and click Save As. Change the file extension to .js before saving the source code. See the following screen shot:
- Copy and paste the following script below the Option Explicit text in the script editor. If you have formatting issues, paste the script into Notepad, then copy and paste it into the VBScript source code file.
Sub AddTree Dim dblX, dblY, objToolButton, blnLyrExists 'Get a reference to the tool button object. Set objToolButton = ThisEvent.Object 'Initialize blnLyrExists flag to False. blnLyrExists = False 'If Trees layer exists, 'set the blnLyrExists flag to true. Dim objLyr For Each objLyr in Map.Layers If StrComp (objLyr.Name, "Trees", 1) = 0 Then blnLyrExists = True Exit For End If Next 'If Trees layer does not exist, 'notify the user, return the tool button to its original state, and exit. If Not blnLyrExists Then MsgBox "The Trees layer is not present in the current map.", vbExclamation, "Layer not present" objToolButton.Click Exit Sub End If 'If the Trees layer does exist, 'get the coordinates of the map where the user clicked. dblX = Map.PointerX dblY = Map.PointerY 'Get a reference to the Trees layer object. Dim objLayer Set objLayer = Map.Layers("Trees") 'If the layer can be made editable, make it editable. If objLayer.CanEdit Then objLayer.Editable = True 'Add a new tree (point feature) at the clicked location. Call Map.AddFeatureXY(dblX,dblY) 'Return the tool button to its original state. objToolButton.Click End If End Sub
- After you paste the script, click the Verify syntax button on the toolbar to perform a syntax check. If the compilation succeeds, you'll hear an audible beep. If you receive an error, review your script. Click Save to save your script. If the compilation fails, compare the script you added to the script shown in the preceding code example and correct any errors, then click Save again. To view both windows, click Tile under the Window menu. See the following screen shot:
You will notice that the <SCRIPT> element gets saved in the ArcPad.apx file. You can return to edit the source file by double-clicking the <SCRIPT> tag (however, you don't need to do this at this time). See the following screen shot:
Attaching the script to the custom tool
- Activate the ArcPad.apx window by clicking its title bar.
- Click the Toolbars button on the toolbar. The Toolbars dialog box appears.
- Click the tlbCustomToolBar1 toolbar that you created earlier and click Edit. The Toolbar dialog box appears.
- Click the tlAddTree tool that you created earlier and click Edit. The Tool Properties dialog box appears.
- Click the Events tab on the Tool Properties dialog box. This displays a list of events that a custom tool or ToolItem object can respond to.
- Click onpointerup under the Events column and type Call AddTree in the Event Script text box. See the following screen shot:
- Click OK on the Tool Properties dialog box. You have just configured the custom tool to run the AddTree script when the custom tool (tlAddTree) fires an OnPointerUp event.
- Click OK on the Toolbar and Toolbars dialog boxes.
Saving the configuration file
- Click the Save button on the toolbar.
- Click File and click Close to close the default configuration and VBScript source code files.
A default ArcPad.apx file is created inside My Documents\My ArcPad when ArcPad starts for the first time. To show the default toolbars and your custom toolbar in ArcPad, you may want to start this tutorial by opening a default ArcPad.apx file in ArcPad Studio. By doing so, you do not need to create default toolbars from the beginning.
After the tutorial, you may want to remove or rename the default ArcPad.apx configuration file as it is for this tutorial only.