How to use certain NetBeans APIs

How to use Common Annotations?

CheckReturnValue annotated method

When the method return value is important value to check (or the only effect the method has) the method can be annotated with CheckReturnValue. Annotation servers as documentation as well as a hint for static code analysis.

CheckForNull annotated method

Method annotated with CheckForNull may return null value. Annotation servers as documentation as well as a hint for static code analysis.

NonNull annotated element

When the field, parameter, local variable or return value of the method must not be null the NonNull annotation can be used to clearly express this. It servers as documentation as well as a hint for static code analysis.

NullAllowed annotated element

Field, parameter or local variable annotated with NullAllowed can contain null value so null check should occur before any dereference. Annotation servers as documentation as well as a hint for static code analysis.

NullUnknown annotated element

Annotation NullUnknown complementing other nullness annotations servers for cases where the element may or may not be null under certain defined circumstances (usage).

SuppressWarnings annotated element

When the analysis tool report false warning it is possible to use SuppressWarning annotation to suppress the warning.

How to use Progress API?

Basic usage

There are 3 types of progress indication:

• 1. indefinite when it's not known how much time will be needed to complete
• 2. definite with time estimate for completion (UI shows time that remains)
• 3. definite without time estimate where the UI shows percentage completed.

The default location of the progress indication is the status bar which aggregates all tasks running in the IDE that show progress. However it's possible to exclude the task from the default location and show the progress in one's custom dialog component. In such a case the same task should not appear in the status line component as well.

It's possible to request cancelling the task from status line progress aggregator if the task allows cancelling.

Progress tasks that get started as a result of explicit user action takes precedence in the status line docked component over tasks that are triggered by the system. (say filesystem refresh for example)

The most common usecase of the API looks like this:

ProgressHandle handle = ProgressHandleFactory.creatHandle("My custom task");
...
// we have 100 workunits
// at this point the task appears in status bar.
handle.start(100);
...
handle.progress(10);
...
handle.progress("half way through", 50);
...
handle.progress(99);
// at this point the task is finished and removed from status bar
// it's not realy necessary to count all the way to the limit, finish can be called earlier.
// however it has to be called at the end of the processing.
handle.finish();

Advanced Usage

In case your usage of the API

• spans across multiple independent modules,
• requires adjusting of number of workunits or
• triggers additional action based on the current progress

then you should consider using the aggregating version of APIs which is similar to the simple APIs but has distinctive differences and additions that allow for more complex scenarios.

It allows to compose the progress bar from 1+ independent sources, all sharing proportional piece of the progress bar. Additionally you can monitor the task's overall progress from one central place and possibly add more contributing sources of the progress during processing.

        // let's have a factory for client code that performs some part of the job to be done..
        Lookup.Result res = Lookup.getDefault().lookup(new LookupTemplate(MyWorkerFactory.class));
        Iterator it = res.allInstances().iterator();
        ProgressContributor[] contribs = new ProgressContributor[res.allInstances().size()];
        int i = 0;
        while (it.hasNext()) {
            MyWorkerFactory prov = (MyWorkerFactory)it.next();
            contribs[i] = AggregateProgressFactory.createProgressContributor("Module X contribution");
            MyWorker worker = prov.createWorker(contribs[i]);
            //... snip ... do something with the worker..
            i = i + 1;
        }
        AggregateProgressHandle handle = AggregateProgressFactory.createHandle("My Task", contribs, null, null);
        // non-cancellable and with out output link.
        
        // calling start() at the time when the actual long running task starts processing
        handle.start("here we go");
        // ...snip...
        // now the individual MyWorker instances log their progress.
        // possibly in other threads too..
        // ... snip...
        // 
        if (myConditionThatSpawnsAnotherContributor()) {
            ProgressContributor cont = AggregateProgressFactory.createProgressContributor("Additional exceptional contribution");
            handle.addContributor(cont);
            // ... snip ...
        }
        
        // the task is finished when all the ProgressContributors finish..

How to use Search API?

Search History

SearchHistory is synchronising history content through netbeans modules and it saves history to preferences.

There are two separate histories. One for search and another for replace. When you add your propertyListener to SearchHistory - you can listen for changes in histories.

SearchHistory has methods for adding new entries and getting whole history list.

SearchInfo API & SPI

This use-case was formerly covered by module org.openidex.search.

The SearchInfo API+SPI allows other modules to specify whether and how should nodes they define be searched.

