Other configuration files making up the helpset are registered in this file. Use the title element to assign the helpset a unique name. The maps element refers to map files that register help topics, defining their unique map IDs, used to reference help topics in the files defining tables of contents and indexes. The view element defines the helpset search engine, tables of contents, and indexes.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE helpset PUBLIC
   "-//Sun Microsys Inc.//DTD JavaHelp HelpSet Version 2.0//EN"
   "http://java.sun.com/products/javahelp/helpset_2_0.dtd">
<helpset version="2.0">
   <title>My Module Help</title>
   <maps>
      <homeID>com.galileo.netbeans.module.about</homeID>
      <mapref location="module-map.xml"/>
   </maps>
   <view mergetype="javax.help.AppendMerge">
      <name>TOC</name>
      <label>Table of Contents</label>
      <type>javax.help.TOCView</type>
      <data>module-toc.xml</data>
   </view>
   <view mergetype="javax.help.AppendMerge">
      <name>Index</name>
      <label>Index</label>
      <type>javax.help.IndexView</type>
      <data>module-idx.xml</data>
   </view>
   <view>
      <name>Search</name>
      <label>Search</label>
      <type>javax.help.SearchView</type>
      <data engine="com.sun.java.help.search.DefaultSearchEngine">
              JavaHelpSearch</data>
   </view>
</helpset>

The map file centralizes registration of help topics within the module. Using its target attribute, you can register HMTL files as help topics and assign them to a unique map ID. Later, refer to the help topics via their map ID when defining files that create tables of contents and indexes. Map IDs are used by the HelpCtx object to call up context-sensitive help, as described later in this section.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC
   "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 2.0//EN"
   "http://java.sun.com/products/javahelp/map_2_0.dtd">
<map version="2.0">
   <mapID target="com.galileo.netbeans.module.about" url="module-about.html"/>
</map>

Table of contents files connect map IDs to help topics displayed as helpset tables of contents. Help topics are grouped into folders containing related topics by nesting elements within other elements, as shown here:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE toc PUBLIC
   "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 2.0//EN"
   "http://java.sun.com/products/javahelp/toc_2_0.dtd">
<toc version="2.0">
   <tocitem text="My Module">
      <tocitem text="About My Module" target="com.galileo.netbeans.module.about"/>
   </tocitem>
</toc>

In the index file, use the element indexitem to register the map IDs of the help topics displayed on the Index tab of the Help window:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE index PUBLIC
   "-//Sun Microsystems Inc.//DTD JavaHelp Index Version 2.0//EN"
   "http://java.sun.com/products/javahelp/index_2_0.dtd">
<index version="2.0">
   <indexitem text="About My Module" target="com.galileo.netbeans.module.about"/>
</index>

Together, the previously described XML files configure help topics in the application. In the New File dialog, the JavaHelp Help Set wizard combines them in a very simple procedure. After completing the wizard, simply create HTML files and register them as help topics (as described in the previous sections) so they open in the Help window when accessed by the user.

Typically, you will display external sites in an external browser, since the Help window is inadequate for that purpose. The NetBeans class that helps you in this regard is BrowserDisplayer. Use the object tag in a help topic to reference it:

<object classid="java:org.netbeans.modules.javahelp.BrowserDisplayer">
   <param name="content" value="http://www.netbeans.org">
   <param name="text" value="http://www.netbeans.org">
   <param name="textFontSize" value="medium">
   <param name="textColor" value="blue">
</object >

The BrowserDisplayer class passes the link to the URLDisplayer service. The default implementation of this service is made available, opening the link in the internal Swing HTML browser. Alternatively, you might want the external browser to open instead. Enabling this, we create a class named ExternalURLDisplayer, extending HtmlBrowser.URLDisplayer. This interface is located in the UI Utilities module, on which you set a dependency. This interface includes the showURL() method, providing the link to open a URL. Via this link, pass in a URI to the browse() method of the Java Desktop class, opening the appropriate page in the external browser.

public class ExternalURLDisplayer extends HtmlBrowser.URLDisplayer{
   public void showURL(URL link) {
      try {
         Desktop.getDesktop().browse(link.toURI());
      } catch(Exception ex) {
         Logger.getLogger("global").log(Level.SEVERE, null, ex);
         // show the user a message dialog
      }
   }
}

Next, register this service provider in the module META-INF/services folder, in a file called org.openide.awt.HtmlBrowser$URLDisplayer:

