How to create an add-in combo box

In this topic

• About the combo box
• Creating a combo box
• Setting properties
• Creating a Java class and defining your business logic
• About the abstract class ComboBox
• add() method
• clear() method
• getSelected() method
• isEnabled() method
• remove() method
• select() method
• Understanding the config.xml
• Creating different types of customizations

About the combo box

• Creating a combo box—Examines the process of creating a combo box in Eclipse.
• Setting properties—Examines all of the properties that can be set for the combo box with detailed descriptions.
• Creating a Java class and defining your business logic—Examines the creation of a Java class that is used to define all the business logic for the combo box.

Creating a combo box

1. Under All add-ins, click the Add button. The Create New Add-In dialog box appears. See the following screen shot:
   
   

2. Select the Combo Box option on the preceding screen shot (there are eight different options), then click OK.
   
   A new section of the add-in editor appears with various properties for you to set for your new combo box. By default, the id*, class*, caption*, and category* are completed with default values to help expedite the development process. Also, observe the warning symbol under the Combo Box Details and next to the class* property. This indicates that the Java class for your new combo box has not been created. In a later step in this workflow, you will learn how to create your Java class and where you will write your business logic. For now, the following screen shot shows you the new Combo Box Details section that is added to the editor with default values:
   
   

Setting properties

• id*—Represents the unique name that is used to identify your combo box. You can create more than one combo box for a project and this id property is used to distinguish between the different combo boxes. The previous screen shot shows a default value for this property. Ideally, you should replace this id with a more meaningful name. Use the Java package naming convention when constructing your id property value. For example, com.esri.arcgis.arcmap.addin.arcmapcombobox could be used to represent the add-in combo box being created for this topic (required).
• class*—Identifies the Java class for your combo box. The Java class is where you write your business logic. This class is important because it is called when the combo box is used in a desktop application. To create a class, click the class property. Notice that the class property has a link (blue and underlined) to indicate this. Use the Java package naming convention when constructing your class. For example, com.esri.arcgis.addin.ArcMapComboBox could be used to represent the combo box class being created (required).
• caption*—Applies a name to the combo box and is used in two different locations after the project is deployed (required). The first location is the Add-In Manager where the caption is used as metadata to help a user identify available types. The following screen shot uses a value of ArcMap Combo Box for the caption property and is exposed in the Add-In Manager (the type of add-in is identified in parentheses):
  
  
  
  The second place that the caption is used is when a user is adding the combo box to the user interface (UI) of a desktop application. For this workflow, see How to deploy your add-in. For reference, the Customize dialog box Commands tab is used and will use the caption defined under the commands text box. See the following screen shot:
  
  

• category*—Applies a name that can identify your add-ins as a group. A category can have more than one add-in by supplying the same name for the category property in each defined customization. For example, you could have an ArcMap add-ins category that can contain all your customizations for ArcMap, such as, a button, tool, toolbar, and so on. To achieve this, give the same category value for each add-in type (required).
  
  Identical to the caption property, the category property is visible in two locations. The first location is the Add-In Manager (notice that the Category explicitly identifies this property). See the following screen shot:
  
  
  
  The second location the category is used, is when a user is locating the add-in project on the Customize dialog box in a desktop application. The Customize dialog box Commands tab lists a number of categories (for example, Animation, ArcScan, and so on), and the category property value you set is used in this list to identify your type of add-in. See the following screen shot:
  
  

• image—16 by 16 pixel image that can be used to represent your combo box. This image is used on the Customize dialog box Commands tab to symbolize your combo box. This image is not used by default in the desktop application to which the combo box is added. Instead, a drop-down menu is used to represent a combo box. Place the image within an image folder in your project and the Browse button allows you to add a reference to this image (optional).

• tooltip—Brief description of your combo box that can be used to intuitively help your end user use your combo box or remind them of the combo box's purpose. The ToolTip appears when the mouse pointer pauses over the combo box in a desktop application. A message dialog box then shows the message supplied for this property (optional).

• message—More detailed description of your combo box that describes what the combo box does. Identical to the ToolTip, the message appears when the mouse pointer pauses over the combo box in a desktop application in conjunction with the ToolTip. This message appears with the value supplied with this property in the status bar of a desktop application, which is located in the lower left corner (optional).

