4/6/2010

Customizing the ArcGIS user interface Customizing the ArcGIS user interface
An application or project may require unique workflows or map creation. The You can change the UI a little or a lot.
ArcGIS UI can be customized to support special tasks or products.
You can change or create toolbars, menus, and shortcut keys without
ArcGIS Desktop contains most of the functionality that you need but it has programming.
been designed to be general purpose. If a user or task does not require a
wide range of functions it can be customized to support just a few required
You can creating custom menus, buttons, and tools that you can
tasks.
program to perform custom tasks.

Customizations can include changing the location of toolbars, menus, tools,

commands and windows, or creating new toolbars, tools, buttons, menus,
etc., using VBA macros.

UI elements UI elements
Menus arrange other commands into a list. A context menu is a floating menu that
Standard ArcMap Menus and toolbar pops up at the location of the pointer when you right‐click.

Buttons and menu commands run programming code when you click them.

Tools require interaction with the display before an action is performed—that is,
before their programming code is run. The Zoom In tool is a good example—you click
or drag a rectangle over a map before seeing its contents in more detail.

Toolbars
lb can containi diff
different types off commands—menus,
d b
buttons, tools,
l Combo boxes allow you to choose an option from a drop‐down list
list.
combo boxes, or edit boxes.
Text boxes or edit boxes allow you to type in text.
Each command has code associated with it, either core to the application or
something you create.

1
 4/6/2010

Using the Customize dialog box Using the Customize dialog box
A graphic interface for customization.
The way to tailor an application is to use the Customize dialog box to
change menus and toolbars.
Modify user interface
Click Customize on the Tools menu or right‐click any open toolbar and choose – Turn toolbars on and off
Customize from the menu.
– Create new toolbars
– Create new controls
When you open the Customize dialog box, you can modify existing menus, – Add,, delete,, and move
toolbars,
lb and
d context menus with
h simple
l drag‐and‐drop
d dd techniques.
h You can controls (buttons and
also create your own menus, toolbars, and context menus. menus)
– Manage shortcut keys

Creating a new tool bar Creating a Menu

• Organize related controls • New Menu and Menu Items
• Name the toolbar
• Drag commands, controls, or
macros onto (off) the toolbar

2
 4/6/2010

Adding commands to context menus Saving Customizations

Click the Tools menu and click Customize. When you make customization changes to the UI, they are saved in one of the
Click the Toolbars tab. following three places:
Check the Context Menus toolbar.
Click Context Menus on the Context Menus toolbar.
The current map document: There is always a map document open in ArcMap.

A base template: A kind of map document that provides a quick way to create a
new map document. Templates may contain any of the following: data, a custom
interface,, and a predefined
p layout
y that arranges
g map p elements,, such as north
arrows, scale bars, and logos, on the virtual page. ArcMap templates have a .mxt file
extension. There may not always be a base template loaded in ArcMap.

The Normal template: A special template that is automatically loaded in ArcMap.

This template stores any personal settings you have made to the user interface that
you want loaded every time you use ArcMap

Drag commands onto the context menu

Saving Customizations Documents and Templates

All customization in ArcMap is stored in a map document or a map template.
The Normal template
Whenever you are using ArcMap you are working with a
When you first start ArcMap, a Normal template is automatically created and put in
document referred to as a map.
your profiles location:
C:\Documents and Settings\<your user name>\Application The map document stores the map state, the state of the
Data\ESRI\ArcMap\Templates\ user interface, custom user interface settings, a Visual
Basic for Applications project, and other application‐
This is the default, out‐of‐the‐box Normal template that contains all the standard specific information, such as cartographic layouts.
toolbars and commands and places the toolbars and the table of contents in their
default positions. Any customizations that you save in your Normal template get saved
to this file. Map documents are based on templates. They can be
based on a project template or directly on the normal
template

Since any modifications made to the Normal template will be reflected every time A template provides specifications for a map document
you create or open a document, you should be careful when making changes to
Project templates can be created anywhere on your file
Normal.
system. Changes made to the project templates
propagate to all documents based on that template.

3
 4/6/2010

Saving your customizations in a template

UI Controls
Create a new map document. You can create a new button, tool, combo box, or edit box (collectively called
UIControls), then attach code to the control's events, such as what happens
Make all the changes to the user interface you want. when you click a button. After you have created it, you can drag this new
When you make any of your changes to the user interface, make sure that the document control onto a toolbar
name is selected in the drop‐down Save in combo box

