plugins.adufour.vars.gui
Class VarEditor<V>

java.lang.Object
  plugins.adufour.vars.gui.VarEditor<V>

Type Parameters:

V - the inner type of the variable controlled by this editor

All Implemented Interfaces:

VarListener<V>

Direct Known Subclasses:

SwingVarEditor

public abstract class VarEditor<V>
extends java.lang.Object
implements VarListener<V>

Class handling the graphical component used to view or modify the value of a Variable. This class provides an abstraction layer between a Variable object (i.e. the model in the MVC sense) and its associated graphical user interface. This abstraction has a number of purposes:

• MVC-like behavior: Variables are detached from their graphical interface counterpart (allowing any scenario from headless manipulation to multiple synchronized editors handling the same Variable).
• Facilitate the integration of the graphical component within a larger user interface, by avoiding the container to handle interface updates and user input events.
• Sub-packages may provide bindings with one (or more) toolkits, while others can be adapted with minimal effort (in theory).

A number of default editors are available for the most common Variable types (see links below). However, these editors can be extended or replaced by more advanced ones to support custom Variable types.

Author:

Alexandre Dufour

Field Summary

protected Var<V>

variable The Variable handled by this editor.

Constructor Summary

VarEditor(Var<V> variable)
Constructs a new editor for the specified Variable.

Method Summary

