well, I first thought (based on docs to OptionsDisplayer.open() method javadoc) that the API allows it. 
Lets say I have a Miscelaneous category that is described in layers as OptionsDialog/Advanced/Maven.instance
My first assumption as that passing "Maven" as category ID is ok. That one reports a problem in messages.log.
The next try was "Advanced/Maven" but that one was just silently ignored.
Isn't that a bug rather than feature enhancement?

I vote for bug too. 

Not a bug (you can consider it to be an API bug) but OptionsDisplayer was really designed to work just with categories.
Although subcategories were considered - finally it was left for future decision because there was no real requirement
for subcategories at that time. I do not plan to fix it for 6.0. 

If you think that current javadoc is misleading that please report a separate bug.

moving opened issues from TM <= 6.1 to TM=Dev

*** Issue 134537 has been marked as a duplicate of this issue. ***

*** Issue 134932 has been marked as a duplicate of this issue. ***

Created attachment 61430 [details]
Proposed API change with tests.

Please, review attached changes. Method OptionsDisplayer.open(categoryId, subcategoryId) is added to API and
OptionsPanelController.setCurrentSubcategory(subcategoryId) to SPI.

MK1: do we have other categories than "Miscellaneous" that have subcategories? I thought the API now has either Category
or AdvancedCategory (or something along the lines) contracts only. So I'm sort of forced here to enter the
"miscellaneous" category everytime even though it's not really necessary. Can we have a method like
openSubcategory(subcategory) that would automatically route to The Miscelaneous panel content? or at least expose the ID
of the Misc. category as constant.

>MK1: Subcategories exist for example in Editor category. And my proposal should allow to select such subcategory.
OptionsDisplayer.open(categoryId, subcategoryId) calls setCurrentSubcategory(subcategoryId) in category's
OptionPanelController and it is up to implementators how they implement this method. Implementation for 'Advanced'
category is in AdvancedPanelController and subsequently in AdvancedPanel.

Re MK1: may be useful for the Java Code category as well. I agree that a constant with ID of the Misc/Advanced category
would be useful.

JL1: Is there a reason why OptionsDisplayer.open("Known Category", "Unknown Subcategory") returns true? I would expect
false here. OptionsPanelController.setCurrentSubcategory would than need to return boolean status.

JL2: just an idea - consider the following usecase: a (Java) hint is shown. The user is given option to show settings
for the hint. Using the proposed API, it is possible to open the "Java Code" category, and select "Hints" subcategory.
The API does not directly allow to select the correct hint in the Hints tree, though. Maybe it would make sense to
extend the API to allow passing additional information from the caller to the Options panel?

Created attachment 61817 [details]
New version of patch.

Please, look at a new version of patch reflecting your comments and also enhancement 99689. Now it is possible to call

OptionsDisplayer.getDefault().open("CategoryID/SubcategoryID/SubsubID");

Subpath is passed to particular OptionsPanelController.setCurrentSubcategory which can handle subcategories selection.

Also it is possible to create arbitrary category with tabbed subcategories according to definition in layer

OptionsPanelController.createAdvanced("SubcategoryID")

> MK1: Added constant pointing to Miscellaneous panel
OptionsDisplayer.getDefault().open(OptionsDisplayer.ADVANCED+"/SubcategoryID");

