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. Choose Window | Favorites and then browse to the "AbcTemplate.abc" file in your module source structure. Notice that the icon assigned to your file type is shown for your file and that you can open the file in the IDE's text editor:

   

3. Next, let's use the IDE to create a new file of our template, using the template registered in the module. To get started, use the New Project dialog (Ctrl-Shift-N) to create any kind of application in the IDE.

4. Once you have a project, 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 a Context-Sensitive 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 org.myorg.abcfiletype.AbcDataObject, which is the fully qualified 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 'File' 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. Optionally, provide an icon to be displayed.

   

   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 actionPerformed method:

   @Override
   public void actionPerformed(ActionEvent ev) {
      FileObject f = context.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.

   The code should now be as follows:

   import java.awt.event.ActionListener;
   import java.awt.event.ActionEvent;
   import org.openide.DialogDisplayer;
   import org.openide.NotifyDescriptor;
   import org.openide.filesystems.FileObject;
   import org.openide.filesystems.FileUtil;
   
   public final class MyAction implements ActionListener {
   
       private final AbcDataObject context;
   
       public MyAction(AbcDataObject context) {
           this.context = context;
       }
   
       public void actionPerformed(ActionEvent ev) {
           FileObject f = context.getPrimaryFile();
           String displayName = FileUtil.getFileDisplayName(f);
           String msg = "I am " + displayName + ". Hear me roar!";
           NotifyDescriptor nd = new NotifyDescriptor.Message(msg);
           DialogDisplayer.getDefault().notify(nd);
       }
   
   }

6. Open the layer.xml file and notice that your Action has been registered in the "Loaders" folder, as follows:

   ...
   ...
   ...
     <folder name="Loaders">
           <folder name="text">
               <folder name="x-abc">
                   <folder name="Actions">
                       <file name="org-myorg-abcfiletype-MyAction.shadow">
                           <attr name="originalFile" stringvalue="Actions/File/org-myorg-abcfiletype-MyAction.instance"/>
                           <attr name="position" intvalue="0"/>
                       </file>
                       <file name="org-openide-actions-CopyAction.shadow">
                           <attr name="originalFile" stringvalue="Actions/Edit/org-openide-actions-CopyAction.instance"/>
                           <attr name="position" intvalue="400"/>
                       </file>
                       <file name="org-openide-actions-CutAction.shadow">
                           <attr name="originalFile" stringvalue="Actions/Edit/org-openide-actions-CutAction.instance"/>
                           <attr name="position" intvalue="300"/>
                       </file>
                       <file name="org-openide-actions-DeleteAction.shadow">
                           <attr name="originalFile" stringvalue="Actions/Edit/org-openide-actions-DeleteAction.instance"/>
                           <attr name="position" intvalue="600"/>
                       </file>
                       <file name="org-openide-actions-FileSystemAction.shadow">
                           <attr name="originalFile" stringvalue="Actions/System/org-openide-actions-FileSystemAction.instance"/>
                           <attr name="position" intvalue="1100"/>
                       </file>
                       <file name="org-openide-actions-OpenAction.shadow">
                           <attr name="originalFile" stringvalue="Actions/System/org-openide-actions-OpenAction.instance"/>
                           <attr name="position" intvalue="100"/>
                       </file>
                       ...
                       ...
                       ...

   Notice that the "org-openide-actions-OpenAction.shadow" file is registered at position 100, while your new Action is registered at position 0. The Action in the first position is the Action known as the "default Action" and will be invoked when the file is created. Rather than invoking your new Action, it makes more sense to invoke the Open Action instead, whenever the file is created. Therefore, change the position in "org-openide-actions-OpenAction.shadow" to 0 and change your own Action's position to 100.

7. Run the module again, as you did in the previous section.

8. 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:

   

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

   

You now know how to create a new context-sensitive 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 text editor. However, it's more likely that you may want to create a custom editor. Some custom editors are for text editing, while others provide a visual representation of the underlying file. In the latter case, you want to let the user drag and drop widgets onto the visual representation of the underlying file. 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 and points you to a tutorial you can follow for extending the window to include widgets from the NetBeans Visual Library.

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.

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 of the TopComponent. To provide a multiview element for the description in the previous step, we need to implement MultiViewElement:

   public final class AbcTopComponent extends CloneableTopComponent implements MultiViewElement {

4. In the TopComponent, you now need to delete (or comment out) the methods findInstance(), getPersistenceType(), writeProperties(), readProperties(), , readPropertiesImpl() and preferredID() because these methods are handled by the MultiViewElement. Also remove the @ConvertAsProperties annotation at the top of the TopComponent, since serialization will also need to be handled via the MultiViewElement implementation.

   Don't worry about any remaining red underline markings; these will be resolved in the next step in this tutorial.

5. 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, in the TopComponent:

       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;
       }

6. 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();
       }
   
   }

