File Type Integration Tutorial

1. In the Projects window, right-click the Abc File Type project and choose Run.

   A new instance of the IDE starts, installing your module into itself.

2. Use the New Project dialog (Ctrl-Shift-N) to create any kind of application in the IDE.
3. Right-click the application node and choose New > Other. In the Other category, a template is available for working with the new file type:

   

   Complete the wizard and you will have created a template that can be used for starting off the user's work with the given file type.

   If you want to provide default code via the template, add the code to the AbcTemplate.abc file that the New File Type wizard created for you.

Adding an Action

In this subsection, we use the New Action wizard to create a Java class that will perform an action for our file type. The wizard will also register the class in the layer.xml file such that the user will be able to invoke the action from the right-click contextual menu of the file type's node in an explorer window.

1. Right-click the project node and choose New > Action.
2. In the Action Type panel, click Conditionally Enabled. Type AbcDataObject, which is the name of the data object generated above by the New File Type wizard, as shown below:

   

   Click Next.

3. In the GUI Registration panel, select the 'Edit' category in the Category drop-down list. The Category drop-down list controls where an action is shown in the Keyboard Shortcuts editor in the IDE.

   Next, Unselect Global Menu Item and then select File Type Contect Menu Item. In the Content Type drop-down list, select the MIME type you specified above in the New File Type wizard, as shown below:

   

   Notice that you can set the position of the menu item and that you can separate the menu item from the item before it and after it. Click Next.

4. In the Name and Location panel, type MyAction as the Class Name and type My Action as the Display Name. Menu items provided by contextual menus do not display icons. Therefore, click Finish and MyAction.java is added to the org.myorg.abcfiletype package.
5. In the Source Editor, add some code to the action's performAction method:

   protected void performAction(Node[] activatedNodes) {
   	AbcDataObject abcDataObject = activatedNodes[0].getLookup().lookup(AbcDataObject.class);
   	FileObject f = abcDataObject.getPrimaryFile();
   	String displayName = FileUtil.getFileDisplayName(f);
   	String msg = "I am " + displayName + ". Hear me roar!"; 
   	NotifyDescriptor nd = new NotifyDescriptor.Message(msg);
   	DialogDisplayer.getDefault().notify(nd);
   }

   Press Ctrl-Shift-I. The IDE automatically adds import statements to the top of the class.

   Some code is still underlined in red, to indicate that not all of the required packages are on the classpath. Right-click the project node, choose Properties, and click Libraries in the Project Properties dialog box. Click add at the top of the Libraries pane and add the Dialogs API.

   In the MyAction.java class, press Ctrl-Shift-I again. The red underlining disappears because the IDE finds the required packages in the Dialogs API.

6. In the Important Files node, expand XML Layer. The two nodes <this layer> and <this layer in context>, together with their subnodes, make up the System Filesystem Browser. Expand <this layer>, expand Loaders, continue expanding nodes until you see the Action that you created above.
7. Drag-and-drop My Action so that it appears below the Open action, as shown below:

   

   As you can see from the last two steps, the System Filesystem Browser can be used to quickly reorganize the sequence of the items that are registered in the System Filesystem.

8. Run the module again, as you did in the previous section.
9. Create an ABC file, using the template shown in the previous section, and right-click the file's node in one of the explorer views, such as in the Projects window or Favorites window.

   Notice that the Abc file has the icon you assigned to it in its module and that the list of actions defined in its layer.xml file is available from the right-click contextual menu:

   

10. Choose the new menu item, the Abc file's name and location are shown:

    

You now know how to create a new action that appears in the context menu of a file of the given type, in the Projects window, Files window or the Favorites window.

Opening the File into a Window

By default, when the user opens a file of the type that we have defined in this tutorial, the file will open into a basic editor. However, sometimes you may want to create a visual representation of the file, and let the user drag and drop widgets onto the visual representation. The first step in creating such a user interface is to let the user open the file into a window. This subsection shows you how to do that.

1. Right-click the project node and choose New > Window Component. Set "editor" for Window Position and "Open on Application Start", as shown below:

   

2. Click Next and type "Abc" as the Class Name Prefix:

   

   Click Finish.

3. Change the DataObject to use OpenSupport instead of DataEditorSupport, by changing the DataObject's constructor as follows:

   public AbcDataObject(FileObject pf, MultiFileLoader loader)
           throws DataObjectExistsException, IOException {
   
       super(pf, loader);
       CookieSet cookies = getCookieSet();
       //cookies.add((Node.Cookie) DataEditorSupport.create(this, getPrimaryEntry(), cookies));
       cookies.add((Node.Cookie) new AbcOpenSupport(getPrimaryEntry()));
                 
   }

4. Create the OpenSupport class:

   class AbcOpenSupport extends OpenSupport implements OpenCookie, CloseCookie {
   
       public AbcOpenSupport(AbcDataObject.Entry entry) {
           super(entry);
       }
   
       protected CloneableTopComponent createCloneableTopComponent() {
           AbcDataObject dobj = (AbcDataObject) entry.getDataObject();
           AbcTopComponent tc = new AbcTopComponent();
           tc.setDisplayName(dobj.getName());
           return tc;
       }
    
   }

   Tweak the TopComponent to extend CloneableTopComponent, instead of TopComponent. Set the TopComponent's class modifier, and its constructor's modifier, to public instead of private.

