Appendix 2 - Device Manager Buttons

Q: How do I add a button to the device manager?

A: com.tridium.ddf.ui.device.BDdfDeviceMgrAgent

Make a class that extends com.tridium.ddf.ui.device.BDdfDeviceMgrAgent
In your driver's module-include file, declare your device manager agent class as an agent on your driver's network.
The BDdfDeviceMgrAgent class implements the interface BIDdfDeviceMgrAgent. Here are the method declarations for BIDdfDeviceMgrAgent. Please review these.

  /**
   * This name can be either just a name or a lexicon key that defines the button text and the
   * optional button label.
   */
  public String getUiName();
  /**
   * This method is called when the user clicks the
   * corresponding button on the device manager for this
   * agent.The developer may define any functionality
   * here.
   *
   * NOTE: This will execute on the client-side proxy's
   * virtual machine. Any access to the server-side
   * host will therefore have to be through properties,
   * actions, etc.
   *
   * @param a reference to the device manager
   * @param a reference to the network that the device manager is
   * operating upon
   *
   * @return an undo/redo command artifact or null
   */
  public CommandArtifact doInvoke(BDdfDeviceManager deviceManager, BDdfNetwork network);

  /**
   * This method is called when the ddf device manager
   * is created. It allows the developer to specify the MGR_CONTROLLER flags
   * that govern whether a button, menu item, toolbar item, etc. is created
   * for this agent.
   *
   * @return
   */
  public int getFlags();

  /**
   * The developer should review the given BDdfDeviceManager and consider
   * updating (eg. enable/disable) the given agentCommand and/or any other
   * commands on the manager's controller. The method is called anytime
   * there is a change of state on the device manager (eg. discovery list
   * selection change, database list selection change, database component
   * event, learn mode changed, etc.)
   *
   * For example (to enable the agent's UI widget(s) if one database item is selected):
   *  agentCommand.setEnabled(deviceManager.getController().getSelectedRows().length == 1);
   *
   * For example (to enable the agent's UI widget(s) if one or more database items are selected):
   *  agentCommand.setEnabled(deviceManager.getController().getSelectedRows().length > 0);
   *
   * For example (to enable the agent's UI widget(s) if zero database items are selected):
   *  agentCommand.setEnabled(deviceManager.getController().getSelectedRows().length == 0);
   *
   * @param deviceManager
   *
   * @param agentCommand this is a special instance of IMgrCommand. It is
   * a reference to the corresponding GUI command (button, menu item, and/or
   * toolbar button) on the device manager.
   */
  public void update(BDdfDeviceManager deviceManager, DdfDeviceMgrAgentCommand agentCommand);

NOTE: BDdfDeviceMgrAgent provides default implementations of the update and getFlags methods. Therefore, you really only need to define the getUiName and doInvoke methods.
BDdfDeviceMgrAgent's default implementation of update does nothing. You should override this if you need to enable or disabled the agent's button or otherwise change the appearance of the device manager (to enable or disable other buttons, etc). Remember, the update method is called often (basically whenever there is any detectable change on anything related to the device manager).
BDdfDeviceMgrAgent's default implementation of getFlags always returns MgrController.BARS. This places your agent onto the device manager as a button, menu item, and toolbar item (if you specify a lexicon key that defines a toolbar icon from your getUiName method).
Following this procedure will place a button, menu item, and (or) toolbar button onto the device manager (depending on the value that the getFlags method returns). When either of these are clicked on the Device Manager, your agent's doInvoke method will be called (on the client-side) Java virtual machine. This is where you may define any behavior that should happen as a result.

NOTE: In order to make complete use of a Device Manager Agent, some familiarity with aspects of the core bajaui and baja driver framework will be required. For example, the value returned by the getFlags method needs to be a Java int with various flags bit wise or'd from the javax.baja.workbench.mgr.MgrController class. These flags can be:

MgrController.MENU_BAR causes the agent to be represented as an item in the Device Manager's main menu.
MgrControler.ACTION_BAR causes the agent to be represented as a button along with the other buttons towards the bottom of the Device Manager (such as the Add, Edit, and Discover buttons).
MgrController.TOOL_BAR causes the agent to be represented as a toolbar item, provided that the agent's getUiName returns a lexicon base key and the lexicon base key contains a .icon definition (this is explained further below)
MgrController.BARS causes the agent to be represented as all of the above. This is equivalent to MENU_BAR | ACTION_BAR | TOOL_BAR.

Example

Here is an example that places an item onto the menu bar, action bar, and toolbar.

BTestDeviceMgrButton.java

package com.testCompany.testDriver.ui;

import javax.baja.sys.Sys;
import javax.baja.sys.Type;
import javax.baja.ui.CommandArtifact;

import com.tridium.ddf.BDdfNetwork;
import com.tridium.ddf.ui.DdfMgrControllerUtil.DdfDeviceMgrAgentCommand;
import com.tridium.ddf.ui.device.BDdfDeviceManager;
import com.tridium.ddf.ui.device.BDdfDeviceMgrAgent;