protected abstract void	activateListeners() Activates listeners on the editor component.
protected abstract java.lang.Object	createEditorComponent() Creates the component to display on the graphical user interface, allowing the user to modify the variable's value via appropriate listeners (listeners should be added or removed via the activateListeners() and deactivateListeners() methods). In order to allow multiple editors to modify the same variable, this method should always return a newly constructed component (by Swing design, a same component can only be used once per interface). Once created, the component is stored in the final editorComponent field to avoid unnecessary re-creations (e.g.
protected abstract void	deactivateListeners() Deactivates listeners on the editor component.
void	dispose() Dispose of resources (e.g.
double	getComponentHorizontalResizeFactor() Indicates whether and how this component should resize horizontally if the container panel allows resizing.
double	getComponentVerticalResizeFactor() Indicates whether and how this component should resize vertically if the container panel allows resizing.
java.lang.Object	getEditorComponent()
abstract java.awt.Dimension	getPreferredSize()
Var<V>	getVariable()
abstract boolean	isComponentEnabled()
boolean	isComponentFocusable()
abstract boolean	isComponentOpaque()
boolean	isComponentResizeable()
boolean	isNameVisible()
void	referenceChanged(Var<V> source, Var<? extends V> oldReference, Var<? extends V> newReference) Called when the variable reference changes
void	setComponentFocusable(boolean componentFocusable)
void	setComponentResizeable(boolean componentResizeable)
abstract void	setComponentToolTipText(java.lang.String s)
protected abstract void	setEditorEnabled(boolean enabled)
void	setEnabled(boolean enabled) Enables (or disables) the graphical component associated with the Variable object.
void	setNameVisible(boolean nameVisible)
protected abstract void	updateInterfaceValue() Updates the graphical interface component to reflect the new value of the underlying variable (accessible via the Var.getValue() method).
void	valueChanged(Var<V> source, V oldValue, V newValue) Called when the value of the source variable changes

Methods inherited from class java.lang.Object

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

Field Detail

variable

protected final Var<V> variable

The Variable handled by this editor. Note that multiple editors can handle the same variable simultaneously.

Constructor Detail

VarEditor

public VarEditor(Var<V> variable)

Constructs a new editor for the specified Variable.
Note that multiple editors be created for the same variable (see the createEditorComponent() method for more details).

Parameters:

variable -

Method Detail

createEditorComponent

protected abstract java.lang.Object createEditorComponent()

Creates the component to display on the graphical user interface, allowing the user to modify the variable's value via appropriate listeners (listeners should be added or removed via the activateListeners() and deactivateListeners() methods).
In order to allow multiple editors to modify the same variable, this method should always return a newly constructed component (by Swing design, a same component can only be used once per interface).
Once created, the component is stored in the final editorComponent field to avoid unnecessary re-creations (e.g. during interface refresh). To bypass this optimization and force the creation of a new component for every interface refresh, consider overriding the getEditorComponent() method.

WARNING: this method is called within the VarEditor(Var) constructor, therefore all instance fields besides the final variable field will be null until this method returns.

Returns:

a graphical input component that is linked to the variable and can be used to view or adjust the variable value

getEditorComponent

public java.lang.Object getEditorComponent()

Returns:

the graphical component used to view or modify the variable's value. By default, the returned component is the one created by the createEditorComponent() method during object construction. This method can be overridden to return a new component for each call (note however that this method may be called many times, e.g. during interface refresh)

getPreferredSize

public abstract java.awt.Dimension getPreferredSize()

Returns:

The preferred dimension of the local editorComponent. By default, this method calls the component's JComponent.getPreferredSize() method. However, this method can be overridden to provide a custom dimension, e.g. to fix the size of the component regardless of its content

getComponentHorizontalResizeFactor

public double getComponentHorizontalResizeFactor()

Indicates whether and how this component should resize horizontally if the container panel allows resizing. If multiple components in the same panel support resizing, the amount of extra space available will be shared between all components depending on the returned weight (from 0 for no resizing to 1 for maximum resizing).
By default, this value is 1.0 (horizontal resizing is always allowed to fill up the maximum amount of space)

Returns:

a value from 0 (no resize allowed) to 1 (resize as much as possible)

getComponentVerticalResizeFactor

public double getComponentVerticalResizeFactor()

Indicates whether and how this component should resize vertically if the container panel allows resizing. If multiple components in the same panel support resizing, the amount of extra space available will be shared between all components depending on the returned weight (from 0 for no resizing to 1 for maximum resizing).
By default, this value is 0.0 (no vertical resizing)

Returns:

a value from 0 (no resize allowed) to 1 (resize as much as possible)

setComponentToolTipText

public abstract void setComponentToolTipText(java.lang.String s)

getVariable

public Var<V> getVariable()

Returns:

The Variable controlled by this editor

isComponentEnabled

public abstract boolean isComponentEnabled()

Returns:

true if the editor is enabled, i.e. whether the graphical component is active and may receive user input. This method can be overridden to force the editor status to a given state

isComponentOpaque

public abstract boolean isComponentOpaque()

Returns:

true if the editor is opaque, or false if the component is transparent. This method can be overridden to force the opacity to a given state

isComponentFocusable

public boolean isComponentFocusable()

Returns:

true if the editor is focusable (i.e. the component may capture a mouse event and become active).

isComponentResizeable

public boolean isComponentResizeable()

Returns:

true if the container panel should allow this component to be resized, false otherwise

isNameVisible

public boolean isNameVisible()

Returns:

true if the name should appear alongside the editor component, false otherwise

activateListeners

protected abstract void activateListeners()

Activates listeners on the editor component. Listeners should be activated here rather than in the createEditorComponent() method, in order to allow the target containers to optimize the scheduling and load of events to fire, and to ensure proper garbage collection when the interface is destroyed.

deactivateListeners

protected abstract void deactivateListeners()

Deactivates listeners on the editor component. Listeners should be deactivated here rather than in the createEditorComponent() method, in order to allow the target containers to optimize the scheduling and load of events to fire, and to ensure proper garbage collection when the interface is destroyed.

setComponentFocusable

public void setComponentFocusable(boolean componentFocusable)

Parameters:

componentFocusable - true if the editor is focusable (i.e. the component may capture a mouse event and become active), false otherwise

setComponentResizeable

public void setComponentResizeable(boolean componentResizeable)

Parameters:

componentResizeable - true if the container panel should allow this component to be resized, false otherwise

setEnabled

public void setEnabled(boolean enabled)

Enables (or disables) the graphical component associated with the Variable object. This method should be used by the enclosing graphical interface instead of the traditional JComponent.setEnabled(boolean), since listeners are automatically activated (or deactivated) to avoid excessive event firing and ensure proper garbage collection.

setEditorEnabled

protected abstract void setEditorEnabled(boolean enabled)

setNameVisible

public void setNameVisible(boolean nameVisible)

Parameters:

nameVisible - true if the name should appear alongside the editor component, false otherwise

updateInterfaceValue

protected abstract void updateInterfaceValue()

Updates the graphical interface component to reflect the new value of the underlying variable (accessible via the Var.getValue() method).

dispose

public void dispose()

Dispose of resources (e.g. listeners, IO etc.) before releasing the editor. This method must be called by overriding implementations to ensure proper cleaning

valueChanged

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

Description copied from interface: VarListener

Called when the value of the source variable changes

Specified by:

valueChanged in interface VarListener<V>

Parameters:

source - the variable firing the listener

oldValue - the old variable value

newValue - the new variable value

referenceChanged

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

Description copied from interface: VarListener

Called when the variable reference changes

Specified by:

referenceChanged in interface VarListener<V>

Parameters:

source - the variable firing the listener

oldReference - the old variable reference

newReference - the new variable reference