Click the File menu and click Save As. • User Interface (UI) Controls
– UIButtons, UItools,
Click the Save as type drop‐down arrow and click ArcMap Templates (*.mxt). UIEditBoxs, and
UIComboBoxes
Navigate to the folder where you want the template saved. The template can be saved in • Control Properties
any folder on your network.
– Text or no text
Type a new name for the new template. You can't use Normal.mxt as a template name; – Image
that name is reserved for the Normal template. – Caption
– Group
Click Save

Creating custom commands with VBA Creating custom commands with VBA.
Click Create to create the control without attaching code to it. The name of the control
Visual Basic Applications is embedded in the applications and provides an
appears in the Commands list. You can add code for the control at another time. If you
integrated programming environment, the Visual Basic Editor (VBE). You can write
want to start adding code to the control right away, click Create and Edit.
Visual Basic (VB) macros, then debug and test them in the application e.g. ArcMap.

In ArcMap, each currently loaded document and template has an associated VBA The Save in: combo box
project in the VBE, allowing you to write macros that are specific to a given map lists the names of the
document or to apply macros to all the documents consuming a specific currently loaded
template. document and
templates In ArcMap
templates. ArcMap,
use this setting to
The VBA project for the document is called Project followed by the name of the
specify whether the
document in brackets. For example, in ArcMap it is named Project (<name of
changes you are about
document>.mxd), and the VBA project for the Normal template is called Normal
to make will be saved in
(Normal.mxt).
the document, the
Normal template, or
another template. The
default setting is the
Normal template.

4
 4/6/2010

Restoring Original Setting Visual Basic Editor

If you change the interface and want to return to the original settings: You can open the VBE in any of the above-listed applications by clicking Tools
on the Main menu, pointing to Macros, then clicking Visual Basic Editor.
Simply delete the Normal template file. Upon startup, ArcMap and ArcCatalog will
regenerate the Normal templates if they are missing.

The ArcCatalog Normal template, Normal.gxt, is located in user settings. For example, in
Windows 2000 or XP, it can be found in C:\Documents and Settings\User\Application
Data\ESRI\ArcCatalog.

The ArcMap Normal template, Normal.mxt, is also located in user settings. For example, in
Windows 2000 or XP, it can be found in C:\Documents and Settings\User\Application
Data\ESRI\ArcMap\Templates.

Visual Basic Editor

Visual Basic Editor
ArcMap has a default project associated with its map document that's listed
in the Project Explorer as Project followed by its filename. In addition, you'll
• Tools> Macros> Visual Basic Editor see another project associated with the Normal template (Normal.mxt).
• View Source
All ArcGIS application documents contain the
class module ThisDocument, a custom object
that represents the specific document
associated with a VBA project.
project

The document object is called MxDocument in

ArcMap and GxDocument in ArcCatalog. The
IDocument interface provides access to the
document's title, type, accelerator table,
command bars collection, parent application,
and Visual Basic project.

5
 4/6/2010

The Visual Basic Development Environment Adding modules and class modules

In the VBA development environment you can add modules, class modules, and
user forms to the default project contained in every ArcGIS application document. Once you've invoked the Visual Basic Editor, you can insert a module, class
module, or user form.

A project can consist of as many modules, class modules, and user forms as your
Then you insert a procedure or enter code for an existing event procedure in
work requires.
the item's Code window, where you can write, display, and edit code.

A project is a collection of items to which

hich you
o add code.
code A mod
module le is a set of
You can open as many Code windows as you have modules, class modules, and
declarations followed by procedures—a list of instructions that your code performs.
user forms, so you can easily view the code and copy and paste between Code
windows. In addition to creating your own modules, you can import other
A class module is a special type of module that contains the definition of a class, modules, class modules, or user forms from disk.
including its property and method definitions.

A user form is a container for user interface controls, such as command buttons and
text boxes.

Creating macros Adding modules and class modules

When you create a macro, you're creating a VB Sub procedure.
Modules and class modules can contain more than one type of procedure: sub,
function, or property. You can choose the procedure type and its scope when you
The procedure's name is the name you assign to the macro.
insert a procedure. Inserting a procedure is like creating a code template into
which you enter code.
You add code to the procedure in a Code window just as you would in VB.
Every procedure has either private or public scope. Procedures with private
When you create a new macro on the Macros dialog box, precede the macro's name scope are limited to the module that contains them—only a procedure within
g
with the name of the module in which to store it. You can organize yyour macros in the same module can call a private procedure. If you declare the procedure
different modules; each module has its own Code window. public, other programs and modules can call it.

