How to create an add-in combo box

Summary
This topic guides you through the workflow for creating a combo box using the Eclipse integrated development environment (IDE). After the workflow is presented, the topic takes a closer look at the abstract ComboBox class and defines additional methods available to you when creating your combo box.

In this topic

About the combo box

A combo box provides a set of choices, visually seen as a drop-down box, from which a selection can be made and acted upon. A combo box can also be enabled to allow an end user to add a value in the combo box and acted on accordingly. The scale combo box in ArcMap is a good example of a combo box. When data with a known coordinate system is added to ArcMap, the scale combo box is enabled giving the user a set of pre-defined scales from which to choose. It also allows a user to type a desired scale not present in the list of options and the map is displayed based on the value added.
The following guides you through the process of creating a combo box using the Eclipse IDE. Before beginning this workflow, make sure that you have created an ArcMap add-in project using Eclipse. For more information, see How to create an add-in project in Eclipse. Since there is no difference between creating a combo box for any ArcGIS for Desktop application, this workflow shows you how to create a combo box for ArcMap.
The workflow for creating a combo box in Eclipse consists of the following (done in the order show):

Creating a combo box

The following shows you how to create a combo box for an existing Eclipse add-in project. Ensure the Add-In view is enabled on the Add-In Editor for the config.xml file and that you have completed the required Add-In Overview properties. See the following screen shot: 

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

  1. 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

A combo box has a number of properties for you to set. The following is a list of all of the properties with an explanation for each:
The Help Content section on the Combo Box details a portion of the editor for the help content you can supply a user with. These properties allow you to supply information that will be used when a user invokes context-sensitive Help. These are generally short pop-up topics that remain on-screen until a user clicks somewhere else.
The following properties comprise this context-sensitive Help:

Creating a Java class and defining your business logic

At this stage, you have finished adding values for all of the properties needed to define your combo box. The final step in this workflow, is to create a Java class that contains your business logic. Do the following steps to create the Java class:
  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.
In this instance, a class called ArcMapComboBox, is similar to the one in the following code example:
[Java] 
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){}
}
The generated class file has two significant pieces. The first is the use of the extends keyword to inherit from the abstract class ComboBox. The second is the five auto-generated methods, as previously shown. The following describes each of these methods, which are required:
[Java] 
private int option1;
private int option2;
@Override public void initialize(){
    try{
        option1 = add("Option 1");
        option2 = add("Option 2");
    }
    catch (Exception e){}
}
The source code assigns a result for each add method to an integer variable. This is done because the add method returns a unique ID (cookie) for each item that is added to the combo box. The returned value is important for determining which option is selected by the user in another method you must define.
[Java] 
@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.");
}
The cookie variable that is passed into this method represents the option that is selected by the user. In the initialize() method, when adding the options, these values are reported back to you. The two instance variables are used here to test which option is selected by the user and reports that fact. Based on the option that a user selects, you can utilize decision logic to execute your business logic accordingly.
The previous code example prints a message dialog box outputting which option was selected by a user, but could be developed further as the application requires. For instructions on how to deploy the add-in combo box, see the previously referenced topic, How to deploy your add-in.

About the abstract class ComboBox

The abstract class ComboBox provides you with additional methods that can be overridden to help you define the required methods. Together, six of these methods exist and are described as follows.

isEnabled() method

This method allows you to add some logic to specify in what state the desktop application should be in for the combo box to be enabled, and thus allows someone to select from the list of options or type their value. An ArcGIS framework system event is called to check if a combo box is enabled or not.

add() method

The add() method allows you to add items to your combo box. Pass in the string you want to appear on the combo box. Also, this method returns an integer representing the unique value for your option. This integer is useful in other methods when determining which item is currently selected or chosen by the end user. This method is final and cannot be overridden.

remove() method

The remove() method allows you to delete items from your combo box. When calling this method, you need the ID of the item for it to be removed. This method is final and cannot be overridden.

clear() method

The clear() method allows you to clear all the elements from the combo box. This method is final and cannot be overridden.

select() method

The select() method allows you to select an element in the combo box. This can be useful if you want to initialize the combo box with a default value applied. The method accepts a cookie argument that represents the ID of your combo box item. This method is final and cannot be overridden.

getSelected() method

The getSelected() method allows you to get the selected item from the combo box. This method returns the ID that represents the item that has been selected by the user. This method is final and cannot be overridden.

Understanding the config.xml file

When setting all of the properties, the config.xml file was being generated behind the scenes. To understand more about how this config.xml file is created, see Understanding the config.xml.

Creating different types of customizations

This topic showed how to create a combo box. However, there are additional types of add-ins that can be created and defined. See the following topics that discuss each type of add-in.





Development licensingDeployment licensing
ArcGIS for Desktop BasicArcGIS for Desktop Basic
ArcGIS for Desktop StandardArcGIS for Desktop Standard
ArcGIS for Desktop AdvancedArcGIS for Desktop Advanced