public class Options extends Object implements XMLSerializable
DocumentOperations,
SequenceAnnotationGenerators
and
SequenceGraphs.
Handles creating a graphical user interface from the options,
provides programmatic access to the options, and handles persistent storage.
This class also provides various types of option implementations,
such as Boolean, String, ComboBox and also provides the ability for custom
types of options to be created.
This class can be used in one of two ways. Either you subclass it
(which is essential if you want to override the default layout of the graphical options panel)
or you can just use it as is.
For examples of both types of usage, see
SequenceAnnotationGenerator.getOptions
or
DocumentOperation.getOptions.
Some of the other functionality provided by this class includes
addBooleanOption,
addStringOption,
addMultipleLineStringOption,
addComboBoxOption,
addEditableComboBoxOption,
addRadioOption,
addIntegerOption,
addDoubleOption,
addDateOption,
addFileSelectionOption,
addExecutableFileSelectionOption,
addLabel,
addDivider,
addButtonOption,
or you can create custom option types by using addCustomOption.
Option.setAdvanced)
which means when they are graphically displayed,
advanced options are hidden by default, and the user has to click be "show more options" button to see
the advanced options.
Option.setDescription addChildOptions),
which are either displayed one above the other (the default) or
as separate pages (addChildOptionsPageChooser).
Options.Option.addDependent(com.biomatters.geneious.publicapi.plugin.Options.Option, Object),
BooleanOption.addDependent
and RadioOption.addDependent.
See Option.setDisabledValue for controlling the value returned from a dislabed option.
Option.addChangeListener.
getDescriptionAndState and to set the values programmatically use setStringValue
beginAlignHorizontally and endAlignHorizontally
or by subclassing Options and overriding createPanel and createAdvancedPanel
savePreferences and restorePreferences
or to XML (see valuesToXML and valuesFromXML).
The default values can be restored using restoreDefaults.
XMLSerializable).
This differs from serializing just the values in that all labels, descriptions, dependencies etc are serialized.
Note that prior to about 2007-08-10 it was not required that Options were XMLSerializable. Therefore it is not
guarenteed that all sub-classes of Options are compatible with being XMLSerialized. Furthermore some Options instances
may use ComboBox options by sub-classing Options.OptionValue, and not all of the existing Options.OptionValue
sub-classes properly implement the XMLSerializable contract.
addMultipleOptions.
verifyOptionsAreValid.
setProOnly,
setFillHorizontalSpace,
setSpanningComponent,
setVisible,
setHidden,
setWarningMessage,
setRestoreDefaultApplies,
addCustomComponent,
getDialogOptions ,
getOptionsHelp ,
addDocumentSelectionOption ,
addPrimerOption,
BooleanOption.addChildOptionsDependent
getPanel or getAdvancedPanel have been made), programmatically changing
the values (by using setValue or setStringValue) may only be performed from the swing thread
since changes to Option values are immediately mirrored to the graphical interface.
Examples
public class OptionsExample1 extends Options {
private StringOption annotationType;
private BooleanOption trimEnds;
private IntegerOption numberOfBasesToTrim;
public OptionsExample1() {
annotationType = addStringOption("annotationType","Annotation Type","CDS");
annotationType.setDescription("The type of annotation to add to the sequence");
trimEnds = addBooleanOption("trimEnds","Trim Ends",false);
numberOfBasesToTrim = addIntegerOption("numberOfBasesToTrim","Number Of Bases To Trim",5);
}
public String getAnnotationType() {
return annotationType.getValue();
}
public int getNumberOfBasesToTrim() {
if (trimEnds.getValue()) {
return numberOfBasesToTrim.getValue();
}
else {
return 0;
}
}
}
public class OptionsExample2 extends Options {
private StringOption annotationType;
private IntegerOption numberOfBasesToTrim;
public OptionsExample2() {
annotationType = addStringOption("annotationType","Annotation Type","CDS");
annotationType.setDescription("The type of annotation to add to the sequence");
beginAlignHorizontally(null,false);
BooleanOption trimEnds = addBooleanOption("trimEnds","Trim Ends",false);
numberOfBasesToTrim = addIntegerOption("numberOfBasesToTrim","",5);
Option basesLabel = addLabel("bases");
endAlignHorizontally();
trimEnds.addDependent(numberOfBasesToTrim, true);
trimEnds.addDependent(basesLabel,true);
numberOfBasesToTrim.setDisabledValue(0);
}
public String getAnnotationType() {
return annotationType.getValue();
}
public int getNumberOfBasesToTrim() {
return numberOfBasesToTrim.getValue();
}
}
public class OptionsExample3 extends Options {
private StringOption annotationType;
private IntegerOption numberOfBasesToTrim;
private RadioOption<TrimType> trimType;
public static final TrimType trimByLength = new TrimType("trimByLength","By Length");
public static final TrimType trimVectors = new TrimType("trimVectors","Vectors");
public static final Sensitivity sensitivityHigh = new Sensitivity("high","UniVec (High sensitivity)","Recommended when the result will be inspected manually");
public static final Sensitivity sensitivityLow = new Sensitivity("low","UniVec_Core (Few false positives)","Recommended for automated pipelines");
private ComboBoxOption<Sensitivity> sensitivity;
private IntegerOption minimum;
private IntegerOption maximum;
public OptionsExample3() {
annotationType = addStringOption("annotationType","Annotation Type","CDS");
annotationType.setDescription("The type of annotation to add to the sequence");
trimType = addRadioOption("trimType","", Arrays.asList(trimByLength,trimVectors),trimByLength, Alignment.VERTICAL_ALIGN);
numberOfBasesToTrim = addIntegerOption("numberOfBasesToTrim","Number of Bases",5);
sensitivity = addComboBoxOption("sensitivity","Sensitivity", Arrays.asList(sensitivityHigh, sensitivityLow),sensitivityHigh);
trimType.addDependent(trimByLength, numberOfBasesToTrim, true);
trimType.addDependent(trimVectors, sensitivity, true);
beginAlignHorizontally(null,false);
minimum = addIntegerOption("min","Between",2,0,10);
maximum = addIntegerOption("max","and",7,0,10);
// Add change listeners to ensure that minimum<=maximum :
minimum.addChangeListener(new SimpleListener() {
public void objectChanged() {
if (minimum.getValue()>maximum.getValue()) {
maximum.setValue(minimum.getValue());
}
}
});
maximum.addChangeListener(new SimpleListener() {
public void objectChanged() {
if (maximum.getValue()<minimum.getValue()) {
minimum.setValue(maximum.getValue());
}
}
});
endAlignHorizontally();
}
public Sensitivity getSensitivity() {
return sensitivity.getValue();
}
public TrimType getTrimType() {
return trimType.getValue();
}
public String getAnnotationType() {
return annotationType.getValue();
}
public int getNumberOfBasesToTrim() {
return numberOfBasesToTrim.getValue();
}
public static final class TrimType extends Options.OptionValue {
public TrimType(String name, String label) {
super(name, label);
}
}
public static final class Sensitivity extends Options.OptionValue {
public Sensitivity(String name, String label, String description) {
super(name, label, description);
}
}
}
DocumentOperation.getOptions
or SequenceAnnotationGenerator.getOptions
and Geneious handles displaying dialogs at appropriate times to display the options. However, should you wish to manually display an options dialog, the following code fragment illustrates how to do this.
Options options = new OptionsExample1();
Dialogs.showOptionsDialog(options,"Choose Annotation",true);
| Modifier and Type | Class and Description |
|---|---|
static class |
Options.Alignment
Used the specifying how other options for a
Options.RadioOption are layed out. |
static class |
Options.BooleanOption
An option that stores a Boolean and is represented graphically as a check box.
|
static class |
Options.ButtonOption
Provides the user with a button which may have actions associated with it by calling
Options.ButtonOption.addActionListener(java.awt.event.ActionListener). |
static class |
Options.ComboBoxOption<ValueType extends Options.OptionValue>
An option that provides the user with a list of options in a combo box
|
static interface |
Options.ComponentCreator
An interface for creating components on demand for use with
addCustomComponent(com.biomatters.geneious.publicapi.plugin.Options.ComponentCreator) |
static class |
Options.DateOption
An option that stores a date.
|
static class |
Options.DoubleOption
An option that stores an Double and is displayed graphically
to the user as a single line text field with a spinner (up and down arrow)
on the right-hand side
|
static class |
Options.EditableComboBoxOption
Like a ComboBoxOption, but besides letting the user choose one of
the preconfigured default values, also allows arbitrary custom strings
to be entered.
|
static class |
Options.ExecutableFileSelectionOption
Provides the user with an executable file name and provides assistance with finding
the location of it.
|
static class |
Options.FileSelectionOption
Provides functionality to let the user choose a file.
|
static class |
Options.IntegerOption
An option that stores an Integer and is displayed graphically
to the user as a single line text field with a spinner (up and down arrow)
on the right-hand side.
|
static class |
Options.LabelOption
An option that is only used for display purposes.
|
static class |
Options.MultipleLineStringOption
An option that stores a String and is displayed to the user as a multiple line text area
|
static class |
Options.MultipleOptions
Stores the multiple options added using
addMultipleOptions(String, Options, boolean)
and provides methods to access the current values (Options.MultipleOptions.getValues()) and to add change listeners
(Options.MultipleOptions.addChangeListener(org.virion.jam.util.SimpleListener) and to
change the enabled state Options.MultipleOptions.setEnabled(boolean). |
static class |
Options.Option<ValueType,ComponentType extends JComponent>
The base class of all types of options.
|
static class |
Options.OptionValue
Possible values that a
Options.RadioOption or Options.ComboBoxOption can
take on. |
static class |
Options.PageChooserType
An enum listing the different types of child options choosers.
|
static class |
Options.RadioOption<ValueType extends Options.OptionValue>
An option that provides the user with a list of radio buttons to select one of
|
static class |
Options.StringOption
An option that stores a String and is displayed graphically to the user as a single line text field.
|
XMLSerializable.OldVersionCompatible, XMLSerializable.VersionSupportType| Modifier and Type | Field and Description |
|---|---|
static String |
ASSOCIATED_OPTION_PROPERTY
The Components (or sub-components) returned by
Options.Option.getComponent() may provide
this property via JComponent.getClientProperty(Object) which will be a reference to the Option the component belongs to. |
ROOT_ELEMENT_NAME| Modifier | Constructor and Description |
|---|---|
protected |
Options()
For use by subclasses only; Equivalent to
Options(getClass()) . |
|
Options(Class cl)
Construct a new options.
|
|
Options(Class cl,
String preferenceNameSuffix)
Construct a new options.
|
protected |
Options(org.jdom.Element element)
Constructor for XML Serialization.
|
| Modifier and Type | Method and Description |
|---|---|
Options.BooleanOption |
addBooleanOption(String name,
String label,
Boolean defaultValue)
Add an option that stores a Boolean and is represented graphically as a check box.
|
Options.ButtonOption |
addButtonOption(String name,
String label,
String buttonLabel)
Adds an option that is represented by a button, and may have actions attached to it which are activated when the user clicks the button (see
Options.ButtonOption.addActionListener(java.awt.event.ActionListener)). |
Options.ButtonOption |
addButtonOption(String name,
String label,
String buttonLabel,
Icon icon,
int alignment)
Adds an option that is represented by a button, and may have actions attached to it which are activated when the user clicks the button (see
Options.ButtonOption.addActionListener(java.awt.event.ActionListener)). |
void |
addChangeListener(SimpleListener listener)
add a listener to be notified when the value of any option changes
The listener is also notified if
some options requires an active license, and the licence type changes.
|
Options |
addChildOptions(String name,
String label,
String description)
Creates, adds and returns some child options.
|
void |
addChildOptions(String name,
String label,
String description,
Options childOptions)
|
void |
addChildOptions(String name,
String label,
String description,
Options childOptions,
boolean useParentPreferences)
Adds a set of existing Options as child options of this Options.
|
Options.Option |
addChildOptionsPageChooser(String name,
String label,
List<String> disabledOptions,
Options.PageChooserType type,
boolean allChildOptionsApplySimultaneously)
Makes all previously added child options available via a list of tab buttons.
|
void |
addCollapsibleChildOptions(String name,
String label,
String description,
Options childOptions,
boolean useParentPreferences,
boolean defaultCollapsed)
Add child options that can be expanded and collapsed.
|
<T extends Options.OptionValue> |
addComboBoxOption(String name,
String label,
List<? extends T> possibleValues,
T defaultValue)
Add a new ComboBoxOption.
|
<T extends Options.OptionValue> |
addComboBoxOption(String name,
String label,
T[] possibleValues,
T defaultValue)
Add a new ComboBoxOption.
|
Options.Option |
addCustomComponent(JComponent component)
Adds a custom component that will be laid out along with all the standard
options.
|
Options.Option |
addCustomComponent(Options.ComponentCreator componentCreator)
Adds a custom component that will be laid out along with all the standard
options.
|
<OptionType extends Options.Option> |
addCustomOption(OptionType option)
Add a custom option.
|
Options.DateOption |
addDateOption(String name,
String label,
Date defaultValue)
Add an option that stores a Date (day, month and year only) and is displayed graphically
to the user as a set of 3 spinners together with a button that opens a new dialog for nicer date selection
from a calendar style view.
|
void |
addDefaultsRestoredListener(SimpleListener listener)
add a listener to be notified when the options are restored to their defaults
(e.g.
|
Options.Option |
addDivider(String label)
Add a new divider that is displayed between options when the options are graphically presented to the user.
|
DocumentSelectionOption |
addDocumentSelectionOption(String name,
String label,
DocumentSelectionOption.FolderOrDocuments defaultValue,
DocumentType documentType,
List<DocumentField> fieldsToDisplay,
boolean allowMultipleSelections,
List<AnnotatedPluginDocument> additionalDocuments)
Equivalent to
addDocumentSelectionOption(name, label, defaultValue, Collections.singleton(documentType), null, null, fieldsToDisplay, allowMultipleSelections, additionalDocuments (which takes a Set of DocumentTypes instead of a single DocumentType) |
DocumentSelectionOption |
addDocumentSelectionOption(String name,
String label,
DocumentSelectionOption.FolderOrDocuments defaultValue,
Set<DocumentType> documentTypes,
DocumentFilter documentFilter,
String documentTypeDescription,
List<DocumentField> fieldsToDisplay,
boolean allowMultipleSelections,
List<AnnotatedPluginDocument> additionalDocuments)
An option to allow the user to select a number of documents of a particular type from their local database.
|
Options.DoubleOption |
addDoubleOption(String name,
String label,
Double defaultValue)
Add an option that stores an Double and is displayed graphically
to the user as a single line text field with a spinner (up and down arrow)
on the right-hand side
For information on what the initial value of this option is set to see
addStringOption. |
Options.DoubleOption |
addDoubleOption(String name,
String label,
Double defaultValue,
Double minimum,
Double maximum)
Add an option that stores an Double and is displayed graphically
to the user as a single line text field with a spinner (up and down arrow)
on the right-hand side
For information on what the initial value of this option is set to see
addStringOption. |
Options.EditableComboBoxOption |
addEditableComboBoxOption(String name,
String label,
String defaultValue,
String[] selectableValues)
Add an option that stores a String that is displayed graphically to the user as a single line text field.
|
Options.EditableComboBoxOption |
addEditableComboBoxOption(String name,
String label,
String defaultValue,
String[] selectableValues,
int historySize)
Add an option that stores a String that is displayed graphically to the user as a single line text field.
|
Options.ExecutableFileSelectionOption |
addExecutableFileSelectionOption(String name,
String label,
String fileName)
Adds an ExecutableFileSelectionOption where the default executable path is just the filename
without a path component, i.e.
|
Options.ExecutableFileSelectionOption |
addExecutableFileSelectionOption(String name,
String label,
String fileName,
String defaultValue)
Add an option that provides the user with an executable file name and provides assistance with finding
the location of it.
|
Options.FileSelectionOption |
addFileSelectionOption(String name,
String label,
String defaultValue)
Add an option that provides functionality to let the user choose a file.
|
Options.FileSelectionOption |
addFileSelectionOption(String name,
String label,
String defaultValue,
String[] selectableFileNames,
String buttonLabel)
Add an option that provides functionality to let the user choose a file.
|
Options.FileSelectionOption |
addFileSelectionOption(String name,
String label,
String defaultValue,
String[] selectableFileNames,
String buttonLabel,
FilenameFilter filter)
Add an option that provides functionality to let the user choose a file.
|
void |
addHelpButton(String dialogTitle,
String dialogMessage)
Equivalent to
addHelpButtonOption(String, String) |
Options.Option |
addHelpButtonOption(String dialogTitle,
String dialogMessage)
Adds a little help button (with a question mark on it) which when clicked shows a dialog containing a message
|
Options.IntegerOption |
addIntegerOption(String name,
String label,
Integer defaultValue)
Add option that stores an Integer and is displayed graphically
to the user as a single line text field with a spinner (up and down arrow)
on the right-hand side
For information on what the initial value of this option is set to see
addStringOption. |
Options.IntegerOption |
addIntegerOption(String name,
String label,
Integer defaultValue,
Integer minimum,
Integer maximum)
Add option that stores an Integer and is displayed graphically
to the user as a single line text field with a spinner (up and down arrow)
on the right-hand side
For information on what the initial value of this option is set to see
addStringOption. |
Options.Option<String,? extends JComponent> |
addLabel(String label)
Add a new label that is displayed between options when the options are graphically presented to the user.
|
Options.Option<String,? extends JComponent> |
addLabel(String label,
boolean centreText,
boolean spanEntirePanelWidth)
Add a new label that is displayed between options when the options are graphically presented to the user.
|
Options.LabelOption |
addLabelWithIcon(String label,
Icons icons)
Adds a label with an icon to the left of it.
|
Options.MultipleLineStringOption |
addMultipleLineStringOption(String name,
String label,
String defaultValue,
int rows,
boolean lineWrap)
Add an option that stores a String and is displayed to the user as a multiple line text area
It will have its value set to its default value.
|
Options.MultipleOptions |
addMultipleOptions(String name,
Options multipleOptions,
boolean isAdvanced)
Adds a set of Options so that the user is able to choose to have one or more instances
of these child options through the use of +/- buttons to the right of the options.
|
DocumentSelectionOption |
addPrimerSelectionOption(String name,
String label,
DocumentSelectionOption.FolderOrDocuments defaultValue,
boolean allowMultipleSelections,
List<AnnotatedPluginDocument> additionalDocuments)
A convenience method for adding a document selection option for primers.
|
<T extends Options.OptionValue> |
addRadioOption(String name,
String label,
List<T> possibleValues,
T defaultValue,
Options.Alignment alignment)
Construct a new Radio option.
|
<T extends Options.OptionValue> |
addRadioOption(String name,
String label,
T[] possibleValues,
T defaultValue,
Options.Alignment alignment)
Construct a new Radio option.
|
Options.Option<WritableDatabaseService,JComponent> |
addServiceOption(String name,
String label,
WritableDatabaseService defaultValue)
Add an option that allows the user to select a WtiableDatabaseService which appears under one of the services returned from
PluginUtilities.getWritableDatabaseServiceRoots(). |
Options.StringOption |
addStringOption(String name,
String label,
String defaultValue)
|
Options.StringOption |
addStringOption(String name,
String label,
String defaultValue,
String watermarkText)
Add an option that stores a String that is displayed graphically to the user as a single line text field.
|
boolean |
areValuesGoodEnoughToContinue()
This is called by Geneious when the user clicks OK in the options dialog.
|
void |
beginAlignHorizontally(String label,
boolean useEqualWidths)
Starts a row of horizontally aligned options that will later be finished with
a call to
endAlignHorizontally(). |
boolean |
canRestoreDefaults()
Return true if calling
restoreDefaults() would change anything. |
protected JPanel |
createAdvancedPanel()
Creates a graphical panel used to display advanced options.
|
protected JPanel |
createPanel()
Creates a graphical panel used to display these options.
|
void |
endAlignHorizontally()
Finishes a previously started row of horizontally aligned options (see
beginAlignHorizontally(String, boolean). |
void |
fromXML(org.jdom.Element element)
Restore the object from the JDOM Element returned by
XMLSerializable.toXML(). |
JPanel |
getAdvancedPanel()
Get a graphical panel used to display advanced options.
|
Map<String,Options> |
getChildOptions()
Get all child options added using
addChildOptions(String, String, String, Options). |
Options.Option |
getChildOptionsPageChooser()
if
addChildOptionsPageChooser(String, String, java.util.List, com.biomatters.geneious.publicapi.plugin.Options.PageChooserType, boolean) has been called, return the
option created for choosing which set of child options are currently active. |
String |
getDescriptionAndState()
Describe all properties and the state of these options.
|
Dialogs.DialogOptions |
getDialogOptions()
Returns a
Dialogs.DialogOptions to use when laying out a dialog containing your options. |
Icons |
getIcons()
Gets Icons associated with these options.
|
List<Options.MultipleOptions> |
getMultipleOptions()
Get all multiple options added using
addMultipleOptions(String, Options, boolean). |
Options.MultipleOptions |
getMultipleOptions(String name)
Get a set of multiple options added using
addMultipleOptions(String, Options, boolean). |
String |
getNamesAndValues(boolean includeLabelsToo)
Provides a text description of all option names and values.
|
Options.Option |
getOption(String optionName)
Get an option or child option.
|
List<Options.Option> |
getOptions()
Get a list of all options added via any of the add*Option methods.
|
String |
getOptionsHelp()
Override this method and return a non-null value to have it displayed as html in a dialog when the user clicks on
a small help button in the corner of any window showing these options.
|
JPanel |
getPanel()
Get a graphical panel used to display these options.
|
Options |
getParentOptions() |
Object |
getValue(String optionName)
get the value of the option with the name
optionName. |
String |
getValueAsString(String optionName)
Get the value of this option as a string.
|
Geneious.MajorVersion |
getVersionSupportForValuesToXML(XMLSerializable.VersionSupportType versionType)
Gets the version support as defined by
OldVersionCompatible#getVersionSupport(com.biomatters.geneious.publicapi.documents.XMLSerializable.VersionSupportType)
for use with valuesToXML(com.biomatters.geneious.publicapi.plugin.Geneious.MajorVersion, String) |
boolean |
hasAdvancedOptions()
Return true if any option or any child options returns true from
Options.Option.isAdvanced() |
boolean |
hasBasicOptions()
Return true if any option or any child options returns false from
Options.Option.isAdvanced() |
boolean |
isEnabled()
Determine if these options appear enabled.
|
boolean |
isHorizontallyCompact()
Returns true if these options or any ancestor options have been set as horizontally compact using
setHorizontallyCompact(boolean). |
boolean |
isProOnly()
Determine whether or not these options require an active license.
|
boolean |
isVisible()
Return true if the graphical component that displays these options would be visible to the user when the panel is showing.
|
void |
removeChangeListener(SimpleListener listener)
Remove a listener to be notified when the value of any option changes
|
void |
removeDefaultsRestoredListener(SimpleListener listener)
Remove a listener to be notified when the options are restored to their defaults
(e.g.
|
void |
restoreDefaults()
Restores all current option values and child options to their default values.
|
void |
restorePreferences()
Restore the current option values from the default persistent storage location
by calling
restorePreferences(null, false)
Note: If there is no value for an option in preferences then it value isn't changed by this method. |
void |
restorePreferences(String preferenceNodeSuffix,
boolean restorePreferencesOfOptionsThatHaveHadTheirValuesAlreadySet)
Restores the current option values from persistent storage, i.e.
|
void |
savePreferences()
Save the current option values persistently in the default storage location
by calling
savePreferences(null) |
void |
savePreferences(String preferenceNodeSuffix)
Save the current option values persistently, i.e.
|
void |
setChildOptionsCollapsed(String name,
boolean collapsed)
Set the collapsed state of child options added previously using
addCollapsibleChildOptions(String, String, String, Options, boolean, boolean). |
void |
setEnabled(boolean enabled)
Sets the enabled state of all these Options.
|
void |
setHorizontallyCompact(boolean horizontallyCompact)
Flags the basic options to be displayed in a visually compact form suitable for displaying in a limited amount of space.
|
void |
setHorizontallyCompactAdvanced(boolean horizontallyCompact)
Flags the advanced options to be displayed in a visually compact form suitable for displaying in a limited amount of space.
|
void |
setIcons(Icons icons)
Sets Icons associated with these options.
|
void |
setInScrollPane(boolean inScrollPane)
Specifies whether the options should be displayed in a scroll pane if the panel is shrunk below it's preferred
size.
|
void |
setProOnly(boolean proOnly)
Sets whether or not these options require an active license
By default all options do not require an active license.
|
void |
setSavePreferencesForInvisibleChildOptions(boolean saveInvisibleChildOptions)
Sets whether or not calling restore defaults (
restoreDefaults())
or save preferences (savePreferences()) will apply only to the child
options (ChildOptions that are currently visible. |
boolean |
setStringValue(String optionName,
String value)
set the value of an option
|
boolean |
setValue(String optionName,
Object value)
set the value of an option
|
void |
setVerticallyCompact(boolean verticallyCompact)
Flags the basic options to be displayed in a visually compact form suitable for displaying in a limited amount of space.
|
void |
setVerticallyCompactAdvanced(boolean verticallyCompact)
Flags the advanced options to be displayed in a visually compact form suitable for displaying in a limited amount of space.
|
void |
setVisible(boolean visible)
Sets the visibility of the graphical component that displays these options and
makes appropriate changes to the size of the window (if any) that contains the graphical component.
|
String |
toString()
|
org.jdom.Element |
toXML()
Convert object to a JDOM element.
|
void |
valuesFromXML(org.jdom.Element root)
Deserializes the current values for these options from XML.
|
void |
valuesFromXML(org.jdom.Element root,
boolean includeOptionsWhichDontRestorePreferences)
Deserializes the current values for these options from XML.
|
org.jdom.Element |
valuesToXML(Geneious.MajorVersion version,
String rootElementName)
Serializes the current values for these options to XML for use with
a later call to
valuesFromXML(org.jdom.Element). |
org.jdom.Element |
valuesToXML(Geneious.MajorVersion version,
String rootElementName,
boolean excludeOptionsWhereRestorePreferenceApplies)
Serializes the current values for these options to XML for use with
a later call to
valuesFromXML(org.jdom.Element). |
org.jdom.Element |
valuesToXML(String rootElementName)
Serializes the current values for these options to XML for use with
a later call to
valuesFromXML(org.jdom.Element). |
String |
verifyOptionsAreValid()
Override this to have the current contents of options checked (for example String options that
allow the user to enter arbitrary text) to make sure they are valid before proceeding.
|
public static final String ASSOCIATED_OPTION_PROPERTY
Options.Option.getComponent() may provide
this property via JComponent.getClientProperty(Object) which will be a reference to the Option the component belongs to.protected Options()
Options(getClass()) .public Options(Class cl)
cl - a class used to generate a unique name under which persistent preferences can be stored.
Usually this should be the class that these options are constructed within.public Options(Class cl, String preferenceNameSuffix)
cl - a class used to generate a unique name under which persistent preferences can be stored.
Usually this should be the class that these options are constructed within.preferenceNameSuffix - A suffix to append to the unique name generated from the class.
For example, a set of sequence alignment options may vary the value of this parameter
depending on whether it is aligning nucleotide or protein sequences in order to have different preference sets
for each type of sequence.IllegalArgumentException - if cl is null and the concrete class of these options is Options.classprotected Options(org.jdom.Element element)
throws XMLSerializationException
XMLSerializableXMLSerializationExceptionpublic Dialogs.DialogOptions getDialogOptions()
Dialogs.DialogOptions to use when laying out a dialog containing your options.
You may specify an array of strings or actions when you construct your DialogOptions, and these will be displayed as the dialog's buttons.
The operation will proceed if the user has clicked on the default button
(see Dialogs.DialogOptions.setDefaultButton(com.biomatters.geneious.publicapi.components.Dialogs.DialogAction) and
Dialogs.DialogOptions.setDefaultButton(String)), and not if the user has clicked on any other buttonpublic Options getParentOptions()
addChildOptions(String, String, String, Options)
or null if this has not been added to another Optionspublic void setEnabled(boolean enabled)
enabled - whether or not these Options should be enabled.public void setVisible(boolean visible)
visible - whether or not the graphical component that displays these options should be visible.isVisible()public boolean isVisible()
setVisible(boolean)public boolean isEnabled()
setEnabled(boolean)
which is true by default)
and if their parent options (if these Options are child options
or multiple options inside other Options) appear enabled.public final void setProOnly(boolean proOnly)
proOnly - true if these options require an active licensepublic boolean isProOnly()
public final void setIcons(Icons icons)
addChildOptionsPageChooser(String, String, java.util.List, com.biomatters.geneious.publicapi.plugin.Options.PageChooserType, boolean) addChildOptionsPageChooser} ,
then this specifies the icon will be used for the tab.icons - the iconspublic final Icons getIcons()
setIcons(Icons)
for more information.public String toString()
toString in class ObjectgetDescriptionAndState()public final String getDescriptionAndState()
getNamesAndValues(boolean)public final String getNamesAndValues(boolean includeLabelsToo)
getDescriptionAndState()includeLabelsToo - to also include the label displayed next to each optiongetDescriptionAndState()public final List<Options.Option> getOptions()
addBooleanOption, addStringOption,
addOption etc).
Note that this does not include child options at using addChildOptions.
To obtain a list of those, use getChildOptions().public final <OptionType extends Options.Option> OptionType addCustomOption(OptionType option)
addBooleanOption,
addStringOption etc.
To create a custom option type, extend Option.option - the option to be addedNullPointerException - if option is nullpublic final Options.Option addCustomComponent(JComponent component)
component is not XMLSerializable
then if these options are
serialized and deserialized, then deserialized component will be a blank panel.
Note: For performance reasons, it is often better to use addCustomComponent(ComponentCreator) instead where possible.component - the component to add which may want to implement XMLSerializable.Option.setSpanningComponent or Option.setFillHorizontalSpace may be used on it to adjust the size of the component.addCustomComponent(ComponentCreator)public final Options.Option addCustomComponent(Options.ComponentCreator componentCreator)
XMLSerializable
then if these options are
serialized and deserialized, then deserialized component will be a blank panel.componentCreator - a create on which Options.ComponentCreator.create() will be later called to create the component when it is about to be rendered. This will be invoked at most once.Option.setSpanningComponent or Option.setFillHorizontalSpace may be used on it to adjust the size of the component.public final Options.StringOption addStringOption(String name, String label, String defaultValue, String watermarkText)
name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.label - a label describing this option to be displayed to the userdefaultValue - the default value for this optionwatermarkText - Watermark to display when no string is entered and textfield doesn't have focus, or null for none.public final Options.StringOption addStringOption(String name, String label, String defaultValue)
public final Options.EditableComboBoxOption addEditableComboBoxOption(String name, String label, String defaultValue, String[] selectableValues)
name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.label - a label describing this option to be displayed to the userdefaultValue - the default value for this optionselectableValues - some selectable values to display in the drop down box.public final Options.EditableComboBoxOption addEditableComboBoxOption(String name, String label, String defaultValue, String[] selectableValues, int historySize)
name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.label - a label describing this option to be displayed to the userdefaultValue - the default value for this optionselectableValues - some selectable values to display in the drop down box.historySize - the maximum number of user-entered strings to store as a history or 0 to keep no historypublic final Options.BooleanOption addBooleanOption(String name, String label, Boolean defaultValue)
name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.
Names should be in standard Java variable name style eg. "myAwesomeOption".label - a label describing this option to be displayed to the user. eg. "My Awesome Option"defaultValue - the default value for this optionpublic final Options.MultipleLineStringOption addMultipleLineStringOption(String name, String label, String defaultValue, int rows, boolean lineWrap)
name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.
Names should be in standard Java variable name style eg. "myAwesomeOption".label - a label describing this option to be displayed to the user. eg. "My Awesome Option"defaultValue - the default value for this optionrows - the number of rows in the text area when displayed to the userlineWrap - true if long lines should be wrapped when the text area is displayed to the userpublic final Options.IntegerOption addIntegerOption(String name, String label, Integer defaultValue, Integer minimum, Integer maximum)
addStringOption.name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.
Names should be in standard Java variable name style eg. "myAwesomeOption".label - a label describing this option to be displayed to the user. eg. "My Awesome Option"defaultValue - the default value for this optionminimum - The minimum value that the option can havemaximum - The maximum value that the option can havepublic final Options.IntegerOption addIntegerOption(String name, String label, Integer defaultValue)
addStringOption.name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.label - a label describing this option to be displayed to the user. eg. "My Awesome Option"defaultValue - the default value for this optionpublic final Options.ButtonOption addButtonOption(String name, String label, String buttonLabel, Icon icon, int alignment)
Options.ButtonOption.addActionListener(java.awt.event.ActionListener)).name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.
Names should be in standard Java variable name style eg. "myAwesomeOption".label - A label describing this option to be displayed to the user. eg. "My Awesome Option". Usually displayed to the left of the button.buttonLabel - The text on the button itselficon - An optional icon which will appear on the button. This icon is not XMLSerializable, and can be null.alignment - choose how to align the button - only works on if this option is spanning (see Options.Option.setSpanningComponent(boolean)). Choices are Options.ButtonOption.LEFT, Options.ButtonOption.CENTER, and Options.ButtonOption.RIGHTpublic final Options.ButtonOption addButtonOption(String name, String label, String buttonLabel)
Options.ButtonOption.addActionListener(java.awt.event.ActionListener)).name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.
Names should be in standard Java variable name style eg. "myAwesomeOption".label - A label describing this option to be displayed to the user. eg. "My Awesome Option". Usually displayed to the left of the button.buttonLabel - The text on the button itselfpublic final Options.DoubleOption addDoubleOption(String name, String label, Double defaultValue, Double minimum, Double maximum)
addStringOption.name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.label - a label describing this option to be displayed to the user. eg. "My Awesome Option"defaultValue - the default value for this optionminimum - The minimum value that the option can havemaximum - The maximum value that the option can havepublic final Options.DoubleOption addDoubleOption(String name, String label, Double defaultValue)
addStringOption.name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.
Names should be in standard Java variable name style eg. "myAwesomeOption".label - a label describing this option to be displayed to the user. eg. "My Awesome Option"defaultValue - the default value for this optionpublic final Options.DateOption addDateOption(String name, String label, Date defaultValue)
name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.
Names should be in standard Java variable name style eg. "myAwesomeOption".label - a label describing this option to be displayed to the user. eg. "My Awesome Option"defaultValue - the default value for this optionpublic final Options.Option<WritableDatabaseService,JComponent> addServiceOption(String name, String label, WritableDatabaseService defaultValue)
PluginUtilities.getWritableDatabaseServiceRoots(). Appears as a label showing the name of the currently
selected service with a button that pops up a tree to change the selected service.
name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.
Names should be in standard Java variable name style eg. "myAwesomeOption".label - a label describing this option to be displayed to the user. eg. "My Awesome Option"defaultValue - the default value for this option. May be null in which case Options.Option.getValue() on the Option may return a dummy service (with unique ID 'dummy') that returns no documents from its retrieve methods.public final <T extends Options.OptionValue> Options.ComboBoxOption<T> addComboBoxOption(String name, String label, List<? extends T> possibleValues, T defaultValue)
addStringOption.name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.label - a label describing this option to be displayed to the user. eg. "My Awesome Option"defaultValue - the default value for this optionpossibleValues - A list containing all possible values (i.e. all the entries to appear in the combo box)public final DocumentSelectionOption addDocumentSelectionOption(String name, String label, DocumentSelectionOption.FolderOrDocuments defaultValue, DocumentType documentType, List<DocumentField> fieldsToDisplay, boolean allowMultipleSelections, List<AnnotatedPluginDocument> additionalDocuments)
addDocumentSelectionOption(name, label, defaultValue, Collections.singleton(documentType), null, null, fieldsToDisplay, allowMultipleSelections, additionalDocuments (which takes a Set of DocumentTypes instead of a single DocumentType)addPrimerSelectionOption(String, String, com.biomatters.geneious.publicapi.plugin.DocumentSelectionOption.FolderOrDocuments, boolean, java.util.List)public final DocumentSelectionOption addDocumentSelectionOption(String name, String label, DocumentSelectionOption.FolderOrDocuments defaultValue, Set<DocumentType> documentTypes, DocumentFilter documentFilter, String documentTypeDescription, List<DocumentField> fieldsToDisplay, boolean allowMultipleSelections, List<AnnotatedPluginDocument> additionalDocuments)
addPrimerOption.name - The name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.
Names should be in standard Java variable name style eg. "myAwesomeOption".label - A label describing this option to be displayed to the user. eg. "My Awesome Option"defaultValue - The default value for this option.documentTypes - The types of documents to allow the user to choose from (for example DocumentType.OLIGO_DOC_TYPE). The type you want to search on must be a type defined prior to the documents being indexed so if you introduce a new document type that matches existing documents those documents will not be found.documentFilter - An optional filter to further reject documents even if they are one of the provided documentTypes. May be null to perform no additional filtering. The filter must not load the internal PluginDocuments. Instead it must only filter using properties of the AnnotatedPluginDocumentdocumentTypeDescription - An optional description of what the documentTypes and documentFilter accept. For example "linear nucleotide sequences". May be null in which case this implementation will choose an reasonable descriptionfieldsToDisplay - A list of DocumentFields which will be displayed in columns in the document selection dialog. If the list is null, then one will be created from the fields present on the documents.allowMultipleSelections - True if the user is able to select more than one document at a time, also enables folder selectionadditionalDocuments - A list of additional documents (possibly not in the user's database), which the user can also choose fromaddPrimerSelectionOption(String, String, com.biomatters.geneious.publicapi.plugin.DocumentSelectionOption.FolderOrDocuments, boolean, java.util.List),
DocumentSelectionOption.setAllowSearchCache(boolean)public final DocumentSelectionOption addPrimerSelectionOption(String name, String label, DocumentSelectionOption.FolderOrDocuments defaultValue, boolean allowMultipleSelections, List<AnnotatedPluginDocument> additionalDocuments)
public final <T extends Options.OptionValue> Options.ComboBoxOption<T> addComboBoxOption(String name, String label, T[] possibleValues, T defaultValue)
addStringOption.name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.label - a label describing this option to be displayed to the user. eg. "My Awesome Option"defaultValue - the default value for this optionpossibleValues - A list containing all possible values (i.e. all the entries to appear in the combo box)public final <T extends Options.OptionValue> Options.RadioOption<T> addRadioOption(String name, String label, T[] possibleValues, T defaultValue, Options.Alignment alignment)
addStringOption.name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.label - a non-null label describing this option to be displayed to the user. eg. "My Awesome Option"possibleValues - An array containing all possible values (i.e. all the radio button names)defaultValue - the default value for this option, not nullalignment - the alignment of the radio buttons (horizontally or vertically)public final <T extends Options.OptionValue> Options.RadioOption<T> addRadioOption(String name, String label, List<T> possibleValues, T defaultValue, Options.Alignment alignment)
addStringOption.name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.label - a non-null label describing this option to be displayed to the user. eg. "My Awesome Option"possibleValues - An array containing all possible values (i.e. all the radio button names)defaultValue - the default value for this optionalignment - the alignment of the radio buttons (horizontally or vertically)public final Options.FileSelectionOption addFileSelectionOption(String name, String label, String defaultValue, String[] selectableFileNames, String buttonLabel)
addStringOption.
If the file is expected to be an executable file, use addExecutableFileSelectionOption(String, String, String) insteadname - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.label - a label describing this option to be displayed to the user. eg. "My Awesome Option"defaultValue - the default value for this optionselectableFileNames - A list of selectable filenames to be provided to the user.buttonLabel - The text displayed on the button instead of "Browse"addExecutableFileSelectionOption(String, String, String)public final Options.FileSelectionOption addFileSelectionOption(String name, String label, String defaultValue, String[] selectableFileNames, String buttonLabel, FilenameFilter filter)
addStringOption.
If the file is expected to be an executable file, use addExecutableFileSelectionOption(String, String, String) insteadname - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.label - a label describing this option to be displayed to the user. eg. "My Awesome Option"defaultValue - the default value for this optionselectableFileNames - A list of selectable filenames to be provided to the user.buttonLabel - The text displayed on the button instead of "Browse"filter - Filter which matches filenames which are a valid selection. This field is not serialized.addExecutableFileSelectionOption(String, String, String)public final Options.FileSelectionOption addFileSelectionOption(String name, String label, String defaultValue)
addStringOption.name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.label - a label describing this option to be displayed to the user. eg. "My Awesome Option"defaultValue - the default value for this optionpublic final Options.ExecutableFileSelectionOption addExecutableFileSelectionOption(String name, String label, String fileName)
addExecutableFileSelectionOption(String,String,String,String) with arguments
(name, label, fileName, fileName).name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.label - a label describing this option to be displayed to the user. eg. "My Awesome Option"fileName - The name of the executable file (without a path component) that we are looking for,
e.g. "clustalw.exe". This will also be the default value for this option.public final Options.ExecutableFileSelectionOption addExecutableFileSelectionOption(String name, String label, String fileName, String defaultValue)
addStringOption.name - the name to be used for referencing this option. For example from scripts or source code which wish to programmatically get or set the value of this option.label - a label describing this option to be displayed to the user. eg. "My Awesome Option"fileName - The name of the executable file (without a path component) that we are looking for,
e.g. "clustalw.exe". This will also be the default value for this option.defaultValue - The default location of the executable file; If you don't have a good default for this,
it's probably best to assume it is on the PATH, and call
addExecutableFileSelectionOption(String, String, String) instead.public void beginAlignHorizontally(String label, boolean useEqualWidths)
endAlignHorizontally(). The row will contain all options
added between those two calls. At the time when the panel is created,
all options in the row must agree whether they are advanced or not
(see Options.Option.isAdvanced()).
The row will fill any remaining available horizontal space if any of the
options in the row would (see Options.Option.isFillHorizontalSpace()
or if useEqualWidths is true.
The row will stretch over the entire width of the options panel if label is null.
A call to this method must precede exactly one corresponding later call
to endAlignHorizontally(). While the aligned row of options is
being populated (i.e. in the time between calling beginAlignHorizontally(String, boolean)
and the corresponding call to endAlignHorizontally()), it is illegal to call
either beginAlignHorizontally(String, boolean), createPanel() or createAdvancedPanel().label - An optional label that is to be displayed at the left side of the current row in the options panel.
A value of null indicates that no label will be displayed and that the horizontally aligned components will begin at the very left of the panel.
A empty string label means that the horizontally aligned components will start to the right of standard component labels.useEqualWidths - true to make all horizontally alignment options have equal widths. This also expands the row to use the full width available.public void endAlignHorizontally()
beginAlignHorizontally(String, boolean). After this method has been called,
it is then again legal to call (String, boolean), or
to call createPanel() or createAdvancedPanel().public final Map<String,Options> getChildOptions()
addChildOptions(String, String, String, Options).
The key in the returned map is the name specified as the parameter to addChildOptions.public void setSavePreferencesForInvisibleChildOptions(boolean saveInvisibleChildOptions)
restoreDefaults())
or save preferences (savePreferences()) will apply only to the child
options (ChildOptions that are currently visible.
This value set by this method replaces the parameter allChildOptionsApplySimultaneously's value from an earlier call to addChildOptionsPageChooser(String, String, java.util.List, com.biomatters.geneious.publicapi.plugin.Options.PageChooserType, boolean)saveInvisibleChildOptions - true to restore defaults and save preferences for invisible child options.public final Options.Option addChildOptionsPageChooser(String name, String label, List<String> disabledOptions, Options.PageChooserType type, boolean allChildOptionsApplySimultaneously)
addChildOptions
followed by calling this method.
When choosing to build a tree from unaligned sequences, the alignment
and tree building options are implemented as child options
without calling this method.name - A programmatic name used for referring to the option created for choosing which options are visible. This option can be retrieved using getChildOptionsPageChooser().label - A label displayed to the userdisabledOptions - provides a list of child option names that are disabledtype - the PageChooserType type of the chooserallChildOptionsApplySimultaneously - If this is false then after calling this
method, choosing to restore defaults (restoreDefaults())
or save preferences (savePreferences()) will apply only to the child
options of the currently visible page or to all pages if the options are not yet displayed.Options.Option.getValueAsString()) of the returned option will match the name of the currently selected child options (which is the first parameter given to addChildOptions(String, String, String, Options))IllegalStateException - if this method is called more than once or if addChildOptions has been called less than twice.Options.Option.addChildOptionsDependent(Options, Object, boolean)public final Options.Option getChildOptionsPageChooser()
addChildOptionsPageChooser(String, String, java.util.List, com.biomatters.geneious.publicapi.plugin.Options.PageChooserType, boolean) has been called, return the
option created for choosing which set of child options are currently active.
The string value (obtained using Options.Option.getValueAsString()) of the returned option will match the name of the currently selected child options.
(which is the first parameter given to addChildOptions(String, String, String, Options) )addChildOptionsPageChooser(String, String, java.util.List, com.biomatters.geneious.publicapi.plugin.Options.PageChooserType, boolean) has not been called.public final Options addChildOptions(String name, String label, String description)
addChildOption(name, label, description, new Options(getClass()), true)name - specifies a prefix use for referencing individual options
within childOptionslabel - a label for the child options. If this label is not an empty string, a divider is created (when not using addChildOptionsPageChooser(String, String, java.util.List, com.biomatters.geneious.publicapi.plugin.Options.PageChooserType, boolean)).description - used mostly for tool tipsaddChildOptionsPageChooser(String, String, java.util.List, com.biomatters.geneious.publicapi.plugin.Options.PageChooserType, boolean),
Options.Option.addChildOptionsDependent(Options, Object, boolean)public final void addChildOptions(String name, String label, String description, Options childOptions)
addChildOptions(name,label,description,childOptions,false).
When savePreferences() is called on the parent options, the child options will have its preferences saved
in its usual location (independent of the parent's preferences). Use addChildOptions(String, String, String, Options, boolean)
if the child options should store its preferences with the parent.name - see addChildOptions(String, String, String, Options, boolean)label - see addChildOptions(String, String, String, Options, boolean)description - see addChildOptions(String, String, String, Options, boolean)childOptions - see addChildOptions(String, String, String, Options, boolean)addChildOptionsPageChooser(String, String, java.util.List, com.biomatters.geneious.publicapi.plugin.Options.PageChooserType, boolean),
Options.Option.addChildOptionsDependent(Options, Object, boolean)public final void addChildOptions(String name, String label, String description, Options childOptions, boolean useParentPreferences)
addChildOptionsPageChooser(String, String, java.util.List, com.biomatters.geneious.publicapi.plugin.Options.PageChooserType, boolean) addChildOptionsPageChooser}
is called after all child options have been added, then each set of child options is made graphically available
in a separate tab.
Individual options within childOptions can be referenced programmatically by prepending the name as a prefix followed by "."
For example, if childOptions contains an option called "test",
and name is "child", then
setStringValue("child.test","abc") will set the value of that option.name - specifies a prefix use for referencing individual options
within childOptionslabel - a label for the child options. If this label is not an empty string, a divider is created (when not using addChildOptionsPageChooser(String, String, java.util.List, com.biomatters.geneious.publicapi.plugin.Options.PageChooserType, boolean)).description - used mostly for tool tipschildOptions - the child optionsuseParentPreferences - If true, Store the preferences for this child when calling savePreferences() on this
parent Options in a sub-node of the parent's preferences. If false, store the preferences for this child in its default
preference node (independent of the parent preferences). NOTE: When savePreferences() is called on the
child options directly, its default location is always used.addChildOptionsPageChooser(String, String, java.util.List, com.biomatters.geneious.publicapi.plugin.Options.PageChooserType, boolean),
Options.Option.addChildOptionsDependent(Options, Object, boolean)public final void addCollapsibleChildOptions(String name, String label, String description, Options childOptions, boolean useParentPreferences, boolean defaultCollapsed)
name - specifies a prefix use for referencing individual options
within childOptionslabel - a label for the child options which is shown on the expander button. must not be null or emptydescription - short description of the options used as the tooltip for the expander buttonchildOptions - the child optionsuseParentPreferences - If true, Store the preferences for this child when calling savePreferences() on this
parent Options in a sub-node of the parent's preferences. If false, store the preferences for this child in its default
preference node (independent of the parent preferences). NOTE: When savePreferences() is called on the
child options directly, its default location is always used.defaultCollapsed - whether or not the child options should be collapsed or not by default.addChildOptionsPageChooser(String, String, java.util.List, com.biomatters.geneious.publicapi.plugin.Options.PageChooserType, boolean),
Options.Option.addChildOptionsDependent(Options, Object, boolean)public final void setChildOptionsCollapsed(String name, boolean collapsed)
addCollapsibleChildOptions(String, String, String, Options, boolean, boolean).name - name of the child options (passed in to addCollapsibleChildOptions(String, String, String, Options, boolean, boolean)collapsed - true to collapse the child options, false to expand them.public final Options.MultipleOptions addMultipleOptions(String name, Options multipleOptions, boolean isAdvanced)
beginAlignHorizontally(String, boolean) and endAlignHorizontally()
when constructing the multipleOptions parameter.
Multiple options can have their values set and retrieved programatically via
setStringValue(String, String) and getValueAsString(String)
by using an option name of the form "multipleName.[0|1|2|...].childName".
When using setStringValue(String,String), the numeric index may be
equal to current number of values (found using Options.MultipleOptions.getValues().size())
to add a new set of values to these multiple options.
Example:
// First create some multiOptions consisting of a string and an integer displayed horizontally adjacent:
Options multiOptions = new Options(OptionsTest.class);
multiOptions.beginAlignHorizontally(null, false);
multiOptions.addStringOption("stringOption", "String", "defaultValue");
multiOptions.addIntegerOption("integerOption", "Integer", 5);
multiOptions.endAlignHorizontally();
final Options options = new Options(OptionsTest.class);
options.addMultipleOptions("multi",multiOptions, false);
options.setStringValue("multi.0.stringOption","test");
options.setStringValue("multi.0.integerOption","6");
// Now add a second set of values:
options.setStringValue("multi.1.stringOption", "test2"); // this implicity adds "multi.1.integerOption" with value the default value (5)
options.getValueAsString("multi.1.integerOption"); // returns "5";
Implementation note: This feature is implemented by XMLSerializing the
multipleOptions parameter and deserializing it again to create
the multiple instances. While Options is XMLSerializable, it is not guarenteed
that sub-classes fulfil the XMLSerializable contract. Trying to
add multiple options for this case will cause a IllegalArgumentException to be thrown.name - a programatic name for referring to the multiple options.multipleOptions - the multiple options to add.isAdvanced - true if these multiple options should appear in the advanced panel instead of the standard panel.IllegalArgumentException - if multipleOptions does not fulfil the XMLSerializable contract, or if any option in multiOptions is advanced.getMultipleOptions(String),
Options.MultipleOptions.getValues()public final Options.MultipleOptions getMultipleOptions(String name)
addMultipleOptions(String, Options, boolean).name - the name of some multiple options specified as the first parameter to addMultipleOptions(String, Options, boolean)public final List<Options.MultipleOptions> getMultipleOptions()
addMultipleOptions(String, Options, boolean).public final Options.Option addDivider(String label)
label - An optional label to display to the left of the divider. Must not be null but may be an empty string.public final Options.Option<String,? extends JComponent> addLabel(String label)
addLabel(String, false, false).label - The label to display to the userpublic final Options.Option<String,? extends JComponent> addLabel(String label, boolean centreText, boolean spanEntirePanelWidth)
Options.Option.setValue(Object) and Options.Option.getValue(),
respectively.label - The label to display to the usercentreText - centre the textspanEntirePanelWidth - make this label span the entire width of the panel rather than using only the space to the right of standard component labels.Options.LabelOption, but this method is not declared to return that for backwards compatibility reasons.public Options.LabelOption addLabelWithIcon(String label, Icons icons)
label - the labelicons - the icon. Using an icon from StandardIcons is recommended.public final void savePreferences(String preferenceNodeSuffix)
restorePreferences().
Typically, this should only be called immediately after a dialog
containing the options panel has its OK button clicked.preferenceNodeSuffix - An optional name under which the preferences should be stored.
Varying this value allows storage of independent sets of preference values. Use null to store in the default location.
Note that this suffix is used in addition to any suffix passed to the constructor, e.g.
to Options(Class, String).public final void savePreferences()
savePreferences(null)public final void restorePreferences()
restorePreferences(null, false)
Note: If there is no value for an option in preferences then it value isn't changed by this method.public final void restorePreferences(String preferenceNodeSuffix, boolean restorePreferencesOfOptionsThatHaveHadTheirValuesAlreadySet)
savePreferences() is called. Immeditately prior to showing
a dialog in future, restorePreferences() should be called.
Note: If there is no value for an option in preferences then it value isn't changed by this method.preferenceNodeSuffix - An optional name under which the preferences should be restored from.
Varying this value allows storage of independent sets of preference values. Use null to restore from the default location.
Note that this suffix is used in addition to any suffix passed to the constructor, e.g.
to Options(Class, String).restorePreferencesOfOptionsThatHaveHadTheirValuesAlreadySet - In some cases it is not desirable to restore the
preferences of Options that have had their value manually set. For example, an operation may want
to set the value of an Option to match some property of of the selected documents. In this case when restorePreferences
is later called, with this parameter false, the Options with values already set won't be restored to their saved values.public final void restoreDefaults()
savePreferences() after this method.canRestoreDefaults()public void addDefaultsRestoredListener(SimpleListener listener)
listener - the listener to be notifiedrestoreDefaults()public void removeDefaultsRestoredListener(SimpleListener listener)
listener - the listener added using addDefaultsRestoredListener(org.virion.jam.util.SimpleListener).public final boolean canRestoreDefaults()
restoreDefaults() would change anything.restoreDefaults() would change anything.public final org.jdom.Element valuesToXML(String rootElementName)
valuesFromXML(org.jdom.Element).
This does not serialize the options (names, descriptions etc) themselves. Use toXML() to do thisrootElementName - the name of the root element for the returned XMLvaluesFromXML(org.jdom.Element)public final Geneious.MajorVersion getVersionSupportForValuesToXML(XMLSerializable.VersionSupportType versionType)
OldVersionCompatible#getVersionSupport(com.biomatters.geneious.publicapi.documents.XMLSerializable.VersionSupportType)
for use with valuesToXML(com.biomatters.geneious.publicapi.plugin.Geneious.MajorVersion, String)versionType - the version support typepublic final org.jdom.Element valuesToXML(Geneious.MajorVersion version, String rootElementName)
valuesFromXML(org.jdom.Element).
This does not serialize the options (names, descriptions etc) themselves. Use toXML() to do thisversion - the version of Geneious to make the XML compatible withrootElementName - the name of the root element for the returned XMLvaluesFromXML(org.jdom.Element)public final org.jdom.Element valuesToXML(Geneious.MajorVersion version, String rootElementName, boolean excludeOptionsWhereRestorePreferenceApplies)
valuesFromXML(org.jdom.Element).
This does not serialize the options (names, descriptions etc) themselves. Use toXML() to do thisversion - the version of Geneious to make the XML compatible withrootElementName - the name of the root element for the returned XMLexcludeOptionsWhereRestorePreferenceApplies - true to exclude option values from the returned XML for which is true. This is useful when we want to save the values of only those options that would not be saved during restorePreferences()valuesFromXML(org.jdom.Element)public final void valuesFromXML(org.jdom.Element root)
valuesFromXML(root, true)
This does not deserialize the options (names, descriptions etc) themselves. Use fromXML(org.jdom.Element) to do this.root - some XML returned from a previous call to valuesToXML(String). Must not be nullvaluesToXML(String),
valuesFromXML(Element, boolean)public final void valuesFromXML(org.jdom.Element root,
boolean includeOptionsWhichDontRestorePreferences)
fromXML(org.jdom.Element) to do this.root - some XML returned from a previous call to valuesToXML(String). Must not be nullincludeOptionsWhichDontRestorePreferences - true to include options for which Options.Option.setRestorePreferenceApplies(boolean) is false.valuesToXML(String)public final void addChangeListener(SimpleListener listener)
listener - the listener to be notifiedpublic final void removeChangeListener(SimpleListener listener)
listener - the listener added using addChangeListener(org.virion.jam.util.SimpleListener).public String verifyOptionsAreValid()
String superMessage = super.verifyOptionsAreValid();
if (superMessage != null) {
return superMessage;
}
areValuesGoodEnoughToContinue() and verifyOptionsAreValid are two methods that essentially
provide the same functionality, although depending on your use case, one may be simpler to implement than
the other. For example verifyOptionsAreValid handles displaying a dialog for you. It
is recommended that an Options implementation only implement one of these two methods.areValuesGoodEnoughToContinue()public boolean areValuesGoodEnoughToContinue()
if (!super.areValuesGoodEnoughToContinue()) {
return false;
}
areValuesGoodEnoughToContinue and verifyOptionsAreValid() are two methods that essentially
provide the same functionality, although depending on your use case, one may be simpler to use than
the other. For example verifyOptionsAreValid handles displaying a dialog for you. It
is recommended that an Options implementation only implement one of these two methods.verifyOptionsAreValid()public final JPanel getPanel()
createPanel() and cached.
public final boolean hasAdvancedOptions()
Options.Option.isAdvanced()Options.Option.isAdvanced()public final boolean hasBasicOptions()
Options.Option.isAdvanced()Options.Option.isAdvanced()protected JPanel createPanel()
addBooleanOption, addStringOption,
addOption etc).
and addChildOptions.
Override this method to customise the layout of the options.
This method is called the first time getPanel() is called and the return value cached.
The default implementation displays a vertical list of all non-advanced options,
one per line.
If you do choose to customise the layout, the
custom components must automatically listen to changes to themselves
and immediately reflect those in the values of the options.
The components must also listen to changes in the value of their
responding Option
and reflect that in the value of the component.
The recommended way to do this automatically is to use
Options.Option.getComponent()
which automatically does all of this. So just add that component
to an appropriate location within a panel.
For example, here is a code fragment of some options which customise their layout
private static class CustomOptions extends Options {
final StringOption test;
final BooleanOption test2;
public CustomOptions() {
super(CustomOptions.class);
test=addStringOption ("test", "test", "value");
test2=addBooleanOption ("test2", "test2", true);
}
protected JPanel createPanel() {
JPanel panel =new JPanel();
// Add both the label and the component:
panel.add(new JLabel(test.getLabel()));
panel.add(test.getComponent());
// For a boolean (checkbox) option, it doesn't have a separate label so just add the component:
panel.add(test2.getComponent());
return panel;
}
}
IllegalStateException - If there is a row created with beginAlignHorizontally(String, boolean),
endAlignHorizontally() in which some options are advanced and some are nonadvanced.public final JPanel getAdvancedPanel()
createAdvancedPanel() and cached.protected JPanel createAdvancedPanel()
getAdvancedPanel() is called and the return value cached.
The default implementation displays a vertical list of all advanced options,
one per line.IllegalStateException - If there is a row created with beginAlignHorizontally(String, boolean),
endAlignHorizontally() in which some options are advanced and some are nonadvanced.public final Object getValue(String optionName)
optionName.
As of 2007-04-16, it is not specified whether this will return
the exact same object that was last set on this option, or a copy
of that value (the value set on the object may have been passed
to setValue(String, Object), Options.Option.setDisabledValue(Object)
or to the Option's constructor as the default value.optionName - the name of the option to get the value forpublic final boolean setValue(String optionName, Object value)
optionName - the name of the option to set the value forvalue - the value to set. Note - since Options
are implemented using Java generics, there is no way to ensure
that value is the correct class type at run time. Therefore,
the value given here it is converted to a string and then converted
back to an object of the expected type, or the default option value
if it is invalid.
Essentially, this is what this method implementation looks like:
return setStringValue(optionName, value.toString());
Note: This method is not thread safe. See documentation towards the end of Options.
Warning: It is almost always preferable to use Options.Option.setValue(Object)
because it is typesafe. The Option object on which to set the value can
either be obtained via getOption(String), or may be exposed by
the Options subclass via a getter method (e.g. getMaxIterationsOption() or similar).
A subclass may also choose to provide direct getter and setter methods
for particular option values, e.g. int getMaxIterations() and
setMaxIterations(int) in the example case of an option
holding the maximum number of iterations for something.public final boolean setStringValue(String optionName, String value)
optionName - the name of the option to set the value forvalue - a string representation of the value to set.
The string will be converted to an object of the expected type, or the default option value
if it is invalid.
Note: This method is not thread safe. See documentation towards the end of Options.public final Options.Option getOption(String optionName)
optionName - the name of the option or the childOptions name followed
by a "." followed by an option name within those child options.public final String getValueAsString(String optionName)
Options.Option.getValue() because
it is typesafe. If you don't have the Option object available, use getOption(String).
A subclass may also choose to expose the Option via a getter method
(e.g. getMaxIterationsOption() or similar) so that it can
be typed correctly rather than just as a generic Option.
A subclass may also choose to provide direct getter and setter methods
for particular option values, e.g. int getMaxIterations() and
setMaxIterations(int) in the example case of an option
holding the maximum number of iterations for something.optionName - the name of the option to get the value for, or empty string if the option does not existpublic org.jdom.Element toXML()
XMLSerializableXMLSerializable.fromXML(org.jdom.Element) can completely
restore the objects representation.
It is recommended that the returned element use XMLSerializable.ROOT_ELEMENT_NAME as its name,
in which case it must not define an attribute called "type". In this case,
fromXML, will be called with an element whose name may differ from the element
return from this function. This recommendation allows a more compact representation
of the XML can be stored.
This method generally should not be called directly. Instead, you should usually call
XMLSerializer.classToXML(String, XMLSerializable)
which calls this method internally.
PluginDocument implementations of this method may choose to throw an XMLSerializationException,
enclosed in a RuntimeException.toXML in interface XMLSerializablepublic void fromXML(org.jdom.Element element)
throws XMLSerializationException
XMLSerializableXMLSerializable.toXML().
This method generally should not be called directly. Instead, you should usually call
XMLSerializer.classFromXML(org.jdom.Element)
or XMLSerializer.classFromXML(org.jdom.Element, Class)
which calls this method internally.
It is optional to implement this method. Instead of implementing an empty constructor and implementing
this method properly, the implementation may instead
throw an UnsupportedOperationException and implement a constructor
that takes a single Element as a parameter.
This allows for cleaner code such as support for final fields in the XMLSerializable class.
The element parameter should not be modified since it may be reused. If you need a modified version of it,
take a copy with Element.clone().fromXML in interface XMLSerializableelement - representation from a previous call to XMLSerializable.toXML()XMLSerializationException - if the Element can't be converted into this type of objectpublic void setHorizontallyCompact(boolean horizontallyCompact)
setHorizontallyCompactAdvanced(boolean) to make the advanced options horizontally compact.horizontallyCompact - true to display a compact form of these options.IllegalStateException - if getPanel() has already been called on these options.public void setHorizontallyCompactAdvanced(boolean horizontallyCompact)
horizontallyCompact - true to display a compact form of these options.IllegalStateException - if getPanel() has already been called on these options.public void setInScrollPane(boolean inScrollPane)
inScrollPane - true to have the options added to scroll paneIllegalStateException - if getPanel() has already been called on these options.public void setVerticallyCompact(boolean verticallyCompact)
setVerticallyCompactAdvanced(boolean) to make the advanced panel vertically compact.verticallyCompact - true to display a compact form of these options.IllegalStateException - if getPanel() has already been called on these options.public void setVerticallyCompactAdvanced(boolean verticallyCompact)
verticallyCompact - true to display a compact form of these options.IllegalStateException - if getPanel() has already been called on these options.public boolean isHorizontallyCompact()
setHorizontallyCompact(boolean).setHorizontallyCompact(boolean).public void addHelpButton(String dialogTitle, String dialogMessage)
addHelpButtonOption(String, String)public Options.Option addHelpButtonOption(String dialogTitle, String dialogMessage)
dialogTitle - the title of the dialogdialogMessage - the contents of the dialog, which may be html.public String getOptionsHelp()