Introduction

This document lists changes made to the Options Dialog APIs. Please ask on the [email protected] mailing list if you have any questions about the details of a change, or are wondering how to convert existing code to be compatible.

Index of APIs

Options Dialog API

Incompatible changes by date

Fuller descriptions of all changes can be found below (follow links).

Not all deprecations are listed here, assuming that the deprecated APIs continue to essentially work.

For a full deprecation list, please consult the Javadoc.

(Mar 15 '13) Should Import Require Restart?
(Mar 30 '09) "Classic" mode fully implemented in module

All changes by date

(Dec 3 '13) API to handle selection of subcategory from a composite OptionspanelController
(Mar 15 '13) Should Import Require Restart?
(Feb 26 '13) API to control whether the options window should be modal or not when opened
(Oct 18 '12) API to handle successfull search in some panel in options window
(Oct 2 '12) Annotation to register keywords for some panel in the Options dialog
(Sep 14 '09) Annotations to register dialog panels
(Mar 30 '09) "Classic" mode fully implemented in module
(Jul 17 '08) Support for searchable options
(Jul 11 '08) Support for searchable options
(May 28 '08) API to open the options dialog with some subcategory pre-selected
(Dec 19 '06) API to open the options dialog with some category pre-selected
(Jun 13 '06) The Options Dialog API has been stabilized.
(Aug 18 '05) Options Dialog API integrated.

Changes by version

These API specification versions may be used to indicate that a module requires a certain API feature in order to function. For example, if you see here a feature you need which is labelled 1.20, your manifest should contain in its main attributes the line:

OpenIDE-Module-Module-Dependencies: org.netbeans.modules.options.api/1 > 1.20

(1.38) API to handle selection of subcategory from a composite OptionspanelController
(1.34) Should Import Require Restart?
(1.33) API to control whether the options window should be modal or not when opened
(1.30) API to handle successfull search in some panel in options window
(1.29) Annotation to register keywords for some panel in the Options dialog
(1.14) Annotations to register dialog panels
(1.12) "Classic" mode fully implemented in module
(1.10) Support for searchable options
(1.9) Support for searchable options
(1.8) API to open the options dialog with some subcategory pre-selected
(1.5) API to open the options dialog with some category pre-selected
(1.4) The Options Dialog API has been stabilized.

Changes by affected class

`org.netbeans.spi.options.AdvancedOption`

(Sep 14 '09) Annotations to register dialog panels

`org.netbeans.api.options.OptionsDisplayer`

(Feb 26 '13) API to control whether the options window should be modal or not when opened
(May 28 '08) API to open the options dialog with some subcategory pre-selected
(Dec 19 '06) API to open the options dialog with some category pre-selected

`org.netbeans.spi.options.OptionsPanelController`

(Dec 3 '13) API to handle selection of subcategory from a composite OptionspanelController
(Oct 18 '12) API to handle successfull search in some panel in options window
(Oct 2 '12) Annotation to register keywords for some panel in the Options dialog
(Sep 14 '09) Annotations to register dialog panels
(Jul 17 '08) Support for searchable options
(Jul 11 '08) Support for searchable options

Details of all changes by API and date

Options Dialog API

API to handle selection of subcategory from a composite OptionspanelController

Dec 3 '13; API spec. version: 1.38; affected top-level classes: OptionsPanelController; made by: theofanis; issues: #180821
Added API to handle selection of subcategory. It is meant to be called from a composite OptionspanelController and delegates to OptionspanelController.setCurrentSubcategory.

Should Import Require Restart?

Mar 15 '13; API spec. version: 1.34; made by: jtulach; issues: #226998
Should an import of settings require a restart? Some applications need that, some don't. There is a branding API to control such behavior now.
Compatibility: Compared to previous versions, the default changed - now the restart is not needed. Applications can change that by using this branding API and specifying false as the value of associated key.

API to control whether the options window should be modal or not when opened

Feb 26 '13; API spec. version: 1.33; affected top-level classes: OptionsDisplayer; made by: theofanis; issues: #207120
Added API to control whether the options window should be modal or not when opened.

API to handle successfull search in some panel in options window

Oct 18 '12; API spec. version: 1.30; affected top-level classes: OptionsPanelController; made by: theofanis; issues: #219457
Added API to handle successful search in some panel in options window. By default no action is performed. Each implementor should make special actions, for example to choose a specific sub-panel, if this is required.

Annotation to register keywords for some panel in the Options dialog

Oct 2 '12; API spec. version: 1.29; affected top-level classes: OptionsPanelController; made by: theofanis; issues: #218312
Introduced an annotation inside OptionsPanelController to register keywords for some panel in the Options dialog declaratively.

Annotations to register dialog panels

Sep 14 '09; API spec. version: 1.14; affected top-level classes: OptionsPanelController AdvancedOption; made by: jglick; issues: #171284

Introduced three annotations inside OptionsPanelController to register Options dialog panels declaratively.

Compatibility:

Deprecated subclassing AdvancedOption and using OptionsPanelController.createAdvanced as these do not do anything you cannot do more easily using annotations.

"Classic" mode fully implemented in module

Mar 30 '09; API spec. version: 1.12; made by: jglick
The Advanced Options button (also known as "classic" mode) is now fully implemented in the Options Dialog and SPI module, rather than in Core. The functionality remains the same: any displayable objects (such as beans) present under the UI/Services configuration folder will trigger the button to be displayed which opens a special dialog for them.
Compatibility:

Platform applications using the old UI/Services now need to include this module. Module developers are however strongly encouraged to use the new Options SPI.

Support for searchable options

Jul 17 '08; API spec. version: 1.10; affected top-level classes: OptionsPanelController; made by: msauer; issues: #137338
Added new declarative way of registering options categories (advancedOptionFolder attr in layer.xml), in order to remove duplicate tabbed controllers for each category with subtabs

Support for searchable options

Jul 11 '08; API spec. version: 1.9; affected top-level classes: OptionsPanelController; made by: msauer; issues: #137338
Added new factory methods enabling declarative loading of option panels (createCategory and createSubCategory) to OptionsCategory and AdvancedOption