NetBeans Code Completion Tutorial

This tutorial shows you how to implement the Editor Code Completion API. You will be shown how to implement the API in the context of HTML files. When the user invokes the code completion feature, a code completion box will appear, displaying words that can complete the text typed in the editor. At the end of this tutorial, HTML files will have a code completion box as follows:

The content of the code completion box will come from country names retrieved from the JDK's java.util.Locale package.

Contents

• Introduction to Code Completion Integration
• Creating the Module Project
• Implementing the Completion Provider Class
  • Implementing the createTask Method
  • Implementing the getAutoQueryTypes Method
• Implementing the Completion Item Class
  • Implementing the Action
  • Implementing the Filter
  • Implementing the Tooltip and Documentation Task

To follow this tutorial, you need the software and resources listed in the following table.

Software or Resource	Version Required
NetBeans IDE	version 7.0 or above
Java Developer Kit (JDK)	Version 6

Optionally, for troubleshooting purposes, you can download the completed sample and inspect the sources.

Introduction to Code Completion Integration

Two classes apply to code completion and these will be developed in this tutorial:

• CompletionItem
• CompletionProvider

Both of these come from the Editor Code Completion API and are implemented in this tutorial's module as CountriesCompletionItem and CountriesCompletionProvider.

Creating the Module Project

In this section, we use a wizard to create the source structure that every NetBeans module requires. The source structure consists of certain folders in specific places and a set of files that are always needed. For example, every NetBeans module requires a nbproject folder, which holds the project's metadata, and a layer.xml file, for declarative registration of items such as toolbar buttons and windows.

1. Choose File > New Project (Ctrl-Shift-N). Under Categories, select NetBeans Modules. Under Projects, select Module and click Next.
2. In the Name and Location panel, type CountryCodeCompleter in Project Name. Change the Project Location to any directory on your computer, such as c:\mymodules. Leave the Standalone Module radiobutton selected. Click Next.
3. In the Basic Module Configuration panel, type org.netbeans.modules.countries as the Code Name Base. Do not select the "Generate XML Layer" checkbox and do not select the "Generate OSGi Bundle" checkbox. Leave the location of the localizing bundle and XML layer as they are, so that they will be stored in a package with the name org/netbeans/modules/countries. Click Finish.

The IDE creates the CountriesCodeCompleter project. The project contains all of your sources and project metadata, such as the project's Ant build script. The project opens in the IDE. You can view its logical structure in the Projects window (Ctrl-1) and its file structure in the Files window (Ctrl-2).

Implementing the Completion Provider Class

The first class we will deal with when creating a code completion feature for HTML files is the CompletionProvider. As the user types in an editor, the code completion infrastructure asks all code completion providers registered in the XML layer file to create CompletionTasks. The tasks are created by the CompletionProvider.createTask method. What happens when the method is invoked is up to the implementation. In our implementation, we will create a CompletionItem for a list of countries.

1. Right-click the CountryCodeCompleter project and choose New > Java Class.
2. In Class Name, type CountriesCompletionProvider. In Package, choose org.netbeans.modules.countries. Click Finish.

3. Right-click the CountryCodeCompleter project and choose Properties. In the Project Properties dialog box, click Libraries. Click Add next to the Module Dependencies list. Scroll to "Editor Code Completion" and click OK. Click OK again to exit the Project Properties dialog box. You have now set a dependency on the Editor Code Completion module, which provides the API classes that we need in this tutorial.

   Do the same for "MIME Lookup API", which provides the Java annotation for registering completion providers, and the "Utilities API".

4. In the CountriesCompletionProvider class, change the signature so that the class implements CompletionProvider. Place the cursor on the line that defines the signature. A lightbulb appears. Click it and the IDE adds an import statement for org.netbeans.spi.editor.completion.CompletionProvider. The lightbulb appears again. Click it again and the IDE creates skeleton methods for the two methods required by the CompletionProvider class. You should now see this:

   package org.netbeans.modules.CountryCodeCompleter;
   
   import javax.swing.text.JTextComponent;
   import org.netbeans.spi.editor.completion.CompletionProvider;
   import org.netbeans.spi.editor.completion.CompletionTask;
   
   public class CountriesCompletionProvider implements CompletionProvider {
       
       public CountriesCompletionProvider() {
       }
   
       public CompletionTask createTask(int queryType, JTextComponent component) {
       }
   
       public int getAutoQueryTypes(JTextComponent component, String typedText) {
       }
       
   }
                   