com.galileo.netbeans.module.ExternalURLDisplayer
#position=0

Links to other help topics are created by simply inserting href tags or the nbdocs protocol into your help topics:

<a href="nbdocs://org.netbeans.modules.usersguide/org/netbeans/
   modules/usersguide/configure/configure_options.html">
   Using the options dialog</a>

When using the nbdocs protocol, it is important that you use the code name base of the module to which you will link. In the preceding example, the code name base is org.netbeans. modules.usersguide. After the code name base, specify the path to the applicable help topic. The help system provides an appropriate message if the specified module is not available.

An Options panel consists of a view and a controller. The view provides the GUI, as well as the loading and storing of data. The controller generates the view and mediates between the Options window and the view. The panel that defines the view is derived from the JPanel class. On this panel, you place arbitrary Swing components, which are used to show options in the panel and allow the user to select them.

For example, in Listing 9-9, two text fields are used. The values of these fields are stored and loaded via the Preferences API (see the "Settings Administration" section) using the methods store() and load(). These are called by the controller while opening and closing the panel.

The Options window can be closed by the user when appropriate settings have been selected. At that point, the panel must inform the Options window about its state, either valid or invalid. Implement validation via the valid() method. In this example, we want to make sure the user enters a value in the first field. Accordingly, we add a DocumentListener to the text field. Whenever the user makes an entry in the first text field, the controller is informed via the Controller.changed(), which then calls the valid() method, only returning true when at least one character is entered into the text field.

public final class ModuleOptions1Panel extends JPanel
        implements DocumentListener {
   private JTextField option1;
   private JTextField option2;
   private final ModuleOptions1PanelController controller;
   public ModuleOptions1Panel(ModuleOptions1PanelController  ctrl) {
      this.controller = ctrl;
      initComponents();
      option1.getDocument().addDocumentListener(this);
   }
   public void insertUpdate(DocumentEvent event) {
      controller.changed();
   }
   public void removeUpdate(DocumentEvent event) {
      controller.changed();
   }
   public void changedUpdate(DocumentEvent event) {
      controller.changed();
   }
   public void load() {
      option1.setText(NbPreferences.forModule(ModuleOptions1Panel.class).
              get("option1", "default"));
   }
   public void store() {
      NbPreferences.forModule(ModuleOptions1Panel.class).
              put("option1", option1.getText());
   }
   public boolean valid() {
      if(option1.getText().length() == 0) {
         return false;
      } else {
         return true;
      }
   }
}

Now look at the responsibilities of the controller. Since the controller needs to interact with the Options window, its interfaces are defined by the abstract class OptionsPanelController.

The controller's most important task is creation of the view, using getPanel(), which we provide via the method getComponent(). As you can see in Listing 9-10, getComponent() receives a Lookup. This is a proxy Lookup, containing the Lookups of all controllers available in the Options window. The controller uses the getLookup() method to make a Lookup available, which is already implemented by the abstract class OptionsPanelController. This default implementation provides an empty Lookup. To put objects into the Lookup, override the getLookup() method. This Lookup is received via the getComponent() method, which is used to communicate with other Options panels. See Chapter 6 for a discussion on Lookups.

The method update() is called the first time a panel is accessed. Here, we call the load() method on the panel, which loads data to initialize the fields. When the user clicks the OK button, the applyChanges() method in the Options window is called. Here, the data is saved via the save() method. If the user closes the Options window, we use the cancel() method to handle this scenario, but we obviously do not save the data. Users can also roll back the changes that have been made.

Using the isValid() method, we inform the Options window whether data in the panels is in order. If this is not the case, the OK button is automatically deactivated. Moreover, the Options window must also be informed whether data has been changed. This is done with the isChanged() method.

With the getHelpCtx() method, a HelpCtx object is provided that contains a reference to a help topic displayed if the user clicks the Options window's Help button.

To inform the Options window of changes in data, provide it with code that will register changes. This is achieved via the standard JDK methods addPropertyChangeListener() and removePropertyChangeListener().

You already know the changed() method from the view class ModuleOptions1Panel. This is called when data changes in the view, informing the Options window, which has registered itself as a listener. As a result, the Options window checks again whether data is valid.

