Class Options.Option<ValueType,​ComponentType extends javax.swing.JComponent>

    • Constructor Detail

      • Option

        protected Option​(java.lang.String name,
                         java.lang.String label,
                         ValueType defaultValue)
        Construct a new option
        Parameters:
        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
    • Method Detail

      • addChildOptionsDependent

        public final void addChildOptionsDependent​(Options childOptions,
                                                   ValueType valueRequiredForDependentToBeEnabled,
                                                   boolean displayThisOptionInChildOptionsHeading)
        Make the enabled state of some child options depend on the current value of this option. Also optionally include this option's component in the bounding box heading panel of the child options.
        Parameters:
        childOptions - the child options whose enabled state will change. These must have been already added using Options.addChildOptions(String, String, String, Options).
        valueRequiredForDependentToBeEnabled - the value this option is required to have in order for the child options to be enabled. If the option has any other value, the child options will be disabled.
        displayThisOptionInChildOptionsHeading - if this is true, then the component for this option will be displayed inside the bounding box heading panel of the child options.
      • addDependent

        public final void addDependent​(Options.Option dependent,
                                       ValueType valueRequiredForDependentToBeEnabled)
        Makes another option's enabled state depend on the current value of this option.

        You can also set the value returned by disabled options using setDisabledValue(Object) which can be useful for example to make a BooleanOption return false (or true) from getValue() when it is disabled as a result of being a dependent of another option.

        An option may be a dependent of more than one option which means that that all the options it depends on must have the correct values for the option to be enabled.

        Parameters:
        dependent - the option whose enabled state will change
        valueRequiredForDependentToBeEnabled - the value that this option is required to have for the dependent to be enabled. While this option has any other value, then the dependent will be disabled.
        Throws:
        java.lang.IllegalArgumentException - if the dependent is not in the same Options (or immediate child options) as this option
        See Also:
        addDependentIfNot(Option, Object), getDependents(), getDependentsIfNot()
      • addDependentIfNot

        public final void addDependentIfNot​(Options.Option dependent,
                                            ValueType valueForDependentToBeDisabled)
        Similar to addDependent(Option, Object) except that the dependent is only enabled if the option value is not the value specified here
        Parameters:
        dependent - the option whose enabled state will change
        valueForDependentToBeDisabled - the value that this option is required to not have for the dependent to be enabled. i.e. it will be disabled when the option has this value.
        Throws:
        java.lang.IllegalArgumentException - if the dependent is not in the same Options (or immediate child options) as this option
        Since:
        API 4.202000 (Geneious 2020.0.0)
        See Also:
        addDependent(Option, Object), getDependentsIfNot(), getDependents()
      • setWarningMessage

        public final void setWarningMessage​(java.lang.String message)
        Sets a warning message displayed in a BubbleToolTip on the option component.
        Parameters:
        message - the message to display (may be plaintext or html). Passing in null will have the effect of hiding the tooltip if it is already visible.
        See Also:
        hideWarningMessage()
      • hideWarningMessage

        public final void hideWarningMessage()
        Hides the warning message tooltip for this option if it is visible
        See Also:
        setWarningMessage(String)
      • toXML

        public org.jdom.Element toXML()
        Description copied from interface: XMLSerializable
        Convert object to a JDOM element. The representation should be complete so that XMLSerializable.fromXML(org.jdom.Element) can completely restore the object's 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.

        Specified by:
        toXML in interface XMLSerializable
        Returns:
        object encoded as a JDOM element
      • getValue

        public final ValueType getValue()
        Get the current value of this option. Note: If isEnabled() == false and setDisabledValue(Object) has previously been called with a non-null value, then that value will be returned instead of the actual value that has previously set on this option through setValue(Object). Also, if this option is enabled but setValue(Object) has never been called, then the value returned will be the default value passed to this Option's constructor. As of 2007-04-16, in neither of these cases is it specified whether the exact same object that was previously set will be returned, or whether a copy of that object will be returned.
        Returns:
        the current value of this option
        Throws:
        java.lang.IllegalStateException - if this option has not been added to Options. This can only happen when using custom options, as they are the only ones with a public constructor and can then be created without being added right away.
      • getPossibleValues

        public java.lang.String getPossibleValues()
        Provide a descriptive string representation of possible values of this option. For example, combo box and radio options should provide a list of all available values. The default implementation returns null. Radio and ComboBox options provide Options.ComboBoxOrRadioOption.getPossibleOptionValues() to get possible values as a List of OptionValues.
        Returns:
        a descriptive string representation of possible values of this option or null if this option may have any String value.
        Since:
        API 4.202200 (Geneious 2022.0.0) (this method was protected instead of public prior to 2022.0.0)
        See Also:
        Options.ComboBoxOrRadioOption.getPossibleOptionValues()
      • getDescriptionAndState

        public final java.lang.String getDescriptionAndState()
        Describe all properties and the state of this option.
        Returns:
        a description of all properties and the state of this option.
      • setValue

        public final void setValue​(ValueType value)
        set the current value of this option
        Parameters:
        value - the value to set
      • setValue

        public final void setValue​(ValueType value,
                                   boolean isForUsageTracking)
        Set the current value of this option. This method should always be called from the Swing thread for Options which have previously had their GUI created via calling Options.getPanel(). For Options which have not yet had Swing components created, it is OK to call this outside of the Swing thread.
        Parameters:
        value - the value to set
        isForUsageTracking - true to have the change in value logged by usage tracking
        Since:
        API 4.601 (Geneious 6.0.1)
      • setDisabledValue

        public final void setDisabledValue​(ValueType value)
        Changes the value observed through getValue() when the option is disabled (i.e. isEnabled() == false). This can be either a fixed specified value, or null to indicate that it should be the same as if the option was not disabled (this is the default behaviour before this method gets called).
        Parameters:
        value - the value returned by getValue() when isEnabled()==false, or null to indicate that getValue() should return the same value as if isEnabled() was true.
      • generateValidValue

        protected ValueType generateValidValue​(ValueType candidateValue)
        Converts a potentially invalid value into a valid one. The default implementation always returns candidateValue, implying that all values are valid. Subclasses can override this method e.g. to clamp integer values to a certain interval, or to ensure that a disabled radio item cannot be selected. If a new value is determined to be invalid, a subclass may choose to return the current value (getValue() or any arbitrary other value. IMPORTANT: subclasses which implement this method should call setDefaultValue(Object) at the end of their constructor(s)
        Parameters:
        candidateValue - the value to determine the validity of
        Returns:
        an allowed value.
      • getDescription

        public final java.lang.String getDescription()
        Get a one line description for this option. When displayed graphically, this will be its tool-tip.
        Returns:
        a one line description for this option or null if this has no description.
      • setDescription

        public final void setDescription​(java.lang.String description)
        Set a one line description for this option. When displayed graphically, this will be its tool-tip.
        Parameters:
        description - a one line description for this option or null to give the option no description.
        See Also:
        setHelp(String)
      • getHelp

        public java.lang.String getHelp()
        Returns:
        the help set by setHelp(String)
        Since:
        API 4.1100 (Geneious 11.0.0)
      • setProOnly

        public final void setProOnly​(boolean proOnly)
        Sets whether or not this option requires an active license. By default all options do not require an active license.
        Parameters:
        proOnly - true if this option requires an active license.
      • isProOnly

        public final boolean isProOnly()
        determine whether or not this option requires an active license.
        Returns:
        true if this option requires an active license.
      • setHidden

        public void setHidden​(boolean hidden)
        Marks this option as a hidden option, i.e. the option's component will not be included in the panel or advanced panel of the Options it belongs to. This method is useful in situations where you wish to manully add the component representing this Option as part of the component representing some other custom type of Option.

        Note: if this option is a layout dependent of another option, it will not be hidden unless the other option is also hidden.

        Parameters:
        hidden - whether or not this option should be hidden
        Throws:
        java.lang.IllegalStateException - if this option's component has already been added to any container component.
        Since:
        API 4.1100 (Geneious 11.0.0)
        See Also:
        setVisible(boolean)
      • setAdvanced

        public final void setAdvanced​(boolean advanced)
        Set this option as an advanced option, which means it will only appear in the advanced options panel.
        Parameters:
        advanced - true if this should be an advanced option
        Throws:
        java.lang.IllegalStateException - if this option's component has already been added to any container component.
      • isAdvanced

        public final boolean isAdvanced()
        determine whether or not this option is advanced (appears in the advanced options panel)
        Returns:
        true if this option is advanced
      • getName

        public final java.lang.String getName()
        Get 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".
        Returns:
        the name to be used for referencing this option.
      • getDefaultValue

        public final ValueType getDefaultValue()
        Get the default value for this option
        Returns:
        the default value for this option
      • setDefaultValue

        public final void setDefaultValue​(ValueType defaultValue)
        Changes the default value for this option. In most situations you should specify the default value in the Option constructor instead.
        Parameters:
        defaultValue - the new default value for this option.
      • getLabel

        public final java.lang.String getLabel()
        Get the label display to the user for this option
        Returns:
        the label display to the user for this option
      • getDisplayedLabel

        public java.lang.String getDisplayedLabel()
        Get a label displayed next to this option. For almost all option types this is the same as getLabel() except for BooleanOption which does not display a label next to the check box.
        Returns:
        a label displayed next to this option, or null if there is no such label
      • getValueFromString

        public abstract ValueType getValueFromString​(java.lang.String value)
        Convert a String into an instance of the object type used by this option. This method should generally create a new object every time it is invoked. Only disregard this advice if you know what you are doing - e.g. it is safe to maintain an object pool and return the same object more than once if your Option's ValueType is immutable.

        This method is the inverse of getValueAsString(Object) .

        Parameters:
        value - the string representation of the object value
        Returns:
        the object value or the default value if the string representation is not valid.
      • getValueAsString

        public java.lang.String getValueAsString​(ValueType value)
        Converts this value to a String suitable for returning from Options.getValueAsString(String). The String representation is also used for serialization of option values.

        The default implementation just calls {@link #Object#toString()}.

        This method is the inverse of getValueFromString(String).

        Parameters:
        value - the value to convert to a string.
        Returns:
        the value as a string.
      • getValueAsString

        public final java.lang.String getValueAsString()
        Converts the current value of this option to a String by calling getValueAsString(getValue())

        This method is the inverse of getValueFromString(String).

        Returns:
        the value as a string.
        Since:
        API 4.710 (Geneious 7.1.0)
      • setValueFromString

        public final void setValueFromString​(java.lang.String value)
        Set the value of this option from a string representation of the value
        Parameters:
        value - a string representation of the desired value for this option. If the string representation is invalid, the option will be set to the default value.
      • restoreDefault

        public void restoreDefault()
        Restore this option to its default value
      • addChangeListener

        public final void addChangeListener​(org.virion.jam.util.SimpleListener listener)
        Add a listener to be notified when the value of this option changes.
        Parameters:
        listener - the listener to be notified
      • removeChangeListener

        public final void removeChangeListener​(org.virion.jam.util.SimpleListener listener)
        remove a listener to be notified when the value of this option changes
        Parameters:
        listener - the listener to be notified
      • isEnabled

        public final boolean isEnabled()
        Query whether this option is currently enabled. Options appear enabled only if they are currently set as enabled ( using setEnabled(boolean) which is true by default) and if all the parent Options are enabled. An option may also appear disabled if it requires an active license and there is currently no active license. And Option may also appear disabled if it is a dependent of another option (see addDependent(com.biomatters.geneious.publicapi.plugin.Options.Option, Object) that does not have the correct value.
        Returns:
        true if this option appears enabled
      • setEnabled

        public final void setEnabled​(boolean enabled)
        Set whether this option is currently enabled
        Parameters:
        enabled - true if it should be enabled
      • handleSetEnabled

        protected void handleSetEnabled​(ComponentType component,
                                        boolean enabled)
        Set the enabled state of a component. A sub-class need only override this if it needs to do something more complicated than calling setEnabled on this component
        Parameters:
        component - the component to set the enabled state of
        enabled - true if it should be enabled
      • setVisible

        public void setVisible​(boolean visible)
        Sets the visibility of the graphical component that displays this option together with its label and makes appropriate changes to the size of the window (if any) that contains the graphical component.
        Parameters:
        visible - whether or not the graphical component that displays this option should be visible.
      • isVisible

        public boolean isVisible()
        Get the visibility of the graphical component for this option.
        Returns:
        whether or not the graphical component that displays this option is visible.
        Since:
        API 4.11 (Geneious 5.0)
        See Also:
        setVisible(boolean)
      • setValueOnComponent

        protected abstract void setValueOnComponent​(ComponentType component,
                                                    ValueType value)
        Set the value on this component.
        Parameters:
        component - a component return from createComponent()
        value - the value to set.
      • getComponent

        public final ComponentType getComponent()
        Get a graphical component representing this option. The returned component will automatically listen to changes to itself and reflect those in the value of this option. Changes to the value of the option will also automatically be reflected in value of this component.
        Returns:
        a graphical component representing this option.
      • getComponentWithUnitsAndHelpButton

        public final javax.swing.JComponent getComponentWithUnitsAndHelpButton()
        Returns:
        the component returned from getComponent(), but potentially wrapped in a panel together with label for Options.SpinnerOption.getUnits() and/or the help button for getHelp()
        Since:
        API 4.1100 (Geneious 11.0.0)
      • hasComponentBeenCreated

        public final boolean hasComponentBeenCreated()
        Returns:
        true if the component associated with this Option has alrady been created via a call to getComponent()
        Since:
        API 4.900 (Geneious 9.0.0)
      • createComponent

        protected abstract ComponentType createComponent()
        Create a graphical component representing this option. The implementation is responsible for making sure that the returned component is initialised to the current value of getValue(). The implementation is also responsible for making sure that the returned component listens to any changes made to itself and reflects those changes in the value of this option using the setValue(Object) method. This method will only be called once for each instance of an Option. After it has been called, getComponent() will return a cached copy of it.
        Returns:
        a graphical component representing this option. May not be null.
      • getExtraPersistentInformation

        protected java.lang.String getExtraPersistentInformation()
        Gets any information in addition to the option value that should be persistent between instances. For example, an editable combo box option stores a list of previous entries the user has entered. The default implementation returns null.
        Returns:
        any additional persistent information or null if this option has none.
      • setExtraPersistentInformation

        protected void setExtraPersistentInformation​(java.lang.String extras)
        Sets any information in addition to the option value that should be persistent between instances. For example, an editable combo box option stores a list of previous entries the user has entered. The default implementation does nothing.
        Parameters:
        extras - any additional persistent information or null if this option has none.
      • setLabelComponent

        public void setLabelComponent​(javax.swing.JLabel jlabel)
        Sets the label component associated with this Option so that its visibility and enabled state change correctly when the associated Option changes visibility or enabled.

        This method should only be called by code that is laying out the panel to contain Options. (i.e. it should only be called by an Options that overrides Options.createPanel().

        Parameters:
        jlabel - a label that is associated with this option.
      • setSpanningComponent

        public final void setSpanningComponent​(boolean isSpanningComponent)
        Set whether the default generated panel treats this options's component as spanning when it has an empty label. Spanning means that it uses the entire width of the panel rather than just the space to the right of all the labels.
        Parameters:
        isSpanningComponent - true if this option's component should be a spanning component.
        See Also:
        isSpanningComponent(), isFillHorizontalSpace(), setFillHorizontalSpace(boolean)
      • isSpanningComponent

        protected boolean isSpanningComponent()
        Does the default generated panel treat this options's component as spanning when it has an empty label? Spanning means that it uses the entire width of the panel rather than just the space to the right of all the labels.
        Returns:
        true if this option's component should be a spanning component.
        See Also:
        setSpanningComponent(boolean), isFillHorizontalSpace(), setFillHorizontalSpace(boolean)
      • getVerticalWeight

        public final double getVerticalWeight()
        Get the weighting used to decide how much this component should stretch when its container is resized.
        Returns:
        the vertical weight of this option's component (ie. weightY)
        Since:
        API 4.700 (Geneious 7.0.0)
        See Also:
        GridBagConstraints.weighty, setVerticalWeight(double)
      • setVerticalWeight

        public final void setVerticalWeight​(double weightY)
        Set the weighting used to decide how much this component should stretch when its container is resized. By default this is 0 which means the component will not resize. Any additional space is divided up amongst components relative to their weightY value.
        Parameters:
        weightY - the vertical weight of this option's component
        Since:
        API 4.700 (Geneious 7.0.0)
        See Also:
        GridBagConstraints.weighty
      • setAlwaysUsesDefaultPreferenceLocation

        public final void setAlwaysUsesDefaultPreferenceLocation​(boolean alwaysUsesDefaultPreferenceLocation)
        Occasionally when dealing with Options we want some values to remain persistent across different sets of preferences. For example, when you set up clustal alignment the location of the executable should be the same no matter which preferences you are dealing with. When this method is called (with true as the parameter) then this Option will always store its value in the default preferences location. Additionally, it will always remember its value even before Options.restorePreferences() is called. A Options.ExecutableFileSelectionOption automatically calls this method in its constructor.
        Parameters:
        alwaysUsesDefaultPreferenceLocation - true to always store the value of this preference in the default preference location.
      • setFillHorizontalSpace

        public final void setFillHorizontalSpace​(boolean fillHorizontalSpace)
        Set whether this option's component should fill all available horizontal space.
        Parameters:
        fillHorizontalSpace - true if this option's component should fill all available horizontal space.
        See Also:
        isFillHorizontalSpace(), isSpanningComponent(), setSpanningComponent(boolean)
      • isRestoreDefaultApplies

        public boolean isRestoreDefaultApplies()
        Returns true if calling Options.restoreDefaults() should restore this setting to its default value
        Returns:
        true if calling Options.restoreDefaults() should restore this setting to its default value
      • setRestoreDefaultApplies

        public void setRestoreDefaultApplies​(boolean restoreDefaultApplies)
        Set whether calling Options.restoreDefaults() should restore this setting to its default value. Note that calling restoreDefault() will still restore this setting to its default value.
        Parameters:
        restoreDefaultApplies - true if calling Options.restoreDefaults() should restore this setting to its default value
      • setRestorePreferenceApplies

        public void setRestorePreferenceApplies​(boolean restorePreferenceApplies)
        Set whether calling Options.restorePreferences() should restore this setting to its value saved in preferences.
        Parameters:
        restorePreferenceApplies - true if calling Options.restorePreferences() should restore this setting to its value saved in preferences.
      • getParentOptions

        public Options getParentOptions()
        Returns the Options in which this option is contained
        Returns:
        the Options in which this option is contained
      • setPreferredWidth

        public void setPreferredWidth​(int preferredWidthInPixels)
        Sets the preferred width of the component which will be returned from getComponent(), keeping the component at its current preferred height.
        Parameters:
        preferredWidthInPixels - the preferred width of the component. If this is 0, then the component will continue to use its current or default preferred width.
        Since:
        API 4.14 (Geneious 5.1)
      • setPreferredHeight

        public void setPreferredHeight​(int preferredHeightInPixels)
        Sets the preferred height of the component which will be returned from getComponent(), keeping the component at its current preferred width.
        Parameters:
        preferredHeightInPixels - the preferred height of the component. If this is 0, then the component will continue to use its current or default preferred height.
        Since:
        API 4.14 (Geneious 5.1)
      • moveToOptions

        public boolean moveToOptions​(Options newParentOptions,
                                     java.lang.String optionalNewLabel,
                                     java.lang.String optionalNewName)
        Moves this Option from its current parent Options to another parent Options. Any option dependencies will be removed.

        The original parent Options should no longer be used after the move and may be left in an inconsistent state.

        Options that have already had its component constructed cannot be moved - they will return false

        Parameters:
        newParentOptions - the Options to move this Option to
        optionalNewLabel - a new label (see getLabel()) to assign to this Option or null to leave it unchanged.
        optionalNewName - a new name (see getName() ()})to assign to this Option or null to leave it unchanged.
        Returns:
        true if this option was successfully moved.
        Since:
        API 4.700 (Geneious 7.0.0)
      • getNormalizedStringValue

        protected java.lang.String getNormalizedStringValue​(java.lang.String value)
        For options that may have multiple valid string representations of the same value, this method returns the normalized (canonical) representation of a value. For example a DoubleOption, "3" may also be represented as "3.0".
        Parameters:
        value - the value to get the normalized representation of.
        Returns:
        the normalized (canonical) representation of value or value if value is not a valid value for this option. The default implementation returns value.
        Since:
        API 4.201900 (Geneious 2019.0.0)