Appendix 3 - Point Manager Buttons

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

A: com.tridium.ddf.ui.point.BDdfPointMgrAgent

The procedure for this is very similar to the procedure for adding a button to the device manager as described in Appendix 2.
Make a class that extends com.tridium.ddf.ui.point.BDdfPointMgrAgent
In your driver's module-include file, declare your point manager agent class as an agent on your driver's device or point-device-extension.
The BDdfPointMgrAgent class implements the interface BIDdfPointMgrAgent. 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 point 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 point manager
   * @param a reference to the network that is above the point device extension
   * that the point manager is operating upon.
   * @param a reference to the device that is above the point device ext
   * that the point manager is operating upon
   * @param a reference to the point-device-ext that the point manager
   * is operating upon.
   *
   * @return an undo/redo command artifact or null
   */
  public CommandArtifact doInvoke(BDdfPointManager deviceManager, BDdfNetwork network, BDdfDevice device, BDdfPointDeviceExt ptDevExt);

  /**
   * This method is called when the ddf point 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 BDdfPointManager 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 point 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(pointManager.getController().getSelectedRows().length == 1);
   *
   * For example (to enable the agent's UI widget(s) if one or more database items are selected):
   *  agentCommand.setEnabled(pointManager.getController().getSelectedRows().length > 0);
   *
   * For example (to enable the agent's UI widget(s) if zero database items are selected):
   *  agentCommand.setEnabled(pointManager.getController().getSelectedRows().length == 0);
   *
   * @param pointManager
   *
   * @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(BDdfPointManager pointManager, DdfPointMgrAgentCommand agentCommand);

NOTE: BDdfPointMgrAgent provides default implementations of the update and getFlags methods. Therefore, you really only need to define the getUiName and doInvoke methods.
BDdfPointMgrAgent'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 point manager).
BDdfPointMgrAgent'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 point manager (depending on the value that the getFlags method returns). When either of these are clicked on the Point 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 Point 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 Point 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 Point 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

Please refer to the example provided in appendix 2. Although that example illustrates how to implement an agent on the device manager, everything required of the point manager is analogous to everything that is required for the device manager.