final class ModuleOptions1PanelController extends OptionsPanelController  {
   private ModuleOptions1Panel panel;
   private final PropertyChangeSupport pcs = new PropertyChangeSupport(this);
   private boolean changed;
   public JComponent getComponent(Lookup masterLookup) {
      return getPanel();
   }
   private ModuleOptions1Panel getPanel() {
      if (panel == null) {
         panel = new ModuleOptions1Panel(this);
      }
      return panel;
   }
   public void update() {
      getPanel().load();
      changed = false;
   }
   public void applyChanges() {
      getPanel().store();
      changed = false;
   }
   public void cancel() {
   }
   public boolean isValid() {
      return getPanel().valid();
   }
   public boolean isChanged() {
      return changed;
   }

public HelpCtx getHelpCtx() {
      return null;
   }
   public void addPropertyChangeListener(PropertyChangeListener l) {
      pcs.addPropertyChangeListener(l);
   }
   public void removePropertyChangeListener(PropertyChangeListener l) {
      pcs.removePropertyChangeListener(l);
   }
   public void changed() {
      if (!changed) {
         changed = true;
         pcs.firePropertyChange(OptionsPanelController.PROP_CHANGED, false, true);
      }
      pcs.firePropertyChange(OptionsPanelController.PROP_VALID, null, null);
   }
}

Option panels can be integrated declaratively into the application via the layer file. The layer file entries are processed by two factory methods, responsible for Options panel controller creation, dependent on the type of the panel concerned. The wizard creates the necessary entries in the layer file. These are shown in Listing 9-11.

<folder name="OptionsDialog">
  <folder name="Advanced">
    <file name="com-galileo-netbeans-module-ModuleOptions1AdvancedOption.instance">
      <attr name="controller" newvalue="
              com.galileo.netbeans.module.ModuleOptions1OptionsPanelController"/>
      <attr name="displayName" bundlevalue="com.galileo.netbeans.module.Bundle
              #AdvancedOption_DisplayName_ModuleOptions1"/>
      <attr name="instanceCreate" methodvalue="
              org.netbeans.spi.options.AdvancedOption.createSubCategory"/>
      <attr name="keywords" bundlevalue="com.galileo.netbeans.module.Bundle
              #AdvancedOption_Keywords_ModuleOptions1"/>
      <attr name="keywordsCategory" stringvalue="Advanced/null"/>
      <attr name="toolTip" bundlevalue="com.galileo.netbeans.module.Bundle
              #AdvancedOption_Tooltip_ModuleOptions1"/>
    </file>
  </folder>
</folder>

The controller attribute specifies the panel controller, which we looked at earlier. The displayName attribute is a pointer to a bundle where the name of the created panel is stored. The same applies to the toolTip and keywords attributes. The keywordsCategory attribute specifies the relative path to your panel inside the Options window.

Important is the instanceCreate attribute. It is used to specify the factory method, which is new to version 6.5 and is responsible for the controller creation. When dealing with a secondary panel, this is the AdvancedOption.createSubCategory() method.

The registration of a primary panel differs slightly, depending on whether the panel allows secondary panels or not (see Listing 9-12).

<folder name="OptionsDialog">
   <file name="ModuleOptions2OptionsCategory.instance">
      <attr name="categoryName" bundlevalue="com.galileo.netbeans.module.Bundle
              #OptionsCategory_Name_ModuleOptions2"/>
      <attr name="controller" newvalue="
              com.galileo.netbeans.module.ModuleOptions2OptionsPanelController"/>
      <attr name="iconBase" stringvalue="com/galileo/netbeans/module/icon.png"/>
      <attr name="instanceCreate" methodvalue="
              org.netbeans.spi.options.OptionsCategory.createCategory"/>
      <attr name="keywords" bundlevalue="com.galileo.netbeans.module.Bundle
              #OptionsCategory_Keywords_ModuleOptions2"/>
      <attr name="keywordsCategory" stringvalue="ModuleOptions2"/>
      <attr name="title" bundlevalue="com.galileo.netbeans.module.Bundle
              #OptionsCategory_Title_ModuleOptions2"/>
   </file>
</folder>

Additional to the secondary panel, the preceding entries include the primary panel registration and an icon definition via the iconBase attribute. The factory method for a primary panel is OptionsCategory.createCategory(). This type of registration allows no secondary panels, because of the controller attribute, which specifies that the controller provides an Options panel.

If you've checked the option allowing the primary panel to have secondary panels, the preceding layer entry will contain the advancedOptionsFolder attribute instead of the controller attribute:

<attr name="advancedOptionsFolder"
        stringvalue="OptionsDialog/ModuleOptions2OptionsCategory"/>