> JL1: setCurrentSubcategory is void because subcategories are selected asynchronously. OptionsDisplayer.open("Known
Category", "Unknown Subcategory") returns true and it is up to controllers to handle such situation.

> JL2: As mentioned above, subpath is passed to controller.

Y01 missing @since on new API elements (p1)
Y02 public void setCurrentSubcategory(String subpath) - shall be protected, imho, as it is called by the 
infrastructure and not supposed to be called by anyone else (p3)

If there are no more objections I will integrate the patch with following changes on May 28-th.

> Y01 missing @since on new API elements (p1)

I will add it.

> Y02 public void setCurrentSubcategory(String subpath) - shall be protected, imho, as it is called by the 
> infrastructure and not supposed to be called by anyone else (p3)

It must be public because it is called from implementation.

Re. Y02, in such case I suggest to make it protected. Use friend accessor pattern to call it:
http://openide.netbeans.org/tutorial/api-design.html#design.less.friend
there is no reason for users of the API to be confused (as they do not know whether to call it or implement it only) 
by making it public. I'd prefer this solution, still, it is still only TCA.

Integreated as suggested and with Y02 included. Use the following to open Options dialog with selected subcategory:

OptionsDisplayer.getDefault().open("CategoryID/SubcategoryID");

http://hg.netbeans.org/core-main/rev/08412c8d2c6f
http://hg.netbeans.org/main/rev/08412c8d2c6f

In connection with this issue I changed options panel wizard to support creation of tabbed subcategories.

http://hg.netbeans.org/core-main/rev/71dba92d8981
http://hg.netbeans.org/main/rev/71dba92d8981

Integrated into 'main-golden', available in NB_Trunk_Production #234 build
Changeset: http://hg.netbeans.org/main/rev/08412c8d2c6f
User: Jiri Skrivanek <jskrivanek@netbeans.org>
Log: #109538 - Changed API to allow select subcategory while opening Options dialog.

Integrated into 'main-golden', available in NB_Trunk_Production #236 build
Changeset: http://hg.netbeans.org/main/rev/18e1c19070d1
User: Maros Sandor <msandor@netbeans.org>
Log: Taking advantage of #109538

verified, API exists/works

Yes,tested working great! Thanks.

verified in M1

I am struggling to determine the purpose of OptionsPanelController.createAdvanced. It seems to nearly duplicate what
OptionsCategory.createCategory with an advancedOptionsFolder parameter does, with the disadvantages that

1. There is no apparent way to specify the description, keywords, or keywordsCategory attributes (assuming these are
important somehow).

2. You need to create an extra Java class which doesn't do anything interesting.

There is little in the way of examples to go on, because (in all of main & contrib)
OptionsCategory.createCategory/advancedOptionsFolder is used only by options.editor, and
OptionsPanelController.createAdvanced is used only by php.project.

If I modify php.project to use OptionsCategory.createCategory/advancedOptionsFolder, the PHP panel of the Options dialog
looks exactly the same. Calls to
OptionsDisplayer.getDefault().open("org-netbeans-modules-php-project-ui-options-PHPOptionsCategory"), however, do
nothing - just print a warning on console that the category is unknown. (E.g. New Project, PHP app, Next to 3rd panel,
select Run Script and click Configure.) It seems like this would be simple to fix, in which case there would be no
reason to use OptionsPanelController.createAdvanced at all, and it could be deprecated - or am I wrong?

FWIW, OptionsCategory.createCategory/advancedOptionsFolder is what is offered by apisupport when you ask to make a
Primary Panel and click Allow Secondary Panels.

Created attachment 86939 [details]
Example patch to php.project

BTW CndOptionsPanelController uses its own weird style for no discernible reason - could probably be simplified to use
one of the two container panel styles under discussion.

Please notice that it needs to be possible to open a PHP "subcategory" (a tab in PHP category, right now only
Symfony is present). So, if the patch won't disable this functionality, I'm OK with it. Thanks.

I agree OptionsPanelController.createAdvanced is redundant. It was left untouched when msauer introduced layer
registration. Also it is no more used in apisupport wizard (see issue 140499, main #5f06aeacf11e). I agree to deprecate it.
Opening of PHP category will work if you fix file name in your patch.

-        <file name="org-netbeans-modules-php-project-ui-options-PHPOptionsCategory.instance">
+        <file name="org-netbeans-modules-php-project-ui-options.instance">

Ah, did not realize that the file name under which the advanced folder was registered was significant, as well as the
advanced folder path itself. With that corrected, the patch does indeed work, so applied as core-main #67995573872d in
preparation for deprecating OptionsPanelController.createAdvanced as part of issue #171284. I also confirmed that
selection of subpanels such as Symfony continues to work (and adjusted calls in php.project to open the General tab
specifically, which seems to have been the original intent).

Integrated into 'main-golden', will be available in build *200909030951* on http://bits.netbeans.org/dev/nightly/ (upload may still be in progress)
Changeset: http://hg.netbeans.org/main-golden/rev/67995573872d
User: Jesse Glick <jglick@netbeans.org>
Log: Removing use of OptionsPanelController.createAdvanced as it seems unnecessary. (Cf. #109538.)