JBuilder browser concepts

General description

Browser is the main JBuilder IDE window. It constructs and establishes the relationships between all the other major UI elements, which are listed here:

You should obtain references to all these UI elements from a specific instance of Browser. To modify the browser menu bar and toolbar, however, use the OpenTools API interfaces only. These interfaces allow the adding and removing of ActionGroup objects and they apply to all instances of Browser. You must modify a menu or toolbar ActionGroup only within your OpenTool's initOpenTool() method so that the changes you make are in place when JBuilder finishes loading. For more information about how OpenTools are loaded and initialized, see JBuilder OpenTools loader concepts.

Browser fires events to each registered BrowserListener. Such listeners can be registered on either of two lists: one for a specific instance of Browser, and one for any Browser instance. You can use the convenient BrowserAdapter class to make implementing the BrowserListener interface easier.

Browser defines some DelegateAction objects that are usually tied to toolbar buttons. The IDE window that has the current focus can optionally provide the actual implmentation of these actions. These are the actions:


Detailed description of feature/subsystem

Adding and removing menu bar groups

The BrowserMenuBar class is an extension of the ActionMenuBar class. It adds the registered menu ActionGroup objects to the browser menu bar. Each ActionGroup adds a new menu to the menu bar in the order it was registered through the OpenTools API. All the native menus of JBuilder are registered at application startup before the OpenTools discovery process begins.

You must add or remove a menu group within the OpenTool's initOpenTool() method only. The following example adds a new menu to the browser's menu bar. First it adds the desired close actions to the new menu group, then the new group is added to the browser menu bar with the call to Browser.addMenuGroup():

  public static void initOpenTool(byte majorVersion, byte minorVersion) {
    if (majorVersion == PrimeTime.CURRENT_MAJOR_VERSION) {
      GROUP_MyClosersGroup.add(ProjectView.ACTION_ProjectCloseActive);
      GROUP_MyClosersGroup.add(Browser.ACTION_NodeClose);
      GROUP_MyClosersGroup.add(Browser.ACTION_NodeCloseAll);
      GROUP_MyClosersGroup.add(Browser.ACTION_NodeRevert);

      GROUP_MyClosers.add(GROUP_MyClosersGroup);

      Browser.addMenuGroup(GROUP_MyClosers);
    }
  }

  public static ActionGroup GROUP_MyClosersGroup = new ActionGroup();
  public static ActionGroup GROUP_MyClosers = new ActionGroup("MyClosers", 'm', true);

Here is the code that removes the native Edit menu of JBuilder:

  Browser.removeMenuGroup(com.borland.jbuilder.JBuilderMenu.GROUP_Edit);

Adding and removing individual menu Actions or ActionGroups

Add a menu Action or ActionGroup only within your OpenTool's initOpenTool() method. This is the logic to add the Revert action to the New group of the native File menu of JBuilder:
  JBuilderMenu.GROUP_FileNew.add(Browser.ACTION_NodeRevert);

This code removes the four New Actions from the native File menu of JBuilder:

  JBuilderMenu.GROUP_File.remove(JBuilderMenu.GROUP_FileNew);

Adding and removing toolbar groups

The BrowserToolBarPane class is an extension of ActionToolBarPane class. It adds the registered toolbar ActionGroup objects. Each ActionGroup appends to the browser toolbar in the order it was registered through the OpenTools API. Each ActionGroup also appears in the toolbar popup menu to allow users to hide or reveal it just as they can the native toolbar groups. All the native toolbar groups of JBuilder are registered at application startup prior to the OpenTools discovery process.

The following example adds a new group to the browser's toolbar. First it adds the desired close actions to the new group, then the new group is added to the browser toolbar with the call to Browser.addToolBarGroup():

  public static void initOpenTool(byte majorVersion, byte minorVersion) {
    if (majorVersion == PrimeTime.CURRENT_MAJOR_VERSION) {
      GROUP_MyClosersGroup.add(ProjectView.ACTION_ProjectCloseActive);
      GROUP_MyClosersGroup.add(Browser.ACTION_NodeClose);
      GROUP_MyClosersGroup.add(Browser.ACTION_NodeCloseAll);
      GROUP_MyClosersGroup.add(Browser.ACTION_NodeRevert);

      GROUP_MyClosers.add(GROUP_MyClosersGroup);

      Browser.addToolBarGroup(GROUP_MyClosers);
    }
  }

  public static ActionGroup GROUP_MyClosersGroup = new ActionGroup();
  public static ActionGroup GROUP_MyClosers = new ActionGroup("MyClosers", 'm', true);

This is the logic to remove the File group from the native JBuilder toolbar:

  Browser.removeToolBarGroup(com.borland.jbuilder.JBuilderToolBar.GROUP_FileBar);

Hiding and revealing toolbar groups

The View|Toolbars menu allows the user to hide or reveal a toolbar group. You can do this programmatically for a specific Browser instance:
  boolean bVisible = true;
  Browser browser = Browser.getActiveBrowser();
  browser.getToolBarPane().setToolBarVisible(JBuilderToolBar.GROUP_FileBar, bVisible);

Adding and removing specific toolbar buttons

This logic adds a Revert button to the native JBuilder toolbar Edit group:
  JBuilderToolBar.GROUP_EditBar.add(Browser.ACTION_NodeRevert);

This code removes the Close button from the native JBuilder toolbar:

  JBuilderToolBar.GROUP_FileBar.remove(Browser.ACTION_NodeClose);

Delegated actions

Browser defines DelegateAction objects that are used to funnel an action request to the UI component that has the current focus. By default, the action is disabled. To enable one of these actions, your class must implement the DelegateHandler interface and override its single getAction() method. For example, this getAction() method handles the DELEGATE_Copy action:

  public Action getAction(DelegateAction delegate) {
    if (delegate == com.borland.primetime.ide.Browser.DELEGATE_Copy) {
      return ACTION_CopyContent;
    }
    return null;
  }

  private static ClipboardOwner clipWatcher = new ClipboardObserver();
  protected static class ClipboardObserver implements ClipboardOwner {
    public void lostOwnership(Clipboard clipboard, Transferable contents) {}
  }

  public UpdateAction ACTION_CopyContent =
    new UpdateAction("Copy", 'C', "Copy selected content") {
    public void update(Object source) {
      setEnabled(isSelection());
    }
    public void actionPerformed(ActionEvent e) {
      String str = getSelection();
      if (str != null) {
        Clipboard clipboard = Toolkit.getDefaultToolkit().getSystemClipboard();
        clipboard.setContents(new StringSelection(str), clipWatcher);
      }
    }
  };

Listening for Browser events

The Browser class maintains two lists for listeners. One list of listeners listens for events that any instance of Browser fires, while the other list of listeners listens for events that a particular Browser instance fires. Use addStaticBrowserListener() to listen for all BrowserListener events or use addBrowserListener() to listen to the events fired by a particular Browser. Using BrowserAdapter provides a convenient way to listen for only those events you need. For example,
  Browser.addStaticBrowserListener(new BrowserAdapter() {
    public void browserNodeActivated(Browser browser, Node node) {
      if (node != null) {
        System.out.println("Active node is " + node.getLongDisplayName());
      }
    }
  });