How to create an add-in dockable window

Summary This document will guide you through the workflow for creating a dockable window using the Eclipse integrated development environment (IDE). After the workflow is presented the documentation 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 is a window that 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).
The following will guide you through the process of creating a dockable window using the Eclipse IDE. Before beginning this workflow, you must make sure that you have created a new ArcMap add-in project using Eclipse (see How to create an add-in project in Eclipse for details). Since there is no difference between creating a dockable window for any one of the ArcGIS Desktop applications, 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 steps:
  2. Setting properties
  3. Creating a Java class and defining your business logic
Step 1 will examine the process of creating a new dockable window in Eclipse. Step 2 will examine all of the properties that can be set for the dockable window with detailed descriptions for each property. The final step examines the creation of a Java class that is used to define all the business logic for the dockable window.

Creating a new dockable window

The following will show you how to create a new dockable window for an existing Eclipse add-in project. Please ensure that you have the add-in view enabled for the add-in editor on the config.xml file and that you have filled out the required overview properties.
  1. Under all add-ins, click the add button.

    You are presented with a dialog box asking you which type of add-in you wish to create. Notice that all 8 different customizations are presented to you at this point.
  1. Choose dockable window and click OK.
A new section of the editor now appears with a number of properties for you to set for your new dockable window. By default, the id*, class*, and caption* are filled in for you with default values to help expedite the development process. Also, observe the warning symbol under dockable window details and next to the class* property. This indicates to you that the Java class for your new dockable window has not been created yet. At a latter step in this workflow you will learn how to create your new Java class and where you will write your business logic. For now, the following figure 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:
  • id* - The id represents the unique name that is used to identify your dockable window. It is possible for you to create more than one dockable window for a given project and this id property is used to distinguish between the different dockable windows. Notice that the previous image shows a default value for this property. Ideally, you should replace this id with a more meaningful name. It is also highly recommended that the Java package naming convention is used when constructing your id property value. For example, com.esri.arcgis.arcmap.addin.arcmapdockablewindow could be used to represent the add-in dockable window being created for this document (Required).
  • class* - The class property is used to identify the Java class for your dockable window. The Java class is where you will write your business logic. This class is important because it is called whenever the dockable window is used in a desktop application. To create a new class you can click on the class property itself - notice that the class property is blue and underlined to indicate this to you (Required).
  • image - A 16x16 pixel image that can be used to help represent your dockable window when it is unpinned in a desktop application. The image itself can be placed within an image folder in your add-in project and the browse button allows you to add a reference to this image (Optional).

    An example of a dockable window’s image is the following table of contents as seen in ArcMap:
  • caption* - The caption property is used to give a name to the dockable window and is used in two different locations after a project is deployed (Required).

    The first location is the Add-In Manager where the caption is used as meta-data to help a user identify types of customizations available. The following example uses a value of "ArcMap Dockable Window" for the caption property and is exposed in the Add-In Manager as follows:

    The second place that the caption is used is when the dockable window is unpinned to the desktop application interface. For example, if "ArcMap Dockable Window" is used as a value, it would show up in ArcMap as follows:
The next section, Initial Placement, of the dockable window details portion of the editor is, as the title suggests, for the initial placement of your dockable window when it is displayed in a desktop application. The properties contained in this section allow you to set properties that will determine how your dockable window will be displayed in a desktop application in accordance with existing user interface (UI) components the first time it is displayed. Your user will have full control to move the dockable window as necessary.
The following properties comprise the placement properties for the dockable window and explained further here:
  • Width - An integer that is used to represent the width of your dockable window (Optional).
  • Height - An integer that is used to represent the height of your dockable window (Optional).
  • Neighbor - A drop down list that gives you the ID for various ArcGIS Desktop UI components that your add-in dockable window can be neighbored with (Optional).
  • State - There are 3 possible states that you can setup for your dockable window (Optional).

    First, pinned, is when your dockable window is attached to a desktop application and is visible at all times. The following image shows the ArcMap dockable window example that is in the pinned state:

    Notice the pin in the right hand corner. This representation of the pin means that the dockable window will remain visible even though it does not have the focus (the user has not clicked inside the dockable window).

    Second, unpinned (default) , is when your dockable window is attached to a desktop application, but is only visible when it is in focus. The following image shows the ArcMap dockable window example that is in the unpinned state:

    Notice the pin the right hand corner. This representation of the pin means that as soon as the user clicks away from the dockable window it will become hidden on the UI of the desktop application (in the same fashion that the caption property image illustrated to you and represented with the description of the hidden state).

    Third, hidden, is when your dockable window is hidden or minimized to a desktop application to save important screen real estate for your end user.  The following image shows the ArcMap dockable window example that is in the hidden state:

    This example figure is illustrated next to a hidden table of contents in ArcMap to show that in a hidden state it appears like a tabbed item. As soon as an end user hovers over the dockable window it will be exposed again, but once the dockable window loses focus will retreat back to the state represented in this image.
  • Position - The position property represents where a dockable window will be positioned relative to existing UI components in a desktop application. The options available to you are left, right, top, bottom, float, and group (Optional).