Run the module again and then, when an Abc file is opened, the OpenSupport class handles the opening, such that it opens the file into the TopComponent instead of the basic editor that DataEditorSupport provides:

The NetBeans Visual Library Tutorial provides an example of what you can do to develop the TopComponent further such that it will visually display the content of a file that corresponds to the file type defined in this tutorial.

Creating a Multiview Window

Now that we are able to open a file into a window, let's make the window more interesting. We'll create a multiview window. The first tab of a multiview window is typically used to display a visual representation of the file, while the second tab typically shows the source view. More than two tabs can also be provided, each tab providing further levels of detail about the opened file.

1. Right-click the project node and choose Properties. In the Project Properties dialog, choose Libraries, and click Add. Set a dependency on "MultiView Windows". Click OK and then click OK again to exit the Project Properties dialog.

2. For each tab that you want to create in the multiview window, create a class that implements MultiViewDescription and Serializable.

   For purposes of this tutorial, start by creating a class called AbcMultiviewDescription1, implementing the specified classes:

   public class AbcMultiviewDescription1 implements MultiViewDescription, Serializable {
   
       public int getPersistenceType() {
           throw new UnsupportedOperationException("Not supported yet.");
       }
   
       public String getDisplayName() {
           throw new UnsupportedOperationException("Not supported yet.");
       }
   
       public Image getIcon() {
           throw new UnsupportedOperationException("Not supported yet.");
       }
   
       public HelpCtx getHelpCtx() {
           throw new UnsupportedOperationException("Not supported yet.");
       }
   
       public String preferredID() {
           throw new UnsupportedOperationException("Not supported yet.");
       }
   
       public MultiViewElement createElement() {
           throw new UnsupportedOperationException("Not supported yet.");
       }
   
   }

   In the AbcMultiviewDescription1 class above, the method createElement() returns a MultiViewElement. What you want to return here is your TopComponent, which we will do in the next step.

3. Rewrite the class signature. To provide a multiview element for the description in the previous step, we need to extend JPanel instead of TopComponent and we need to implement MultiViewElement:

   public final class AbcTopComponent extends JPanel implements MultiViewElement {

   In the TopComponent, you now need to delete (or comment out) the methods findInstance(), getPersistenceType(), writeReplace() and preferredID().

4. For the moment, provide very simple implementations of each of the required methods. Start by defining a new JToolbar at the top of the TopComponent class:

   private JToolBar toolbar = new JToolBar();

   Next, implement the methods as follows:

       public JComponent getVisualRepresentation() {
           return this;
       }
   
       public JComponent getToolbarRepresentation() {
           return toolbar;
       }
   
       public void setMultiViewCallback(MultiViewElementCallback arg0) {
       }
   
       public CloseOperationState canCloseElement() {
           return null;
       }
   
       public Action[] getActions() {
           return new Action[]{};
       }
   
       public Lookup getLookup() {
           return Lookups.singleton(this);
       }
   
       public void componentShowing() {
       }
   
       public void componentHidden() {
       }
   
       public void componentActivated() {
       }
   
       public void componentDeactivated() {
       }
   
       public UndoRedo getUndoRedo() {
           return UndoRedo.NONE;
       }

5. Now you can redefine the AbcMultiviewDescription1 as follows:

   public class AbcMultiviewDescription1 implements MultiViewDescription, Serializable {
   
       public int getPersistenceType() {
           return TopComponent.PERSISTENCE_ALWAYS;
       }
   
       public String getDisplayName() {
           return "Tab 1";
       }
   
       public Image getIcon() {
           return ImageUtilities.loadImage("/org/myorg/abcfiletype/Datasource.gif");
       }
   
       public HelpCtx getHelpCtx() {
           return null;
       }
   
       public String preferredID() {
          return "AbcMultiviewDescription1";
       }
   
       public MultiViewElement createElement() {
           return new AbcTopComponent();
       }
   
   }

6. Change the createCloneableTopComponent method in the OpenSupport class to open your TopComponent via the MultiViewDescription class you created above:

   protected CloneableTopComponent createCloneableTopComponent() {
   
       // Create an array of multiview descriptors:
       AbcMultiviewDescription1 firstTab = new AbcMultiviewDescription1();
       MultiViewDescription[] descriptionArray = { firstTab };
   
       // Create the multiview window:
       CloneableTopComponent tc = MultiViewFactory.createCloneableMultiView(descriptionArray, firstTab,  null);
       tc.setDisplayName(entry.getDataObject().getName());
       return tc;
   
   }

   The second argument in MultiViewFactory.createCloneableMultiView determines which of the tabs is open by default. Here it is firstTab, the tab defined by AbcMultiViewDescription1.

7. Install and open the file again. Now you have a multiview window with one tab:

   

You now have a single tab in a multiview window. For each additional tab, create a new MultiviewDescription class, with a new JPanel, and then instantiate the MultiViewDescription class in the OpenSupport extension class, as shown above.

1. In the Projects window, right-click the Abc File Type project and choose Create NBM.

   The NBM file is created and you can view it in the Files window (Ctrl-2):

   

2. Make it available to others via, for example, the NetBeans Plugin Portal. The recipient should use the Plugin Manager (Tools > Plugins) to install it.