In this case, you can place your secondary panels under the folder OptionsDialog/ModuleOptions2OptionsCategory.

Using the OptionsDisplayer class, you can access the Options window. You can access this window directly with a particular tab opened as follows:

OptionsDisplayer.getDefault().open("ModuleOptions2OptionsCategory");

As you saw in Chapter 7, the Children class creates and manages child nodes, while also acting as their container. We use this class to manage the categories displayed as genres in the palette. As in most such cases, we start by extending Children.Keys<String>, which has the createNodes() method for generating nodes. In the example that follows (see Listing 9-16), this approach is used to create three genre nodes.

It's possible you'd create the genre nodes from records retrieved from a database. To do this, see Chapter 13, where the connection and usage of databases in the context of NetBeans Platform Applications is discussed, and extend the example by adding a palette.

Start with the GenreNode, which is quite a simple class. Its constructor receives a Genre as a parameter, which is immediately passed to the AlbumNodeContainer class, at which point we find ourselves within the second and third levels of the node hierarchy.

public class GenreNodeContainer extends Children.Keys<String>{
   protected void addNotify() {
      setKeys(new String[] {"root"});
   }
   protected Node[] createNodes(String root) {
      return(new Node[]{
         new GenreNode("Techno, Trance and Dance"),
         new GenreNode("Rock and Pop"),
         new GenreNode("Country and Classic")});
   }
}
public Class GenreNode extends AbstractNode{
   public GenreNode(String genre) {
      super(new AlbumNodeContainer(genre));
      this.setDisplayName(genre);
   }
}

The AlbumNodeContainer class, responsible for the creation of albums for a particular genre, is defined in the same way as the GenreNodeContainer class. In the example in Listing 9-17, we again create three nodes, this time of the AlbumNode type and using the createNodes() method, which receives the genre when the addNotify() method is invoked. That happens when users expand the category node. Using the genre parameter, a database for suitable albums that match the genre might be queried. Album data is managed by the Album class.

public class AlbumNodeContainer extends Children.Keys<String>{
   private String genre = new String();
   public AlbumNodeContainer(String genre) {
      this.genre = genre;
   }
   protected void addNotify() {
      setKeys(new String[] {genre});
   }
   protected Node[] createNodes(String genre) {
      return(new Node[] {
         new AlbumNode(
            new Album("Tunnel Trance Force 39", "42", "2","2007",
                  "com/galileo/netbeans/Module/cover_small.jpg",
                  "com/galileo/netbeans/Module/cover_big.jpg")),
         new AlbumNode(
            new Album("Dream Dance 43", "39", "3", "2007",
                  "com/galileo/netbeans/Module/cover2_small.jpg",
                  "com/galileo/netbeans/Module/cover2_big.jpg")),
         new AlbumNode(
            new Album("DJ Networx 31", "45", "2", "2006",
                  "com/galileo/netbeans/Module/cover3_small.jpg",

"com/galileo/netbeans/Module/cover3_big.jpg"))
      });
   }
}

Finally, the AlbumNode class is responsible for display of the albums in the palette (as you can see in Figure 9-8). Since an AlbumNode does not own its own nodes, we pass the empty container Children.LEAF to the superclass via the constructor.

Use setDisplayName() to define the name shown on the palette. To make the display name more attractive, you may use HTML tags as well. In Listing 9-18, you can see the getLabel() method, which constructs an HTML string that shows the album data in a table and is used by setDisplayName() in the constructor defining the component display name. The value of getHtmlDisplayName() is used by the Palette Manager, which can be opened after right-clicking inside the palette.

Next, getIcon() shows the component icon, which in this case is an album cover. The user selects whether small or large icons are displayed, assuming that they have provided both types of icons.

