<change id="optionsSearchAnnotation">

      <api name="OptionsAPI"/>

      <summary>Annotation to register keywords for some panel in the Options dialog</summary>

      <version major="1" minor="28"/>

      <date day="20" month="9" year="2012"/>

      <author login="theofanis"/>

      <compatibility addition="yes" binary="compatible" source="compatible" deprecation="no" semantic="compatible" modification="no" deletion="no"/>

      <description>

          Introduced an annotation inside <code>OptionsPanelController</code>

          to register keywords for some panel in the Options dialog declaratively.

      </description>

      <class package="org.netbeans.spi.options" name="OptionsPanelController"/>

      <issue number="218312"/>

    </change>

    static final String OD_LAYER_KEYWORDPANELS_FOLDER_NAME = "OptionsDialog/KeywordPanels"; // NOI18N

import java.util.ArrayList;

import java.util.Collections;

import java.util.Comparator;

import javax.swing.JPanel;

import org.netbeans.api.options.OptionsDisplayer;

import org.netbeans.spi.options.OptionsPanelController.KeywordPanel;

import org.netbeans.spi.options.OptionsPanelController.KeywordPanels;

        ArrayList<KeywordPanel> advanced = new ArrayList<KeywordPanel>();

        for (Element e : roundEnv.getElementsAnnotatedWith(KeywordPanel.class)) {

            KeywordPanel annotation = e.getAnnotation(KeywordPanel.class);

            if (annotation != null) {

                String location = annotation.location();

                if(location.equals(OptionsDisplayer.ADVANCED)) {

                    advanced.add(annotation);

                }

            }

        }

        Collections.sort(advanced, new AdvancedComparable());

        for (Element e : roundEnv.getElementsAnnotatedWith(KeywordPanel.class)) {

            handleElement(e, e.getAnnotation(KeywordPanel.class), advanced, "");

        }

        for (Element e : roundEnv.getElementsAnnotatedWith(KeywordPanels.class)) {

            KeywordPanels r = e.getAnnotation(KeywordPanels.class);

            KeywordPanel[] panels = r.value();

            for (int i = 0; i < panels.length; i++) {

                handleElement(e, panels[i], advanced, Integer.toString(-(i + 1)));

            }

        }

    private void handleElement(Element e, KeywordPanel annotation, ArrayList<KeywordPanel> advanced, String name) throws LayerGenerationException {

        int index = annotation.index();

        if (annotation.location().equals(OptionsDisplayer.ADVANCED)) {

            index = advanced.indexOf(annotation);

        }

        File file = layer(e).

                file("OptionsDialog/KeywordPanels/".concat(e.asType().toString()).concat(name)).

                stringvalue("instanceOf", JPanel.class.getName()).

                bundlevalue("location", annotation.location(), annotation, "location").

                bundlevalue("id", annotation.id()).

                intvalue("index", index);

        int i = 1;

        for (String keyword : annotation.keywords()) {

            file.bundlevalue("keyword-".concat(Integer.toString(i++)), keyword, annotation, "keywords");

        }

        file.write();

    }

    private class AdvancedComparable implements Comparator<KeywordPanel> {

        @Override

        public int compare(KeywordPanel r1, KeywordPanel r2) {

            return r1.id().compareTo(r2.id());

        }

    }

    /**

     * Similar to {@link KeywordPanel} but permits multiple registrations of

     * one class.

     *

     * @since org.netbeans.modules.options.api/1 1.28

     */

    @Target({ElementType.TYPE})

    @Retention(RetentionPolicy.SOURCE)

    public @interface KeywordPanels {

        /**

         * List of KeywordPanel registrations.

         */

        KeywordPanel[] value();

    }

    /**

     * Registers keywords for some panel in the Options dialog. Should be placed

     * on a {@link JPanel} instance.

     *

     * @since org.netbeans.modules.options.api/1 1.28

     */

    @Target({ElementType.TYPE})

    @Retention(RetentionPolicy.SOURCE)

    public @interface KeywordPanel {

        /**

         * Keywords for use with search inside the Options dialog. You may use

         * {@code #key} syntax.

         */

        String[] keywords();

        /**

         * Keyword category for use with search inside the Options dialog.

         *

         * Location of this panel inside some top-level panel matching

         * {@link ContainerRegistration#id} or {@link SubRegistration#location}.

         * Typically this should be a reference to a compile-time constant also

         * used for the container's ID.

         */

        String location();

        /**

         * Path that can be used (with {@link #location}) in

         * {@link OptionsDisplayer#open(String)} matching

         * {@link SubRegistration#id}. Typically this should be a reference to a

         * compile-time constant to which other code can refer. You may use

         * {@code #key} syntax.

         */

        String id();

        /**

         * Position relative to sibling subpanels matching the tab index in a tabbed pane.

         * Miscellaneous panel's tabs are always sorted alphabetically.

         */

        int index();

    }