plugins.adufour.ezplug
Class EzVar<T>

java.lang.Object
  plugins.adufour.ezplug.EzComponent
      plugins.adufour.ezplug.EzVar<T>

All Implemented Interfaces:

VarListener<T>

Direct Known Subclasses:

EzVarBoolean, EzVarDoubleArray, EzVarDoubleArrayNative, EzVarEnum, EzVarFile, EzVarFileArray, EzVarFloatArray, EzVarFloatArrayNative, EzVarFolder, EzVarIntegerArray, EzVarIntegerArrayNative, EzVarNumeric, EzVarPlugin, EzVarSequence, EzVarSwimmingObject, EzVarText

public abstract class EzVar<T>
extends EzComponent
implements VarListener<T>

Class defining a variable for use within an EzPlug.

EzVar objects are powerful components that bind each parameter type to a specific graphical component that can be used to receive input from the user interface. It is designed to be used by plug-in developers in a simple and fast manner with zero knowledge in graphical interface programming.
A wide-range of EzVar subclasses are available, depending on the type of data to handle (numerical value, boolean flags, image sequences, file arrays, etc.). Advanced developers may also contribute to the EzVar class hierarchy by implementing additional variable types to fit their needs and that of others.

EzVar objects are always instantiated using the subclass corresponding to the parameter type to use. Once created, the variable can be added to the graphical interface of the EzPlug via the EzPlug.addEzComponent(EzComponent) method (see sample code in the EzPlug class documentation).

Author:

Alexandre Dufour

Field Summary

Fields inherited from class plugins.adufour.ezplug.EzComponent

name, visible

Constructor Summary

protected	EzVar(Var<T> variable, T[] defaultValues, int defaultValueIndex, boolean freeInput) Creates a new variable with a JComboBox as default graphical component
protected	EzVar(Var<T> variable, VarEditorModel<T> constraint) Constructs a new variable

Method Summary

protected void	addTo(java.awt.Container container)
void	addVarChangeListener(EzVarListener<T> listener) Adds a new listener that will be notified is this variable changes
void	addVisibilityTriggerTo(EzComponent targetComponent, T... values) Sets a visibility trigger on the target EzComponent.
protected void	dispose()
protected void	fireVariableChanged(T value)
T[]	getDefaultValues(T[] dest) Retrieves the default values into the destination array, or returns a new one if dest is not big enough.
T	getValue() Returns the variable value.
T	getValue(boolean forbidNull) Returns the variable value (or fails if the variable is null).
protected VarEditor<T>	getVarEditor()
Var<T>	getVariable()
boolean	isEnabled() Indicates whether this variable is enabled, and therefore may be used by plug-ins.
void	referenceChanged(Var<T> source, Var<? extends T> oldReference, Var<? extends T> newReference) Called when the variable reference changes
void	removeAllVarChangeListeners() Removes all change listeners for this variable
void	removeVarChangeListener(EzVarListener<T> listener) Removes the given listener from the list
void	setDefaultValues(T[] values, int defaultValueIndex, boolean allowUserInput) Replaces the list of values available in the combo box of this variable NOTE: this method has no effect if the user component is not already a combo box
void	setEnabled(boolean enabled) Sets whether the variable is enabled, i.e.
void	setOptional(boolean optional) Sets a flag indicating whether this variable should be considered "optional".
void	setToolTipText(java.lang.String text) Assigns a tool-tip text to the variable, which pops up when the user hovers the mouse on it.
void	setValue(T value) Sets the new value of this variable
void	setVisible(boolean newVisibleState) Sets the visibility state of this variable, and updates the chain of visibility states (components hiding other components)
java.lang.String	toString()
protected void	updateVisibilityChain()
void	valueChanged(Var<T> source, T oldValue, T newValue) Called when the value of the source variable changes

Methods inherited from class plugins.adufour.ezplug.EzComponent

getGroup, getVisible, isVisible, setGroup

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

EzVar

protected EzVar(Var<T> variable,
                VarEditorModel<T> constraint)

Constructs a new variable

Parameters:

variable - The variable to attach to this object

constraint - the constraint to apply on the variable when receiving input, or null if a default constraint should be applied

EzVar

protected EzVar(Var<T> variable,
                T[] defaultValues,
                int defaultValueIndex,
                boolean freeInput)

Creates a new variable with a JComboBox as default graphical component

Parameters:

variable - the variable to attach to this EzVar

defaultValues - the list of values to store in the combo box

defaultValueIndex - the index of the default selected item

freeInput - true to allow user manual input, false to restrict the selection to the given list

Method Detail

addVarChangeListener

public void addVarChangeListener(EzVarListener<T> listener)

Adds a new listener that will be notified is this variable changes