The definition is represented by objects extending class SearchInfoDefinition . To customize searching on a custom node, a SearchInfoDefinition object must be added to the node's lookup. In most cases, there is no need to define own class extending the class - one can use factory methods of class SearchInfoDefinitionFactory .

In some cases implementators may need to apply the same set of SearchFilterDefinitions in the whole subtree of a node. If so, it is not needed to put SearchInfoDefinition to all nodes' lookups, but only one instance of SubTreeSearchOptions have to be put into the lookup of the root node.

Enhance IDE searching features

People that want to enhance IDE searching features (with custom search criteria or specialized algorithms) can add a new tab to the "Search in Projects" dialog.

They need to implement several classes:

• SearchProvider to register the new search feature to the IDE or platform application.
• SearchProvider.Presenter that creates visual component for adding to the search dialog and that can interact with dialog buttons.
• SearchResultsDisplayer to show search results to the user.
• SearchComposition that encapsulates setting and state of searches, provide access to result displayer, and is able to start and terminate the search.

Search in Projects API

This API enables other modules to open Find in Projects dialog with some pre-defined criteria and to start searching programatically.

How to use Visual Library API?

See documentation for complete set of use-cases.

How to use MultiView Windows?

MultiView faq:

How does serialization work?

First of all, you don't need to worry about serialization if all your MultiViewDescription instances contained in the multiview state to be non serializable. Meaning they all return TopComponent.PERSISTENCE_NEVER in MultiViewDescription.getPersistenceType().

If at least one of the views requires serialization, you have no choice but to make all MultiViewDescription implementors serializable. You also can persist the MultiViewElement instances that the multiview contains. The algorithm here is a bit complicated for performance reasons. Only those Elements are stored that were created during the session and which are Serializable. So if the user never switches to the 4rd tab, and it's corresponding element and visual component never get created, then it won't be stored. (We would have to create it just for the sake of persistance). So if your visual component needs some inital context for creation, you should store it in the description instance, and if the visual component wants to store it's state (location of cursor, selected field, something else that makes sense for the opened component) you should store it in the MultiViewElement. So basically if you are always able create the Element from Description without any persisted data, you don't need to persist anything.

If you define your own CloseOperationHandler implementation for the multiview component, then you also ought to define it Serializable. Otherwise it will be silently replaced by the default handler on restoration of the multiview component.

How to set the display name?

Each MultiViewDescription defines display name and icon. While the icon is meant for the whole document/view tab, the display name is just for the inner switching button. So how does one set the name for the whole MultiView component? It can be done when creating the component.

    TopComponent mvtc = MultiViewFactory.createMultiView(myDescriptions);
    mvtc.setDisplayName("My static mvtc displayName");

Later in the lifecycle of the component, it can be also influenced from within the individual multiview visual elements using the MultiViewElementCallback.updateTitle() method.

How to use UI Handler Library?

XXX no answer for arch-usecases

How to use Auto Update Services?

Browse all available units

Browse all units by chosen style (e.g. modules, features, localization)

Browse installed modules

Search for new functionality

Install new functionality

• Client needs install NetBeans module in required minimal specification version.
• Find corresnponing UpdateUnit by module's code name and finds UpdateElement what fits the required version.
• So, the client now have UpdateElement which wants to install.
• Take the OperationContainer for install, e.g. OperationContainer.createForInstall
• Adds the element into container OperationContainer.add(UpdateElement) and gets OperationInfo for that operation.
• Identify other required elements: OperationInfo.getRequiredElements()
• Check if there is no broken dependencies: OperationInfo.getBrokenDependency() Note: if there are some broken dependencies then operation cannot continue.
• If all okay, then install the unit: OperationContainer.doOperation()

Update of installed unit

Uninstall functionality

• Client knows UpdateElement which wants to uninstall.
• Take the OperationContainer for uninstall, e.g. OperationContainer.createForUninstall
• Adds the element into container OperationContainer.add(UpdateElement) and gets OperationInfo for that operation.
• Identify other required elements: OperationInfo.getRequiredElements()
• If all okay, then uninstall the unit: OperationContainer.doOperation()

Switch off functionality

• Client knows UpdateElement which wants to uninstall.
• Take the OperationContainer for disable, e.g. OperationContainer.createForDisable
• Adds the element into container OperationContainer.add(UpdateElement) and gets OperationInfo for that operation.
• Identify other required elements: OperationInfo.getRequiredElements()
• If all okay, then disable the unit: OperationContainer.doOperation()

Switch on functionality

Rollback of previous update

