GUI Integration

 

Some client extensions can be completely invisible to the user but the majority of extensions are integrated into the JMap Pro GUI. This integration can take many forms. The initGui() method must be used to initialize the graphical interface of an extension.

JMapGuiService class

The JMapGuiService class is used to access the components of the graphical user interface (menus, toolbars, etc.) and to add or remove components. To simplify access to the graphical components, each component has a unique key. This key must be provided when a component is added or removed. For a complete list of available keys, see the section List of GUI components. The JMapGuiFactory class described below provides methods for creating GUI components.

The main methods of the JMapGuiService class are listed below:

Most commonly used methods of the JMapGuiService class

addMenuItem()

Adds an item to an existing menu by specifying the menu key.

getMenu()

Retrieves a menu using its key. The returned object can then be used to modify the menu.

addToolBar()

Adds a toolbar to a specific position in the application interface.

getToolBar()

Retrieves a toolbar using its key. The returned object can then be used to modify the toolbar.

addDockableComponent()

Adds a dockable window at a specific position in the application interface.

removeDockableComponent()

Allows you to remove a dockable window using its key.

getGuiFactory()

Returns the JMapGuiFactory instance. This class allows you to create GUI components such as buttons and toolbars.

JMapGuiFactory class

The JMapGuiFactory class is used to create buttons, menus and toolbars that are compatible with JMap applications. Methods such as createButton () createMenu () createToolBar (), etc. are called to create the appropriate components.

 
Integration examples

Adding a button to an existing toolbar

The following code shows how to add a button to an existing toolbar. The toolbar is retrieved using its key. For a complete list of available keys, see section List of GUI components. Note that the action associated with the button is not shown in the example.

 
// This button will be in a group thus only onebutton can be pressed among this group.
AbstractButton button = guiFactory.createToggleButton(new ButtonAction(),
    appContext.getApplication().getGuiService().getMainButtonGroup());
   
// Add the button on the Zoom and Pan toolbar.
appContext.getApplication().getGuiService().getToolBar("ZOOM_PAN").add(button);

 

 

Adding a toolbar

The following code example shows how to create a toolbar using the JMapGuiFactory class. In this example, the JMapApplicationActionManager class is used to access the buttons' actions. This class can manage single instances of actions. Afterwards, two buttons are created and added to the bar. Finally, the toolbar is added vertically, on the right side of the application. Notice the HashMap of properties that is used to place the toolbar. This principle is used with all components to specify their characteristics.

 
// Create the new toolbar
final ToolBar toolBar = guiFactory.createToolBar("SHOWCASE", "JMap example showcase");
 
// Create and add buttons on toolbar
toolBar.add(
    guiFactory.createToggleButton(applicationActionManager.getAction(CreatePolygonAction.class), jmapGuiService.getMainButtonGroup())
  );
   
toolBar.add(
    guiFactory.createButton(applicationActionManager.getAction(ShowDockingPanelAction.class))
  );
   
// Adds the new toolbar vectically to the right side of the application frame.
HashMap<String, Object> properties = new HashMap<String, Object>();
properties.put("CONTEXT_INIT_SIDE", new Integer(SwingConstants.EAST)); // Dock to the east
jmapGuiService.addToolBar(toolBar, properties);

 

Adding a window

The addDockableComponent() method adds components such as windows to the interface. It takes a HashMap of key-value pairs as a parameter to define the display settings of the new window. All keys and possible values are defined in the method's documentation.

 
// Create a panel with the needed components
final JPanel panel = new JPanel();
...
 
// Set the properties of the dockable panel.
HashMap<String, Object> properties = new HashMap<String, Object>();
properties.put("KEY", COMPONENT_KEY);                     // Will be used to reference the panel
properties.put("TITLE", "JMap 6.5 SDK showcase.");       // Will be displayed on the title bar
properties.put("CONTEXT_INIT_SIDE", SwingConstants.EAST); // Tells JMap to dock the panel to the east of the frame
 
appContext.getApplication().getGuiService().addDockableComponent(panel, properties);

 

 

Adding a menu

The following code example shows how to create and add a menu to the interface.

 
// Create menu and add items to it
JMenu menu = new JMenu("SDK");
   
JMenuItem item1 = new JMenuItem("Item 1");
JMenuItem item2 = new JMenuItem("Item 2");
   
this.menu.add(item1);
this.menu.add(item2);
   
// Add menu to menu bar at position 4
appContext.getApplication().getGuiService().getMenuBar().add(menu, 4);

 

 

