Exercise 1: Creating a default configuration file for toolbars (pole inspection)
Creating a default configuration file that replaces existing toolbars with custom toolbars
This exercise describes the same steps outlined in Exercise 1: Creating a default configuration file for toolbars (tree inventory). This exercise demonstrates that configuration files are always the same, regardless of whether you use shapefiles or ArcPad Exchange Files (AXF) to store your data. If you have already completed Exercise 1: Creating a default configuration file for toolbars (tree inventory), you can skip this exercise and proceed to customizing forms for AXF files.
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 installation 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 pole to the Poles layer. Click the Add Custom button. The Tools Properties dialog box appears.
- Type tlAddPole in the Name text box.
- Type Add Pole in the Tooltip text box.
- Type Add a new pole to the Poles layer in the Prompt text box.
- You will now select the image for this new tool, but first you need to create a bitmap image. Navigate to C:\Documents and Settings\All Users\Documents\ArcPad\Samples\Layer Icons. On computers running Windows Vista or Windows 7, the sample data folder is installed under Public Documents.
- Open the Street_Light.ico file in an graphics software program (for example, Paint) that can save this image as a bitmap. See the following screen shot:
- Save Street_Light.ico as Street_Light.bmp inside your project folder, for example, C:\PoleInspection.
- Click Browse on the Tool Properties dialog box. Navigate to the project folder and open Street_Light.bmp. See the following screen shot:
- Click OK on the Tool Properties dialog box.
- On the Toolbar dialog box click the Move Up or Move Down buttons to move your user-defined custom command, click tlAddPole, 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 command 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 pole will be added, then add the pole's attribute information into your custom edit form. You decide that the script will be called when the tool fires an OnPointerUp event and will do the following:
- Make sure the Poles layer is in the current map.
- Make the Poles layer editable if it is not already editable.
- Get the coordinates of the map location clicked by the user.
- Add a new pole (point feature) to the Poles layer at the defined 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 ArcPad.vbs is created.
This tutorial included script samples in VBScript. If you prefer to use JScript or Python, or if you have previously used a different langauge and need to change back to VBScript, you can change the default script language used by ArcPad Studio by selecting your chosen language on the scripting tab of the Options dialog box listed under the Tools menu. Restart ArcPad Studio for default script language changes to take effect.
- Copy and paste the following sample into the script window. If you have formatting issues, paste the script into Notepad, then copy and paste it into the VBScript source code file.
Sub AddPole 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 Poles layer exists, 'set the blnLyrExists flag to true. Dim objLyr For Each objLyr in Map.Layers If StrComp (objLyr.Name, "Poles", 1) = 0 Then blnLyrExists = True Exit For End If Next 'If Poles layer does not exist, 'notify the user, return the tool button to its original state, and exit. If Not blnLyrExists Then MsgBox "The Poles layer is not present in the current map.", vbExclamation, "Layer not present" objToolButton.Click Exit Sub End If 'If the Poles layer does exist, 'get the coordinates of the map where the user clicked. dblX = Map.PointerX dblY = Map.PointerY 'Get a reference to the Poles layer object. Dim objLayer Set objLayer = Map.Layers("Poles") 'If the layer can be made editable, make it editable. If objLayer.CanEdit Then objLayer.Editable = True 'Add a new pole (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 tlAddPole 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 AddPole 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 AddPole script when the custom tool (tlAddPole) 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.