• Client knows UpdateElement which wants to uninstall.
• Take the OperationContainer for enable, e.g. OperationContainer.createForEnable
• Adds the element into container OperationContainer.add(UpdateElement) and gets OperationInfo for that operation.
• Identify other required elements: OperationInfo.getRequiredElements()
• If all okay, then enable the unit: OperationContainer.doOperation()

Resolve problems what accrued while processing operation

Make IDE up-to-date

Get all subscriptions to Update Center

Subscribe new Update Center

Customization of Update Center subscription

Unsubscribe of some Update Center

Refresh content of subscribed Update Center

Specify the cluster where to install

Get all installed files of given unit

How to use Auto Update UI?

Download and Install

How to use MIME Lookup API?

Per mime-type operation

Provide list of instances as lookup result

Nested mime-types

Known clients summary

Find class instances for the given mime-type

Getting embeded mime-type specific Lookup

    MimePath scriptletPath = MimePath.parse("text/x-jsp/text/x-java");
    Lookup lookup = MimeLookup.getLookup(scriptletPath);

Providing implemented MimeLookupInitializer

How to use Keyring API?

XXX no answer for arch-usecases

How to use Options Dialog and SPI?

Register top level Options Panel

Client can install new panel to Options Dialog - see JavaDoc for OptionsCategory class.

Register panel to Advanced Options Panel

Client can install new panel to Advanced Options Panel - see JavaDoc for AdvancedOption class.

How to use Print?

The typical client of Print module can be any tool to print custom data.

The simple way to enable printing for a custom data is:

If the data is a Swing component which extends javax.swing.JComponent and shown in a org.openide.windows.TopComponent, the key "print.printable" (PrintManager.PRINT_PRINTABLE) with value "Boolean.TRUE" in the component must be set as a client property. See example:

      public class MyComponent extends javax.swing.JComponent {
        public MyComponent() {
          ...
          putClientProperty("print.printable", Boolean.TRUE); // NOI18N
        }
        ...
      }

How to use General Queries API?

Particular use cases are enumerated in the Javadoc for each query API. Usage consists of simple static method calls. Potentially a wide variety of modules could use these queries; implementations are typically registered by project type providers, though also by Java library and platform implementations.

How to use Command Line Parsing API?

Just Parse the Command Line

Parse the Command Line with Own Options

public final class MyOption implements Runnable {
  @Arg(longName="hello")
  public String name;

  public void run() {
    System.out.println("Hello " + name + "!");
  }
  
  public static void main(String... args) {
    CommandLine line = CommandLine.create(MyOption.class);
    line.process(args);
  }
}

If the above main class is called with parameters --hello World it will print out Hello World!.

Short and Long options with or without an argument

Options with or without an argument

Support for --

Multiple Independent CLI Handlers

Extensible Options Set

Q: How shall one write an OptionProcessor that recognizes set of basic options, however contains one open slot? The processor wants other modules to provide recognizers for that slot and wants to communicate with them. For example, by default the processor recognizes option --channel <name_of_the_channel> which describes a source of data, and stores such data into a sink. There can be multiple sinks - discard the output, save it to file, show it on stdout, stream it to network. The processor itself can handle the copying of data, but does not itself know all the possible sink types.

To implement OptionProcessor like this one shall define an additional interface to communicate with the sink providers:

   package my.module;
   public interface SinkProvider {
     /** gets the option (even composite) that this sink needs on command line */
     public Option getOption();

     /** processes the options and creates a "sink" */
     public OutputStream createSink(Env env, Map<Option,String[]> values) throws CommandException;
   }
       

Other modules would then registered implementations of this interface in the META-INF/services/my.module.SinkProvider files. The OptionProcessor itself would just look all the implementations up, queried for the sinks, and then did the copying:

   class CopyingProvider extends OptionProvider {
     public Option getOption() {
        List<Option> l = ...;
        for (SinkProvider sp : Lookup.getDefault().lookupAll(SinkProvider.class)) {
          l.add(sp.getOption());
        }

        // we need only one provider to be present
        Option oneOfSinks = OptionGroups.oneOf(l.toArray(new Option[0]));

        // our channel option
        Option channel = ...;

        // the channel option needs to be present as well as a sink
        return OptionGroups.allOf(channel, oneOfSinks);
     }

     public void process(Env env, Map<Option,String[]> values) throws CommandException {
        OutputStream os = null;
        for (SinkProvider sp : Lookup.getDefault().lookupAll(SinkProvider.class)) {
          if (values.containsKey(sp.getOption())) {
            os = sp.createSink(env, values);
            break;
          }
        }
        if (os == null) {
          throw CommandException.exitCode(2);
        }

        // process the channel option and
        // handle the copying to the sink os
     }
   }
       

