How to create an add-in dockable window

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

In this topic

About the dockable window

A dockable window can exist in a floating state or can be attached to the main application window. The table of contents (TOC) in ArcMap is a good example of a dockable window. The TOC exposes layers that are present in a map and allow a user to work with those layers (for example, layer visibility, context-menu, and so on).
This topic guides you through the process of creating a dockable window 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 dockable window for any ArcGIS for Desktop application, this workflow shows you how to create a dockable window for ArcMap.
The workflow for creating a dockable window in Eclipse consists of the following (done in the order as shown):

Creating a dockable window

The following shows you how to create a dockable window 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 Dockable Window option on the preceding screen shot (there are eight different options), then click OK.

    A new section of the editor appears with a number of properties for you to set for your new dockable window. By default, the id*, class*, and caption* are completed with default values to help expedite the development process. Also, observe the warning symbol under the Dockable Window Details and next to the class* property. This indicates that the Java class for your new dockable window has not been created. In a later step in this workflow, you will learn how to create your Java class and where you write your business logic. For now, the following screen shot shows you the new Dockable Window Details section that is added to the editor with default values:

Setting properties

A dockable window 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 Initial Placement section of the Dockable Window Details is for the initial placement of the dockable window when it shows in a desktop application. The properties in this section, allow you to set values that determine how your dockable window appears in a desktop application in accordance with existing user interface (UI) components the first time it shows. The user has full control of moving the dockable window as necessary.

The following values comprise the placement properties for the dockable window:

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 the dockable window. 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 Dockable Window 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 automatically unavailable because the class that you create must inherit the abstract class, DockableWindow, from the com.esri.arcgis.addins.desktop package. This abstract class is used to hide the implementation details for making the dockable window work with a desktop application.
  2. Add a name for your new Java class file and click Finish. The generated class, in this instance, is called ArcMapDockableWindow. See the following code example:
[Java] 
public class ArcMapDockableWindow extends DockableWindow{
    @Override public Component createUI(){
        return null;
    }
}
The generated class file has the following significant pieces:
The createUI() method is required and is described as follows:
[Java] 
private JButton jButton;
private JPanel jPanel;
@Override public Component createUI(){
    jButton = new JButton("Click Me!");
    jPanel = new JPanel();

    jButton.addActionListener(new ActionListener(){
        public void actionPerformed(ActionEvent e){
            JOptionPane.showMessageDialog(null, "Hello, World"); 
        }
    }
    );
    jPanel.setLayout(new BorderLayout());
    jPanel.add(jButton, BorderLayout.NORTH);

    return jPanel;
}
Notice that the default auto-generated return value has been replaced with a new return value, an Abstract Window Toolkit (AWT) component (in this example, a JPanel that inherits from an AWT component). The sample creates a button and places it on a JPanel using the North region of a BorderLayout.
You are not finished with a dockable window at this stage. If you were to save the Eclipse project, deploy it, and open ArcMap, you would not obtain any visual result for your dockable window. To expose your dockable window in ArcMap, it must be connected to a button, tool, or combo box item. In other words, an end user must perform some action and a dockable window displays as a result of that action. To continue with this example, a button was created and defined. For details on creating a button, see How to create an add-in button. 
The code presented next can be applied in a similar manner if you use a tool or combo box to expose your dockable window.
The first piece of code you need to write obtains a reference to your dockable window using the ID you set when you defined its properties. Because a button is used in this scenario, the following code example is written in the button's init() method:
[Java] 
private IDockableWindow docWin;

@Override public void init(IApplication app){
    try{
        IDockableWindowManager dwm = new IDockableWindowManagerProxy(app);

        //Create a UID object.
        UID uid = new UID();
        //Obtain the Dockable Window id from your Dockable Window Add-In Editor and set the UID with this ID
        uid.setValue("com.esri.arcgis.arcmap.addin.arcmapdockablewindow");

        //Get the dockable window object based on its ID.
        docWin = dwm.getDockableWindow(uid);
    }
    catch (Exception e){
        e.printStackTrace();
    }
}
To obtain a reference to your dockable window, use the dockable window manager. Remember, it is possible for you to have more than one dockable window for your projects. The manager allows you to uniquely identify your dockable window. The first line of code in the init() method creates that object, passing in the application that is passed into the init() method.
Next, the source code creates a unique identifier (UID) object to call the setValue() method, where you pass in the ID that you previously set for your add-in dockable window. The final piece of code calls the getDockableWindow() method passing in the ID object and storing this particular dockable window in the docWin variable. You now have an object that points to your dockable window.
The second piece of code you need to write toggles your dockable window on and off as the button is clicked. See the following code example:
[Java] 
@Override public void onClick()throws IOException, AutomationException{
    try{
        if (docWin != null){
            docWin.show(!docWin.isVisible());
        }
    }
    catch (Exception e){
        e.printStackTrace();
    }
}
To achieve this functionality, the onClick() method is overridden and the logic is placed within. The show() method on the docWin object is called with a Boolean argument indicating if the dockable window is shown or hidden.
When the example is deployed, and the button is clicked, the dockable window displays. If the "Click Me!" button within the dockable window is clicked, a message dialog box appears with the "Hello, World!" message. For more information, see How to deploy your add-in.

About the abstract class DockableWindow

The abstract class, DockableWindow, provides additional methods that can be overridden to add additional capabilities to your dockable window. The following describe these additional methods.

init() method

The first, and most significant, is the init() method. When working with ArcGIS for Desktop applications, you might need to access various items within the applications. For example, in ArcMap you might want to access the maps (data frames) or layers contained within a map. 
Your Java application cannot just instantiate an instance of the ArcMap application; instead, you are passed a reference to an object that gives you the application that the dockable window is contained within. The init() method serves this purpose as well as defining any logic that is necessary to initialize the dockable window (for example, instantiate objects that are needed in your createUI() method).
To get an object that points to the desktop application the dockable window is hosted in, write code to hold onto the application object that is passed into the init() method when it is invoked. This can be achieved with the following initialization code example:
[Java] 
private IApplication app;
@Override public void init(IApplication app){
    this.app = app;
}
When you have a reference to the application object, use it to obtain a reference to the desktop application the dockable window is being consumed in.
  1. Obtain an object reference to ArcMap. See the following code example:
[Java] 
IMxDocument mxDocument = (IMxDocument)app.getDocument();
  1. Obtain an object reference to ArcCatalog. See the following code example:
[Java] 
IGxDocument gxDocument = (IGxDocument)app.getDocument();
  1. Obtain an object reference to ArcGlobe. See the following code example:
[Java] 
IGMxDocument gMxDocument = (IGMxDocument)app.getDocument();
  1. Get an object reference to ArcScene. See the following code example:
[Java] 
ISxDocument sxDocument = (ISxDocument)app.getDocument();

dispose() method

The dispose() method disposes the dockable window. The dispose() method is the last method called and can be used to release any resources that might have been consumed by the dockable window.
This method does not need to be invoked because it is invoked by the ArcGIS framework at the appropriate time. If you choose to override this method, release resources that are no longer required when the dockable window is no longer in use.

Understanding the config.xml file

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

Creating different types of customizations

This topic showed how to create a dockable window. 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