To add your macro to a specific module, type the module name before the macro's Variables in your procedures may either be local or global. Global variables exist
name, for example, "Department.WorkMacro". If the module doesn't exist, a new during the entire time the code executes.
module with that name is created for you and added to the VBA project. Similarly,
if you provide a name for a new macro but don't specify which module to store it Local variables exist only while the procedure in which they are declared is running.
in, a new module, NewMacros, is created. The next time you execute a procedure, all local variables are reinitialized. You can
preserve the value of all local variables in a procedure for the code's lifetime by
declaring them static – fixes their value.

6
 4/6/2010

Adding a procedure to an existing module

Creating macros
In the Project Explorer, double‐click the ArcMap Objects or Modules folder, then
choose the name of a module. Ensure that the code view of the module is active by
When the macro is created: clicking the View Code button.

The stub for a Sub procedure for the macro appears in the Code window. Click the Insert menu and click Procedure.

Type the code for the macro between the first line (Sub name()) and last line (End Type the name of the procedure in the Name text
Sub). box.

Click the VBE File menu and click Save Project

Project. Click the Type dropdown arrow and click the type
of procedure: Sub, Function, or Property.
Click the Scope dropdown arrow and click Public or
Private.

To declare all local variables static, check the All

Local variables as Statics check box.
Click OK. VBA stubs in a procedure into the item's
Code window into which you can enter code. The
stub contains the first and last lines of code for the
type of procedure you've added.
Enter code into the procedure.

Variable declaration Procedure to Add a text file to the map

Public Sub AddTextFile()

Declare variables before use to prevent mistakes. ' Get the ITable from the geodatabase
Dim pFact As IWorkspaceFactory
Use Public and Private to declare variables at module scope and Dim in local scope. Dim pWorkspace As IWorkspace
(Dim and Private mean the same at Module scope; however, using Private is more Dim pFeatws As IFeatureWorkspace
informative.) Dim pTable As ITable

Always provide an explicit type for variables,

variables arguments
arguments, and functions
functions. Otherwise
Otherwise, Set pFact = New TextFileWorkspaceFactory
they default to Variant, which is less efficient. Set pWorkspace = pFact.OpenFromFile("d:\tables81\testing", 0)
Set pFeatws = pWorkspace
Only declare one variable per line unless the type is specified for each variable. Set pTable = pFeatws.OpenTable("farms.txt")

' Add the table

Add_Table_TOC pTable

7
 4/6/2010

Running a macro from a Visual Basic module

Object library
In the Visual Basic Editor, open the Code window where the macro's code is
saved. ArcGIS is component object model (COM)‐based, and the system is built and
extended using the ArcObject software components.
In the Code window, click inside the Sub procedure of the macro you want to
run. ArcObjects are an integrated collection of cross‐platform GIS software
components that are client/server ready. ArcGIS relies on ArcObjects to provide
Click the Run menu and click Run Sub/UserForm. data management, map presentation functionality, and more.

Running a macro in the Macros dialog box There is an extensive ArcObjects object library available to help you customize
Click the Tools menu, point to Macros, then click Macros. applications in ArcGIS Desktop. The ESRI Developer Network (EDN) describes the
classes, interfaces, properties, methods, and enumerations that are available
Click the Macros in drop‐down arrow and click the document or template containing
the macro you want to run.
If you are using VBA inside ArcMap or ArcCatalog, most of the common ESRI object
Type the name of the macro you want to run or click its name in the list. libraries are already referenced for you.

Click Run.

Working with Objects For interface references, declare an interface variable and use the Set statement
Your code manipulates objects by getting and setting properties on their to assign the interface reference to the property.
interfaces, such as setting the MaximumScale and MinimumScale of a map's
FeatureLayer; invoking methods on the interfaces, such as adding a vertex to a For other values, declare a variable with an explicit data type or use Visual
polyline; or setting a field's value. The code runs when an event occurs. Basic’s Variant data type. Then, use a simple assignment statement to assign the
value to the variable.

Properties that are interfaces can be set either by reference or by value.

Properties
that are set by value do not require the Set statement.

Dim pEnv As IEnvelope

Set pEnv = pActiveView.Extent 'Get extent property of view.
pEnv.Expand 0.5, 0.5, True 'Shrink envelope.
pActiveView.Extent = pEnv 'Set By Value extent back on
IActiveView.
Dim pFeatureLayer as IfeatureLayer
Set pFeatureLayer = New FeatureLayer 'Create New Layer.
Set pFeatureLayer.FeatureClass = pClass 'Set ByRef a class into
layer.

8
 4/6/2010

Private Function UIButtonControl1_Checked() As Boolean

