Bug 171284

Will not support either OptionsCategory.createCategory with advancedOptionsFolder or
OptionsPanelController.createAdvanced until I get an answer to my question in issue #109538. Anyway there are only two
known usages of these two combined - Editor & PHP (and potentially a third in CND), so an annotation would not be very
important.

Created attachment 86946 [details]
Start of proposed patch, incl. API changes and example usages

Please review.

JS01: Add @SubLevelRegistration with String topLevel(). Then @AdvancedRegistration is a shortcut for
@OptionsPanelController.SubLevelRegistration(topLevel = "Advanced",displayName = "#displayName").

To JS01 - having a single @OPC.Registration with a category="..." attr (which could be a new constant ADVANCED_CATEGORY,
some other value such as "org-...-php-Whatever", or omitted for a top-level registration) would certainly be attractive
and simple to understand. But would it work identically? There are completely separate code paths for Advanced subpanels
as opposed to "regular" panels - is this only a historical accident that can now be ignored? I presume iconBase is
meaningful iff category is omitted?

Please excuse my ignorance, it just seems that the Options SPI has a lot of different ways of doing nearly the same
thing and it is not clear what may be obsolete.

Created attachment 86975 [details]
Failed experiment

JS01 cont'd - the last-attached patch does not work. "Tasks" is displayed as a top-level button with no icon, not in the
Miscellaneous panel.

I think I see what you meant. core-main #197bb79bce9d shows AdvancedOption.createSubCategory working for PHP subpanels.

Created attachment 86992 [details]
Progress: renamed @SubRegistration, new id & location attrs, usage in php.project, two @Deprecation's, new LayerBuilder util method

Nice cleanup. Y01 A test for the processor would be nice.

Created attachment 87013 [details]
Attempt at processor test

Y01 - I tried rewriting the test to use the annotation-produced registrations. No luck so far (various errors I don't
really understand). The existing test uses old styles of registration and it is not trivial to update it to understand
panels created by factory methods. Maybe someone with better knowledge of the module's internals would be able to do it.

Created attachment 87014 [details]
Now have @ContainerRegistration, used successfully in php.project

Re. Y01: I do not recommend to change (and thus destroy) the existing test. It shall still test what it used to, as 
that remains valid use of the API. I thought you will create new test (possibly based on the copy of previous) to 
cover the new stuff with annotations. I would verify that @registration really registers something (which can be 
created and looks sane) and also that processor correctly detects inconsistencies in annotations (for example 
keywordCategory specified but no keywords yields an error).

Y02 Really tentative. You seem to enjoy improving the option system quite a lot. When you are at it, you could also 
look at issue 166871. You have the knowledge of option categories, me and Pavel Flaška can provide info about the rest 
(probably elsewhere, not in this issue). It would be good to have another person with experience with the static 
analysis and dynamic verification. If you are interested, let us know. Otherwise ignore this offer.

Integrated into 'main-golden', will be available in build *200909021401* on http://bits.netbeans.org/dev/nightly/ (upload may still be in progress)
Changeset: http://hg.netbeans.org/main-golden/rev/bf566b2b6ac5
User: Jesse Glick <jglick@netbeans.org>
Log: Lazy-load capability for option panels.
Currently seems to help only for those advanced subpanels using AdvancedOption.createSubCategory.
Many advanced subpanels currently have an explicit OptionsPanelController impl, though that is their fault (cf. #171284).
Does not work yet for main panels; principal problem seems to be eager merging of OPC.lookup's into mainLookup.

Re. desc6: I must admit there are duplicates in code. Possibly all in options.advanced have a counterpart in new
"tabbed" infrastructure (e.g. AdvancedPanelController vs. TabbedController). But in options.advanced there might be some
fixes which are not in "tabbed". If options.advanced is removed, then it must be carefully checked that everything works
as before. There are not enough tests to rely just on them.

Y01 - OK. The existing test continues to pass, as I am not changing anything that was there before. Can make another
attempt to write a test checking the runtime behavior of anno-registered panels, though it does not appear
straightforward to find these from the API side. Testing negative aspects of the processor is of course straightforward,
though there is not a lot to test since it is nearly a 1-1 translation from the annotations.


desc6 discussion - I was certainly not proposing to remove/deprecate options.advanced myself, though someone more
knowledgeable could attempt it. Despite the obvious similarities there are various subtle differences. For example,
Advanced subpanels are organized alphabetically, not by SFS position. Anyway it seems so far that the current set of
three annotations suffices to cover the use cases with no visible change in functionality (still TBD whether the CND
top-level panel can be rewritten to follow the normal pattern).

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/197bb79bce9d
User: Jesse Glick <jglick@netbeans.org>
Log: Can use AdvancedOption.createSubCategory rather than extending AdvancedOption.
(Hinted at in #171284.)

I'm fine to change CND's approach (introduced in days when only Advanced tab had registration mechanism). Let me now
where to look at for the "right" impl. 
Or if you can provide patch => I can test it.

Simplified CND options in core-main #27e35ca9221f. No apparent use of OptionsDisplayer. Displays correctly, OK stores
correctly, Help shows right page.

Integrated into 'main-golden', will be available in build *200909111401* on http://bits.netbeans.org/dev/nightly/ (upload may still be in progress)
Changeset: http://hg.netbeans.org/main-golden/rev/27e35ca9221f
User: Jesse Glick <jglick@netbeans.org>
Log: Modernizing Options subpanel for CND. (Mentioned in #171284.)

core-main #f8f73cf077bc

Integrated into 'main-golden', will be available in build *200909181401* on http://bits.netbeans.org/dev/nightly/ (upload may still be in progress)
Changeset: http://hg.netbeans.org/main-golden/rev/f8f73cf077bc
User: Jesse Glick <jglick@netbeans.org>
Log: Issue #171284: register Options dialog panels declaratively.
Using new annotations in some representative modules.