7. 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.

8. 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 TopComponent, and then instantiate the MultiViewDescription class in the OpenSupport extension class, as shown above.

1. Open the AbcDataObject class and notice this method:

   @Override
   protected Node createNodeDelegate() {
       return new DataNode(this, Children.LEAF, getLookup());
   }

   The method above provides a default Node for the underlying file. The default Node has no child nodes, which is evident by the "Children.LEAF" parameter that you see above.

   Instead of passing in "Children.LEAF", use the ChildFactory class to create new child nodes of our Node class:

   @Override
   protected Node createNodeDelegate() {
       return new DataNode(
               this,
               Children.create(new AbcChildFactory(this), true),
               getLookup());
   }

2. Define the ChildFactory as follows:

   private static class AbcChildFactory extends ChildFactory<String> {
   
       private final AbcDataObject dObj;
   
       public AbcChildFactory(AbcDataObject dObj) {
           this.dObj = dObj;
       }
   
       @Override
       protected boolean createKeys(List list) {
           FileObject fObj = dObj.getPrimaryFile();
           try {
               List<String> dObjContent = fObj.asLines();
               list.addAll(dObjContent);
           } catch (IOException ex) {
               Exceptions.printStackTrace(ex);
           }
           return true;
       }
   
       @Override
       protected Node createNodeForKey(String key) {
           Node childNode = new AbstractNode(Children.LEAF);
           childNode.setDisplayName(key);
           return childNode;
       }
   
   }

3. In your module, open AbcTemplate.abc and enter the following text, or something like it, i.e., add several lines of text to your template file:

   hello
   world
   how are things
   today

4. Run the module again and then notice that you can expand the template file:

   

1. Open the AbcDataObject class and change the createNodeDelegate method so that our own AbcNode will be created instead of the generic DataNode:

   @Override
   protected Node createNodeDelegate() {
       return new AbcNode(
               this,
               Children.create(new AbcChildFactory(this), true),
               getLookup());
   }

   The AbcNode does not exist yet, you will create it in the next step.

2. Define the AbcNode as follows:

   class AbcNode extends DataNode {
   
       public AbcNode(AbcDataObject aThis, Children kids, Lookup lookup) {
           super(aThis, kids, lookup);
       }
   
       @Override
       protected Sheet createSheet() {
           Sheet sheet = super.createSheet();
           Sheet.Set set = Sheet.createPropertiesSet();
           sheet.put(set);
           set.put(new LineCountProperty(this));
           return sheet;
       }
   
       private static class LineCountProperty extends ReadOnly<Integer> {
   
           private final AbcNode node;
   
           public LineCountProperty(AbcNode node) {
               super("lineCount", Integer.class, "Line Count", "Number of Lines");
               this.node = node;
           }
   
           @Override
           public Integer getValue() throws IllegalAccessException, InvocationTargetException {
               int lineCount = 0;
               DataObject abcDobj = node.getDataObject();
               FileObject abcFo = abcDobj.getPrimaryFile();
               try {
                   lineCount = abcFo.asLines().size();
               } catch (IOException ex) {
                   Exceptions.printStackTrace(ex);
               }
               return lineCount;
           }
   
       }
   
   }

3. Run the module again, open the Properties window, and notice your property is displayed:

   

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.