Using the Global Application objects UIButtonControl1_Checked = False
End Function
Application and ThisDocument are examples of global system variables that can be
accessed by any module or class in the VBA environment while ArcMap is running. Private Sub UIButtonControl1_Click()
This variable is automatically set to reference the current document when ArcMap Dim pMxDoc As IMxDocument
opens the document. Dim SelCount As Long
Set pMxDoc = Application.Document
You can use ThisDocument as a shortcut when programming in VBA to access the SelCount = pMxDoc.FocusMap.SelectionCount
current document. Here is an example of how to use both the Application and MsgBox SelCount
ThisDocument: End Sub

Dim pMxDoc as IMxDocument Private Function UIButtonControl1_Enabled() As Boolean

Set pMxDoc =Application.Document 'or Dim pMxDoc As IMxDocument
Set pMxDoc =ThisDocument
Dim LayerCount As Long
Set pMxDoc = Application.Document
LayerCount = pMxDoc.FocusMap.LayerCount
If LayerCount > 0 Then
UIButtonControl1_Enabled = True
Else
UIButtonControl1_Enabled = False
End If
End Function

Running VBA code

Private Function UIButtonControl1_Message() As String As you build and refine your code, you can run it within VBA to test and debug it.
UIButtonControl1_Message = "Return selection count for all For more information about running and debugging a VBA program, such as adding
layers" breakpoints, adding watch expressions, and stepping into and out of execution, see
End Function Microsoft Visual Basic online help.

To run your code in the Visual Basic Editor or from the Macros dialog box
Private Function UIButtonControl1_ToolTip() As String Click the Tools menu and click Macros.
UIButtonControl1_ToolTip = "Selection Count" In the Macro list, click the macro you want and click Run.
End Function If the macro you want is not listed, make sure you've chosen the appropriate item:
either Normal, Project, or TemplateProject in the Macros In box. Private procedures
do not appear in any menus or dialog boxes.

To run only one procedure in the Visual Basic Editor

In the Project Explorer, open the module that contains the procedure that you want
to run.

In the Code window, click an insertion point in the procedure code.

Click the Run menu and click Run Sub/UserForm.

9
 4/6/2010

Saving a VBA project Adding user forms

To save your ArcMap document and your VBA project, click Save from the ArcMap A user form is a container for user‐interface controls, such as command
File menu or Save <File Name> from the File menu in the Visual Basic Editor. buttons and text boxes.
Use VBA's user forms if you want your code to prompt the user for information,
Both commands save your file with the project and any items stored in it. After or you want to display the result of some action performed when the user
saving the file, its filename is displayed in the Project Explorer in parentheses after invokes an application command or tool, or in response to some other event.
the project name. To save the document as a template, click Save As from the
ArcMap File menu and specify ArcMap Templates (*.mxt) as the File type. User forms provide access to a set of integrated controls. Some of these
controls are similar to the UIControls that are available as part of the Customize
d l box's
dialog b ' Commands d tab.
b

A control is a Visual Basic object you place on a user form that has its own
properties, methods, and events. You use controls to receive user input, display
output, and trigger event procedures. You can set the form to be either modal,
in which case the user must respond before using any other part of the
application, or modeless, in which case subsequent code is executed as it's
encountered.

To add and start coding in a user form Reseting core commands

In the Project Explorer, select the Project to which you want to add a user form.
Click the Insert menu and click UserForm.

VBA inserts a user form into your project and opens the Controls Toolbox. Click View, point to Toolbars, and check to show the toolbar with the command you want
to reset.
Click the controls in the Controls Toolbox that you want
to add to the form. Click the Tools menu and click Customize.
Add code to the user form or to its controls.
On the toolbar, right‐click the command you want to change.
To display the Code window for a user form or control,
double‐click the user form or control. Then, choose the Click Reset.
event you want your code to trigger from the The command returns to its default settings.
dropdown list of events and procedures in the Code
window and start typing your code. Or insert a
procedure and start typing code.

To display the form during an ArcMap session in

response to some action, invoke its Show method, as in
this example:

UserForm1.Show vbModeless 'show modeless

10
 4/6/2010

Resources
Getting to Know ArcObjects: Programming ArcGIS with VBA
An introduction to VB and to ArcObjects
Focus on GUI, vector programming tasks. Doesn't get into much detail
on complex analytical solutions (i.e. spatial analysis)

Exploring ArcObjects ‐ Vol I and II

More reference manuals than tutorials
Must have decent VB knowledge and preferebly a little ArcObjects
practice before picking this up.

ArcScripts

11