5. Before coding the CompletionProvider class, let's register it in the XML layer file.

   package org.netbeans.modules.countries;
   
   import javax.swing.text.JTextComponent;
   import org.netbeans.api.editor.mimelookup.MimeRegistration;
   import org.netbeans.spi.editor.completion.CompletionProvider;
   import org.netbeans.spi.editor.completion.CompletionTask;
   
   @MimeRegistration(mimeType = "text/html", service = CompletionProvider.class)
   public class CountriesCompletionProvider implements CompletionProvider {
   
       @Override
       public CompletionTask createTask(int queryType, JTextComponent component) {
           throw new UnsupportedOperationException("Not supported yet.");
       }
   
       @Override
       public int getAutoQueryTypes(JTextComponent component, String typedText) {
           throw new UnsupportedOperationException("Not supported yet.");
       }
       
   }

   Read @MimeLocation, @MimeRegistration and @MimeRegistrations added for details on the annotation above.

Implementing the Completion Item Class

In this section we will create a class that implements CompletionItem. Once we have defined this class, we will fill out the query method in the CompletionProvider class. The CompletionProvider will create instances of our CompletionItem.

1. Right-click the CountryCodeCompleter project and choose New > Java Class. In Class Name, type CountriesCompletionItem. In Package, choose org.netbeans.modules.countries. Click Finish.
2. We will return to this class in later steps. For now, we will fill out the query method that we defined in the CompletionProvider class. Fill out the AsyncCompletionTask as follows, and note the explanatory comments in the code:

   return new AsyncCompletionTask(new AsyncCompletionQuery() {
   
       @Override
       protected void query(CompletionResultSet completionResultSet, Document document, int caretOffset) {
   
           //Iterate through the available locales
           //and assign each country display name
           //to a CompletionResultSet:
           Locale[] locales = Locale.getAvailableLocales();
           for (int i = 0; i < locales.length; i++) {
               final Locale locale = locales[i];
               final String country = locale.getDisplayCountry();
               if (!country.equals("")) {
                   completionResultSet.addItem(new CountriesCompletionItem(country, caretOffset));
               }
           }
   
           completionResultSet.finish();
       }
   
   }, component);

   A red underline remains, after you let the IDE add various import statements. The error underline tells you that the CompletionItem's constructor does not expect the values that you are passing to it. In the next step, we will fill out the CompletionItem so that it meets the requirements of the CompletionProvider.

   Read Java Classes in Code Completion to learn how to put Java classes in the code completion box, instead of the locales that are used above.

3. In the CountriesCompletionItem class, change the signature so that the class implements CompletionItem. Let the IDE create import statements and skeleton implementations for the class's required methods. Read the entry in the NetBeans Javadoc for CompletionItem to begin to understand what each of the methods is for. For now, we will implement a minimal completion item, just enough to be able to compile the module and see the code completion box.
4. In the CountriesCompletionItem class, define the constructor as follows:

   private String text;
   private static ImageIcon fieldIcon =
           new ImageIcon(Utilities.loadImage("org/netbeans/modules/countries/icon.png"));
   private static Color fieldColor = Color.decode("0x0000B2");
   private int caretOffset;
   
   public CountriesCompletionItem(String text, int caretOffset) {
       this.text = text;
       this.caretOffset = caretOffset;
   }

   Note that here we're referencing an icon. This is the icon that will appear next to each entry represented by the CompletionItem in the code completion box. The icon can be any icon with a dimension of 16x16 pixels. For example, you could make use of this icon:

   

   If you like, you can right-click the image above and save it to the location specified in the ImageIcon definition above.

5. Next define the getPreferredWidth() and render() methods as follows:

   public int getPreferredWidth(Graphics graphics, Font font) {
       return CompletionUtilities.getPreferredWidth(text, null, graphics, font);
   }
   
   public void render(Graphics g, Font defaultFont, Color defaultColor,
           Color backgroundColor, int width, int height, boolean selected) {
       CompletionUtilities.renderHtml(fieldIcon, text, null, g, defaultFont,
               (selected ? Color.white : fieldColor), width, height, selected);
   }
                   

   Define the getSortText() method as follows:

   public CharSequence getSortText() {
       return text;
   }
                   

   Next, define the getInsertPrefix() method:

   public CharSequence getInsertPrefix() {
       return text;
   }

   Finally, create dummy implementations of the remaining methods. So, return null for createDocumentationTask(), createToolTipTask(), and getInsertPrefix(). Then return false for instantSubstitution() and return 0 for getSortPriority().

6. Right-click the module and choose Run. A new instance of the IDE starts up and installs your module. Open an HTML file in the IDE. Type something and press Ctrl-Space.

   You should now see the following:

   

   When you press Enter in the list above, nothing happens. That is because we have not defined the defaultAction() method yet. We will do so in the next section. Also note that the list does not narrow while you are typing. That is because we have not created a filter yet. The filter will detect what we are typing and adjust the entries in the list accordingly. We will create a filter in a later section.

Congratulations, you have now completed a simple implementation of a code completion integration module.