Adding a menu item to an existing menu

The following code example shows how to add items to existing application menus. Note that a key is used to retrieve existing menus. For a complete list of available keys, see the section List of GUI components.

   
// Add 2 menu items to existing menus TOOLS and HELP
JMenuItem item3 = new JMenuItem("Item 3");
JMenuItem item4 = new JMenuItem("Item 4");
 
appContext.getApplication().getGuiService().addMenuItem("TOOLS", item3, false);
appContext.getApplication().getGuiService().addMenuItem("HELP", item4, false);

 

 

Adding an item to the map pop-up menu

The following code shows how to add a section of items to the map's pop-up menu. This menu appears when the user right-clicks on the map. In addition, the menu item is only active if the user has clicked on at least one element of a map layer. Otherwise, the menu item will be disabled.

 
final ViewMenuAction menuAction = new ViewMenuAction();
 
// Obtain the currently active view
View view = JMapApplicationContext.getInstance().getViewManager().getActiveView();
if (view != null)
{
  // Add a separatr and a menu item
  view.addPopupMenuSeparator();
  view.addPopupMenuAction(menuAction);
}

// Register an event listener with the View Manager so that we are notified when the view popup menu is about to be displayed
JMapApplicationContext.getInstance().getViewManager().addViewEventListener(new ViewAdapter()
{
  @Override
  public void viewPopupMenuShowing(ViewPopupMenuShowingEvent e)
  {
    // Enable map menu item only if the user clicked on some element
    K2DElement[] elements = e.getView().getLayerManager().getElementsAtPoint(e.getWcCoord(), e.getView().getViewState(), false);
    menuAction.setEnabled(elements.length > 0);
  }
});

 

 

Adding a section to a layer's settings window

It is possible to add sections to the settings window of a layer, as shown in the image below. To do this, you must implement your own class derived from the abstract class AbstractLayerSettingsCustomPage and implement that class's 3 abstract methods. You must provide a title and icon for your section by passing them to the constructor of the superclass; they will be displayed in the settings window.

Additional layer setting page created programatically

Additional layer setting page created programatically

 

Abstract methods of the AbstractLayerSettingsCustomPage class

getContentPanel()

In this method, you must create and return the the instance of JPanel that displays the GUI of the settings in your section. This is the graphical interface that will be displayed.

validateSettings()

This method is called when the user clicks on the OK button to confirm the changes and close the window. Your method should return true only if the parameters entered are valid. Otherwise, the window will refuse to close.

applySettings()

This method is called when the user clicks on the OK button to confirm the changes and close the window, and after calling the validateSetting() method. You must apply the parameter changes on the layer.

 

The getLayer() method of the AbstractLayerSettingsCustomPage class lets you know to which layer the parameters apply. To save your settings section, you must use the method addLayerSettingsCustomPage of the ShowLayerSettingsAction class, as shown in the following source code example.

 

// Obtain a reference to the ShowLayerSettingsAction instance

ShowLayerSettingsAction showLayerSettingsAction = (ShowLayerSettingsAction)appContext.getApplicationActionManager()

                                                                                      .getAction(ShowLayerSettingsAction.class);

 

// Add the custom panel for the Cities layer

showLayerSettingsAction.addLayerSettingsCustomPage(SDKLayerSettingsPanel.class.getName(), layerCities.getId());

 

 

 

Adding a custom button to the layer manager

You can add buttons associated with a layer in the layer manager. These buttons can be used to trigger custom actions that are specific to a layer. The buttons are added in different ways in the hierarchical section and list section.

Example of custom button added to a layer

Example of custom button added to a layer

 

The following source code example shows how to add a button to the Cities layer.

 

// Obtain layer instance from layer manager

Layer layerCities = appContext.getViewManager().getLayerManager().getLayer("Cities");

 

JMapGuiService guiService = appContext.getApplication().getGuiService();

JMapGuiFactory guiFactory = guiService.getGuiFactory();

 

AbstractButton abstractButton = guiFactory.createButton(new ButtonAction());

 

// Add the button to the 'More options' of the LayerTreeBar (hierarchy) for the layer Cities

guiService.getLayerTreeBar().addCustomButton(abstractButton, layerCities.getId());

 

// Add the button to the LayerPanel of the LayerBar (list) for the layer Cities

LayerPanel layerPanel = guiService.getLayerBar().getLayerPanel(layerCities.getId());

Button button = new Button(new ButtonAction(), false, new Dimension(18, 18));

layerPanel.addCustomButton(button);