Another possible approach how to allow sharing of one option between multiple modules is to expose the option definition and its handling code as an interface to other modules, and then let the modules to write their own OptionProcessors. Necessary condition is that each of the processor is uniquely identified by some additional option, so when the shared option appears the infrastructure knows which processor to delegate to. This is demonstrated in the SharedOptionTest which basically does the following:

   /** the shared option, part of an interface of some module */
   public static final Option SHARED = ...;
   /** finds value(s) associated with the SHARED option and 
   * creates a JPanel based on them */
   public static JPanel getSharedPanel(Map<Option,String[]> args) { ... }
       

Then each module who wishes to reuse the SHARED option and the factory method that knows how to process their values for their own processing can just:

  public static final class ShowDialog extends OptionProcessor {
    private static final Option DIALOG = Option.withoutArgument('d', "dialog");

    protected Set<Option> getOptions() {
        // the following says that this processor should be invoked
        // everytime --dialog appears on command line, if the SHARED
        // option is there, then this processor wants to consume it 
        // as well...
        return Collections.singleton(Option.allOf(DIALOG, Option.anyOf(SHARED)));
    }

    protected void process(Env env, Map<Option, String[]> optionValues) throws CommandException {
        JPanel p = getSharedPanel(optionvalues);
        if (p == null) {
           // show empty dialog
        } else {
           // show some dialog containing the panel p
        }
    }
  }
       

The other modules are then free to write other processors refering to SHARED, for example one can write ShowFrame that does the same, just shows the panel in a frame, etc. The infrastructure guarantees that the exactly one provider which matches the command line options is called.

Printing Full Help Text

Finding and Reporting when Options Are Not Correct

Processing Extra Command Line Arguments

       --open X.java Y.java Z.txt
       X.java Y.java --open Z.txt
       

Handling Input and Output

Returning Exit Code

Processing Only Extra Command Line Arguments

Only those processor need to process the options are created

Complex Option Relations

class PP extends OptionProcessor {
    private static Option tune = Option.requiredArgument(Option.NO_SHORT_NAME, "tune");
    private static Option stream = Option.requiredArgument(Option.NO_SHORT_NAME, "stream");
    
    public Set<Option> getOptions() {
      return Collections.singleton(
        OptionGroups.allOf(tune, stream)
      );
    }
    
    public void process(Env env, Map>Option,String[]> values) throws CommandException {
        String freq = values.get(tune)[0];
        String output = values.get(stream)[0];

        // XXX handle what is needed here
    }
}

Alternative Options

Option freq = Option.requiredArgument(Option.NO_SHORT_NAME, "tune");
Option station = Option.requiredArgument(Option.NO_SHORT_NAME, "station");
Option tune = OptionGroups.oneOf(freq, station);    

How to use UI Gestures Collector Infrastructure?

Gather information about UI gestures

Primary purpose of this module is collect information about the user actions that take place in the running NetBeans based application.

The info about various UI events in the system is collected thru listening on log records send to Logger.getLogger(UI_LOGGER_NAME_VALUE) , where UI_LOGGER_NAME_VALUE is a value of UI_LOGGER_NAME resource bundle key, defining the name of the UI usage logger. Any code in the system can get instance of this logger or any child logger and send useful informations to it. At the end of the session the last few hundereds events is taken and displayed to the user for further processing. The info about various UI events in the system is collected thru listening on log records send to Logger.getLogger(METRICS_LOGGER_NAME_VALUE) , where METRICS_LOGGER_NAME_VALUE is a value of METRICS_LOGGER_NAME resource bundle key, defining the name of the metrics logger. Any code in the system can get instance of this logger or any child logger and send useful informations to it. At the end of the session the last few hundereds events is taken and displayed to the user for further processing.

Presenting usage statistics

Important part of the behaviour of this module is the ability to cooperate with information analyzing tools and present their results. This is done thru special HTTP contracts, where the module reads and understands various server responses and is able to open browser after submitting data to analysis.