Parameters:

listener - the listener to add

addVisibilityTriggerTo

public void addVisibilityTriggerTo(EzComponent targetComponent,
                                   T... values)

Sets a visibility trigger on the target EzComponent. The visibility state of the target component is set to true whenever this variable is visible, and takes any of the trigger values, and false otherwise. If no trigger value is indicated, the target component will always be visible as long as the source component is both visible and enabled

Parameters:

targetComponent - the component to hide or show

values - the list of values which will set the visibility of the target component to true. If no value is indicated, the target component will be visible as long as the source component is both visible and enabled

addTo

protected void addTo(java.awt.Container container)

Specified by:

addTo in class EzComponent

dispose

protected void dispose()

Overrides:

dispose in class EzComponent

fireVariableChanged

protected final void fireVariableChanged(T value)

getDefaultValues

public T[] getDefaultValues(T[] dest)

Retrieves the default values into the destination array, or returns a new one if dest is not big enough.

Parameters:

dest - the array to fill with the values. the array is left untouched if it is not big enough

Throws:

java.lang.UnsupportedOperationException - if the user input component is not a combo box

getVarEditor

protected VarEditor<T> getVarEditor()

getValue

public T getValue()

Returns the variable value. By default, null is considered a valid value. In order to show an error message (or throw an exception in head-less mode), use the getValue(boolean) method instead

Returns:

The variable value

getValue

public T getValue(boolean forbidNull)
           throws EzException

Returns the variable value (or fails if the variable is null).

Parameters:

forbidNull - set to true to display an error message (or to throw an exception in head-less mode)

Returns:

the variable value

Throws:

EzException - if the variable value is null and forbidNull is true

getVariable

public Var<T> getVariable()

isEnabled

public boolean isEnabled()

Indicates whether this variable is enabled, and therefore may be used by plug-ins. Note that this method returns a simple flag, and it is up to the accessing plug-ins to behave accordingly (i.e. it is not guaranteed that a disabled variable will not be used by plug-ins)

Returns:

true if this variable is enabled, false otherwise

removeVarChangeListener

public void removeVarChangeListener(EzVarListener<T> listener)

Removes the given listener from the list

Parameters:

listener - the listener to remove

removeAllVarChangeListeners

public void removeAllVarChangeListeners()

Removes all change listeners for this variable

setDefaultValues

public void setDefaultValues(T[] values,
                             int defaultValueIndex,
                             boolean allowUserInput)

Replaces the list of values available in the combo box of this variable
NOTE: this method has no effect if the user component is not already a combo box

Parameters:

values -

defaultValueIndex -

allowUserInput -

setEnabled

public void setEnabled(boolean enabled)

Sets whether the variable is enabled, i.e. that it is usable by plug-ins, and accepts modifications via the graphical interface

Parameters:

enabled - the enabled state

setOptional

public void setOptional(boolean optional)

Sets a flag indicating whether this variable should be considered "optional". This flag is typically used to mark a plug-in parameter as optional, allowing plug-ins to react accordingly and save potentially unnecessary computations. Setting a variable as optional will add a check-box next to the variable editor to provide visual feedback

Parameters:

optional - true if this parameter is optional, false otherwise

setValue

public void setValue(T value)
              throws java.lang.UnsupportedOperationException

Sets the new value of this variable

Parameters:

value - the new value

Throws:

java.lang.UnsupportedOperationException - thrown if changing the variable value from code is not supported (or not yet implemented)

setToolTipText

public void setToolTipText(java.lang.String text)

Description copied from class: EzComponent

Assigns a tool-tip text to the variable, which pops up when the user hovers the mouse on it.

Specified by:

setToolTipText in class EzComponent

Parameters:

text - the text to display (usually no more than 20 words)

setVisible

public void setVisible(boolean newVisibleState)

Sets the visibility state of this variable, and updates the chain of visibility states (components hiding other components)

Overrides:

setVisible in class EzComponent

Parameters:

newVisibleState - the new visibility state

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

updateVisibilityChain

protected void updateVisibilityChain()

valueChanged

public void valueChanged(Var<T> source,
                         T oldValue,
                         T newValue)

Description copied from interface: VarListener

Called when the value of the source variable changes

Specified by:

valueChanged in interface VarListener<T>

Parameters:

source - the variable firing the listener

oldValue - the old variable value

newValue - the new variable value

referenceChanged

public void referenceChanged(Var<T> source,
                             Var<? extends T> oldReference,
                             Var<? extends T> newReference)

Description copied from interface: VarListener

Called when the variable reference changes

Specified by:

referenceChanged in interface VarListener<T>

Parameters:

source - the variable firing the listener

oldReference - the old variable reference

newReference - the new variable reference