• width—Represents the length of the combo box by using any character and repeating that character to represent the number of characters visible in the combo box. For example, if you want the combo box to show five characters, the width property will have a value of, XXXXX for any character (optional).

• item width—Defines the combo box's drop-down width. When a user clicks the down arrow on the combo box, the specified item width will be used to represent the length of this drop-down box. Similarly to the width property, the item width's value is represented with any character, repeated the number of times desired for the length of the drop-down box (optional).

• row—Determines the number of rows shown in the combo box drop-down list. This property is specified using an integer value (optional).

• hint—Defines the unavailable text shown on the comb box when it is not active in the desktop application. This text can be used to educate the user about the types of items they select from or about the kind of items they need to select from the combo box (optional).

• editable—Check box that indicates if the combo box allows a user to add a value into the combo box. By default, this option is turned off and the user is unable to add their item into the combo box. However, if you select the check box, the user is allowed to add their value.

• display caption in toolbar—Check box that indicates if the caption* property shows in conjunction with the combo box. By default, this option is turned off and only the combo box appears in the desktop application. However, if you select the check box, the caption* property shows to the left of the combo box when added to the toolbar. The following screen shot shows an example of the caption property shown next to the combo box in ArcMap (the caption property value is ArcMap Combo Box on this screen shot example):
  
  

• Heading—Indicates what the text is about (optional).

• Content—Where you place the content for the combo box's context-sensitive Help (optional).

Creating a Java class and defining your business logic

1. Click the class* property under the Combo Box details. A Java class dialog box appears with a few pre-populated form boxes. The one of interest is the superclass property. This property is unavailable automatically because the class that you create must inherit the abstract class ComboBox from the com.esri.arcgis.addins.desktop package. This abstract class is used to hide the implementation details for making the combo box work with a desktop application.
2. Add a name for the new Java class file and click Finish.

public class ArcMapComboBox extends ComboBox{
    @Override public void initialize(){}
    @Override public void onEditChange(String editString){}
    @Override public void onEnter(){}
    @Override public void onFocus(boolean setFocus){}
    @Override public void onSelChange(int cookie){}
}

• initialize()—Invoked when the defined comb box is initialized by the desktop application. A typical use case for this method is to populate the combo box with options. To achieve this, another method, add(), can be used. For example, the following initialize() method will add two options to the combo box on initialization:

private int option1;
private int option2;
@Override public void initialize(){
    try{
        option1 = add("Option 1");
        option2 = add("Option 2");
    }
    catch (Exception e){}
}

• onEditChange()—Only applicable when the editable property is enabled by selecting the check box on the add-in editor (see previous instructions for more information on this property). This method is invoked by the ArcGIS framework every time a single character is added in the edit box. You can use this method to write your business logic to respond to any character that is entered.
• onSelChange()—The onSelChange() method is called by the ArcGIS framework every time a new selection is made on the combo box. For example, the initialize() method adds two options to the combo box, and the following code example can be used to capture that event:

@Override public void onSelChange(int cookie){
    if (cookie == option1)
        JOptionPane.showMessageDialog(null, "Option 1 selected.");
    else if (cookie == option2)
        JOptionPane.showMessageDialog(null, "Option 2 selected.");
}

• onFocus()—Called by the ArcGIS framework when the combo box gets focus or when the combo box loses focus. A Boolean variable, setFocus, is passed into this method to indicate combo box's state. The variable is set to true when the combo box gets the focus, and false otherwise.
• onEnter()—Called by the ArcGIS framework only when the user presses the Enter key on the edit box of the combo box. This method allows you to wait for the user to completely finish typing a value before attempting to process your business logic based on the added value. The Enter key is a way for your user to let your business logic know that they have added a value.

About the abstract class ComboBox

isEnabled() method

add() method

remove() method

clear() method

select() method

getSelected() method

Understanding the config.xml

Creating different types of customizations

• How to create an add-in button
• How to create an add-in tool
• How to create an add-in toolbar
• How to create an add-in tool palette
• How to create an add-in menu
• How to create an add-in dockable window
• How to create an add-in application extension