org.netbeans.spi.options.OptionsPanelController Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.netbeans.spi.options;
import java.beans.PropertyChangeListener;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.util.List;
import javax.swing.JComponent;
import org.netbeans.api.options.OptionsDisplayer;
import org.netbeans.modules.options.OptionsPanelControllerAccessor;
import org.netbeans.modules.options.advanced.AdvancedPanelController;
import org.openide.util.HelpCtx;
import org.openide.util.Lookup;
/**
* PanelController creates visual representation of one Options Dialog
* category, and manages communication between Options Dialog and this
* panel.
*/
public abstract class OptionsPanelController {
/**
* Property name constant.
*/
public static final String PROP_VALID = "valid";
/**
* Property name constant.
*/
public static final String PROP_CHANGED = "changed";
/**
* Property name constant.
*/
public static final String PROP_HELP_CTX = "helpCtx";
static {
OptionsPanelControllerAccessor.DEFAULT = new OptionsPanelControllerAccessor() {
@Override
public void setCurrentSubcategory(OptionsPanelController controller, String subpath) {
controller.setCurrentSubcategory(subpath);
}
};
}
/**
* Creates an advanced tabbed controller, just like Miscellaneous section.
* @param subpath path to folder under OptionsDialog folder containing
* instances of AdvancedOption class. Path is composed from registration
* names divided by slash. E.g. "MyCategory" for the following registration:
*
* <folder name="OptionsDialog">
* <file name="MyCategory.instance">
* <attr name="instanceClass" stringvalue="org.foo.MyCategory"/>
* <attr name="position" intvalue="900"/>
* </file>
* <folder name="MyCategory">
* <file name="SubCategory1.instance">
* <attr name="instanceClass" stringvalue="org.foo.Subcategory1"/>
* </file>
* <file name="SubCategory2.instance">
* <attr name="instanceClass" stringvalue="org.foo.Subcategory2"/>
* </file>
* </file>
* </folder>
* @return OptionsPanelController a controller wrapping all AdvancedOption instances found in the folder
* @since 1.8
* @deprecated Use {@link ContainerRegistration} instead.
*/
@Deprecated
public static final OptionsPanelController createAdvanced(String subpath) {
return new AdvancedPanelController(subpath);
}
/**
* Component should load its data here. You should not do any
* time-consuming operations inside the constructor, because it
* blocks initialization of OptionsDialog. Initialization
* should be implemented in update method.
* This method is called after {@link #getComponent} method.
* Update method can be called more than one time for the same instance
* of JComponent obtained from {@link #getComponent} call.
*/
public abstract void update ();
/**
* This method is called off EDT when Options Dialog "OK" or "Apply" button is pressed.
*/
public abstract void applyChanges ();
/**
* This method is called when Options Dialog "Cancel" button is pressed.
*/
public abstract void cancel ();
/**
* Should return true if some option value in this
* category is valid.
*
*
* @return true if some option value in this
* category is valid
*/
public abstract boolean isValid ();
/**
* Should return true if some option value in this
* category has been changed.
*
*
* @return true if some option value in this
* category has been changed
*/
public abstract boolean isChanged ();
/**
* Each option category can provide some lookup. Options Dialog master
* lookup is composed from these individual lookups. Master lookup
* can be obtained from {@link #getComponent} call. This lookup is designed
* to support communication anong individual panels in one Options
* Dialog.
*
* There is no guarantee that this method will be called from AWT thread.
*
* @return lookup provided by this Options Dialog panel
*/
public Lookup getLookup () {
return Lookup.EMPTY;
}
/**
* 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.
*
* Note that if the search is cleared (user presses Esc or Enter with empty text)
* this method is called with null as values for both the parameters, giving the
* implementors the chance to undo the filtering done is some previous invocation.
* @param searchText the text the user has entered in the search box in the options window.
* @param matchedKeywords the list of matched keywords for a specific panel in the options window.
* @since 1.30
*/
public void handleSuccessfulSearch(String searchText, List matchedKeywords) {
}
/**
* Returns visual component representing this options category.
* This method is called before {@link #update} method.
*
* @param masterLookup master lookup composed from lookups provided by
* individual OptionsPanelControllers
* - {@link OptionsPanelController#getLookup}
* @return visual component representing this options category
*/
public abstract JComponent getComponent (Lookup masterLookup);
/**
* Enables to handle selection of current subcategory. It is called from
* {@link org.netbeans.api.options.OptionsDisplayer#open(java.lang.String)},
* if some subpath is defined.
* @param subpath path of subcategories to be selected. Path is
* composed from registration names divided by slash.
* @see org.netbeans.api.options.OptionsDisplayer
* @since 1.8
*/
protected void setCurrentSubcategory(String subpath) {
}
/**
* Enables to handle selection of subcategory. It is meant to be called from
* a composite OptionspanelController and delegates to
* {@link #setCurrentSubcategory(java.lang.String)}.
* @param subpath path of subcategory to be selected. Path is
* composed from registration names divided by slash.
* @since 1.38
*/
public final void setSubcategory(String subpath) {
setCurrentSubcategory(subpath);
}
/**
*
* Get current help context asociated with this panel.
*
*
* @return current help context
*/
public abstract HelpCtx getHelpCtx ();
/**
* Registers new listener.
*
*
* @param l a new listener
*/
public abstract void addPropertyChangeListener (PropertyChangeListener l);
/**
* Unregisters given listener.
*
*
* @param l a listener to be removed
*/
public abstract void removePropertyChangeListener (PropertyChangeListener l);
/**
* Registers a simple panel at the top level of the Options dialog.
* Should be placed on a {@link OptionsPanelController} instance.
* @see OptionsCategory
* @since org.netbeans.modules.options.api/1 1.14
*/
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.SOURCE)
public @interface TopLevelRegistration {
/**
* Optional path that can be used in {@link OptionsDisplayer#open(String)}.
* Typically this should be a reference to a compile-time constant to which other code can refer.
*/
String id() default "";
/** Label shown on the button. You may use {@code #key} syntax. */
String categoryName();
/** Path to icon for the button. */
String iconBase();
/**
* Optional keywords (separated by commas) for use with Quick Search (must also specify {@link #keywordsCategory}).
* You may use {@code #key} syntax.
*/
String keywords() default "";
/** Keyword category for use with Quick Search (must also specify {@link #keywords}). */
String keywordsCategory() default "";
/** Position relative to other top-level panels. */
int position() default Integer.MAX_VALUE;
}
/**
* Registers a subpanel inside a top-level container panel in the Options dialog.
* Should be placed on a {@link OptionsPanelController} instance.
* @see AdvancedOption
* @since org.netbeans.modules.options.api/1 1.14
*/
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.SOURCE)
public @interface SubRegistration {
/**
* Optional path that can be used (with {@link #location}) in {@link OptionsDisplayer#open(String)}.
* Typically this should be a reference to a compile-time constant to which other code can refer.
*/
String id() default "";
/**
* Location of this panel inside some top-level panel matching {@link ContainerRegistration#id}.
* If unspecified, placed in the Miscellaneous panel.
* Typically this should be a reference to a compile-time constant also used for the container's ID.
*/
String location() default "Advanced";
/** Label shown on the tab. You may use {@code #key} syntax. */
String displayName();
/**
* Optional keywords (separated by commas) for use with Quick Search (must also specify {@link #keywordsCategory}).
* You may use {@code #key} syntax.
*/
String keywords() default "";
/** Keyword category for use with Quick Search (must also specify {@link #keywords}). */
String keywordsCategory() default "";
/**
* Position relative to sibling subpanels.
* Accepted only for non-default {@link #location} (Miscellaneous panel is sorted alphabetically).
*/
int position() default Integer.MAX_VALUE;
}
/**
* Registers a panel with child panels at the top level of the Options dialog.
* May be placed on any package (i.e. {@code package-info.java}).
* Register children using {@link SubRegistration}.
* @see OptionsCategory
* @since org.netbeans.modules.options.api/1 1.14
*/
@Target(ElementType.PACKAGE)
@Retention(RetentionPolicy.SOURCE)
public @interface ContainerRegistration {
/**
* Path that can be used in {@link OptionsDisplayer#open(String)} and {@link SubRegistration#location}.
* Typically this should be a reference to a compile-time constant to which other code can refer.
*/
String id();
/** Label shown on the button. You may use {@code #key} syntax. */
String categoryName();
/** Path to icon for the button. */
String iconBase();
/**
* Optional keywords (separated by commas) for use with Quick Search (must also specify {@link #keywordsCategory}).
* You may use {@code #key} syntax.
*/
String keywords() default "";
/** Keyword category for use with Quick Search (must also specify {@link #keywords}). */
String keywordsCategory() default "";
/** Position relative to other top-level panels. */
int position() default Integer.MAX_VALUE;
}
/**
* Similar to {@link Keywords} but permits multiple registrations of
* one class.
*
* @since org.netbeans.modules.options.api/1 1.29
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.SOURCE)
public @interface KeywordsRegistration {
/**
* List of Keywords registrations.
*/
Keywords[] value();
}
/**
* Registers keywords for some panel in the Options dialog. Should be placed
* on a {@link javax.swing.JPanel} instance.
*
* @since org.netbeans.modules.options.api/1 1.29
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.SOURCE)
public @interface Keywords {
/**
* Keywords for use with search inside the Options dialog. You may use
* {@code #key} syntax. The case in not important.
*
* Each entry in the provided array is split around comma character.
* For example:
*
*
* Split examples showing array and keywords
* Provided array Keywords { "Boo", "fOo" } { "BOO", "FOO" } { "boo and", "foo" } { "BOO AND", "FOO" } { "boo,and", "foo" } { "BOO", "AND", "FOO" }
*
* The user's search-text is split around the space character to form words.
* All words need to be present in a panel to yield a successful search.
* The registered keywords {"Boo,anD", "fOo"}, for example, yield the following results with these search-texts:
*
*
* Search examples showing search-text and results
* User's search-text Result "boo" keyword found "nd" keyword found "boo and" keyword found "boo moo" keyword NOT found
*/
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.
*
* If the panel is in the Miscellaneous category you must also specify {@link #tabTitle}).
*/
String location();
/**
* Optional title that must be used if the panel is part of a tabbed pane, such as when it is
* in the Editor, Fonts & Colors, Java, PHP, C/C++ or Miscellaneous categories, matching the
* {@link SubRegistration#displayName}.
*
* You may use {@code #key} syntax.
*/
String tabTitle() default "";
}
}