public class BTestDeviceMgrButton
  extends BDdfDeviceMgrAgent
{
  /*-
  class BTestDeviceMgrButton
  {
  }
  -*/
/*+ ------------ BEGIN BAJA AUTO GENERATED CODE ------------ +*/
/*@ $com.testCompany.testDriver.ui.BTestDeviceMgrButton(1190303087)1.0$ @*/
/* Generated Fri Jun 01 10:40:57 EDT 2007 by Slot-o-Matic 2000 (c) Tridium, Inc. 2000 */

////////////////////////////////////////////////////////////////
// Type
////////////////////////////////////////////////////////////////

  public Type getType() { return TYPE; }
  public static final Type TYPE = Sys.loadType(BTestDeviceMgrButton.class);

/*+ ------------ END BAJA AUTO GENERATED CODE -------------- +*/


  /**
   * This name can be either just a name or a lexicon key that defines the button text and the
   * optional button label.
   */
  public String getUiName()
  {
    return "DeviceMgr.TestButton";
  }
  /**
   * This method is called when the user clicks the
   * corresponding button on the device manager for this
   * agent.The developer may define any functionality
   * here.
   *
   * NOTE: This will execute on the client-side proxy's
   * virtual machine. Any access to the server-side
   * host will therefore have to be through properties,
   * actions, etc.
   *
   * @param a reference to the device manager
   * @param a reference to the network that the device manager is
   * operating upon
   *
   * @return an undo/redo command artifact or null
   */
  public CommandArtifact doInvoke(BDdfDeviceManager deviceManager, BDdfNetwork network)
  {
    System.out.println("'Test' button clicked on the device manager!");
    return null;
  }

  /**
   * The developer should review the given BDdfDeviceManager and consider
   * updating (eg. enable/disable) the given agentCommand and/or any other
   * commands on the manager's controller. The method is called anytime
   * there is a change of state on the device manager (eg. discovery list
   * selection change, database list selection change, database component
   * event, learn mode changed, etc.)
   *
   * For example (to enable the agent's UI widget(s) if one database item is selected):
   *  agentCommand.setEnabled(deviceManager.getController().getSelectedRows().length == 1);
   *
   * For example (to enable the agent's UI widget(s) if one or more database items are selected):
   *  agentCommand.setEnabled(deviceManager.getController().getSelectedRows().length > 0);
   *
   * For example (to enable the agent's UI widget(s) if zero database items are selected):
   *  agentCommand.setEnabled(deviceManager.getController().getSelectedRows().length == 0);
   *
   * @param deviceManager
   *
   * @param agentCommand this is a special instance of IMgrCommand. It is
   * a reference to the corresponding GUI command (button, menu item, and/or
   * toolbar button) on the device manager.
   */
  public void update(BDdfDeviceManager deviceManager, DdfDeviceMgrAgentCommand agentCommand)
  {
    // To disable the agent's button, toolbar button, and menu-item, I would need to
    // Do this:
    //  agentCommand.setEnabled(false);
  }
}

module-include.xml

The testDriver's module-include.xml file defines the BTestDeviceMgrButton as follows:

<types>
  <!-- Type Example:
  <type name="YourClass" class="com.yourDriver.BYourClass"/>
  -->
  <type name="TestDeviceMgrButton" class="com.testCompany.testDriver.ui.BTestDeviceMgrButton">
    <agent>
      <on type="myTest:TestDriverNetwork"/>
    </agent>
  </type>

  ...
  <type name="TestDriverNetwork" class="com.testCompany.testDriver.BTestDriverNetwork"/>
  ...

</types>

This defines BTestDeviceMgrButton as an agent on the BTestDriverNetwork component. When initializing itself, the ddf device manager that BTestNetwork automatically receives (since it extends com.tridium.ddf.BDdfNetwork) reviews the network on which it is operating (BTestNetwork in this case) and adds action buttons, toolbar buttons, and menu items for each type in the driver whose class implements BIDdfDeviceMgrAgent provided that the type is registered as an agent on the corresponding network type for the driver.

module.lexicon

DeviceMgr.TestButton.label=Test Device
DeviceMgr.TestButton.icon=module://myTest/images/myTest.png
DeviceMgr.TestButton.accelerator=CTRL+SHIFT+ALT+T
DeviceMgr.TestButton.description=This is a test button on the device manager

Please notice that the getUiName method returns "DeviceMgr.TestButton". The module.lexicon (which is a text, properties file) defines entries for:

DeviceMgr.TestButton.label
DeviceMgr.TestButton.icon
DeviceMgr.TestButton.accelerator
DeviceMgr.TestButton.description

Here is a description and explanation of each:

DeviceMgr.TestButton.label=Test Device: Defines the text that will be displayed inside the corresponding button on the device manager and for the corresponding menu item on the device manager.
DeviceMgr.TestButton.icon=module://myTest/images/myTest.png: OPTIONAL. Defines the icon that will be displayed inside the corresponding button, menu item, and toolbar button on the device manager. This identifies a sixteen-by-sixteen image of png format.
DeviceMgr.TestButton.accelerator=CTRL+SHIFT+ALT+T: OPTIONAL. Defines the hot key that will cause the corresponding button, menu item, and toolbar button to be invoked from the device manager.
DeviceMgr.TestButton.description=This is a test button on the device manager: OPTIONAL. Niagara will use the description as it deems necessary to provide a hint to the end-user explaining the function of the corresponding button, menu item, and toolbar button. For example, Niagara might place this description into the Workbench status line.

The getUiName method, however, does not have to return a base into the lexicon. Alternatively, the getUiName method can return a single key into the lexicon. If that is the case, then the device manager will use the corresponding text directly as the label for the button and the menu text. This manner does not define an icon, however, so no toolbar button will be generated (even if the getFlags method dictates otherwise).

Finally, if the String returned by the getUiName method is not found in your driver's lexicon at all then the String itself will be used as the button and menu item's label (no toolbar button will be generated).