There is a key in the org.netbeans.modules.uihandler.Bundle that specifies the location of the page on a server one shall query and display to the user when the module is about the submit usage data for analysis. There is a key in the org.netbeans.modules.uihandler.Bundle that specifies the location of the page on a server one shall query and display to the user when the module is about the submit metrics data for analysis. There is a key in the org.netbeans.modules.uihandler.Bundle that specifies the location of the page on a server one shall query and display to the user when the module is about the submit an error report. The page pointed by WELCOME_URL can contain any XHTML text, but it also should contain a <form/> tag that defines <input type="hidden" name="submit" value="localizedName"/>. The localizedName is then going to be used for a button for the dialog displaying the summary. When this button is invoked, the "action" URL is then feed with data from the UI logs. The server is then supposed to process the data, create some analytics pages and return them back to the client. If the returned page contains tag like <meta http-equiv='Refresh' content='3; URL=somepage'> an (external) browser is opened with the specified URL and the user can then interact directly with the server, thru pages it serves. For testing purposes one can specify different URL for upload of files, by setting org.netbeans.modules.uihandler.Submit property when invoking NetBeans.

Adding own UI gestures

The base module is in fact just an infrastructure which collects data about UI gestures, but the actual gestures need to be delivered to it somehow. Here is the description of the ways how one can extend own modules to cooperate with this UI gestures infrastructure.

To feed own data about special UI gestures one can just create own Logger.getLogger(UI_LOGGER_NAME_VALUE+".ownname") and send own log records to it. UI_LOGGER_NAME_VALUE is a value of UI_LOGGER_NAME resource bundle key, defining the name of the logger. The format of the log messages shall follow the one described by the structured logging document, e.g. the LogRecord shall have associated ResourceBundle and the record's getMessage shall point to a key in that bundle. there is an extension to the regular formatting done by the logging formatter that, in order to achieve nicer appearance to the user, allows each record to be associated with an icon. Just define MSG_KEY_ICON_BASE in the bundle associated with the LogRecord (where the MSG_KEY is the string returned by record.getMessage()) and the value is then going to be used for the Node representing the UI gesture.

Sometimes direct logging may not be possible. For example for performance data it might be meaningful to collect the information over a longer time period and only at the end output some statistics. This is supported as well. Just implement and register one of the interfaces from the API of this module and properly register them and the implementation will be called when the logger module is activated or when the user finishes the work with the application. In order to keep dependencies clean, it is strongly adviced to make modules that implement this API eager, so they get enabled as soon as the UI logger module is enabled.

These usecases are realized as described in here in provided UI specification.

How to use Quick Search API?

How To Add New Quick Search Provider

1. Implement SearchProvider

• Implement body of SearchProvider.evaluate method like suggested in its javadoc.

2. Register SearchProvider implementation in xml layer

              <folder name="QuickSearch">
                  <folder name="Category1_ID">
                      <attr name="position" intvalue="300"/>
                      <file name="org-netbeans-module1-package1-Provider1Impl.instance"/>
                  </folder>
                  <folder name="Category2_ID">
                      <!--Attribute for localization - provide localized display name of category!-->
                      <attr name="SystemFileSystem.localizingBundle" stringvalue="org.netbeans.modules.yourmodule.YourBundle"/>
                      <!--Attribute for command prefix - used to narrow search to this category only!-->
                      <attr name="command" stringvalue="p"/>
                      <!--Attribute for category ordering!-->
                      <attr name="position" intvalue="200"/>
                      <!--Note that multiple providers can contribute to one category!-->
                      <file name="org-netbeans-module2-package2-Provider2Impl.instance"/>
                      <file name="org-netbeans-module2-package3-Provider3Impl.instance"/>
                  </folder>
              </folder>
            

• Subfolders of "QuickSearch" define search result categories and their order.
• Providers can share category by putting themselves under same subfolder.
• Ordering of categories is done through NetBeans standard FileSystem API ordering "position" attribute
• Display name of category folder uses NetBeans standard FileSystem API "SystemFileSystem.localizingBundle" attribute.
• "command" attribute defines command prefix for category, which is used to narrow Quick Search to only one category. Provide short prefix, ideally containing one or two prefix, that will serve as command to narrow search only this category. In above syntax example, if user types 'p' and space key and then text, only "Category2_ID" category will be searched.
• If several providers share one category, then only one provider needs to specify above attributes. Note however that if your provider shares category with provider from different module, you should have dependency on module which actually define those attributes. Dependency assures there will always be category "description" for category that you are sharing.

How To Share Category Of Results

Quick Search UI shows search results divided into visually separeted sections, called categories. Several SearchProvider implementations may decide to display their results in one shared category of results in Quick Search UI.

In order to share category, module writers have to agree on shared category and its properties, especially its name. It means that all providers (possibly in different NetBeans modules) need to be registered under the same folder, as shown below:

Provider 1

              <folder name="QuickSearch">
                  <folder name="SharedCategory">
                      <attr name="SystemFileSystem.localizingBundle" stringvalue="org.netbeans.modules.yourmodule.YourBundle"/>
                      <attr name="command" stringvalue="p"/>
                      <attr name="position" intvalue="200"/>
                      <file name="org-netbeans-module1-package1-Provider1Impl.instance">
                          <attr name="position" intvalue="300"/>
                      </file>                          
                  </folder>
              </folder>
            

Provider 2

              <folder name="QuickSearch">
                  <folder name="SharedCategory">
                      <file name="org-netbeans-module2-package2-Provider2Impl.instance"/>
                          <attr name="position" intvalue="200"/>
                      </file>                          
                  </folder>
              </folder>
            

Provider 3

              <folder name="QuickSearch">
                  <folder name="SharedCategory">
                      <file name="org-netbeans-module2-package3-Provider3Impl.instance"/>
                          <attr name="position" intvalue="100"/>
                      </file>                          
                  </folder>
              </folder>
            

How To Define and Modify Order of Categories

              <folder name="QuickSearch">
                  <folder name="SecondCategory">
                      <attr name="position" intvalue="300"/>
                      ...
                  </folder>
                  <folder name="FirstCategory">
                      <attr name="position" intvalue="200"/>
                      ...
                  </folder>
             </folder>
            

How To Hide Recent Searches Results and Others

Define module dependency

Disable provider using "_hidden"

              <folder name="QuickSearch">
                  <folder name="Recent_hidden">
                  </folder>
              </folder>
           

How To Use Quick Search in Platform Application

1. Write XML layer registration

        <folder name="Toolbars">
            <folder name="QuickSearch">
            <attr name="SystemFileSystem.localizingBundle" stringvalue="com.myapp.mymodule.MyBundle"/>
                <file name="org-netbeans-modules-quicksearch-QuickSearchAction.shadow">
                    <attr name="originalFile" stringvalue="Actions/Edit/org-netbeans-modules-quicksearch-QuickSearchAction.instance"/>
                </file>
            </folder>
        </folder>
        

2. Localize Toolbar Name

                Toolbars/QuickSearch=Quick Search
             

By default, providers for searching in actions and recent searches will be enabled. Web search provider is disabled by default, see use case below for info how to turn it on.

How To Add a Default Web Search Provider

          <folder name="QuickSearch">
              <folder name="WebSearch">
                  <!--Attribute for localization - provide localized display name of category!-->
                  <attr name="SystemFileSystem.localizingBundle" stringvalue="com.myapp.mymodule.MyBundle"/>
                  <!--Attribute for command prefix - used to narrow search to this category only!-->
                  <attr name="command" stringvalue="g"/>
                  <!--Attribute for category ordering!-->
                  <attr name="position" intvalue="200"/>
                  <!--Note that multiple providers can contribute to one category!-->
                  <file name="org-netbeans-modules-quicksearch-web-WebQuickSearchProviderImpl.instance"/>
              </folder>
          </folder>
        

            quicksearch.web.site=mywebsite.com
        

            quicksearch.web.url_patterns=mywebsite.com/docs,mywebsite.com/files/tutorials
        

How to use Actions APIs?

Actions faq:

How to define configurable Shortcut for Component based shortcut?

In order for the action to show up in Keyboards Shortcut dialog you need the action defined in the layer file under "Actions" folder and have the shortcut defined there under "Keymaps/<Profile Name>" linking to your action.

    <folder name="Actions" >
        <folder name="Window">
            <file name="org-netbeans-core-actions-PreviousViewCallbackAction.instance"/>
        </folder>
    </folder>

    <folder name="Keymaps">
        <folder name="NetBeans">
            <file name="S-A-Left.shadow">
                <attr name="originalFile" stringvalue="Actions/Window/org-netbeans-core-actions-PreviousViewCallbackAction.instance"/>
            </file>
        </folder>
    </folder>

The mentioned Action has to be a subclass of org.openide.util.actions.CallbackSystemAction. It does not necessarily has to perform the action, it's just a placeholder for linking the shortcut. You might want to override it's getActionMapKey() and give it a reasonable key.

The actual action that does the work in your component (preferably a simple Swing javax.swing.Action) is to be put into your TopComponent's ActionMap. The key for the ActionMap has to match the key defined in the global action's getActionMapKey() method.

        getActionMap().put("PreviousViewAction", new MyPreviousTabAction());

This way even actions from multiple TopComponents with the same gesture (eg. "switch to next tab") can share the same configurable shortcut.