Creating a Java class and defining your business logic

At this stage, you have finished entering values for all of the properties needed to define your dockable window. The final step in this workflow is to create a Java class that will contain your business logic. To create the new Java class, do the following:
  1. Click the class* property found under dockable window details of the editor.
A new Java class dialog box will appear with a few pre-populated form boxes. The one of interest is the superclass property. This property is grayed out automatically because the class that you create must inherit the abstract class DockableWindow from the com.esri.arcgis.addins.desktop package. This abstract class is what is used to hide the implementation details for making your dockable window work with a desktop application.
  1. Enter a name for your new Java class file and click finish.
A class, in this instance called "ArcMapDockableWindow", similar to the one generated next:
[Java] 
public class ArcMapDockableWindow extends DockableWindow{
    @Override public Component createUI(){
        return null;
    }
}
The generated class file has two significant pieces. The first is the use of the extends keyword to inherit from the abstract class DockableWindow. The second is the auto-generated method, as illustrated. The createUI() is required and is described in greater detail here:
  • createUI() - The createUI() method is used to create the dockable window’s UI. In this section of code you will use your Java based graphical user interface (GUI) components to create this UI. For example, to get you started, the following createUI() method has been encoded to define a JPanel that will contain a JButton. When the button is clicked a message will display the "Hello, World!" message. The following code shows you how to achieve this:
[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 return value auto-generated for you has been replaced with a new return value, an AWT Component (in this example a JPanel, which 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 wouldn’t obtain any visual result for your dockable window. In order 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 is displayed 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 used in a similar manner if you chose to use a tool or combo box to expose your dockable window.
The first piece of code you need to write will obtain a reference to your dockable window using the id you set when you defined its properties. Because a button is used in this scenario, this code is written in the button’s init() method as such:
[Java] 
private IDockableWindow docWin;

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

        //Create a new 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, you need to use the dockable window manager. Remember, it is possible for you to have more than one dockable window for your projects. The manager will allow you to uniquely identify your dockable window. The first line of code in the init() method creates that object for you, passing in the application that is passed into the init() method.
Next, the source code will create a new UID object (Unique ID) in order to call the setValue() method, where you will pass in the id that you set for your add-in dockable window previously. 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 will toggle your dockable window on and off as the button is being clicked. The following code shows you this:
[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 to be displayed or hidden.
When the example is deployed, see How to deploy your add-in for further details, and the button is clicked the dockable window will display. If the "Click Me!" button within the dockable window is clicked, then a message dialog will appear displaying the "Hello, World!" message.

About the abstract class DockableWindow

The abstract class DockableWindow provides you with additional methods that can be overridden to add additional capabilities to your dockable window. These additional methods are described here in detail.

init() method

The first, and most significant, is the init() method. When working with one of the ArcGIS Desktop applications it is quite possible that you might need to access various items within the applications. For example, in ArcMap you might wish 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 will give 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 your dockable window (for example: instantiate objects that are needed in your createUI() method). How then are you able to get an object that points to the desktop application your dockable window is hosted in? First, you need to write some 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:
[Java] 
private IApplication app;
@Override public void init(IApplication app){
    this.app = app;
}
Once you have a reference to the application object, you can use it to obtain a reference to the desktop application the dockable window is being consumed in with the following code:
  1. Obtain an object reference to ArcMap:
[Java] 
IMxDocument mxDocument = (IMxDocument)app.getDocument();
  1. Obtain an object reference to ArcCatalog:
[Java] 
IGxDocument gxDocument = (IGxDocument)app.getDocument();
  1. Obtain an object reference to ArcGlobe:
[Java] 
IGMxDocument gMxDocument = (IGMxDocument)app.getDocument();
  1. Get an object reference to ArcScene:
[Java] 
ISxDocument sxDocument = (ISxDocument)app.getDocument();

dispose() method

The dispose() method will dispose 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. It is important to note that this method does not need to be invoked because it is invoked by the ArcGIS framework at the appropriate times. Your job, if you choose to override this method, is to release resources that are no longer required when the dockable window is no longer in use.

Understanding the config.xml

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

Creating different types of customizations

The following documentation showed you how to create a dockable window.  However, there are 7 additional types of customizations that can be created and defined.  The following links will take you to those how-to documents.





Development licensing Deployment licensing
ArcView ArcView
ArcEditor ArcEditor
ArcInfo ArcInfo