public class AlbumNode extends AbstractNode {
   private Album album = null;
   public AlbumNode(Album album) {
      super(Children.LEAF);
      this.album = album;
      this.setDisplayName(getLabel());
   }
   public String getHtmlDisplayName() {
      return "<b>" + album.getTitle() + "</b> (" + album.getTracks() + " Tracks)";
   }
   public Image getIcon(int type) {
      return album.getIcon(type);
   }
   private String getLabel() {
      String label = new String("<html>" +
         "<table cellspacing="0" cellpadding="1">" +
            "<tr>" +
               "<td><b>Title </b></td>" +
               "<td>" + album.getTitle() + "</td>" +
             ...
   }
}

Once we create the node hierarchy, providing data for the palette, we initialize the palette and add it to the Lookup of the PlaylistTopComponent. That ensures the palette is displayed whenever the playlist is active.

Use the constructor of the PlaylistTopComponent to provide a root node, from which all child nodes are created. The root node receives a new instance of GenreNodeContainer, handling creation and management of child nodes. Finally, we require a PaletteAction instance, which can simply be empty for now. Later, use createPalette() to create the PaletteController, which is then added to the TopComponent 's local Lookup.

private PlaylistTopComponent() {
   ...
   Node root = new AbstractNode(new GenreNodeContainer());
   PaletteActions a = new MyPaletteActions();
   PaletteController p = PaletteFactory.createPalette(root, a);
   associateLookup(Lookups.fixed(p));
}

What's still missing is drag-and-drop functionality, which lets us drag albums from the palette and drop them onto the TopComponent. Two additional pieces of code are necessary to implement this functionality. First, make some changes to the Album and AlbumNode classes. Next, add code to the TopComponent, which must react appropriately when albums are dropped onto its surface.

The data we transfer onto the TopComponent is defined by the Album class. To allow data to be draggable, we must define the Transferable interface in this class (see Listing 9-19). We create a new DataFlavor, so data can be identified. We create a static instance of the DataFlavor class in the Album. Next, with the method getTransferDataFlavors(), we return our DataFlavor.

Call the method getTransferData() from the TopComponent, using this to retrieve the album instance, assuming the returned DataFlavor is of the type DATA_FLAVOR. If a different DataFlavor is returned, throw an exception.

public class Album implements Transferable {
   public static final DataFlavor DATA_FLAVOR =
            new DataFlavor(Album.class, "album");
   ...
   public DataFlavor[] getTransferDataFlavors() {
      return new DataFlavor[] {DATA_FLAVOR};
   }
   public boolean isDataFlavorSupported(DataFlavor flavor) {
      return flavor == DATA_FLAVOR;
   }
   public Object getTransferData(DataFlavor flavor)
           throws UnsupportedFlavorException {
      if(flavor == DATA_FLAVOR) {
         return this;
      } else {
         throw new UnsupportedFlavorException(flavor);
      }

}
}

Be aware that the user will not be dragging an Album object, but the Node that represents it. We add the drag functionality to the Node, rather than to the Album object itself. This is done by overriding the drag() method in the Node class, which provides a Transferable instance, in our case the Album instance hiding behind the AlbumNode.

public class AlbumNode extends AbstractNode {
   private Album album = null;
   ...
   public Transferable drag() throws IOException {
      return album;
   }
}

Finally, we extend the PlaylistTopComponent such that it takes an action when the palette component is dropped. We also require a TransferHandler registered on the object that displays the result of the dropped component. In our case, we use the table albums with its scroll pane scrollPane.

To define the data that we want to accept and process that data, we begin by implementing our own TransferHandler, called AlbumTransferHandler. In doing so, we simply override two methods. First, we override the canImport() method, which is called when a component is on or over the TopComponent. Here, we determine whether the component is accepted. The test is based on the DataFlavor defined in the Album (see Listing 9-20). If this method returns true, a suitable mouse pointer is shown to the user, indicating that the TopComponent is able to handle the drop event.

Second, we override the importData() method, which is called when the drop event is invoked. Via the TransferSupport object, which is received as a parameter, we obtain the Transferable instance provided by the drag() method from the AlbumNode. We then use getTransferData() and our DataFlavor to obtain the related Album, and then add the data to the JTable.

final class PlaylistTopComponent extends TopComponent {
   private TransferHandler th = new AlbumTransferHandler();
   private PlaylistTopComponent() {
      ...
      albums.setTransferHandler(th);
      scrollPane.setTransferHandler(th);
   }
   private final Class AlbumTransferHandler extends TransferHandler {
      public boolean canImport(TransferSupport support) {
        return support.isDataFlavorSupported(Album.DATA_FLAVOR);
      }
      public boolean importData(TransferSupport support) {
         try {
            Album a = (Album) support.getTransferable().
                    getTransferData(Album.DATA_FLAVOR);

DefaultTableModel model = (DefaultTableModel)albums.getModel();
            model.addRow(new Object [] {
                    a.getTitle(), a.getTracks(), a.getCDs(), a.getYear()} );
            return(true);
         } catch(Exception e) {
            e.printStackTrace();
            return false;
         }
      }
   }
}