Note: Don't define your action's shortcut and don't put it into any of the TopComponent's javax.swing.InputMap. Otherwise the component would not pick up the changed shortcut from the global context.

How to use UI Utilities API?

XXX no answer for arch-usecases

How to use Dialogs API?

How to change the title of a wizard?

A: You can change the format of your wizard's title by WizardDescriptor.setTitleFormat(MessageFormat format) and rid of 'wizard' word in the default wizard's title.

How to use Explorer & Property Sheet API?

XXX no answer for arch-usecases

How to use File System API?

Many of the usecases are described at the overall documentation, in a way how to register a mime type. Some of the additional usecases are covered here.

How to change menus, etc. after login?

See documentation about dynamically changing the system filesystem.

How to use I/O APIs?

There is an SPI but additional implementations are not expected. The API is most important.

Simple usage example:

InputOutput io = IOProvider.getDefault().getIO("My Window", true);
io.select();
OutputWriter w = io.getOut();
w.println("Line of plain text.");
OutputListener listener = new OutputListener() {
    public void outputLineAction(OutputEvent ev) {
        StatusDisplayer.getDefault().setStatusText("Hyperlink clicked!");
    }
    public void outputLineSelected(OutputEvent ev) {
        // Let's not do anything special.
    }
    public void outputLineCleared(OutputEvent ev) {
        // Leave it blank, no state to remove.
    }
};
w.println("Line of hyperlinked text.", listener, true);

How to use Datasystems API?

Using Scripting and Templating Languages

Often many people require ability to create a "clever" template - e.g. write piece of simple text and at the time of its processing do some advanced changes to it using either scripting or templating languages.

This traditionally used to be a bit complicated task, however since version 6.1 there are new interfaces can be registered as a services in a lookup and it is reponsible for handling the whole copy of the template file(s) to the destination folder. and can be registered as a services in a lookup and it is reponsible for providing "hints" - e.g. map mapping strings to various objects. and these interfaces allow anyone to extend the behaviour during creation of new files without writing new DataLoader and co.

Smart Templating Quick How-To
First of all create a file in your module layer located somewhere under the Templates/ folder. Make it a template by adding <attr name="template" boolvalue="true"/>. Associate this template with a scripting language, for example by <attr name="javax.script.ScriptEngine" stringvalue="freemarker"/>. Now make sure that the scripting language integration is also available by requesting a token in standard format, for freemarker just put OpenIDE-Module-Needs: javax.script.ScriptEngine.freemarker in your manifest. This tells the NetBeans module system that a module providing integration with such scripting engine has to be enabled. Now you can use regular script language tags inside of your template file. When you write your instantiate method in your wizard, you can create a Map<String,Object> and fill it with parameters collected from your wizard and then pass it to createFromTemplate(targetFolder, targetName, mapWithParameters) . This will invoke the scripting language and make the mapWithParameters values available to it. Beyond this there is few standard parameters predefined including name, user, date, time, etc. and also additional parameters are collected from all registered CreateFromTemplateAttributesProviders.

Moreover there is a built in support for scripting languages in the standard NetBeans IDE. If a template is annotated with a property that can be associated to templates that either should return real instance of ScriptEngine interface or a String name of the engine that is then used to search for it in the javax.script.ScriptEngineManager. Usually the freemarker engine is the one that is supported by the NetBeans IDE - if your module wants to use it then include a token dependency OpenIDE-Module-Needs: javax.script.ScriptEngine.freemarker in your manifest file (also accessible through project customizer GUI) to indicate to the system that you need it. then the scripting engine is then used to process the template and generate the output file. While running the engine one can rely on few predefined properties:

• contains the name of the DataObject that is being created
• contains the name the user
• contains the name and extension of the file that is being created
• contains String representing the current day like 23. 3. 2007
• contains String the current time like 17:18:30
• contains java.util.Date representing current data and time like
• contains String the file encoding of the template instance

Other properties can indeed be provided by CreateFromTemplateAttributesProviders. After processing, the output is also sent to appropriate org.openide.text.IndentEngine associated with the mime type of the template, for formating.

How to add action to folder's popup menu?

    <folder name="Loaders" >
        <folder name="folder" >
            <folder name="any" >
                <folder name="Actions" >
                    <file name="org-mymodule-MyAction.instance" >
                        <attr name="instanceCreate" stringvalue="org.mymodule.MyAction" />
                    </file>
                </folder>
            </folder>
        </folder>
    </folder>
    

In version 5.8 all the standard loaders were changed to read actions from layer:

• The actions that the standard XML loader shows in its popup menu are read from a layer folder Loaders/text/xml/Actions
• The actions that the loader for unrecognized files shows in its popup menu are read from a layer folder Loaders/content/unknown/Actions
• The actions that the loader for instance and settings files shows in its popup menu are read from a layer folder Loaders/application/x-nbsettings/Actions

How to allow others to enhance actions of your loader?

How to use Module System API?

How a classpath of my module is constructed?

How to use Text API?

XXX no answer for arch-usecases

How to use Utilities API?

How shall I do or influence logging in NetBeans?

If you are interested in logging from inside your module, or in writing your own log handler or in configuring the whole system, then best place to start is the NetBeans logging guide.

How to use Lookup API?

Lookup faq:

How to specify that a service in Lookup should be available only on Windows?

How can I specify (in the xml, or programmatically) that this service should only be added to the Lookup if the platform is Windows? >

• It is possible to write a specific module and enable it only on windows. See os specific modules documentation. Then you can put a registration of your instance into your module's META-INF/services directory and it will be available only on Windows.

• Another possibility that does not require new module, but which executes a code on startup (which may have performance implications) is to use methodvalue attribute. Register your instance in layer using your-Object.instance file as described at services documentation and in your factory method either return the instance your want or null depending on result of Utilities.isWindows() call.

• In some cases, the interface for which you will register an implementation permits a no-operation semantics. For example, InstalledFileLocator.locate(...) can return a valid File, or null. You could always register an InstalledFileLocator instance yet disable it on non-Windows platforms (always returning null).

How shall I write an extension point for my module?

Q: I have more modules one of them providing the core functionality and few more that wish to extend it. What is the right way to do it? How does the Netbeans platform declare such extension point?

Start with declaring an extension interface in your core module and put it into the module's public packages. Imagine for example that the core module is in JAR file org-my-netbeans-coremodule.jar and already contains in manifests line like OpenIDE-Module: org.my.netbeans.coremodule/1 and wants to display various tips of the day provided by other modules and thus defines:

 

package org.my.netbeans.coremodule;

public interface TipsOfTheDayProvider {
    public String provideTipOfTheDay ();
}

And in its manifest adds line OpenIDE-Module-Public-Packages: org.my.netbeans.coremodule.* to specify that this package contains exported API and shall be accessible to other modules.

When the core module is about to display the tip of the day it can ask the system for all registered instances of the TipsOfTheDayProvider, randomly select one of them:

import java.util.Collection;
import java.util.Collections;
import org.openide.util.Lookup;

Lookup.Result result = Lookup.getDefault ().lookup (new Lookup.Template (TipsOfTheDayProvider.class));
Collection c = result.allInstances ();
Collections.shuffle (c);
TipsOfTheDayProvider selected = (TipsOfTheDayProvider)c.iterator ().next ();

and then display the tip. Simple, trivial, just by the usage of Lookup interface once creates a registry that other modules can enhance. But such enhancing of course requires work on the other side. Each module that would like to register its TipsOfTheDayProvider needs to depend on the core module - add OpenIDE-Module-Module-Dependencies: org.my.netbeans.coremodule/1 into its manifest and write a class with its own implementation of the provider:

package org.my.netbeans.extramodule;

class ExtraTip implements TipsOfTheDayProvider {
    public String provideTipOfTheDay () {
        return "Do you know that in order to write extension point you should use Lookup?";
    }
}

Then, the only necessary thing is to register such class by using the J2SE standard into plain text file META-INF/services/org.my.netbeans.coremodule.TipsOfTheDayProvider in the module JAR containing just one line:

org.my.netbeans.extramodule.ExtraTip

and your modules are now ready to communicate using your own extension point.

How to use Window System API?

General Usecases

How to create a '.settings' file for a TopComponent?

How to make a TopComponentGroup?

1. declare the group in the layer file (Windows2/Groups)
2. have code for opening the group
3. have code for closing the group

   protected void componentDeactivated ()
   {
       // close window group containing propsheet, but only if we're
       // selecting a different kind of TC in the same mode
       boolean closeGroup = true;
       Mode curMode = WindowManager.getDefault().findMode(this);
       TopComponent selected = curMode.getSelectedTopComponent();
       if (selected != null && selected instanceof FooTopComponent)
           closeGroup = false;
             if (closeGroup)
       {
           TopComponentGroup group = WindowManager.getDefault().findTopComponentGroup(TC_GROUP);
           if (group != null)
           {
               group.close();
           }
       }
   }