plugins.adufour.ezplug
Class EzPlug

java.lang.Object
  icy.plugin.abstract_.Plugin
      icy.plugin.abstract_.PluginActionable
          plugins.adufour.ezplug.EzPlug

All Implemented Interfaces:

icy.plugin.interface_.PluginImageAnalysis, icy.plugin.interface_.PluginLibrary, java.lang.Runnable

public abstract class EzPlug
extends icy.plugin.abstract_.PluginActionable
implements icy.plugin.interface_.PluginLibrary, java.lang.Runnable

Main component of the EzPlug framework. EzPlug provides numerous additional features to the Plugin class to simplify the development of plug-ins for ICY. In a nut shell, it allows to: a) design intuitive and homogeneous graphical interfaces; b) save/load parameters to/from disk in a standardized way (e.g. XML).
To create an EzPlug and benefit from these features, simply create a class that extends EzPlug instead of Plugin. EzPlug is abstract and requires to implement the following methods:

• The initialize() method should be used to declare the parameters, buttons, groups etc.. This is done via the addEzComponent method. EzPlug here uses the Vars library to provide create tailored graphical components for all major data types (e.g. check box for a boolean, spinner for a numerical parameter, combo box for list of values etc.). See the EzVar class hierarchy for an overview.
  Several helper methods offer additional possibilities such as: 1) group variables together into a panel which can be folded to save space on the interface; 2) automatically show or hide parameters or groups thereof, depending on the value of other parameters (so-called visibility triggers); 3) automatically respond to parameter input events for enhanced user experience; 4) add traditional or custom AWT or Swing components to the interface (for advanced developers).
• The execute() method holds the main execution code of the plug-in, and is called when the "Run" button is clicked on the interface.
• The clean() method should be used to clean "sensitive" resources (if any) created by the plug-in (e.g. sequence painters, I/O streams, etc.), in order to free memory properly and/or avoid polluting the display. This method is called when the interface (or Icy) is closed.

The final generated interface comes with a sleek title bar and an action panel in the bottom, from where the user may start or stop the execution process, load and save parameters from/to disk via XML files.

An example showing most of the features in action is available online here.

Author:

Alexandre Dufour

See Also:

EzInternalFrame

Field Summary

static java.lang.String

EZPLUG_MAINTAINERS

Constructor Summary

protected

EzPlug()

Method Summary

protected void	addComponent(java.awt.Component component)
protected void	addEzComponent(EzComponent component) Adds a graphical component to the interface.
abstract void	clean() Cleans user-defined structures when the plug-in window is closed.
void	compute() Entry point of this EzPlug, which creates the user interface and displays it on the main desktop pane.
void	createUI() Generates the user interface of this EzPlug.
protected abstract void	execute() Main method containing the core execution code of this EzPlug.
static java.lang.String	generateEzPlugCodeFragment(java.lang.String className) Generates an EzPlug code fragment that is ready to use and compile
java.lang.String	getName() Gets the name of this EzPlug (defaults to the class name).
static int	getNbInstances()
long	getStartTime() Gets the starting execution time of this EzPlug (in nanoseconds).
EzGUI	getUI() Gets the graphical interface attached to this EzPlug.
void	hideUI() Hides the user interface (without destroying it)
protected abstract void	initialize() This method lets the developer initialize the user interface of this EzPlug by adding variables and other EzComponent objects via the addEzComponent(EzComponent) method
boolean	isHeadLess()
void	loadParameters(java.io.File file) Saves the EzPlug user parameters into the specified XML file
void	run()
void	saveParameters(java.io.File file) Saves the EzPlug user parameters into the specified XML file
void	setTimeDisplay(boolean displayRunningTime) Sets whether the execution time of this EzPlug should be displayed on the console
void	showUI() Displays the user interface on screen.

Methods inherited from class icy.plugin.abstract_.Plugin

addIcyFrame, addSequence, extractResource, finalize, getActiveImage, getActiveSequence, getActiveViewer, getDescriptor, getFocusedImage, getFocusedSequence, getFocusedViewer, getIconResource, getImageResource, getPlugin, getPreferences, getPreferencesRoot, getResource, getResourceAsStream, getResourceLibraryPath, getResources, getSequences, loadLibrary, removeSequence, report

Methods inherited from class java.lang.Object

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

Field Detail

EZPLUG_MAINTAINERS

public static final java.lang.String EZPLUG_MAINTAINERS

See Also:

Constant Field Values

Constructor Detail

EzPlug

protected EzPlug()

Method Detail

addComponent

protected void addComponent(java.awt.Component component)

addEzComponent

protected void addEzComponent(EzComponent component)

Adds a graphical component to the interface. Components are graphically ordered on the interface panel in top-down fashion in the same order as they are added.

Parameters:

component - the component to add

See Also:

EzVar, EzButton, EzGroup

clean

public abstract void clean()

Cleans user-defined structures when the plug-in window is closed. This method should be used if this EzPlug has references to some structures which should be cleaned properly before closing the plug window (e.g. painters on a sequence, I/O streams, etc.).
NOTE: this method is called after cleaning of the graphical user interface. Hence, any attempt to access graphical components (or change the value of EzVar objects) will result in a null pointer exception.

compute

public final void compute()

Entry point of this EzPlug, which creates the user interface and displays it on the main desktop pane. This method can be called either via ICY's main menu or directly via code.

Specified by:

compute in interface icy.plugin.interface_.PluginImageAnalysis

Overrides:

compute in class icy.plugin.abstract_.PluginActionable

createUI

public void createUI()

Generates the user interface of this EzPlug. Note that the window is not shown on screen (this can be done by calling the showUI() method.

execute

protected abstract void execute()

Main method containing the core execution code of this EzPlug. This method is launched in a separate thread only if it was called from the user interface (via the run button)

generateEzPlugCodeFragment

public static java.lang.String generateEzPlugCodeFragment(java.lang.String className)

Generates an EzPlug code fragment that is ready to use and compile

Parameters:

className - the name of the new class

getName

public java.lang.String getName()

Gets the name of this EzPlug (defaults to the class name).

Returns:

the name of this EzPlug

getNbInstances

public static int getNbInstances()

Returns:

the number of active (not-destroyed) instances of this plug-in

getStartTime

public long getStartTime()

Gets the starting execution time of this EzPlug (in nanoseconds). This method can be used in conjunction with the System.nanoTime() method to measure elapsed time during the execution process

Returns:

the starting execution time in nanoseconds (obtained from the System.nanoTime() method)

getUI

public EzGUI getUI()

Gets the graphical interface attached to this EzPlug. This interface gives access to specific methods related to user interaction (e.g. progress bars, highlighting, etc.).

Returns:

the graphical interface of the EzPlug, or null if the EzPlug has been created via code without generating the interface

hideUI

public void hideUI()

Hides the user interface (without destroying it)

isHeadLess

public boolean isHeadLess()

Returns:

true if the graphical user interface has not been initialized (e.g. when running without screen or on a server). If this method returns true, then the getUI() will return null

initialize

protected abstract void initialize()

This method lets the developer initialize the user interface of this EzPlug by adding variables and other EzComponent objects via the addEzComponent(EzComponent) method

See Also:

EzVar, EzComponent

loadParameters

public void loadParameters(java.io.File file)

Saves the EzPlug user parameters into the specified XML file

Parameters:

file -

See Also:

EzVarIO

run

public void run()

Specified by:

run in interface java.lang.Runnable

saveParameters

public void saveParameters(java.io.File file)

Saves the EzPlug user parameters into the specified XML file

Parameters:

file -

See Also:

EzVarIO

showUI

public void showUI()

Displays the user interface on screen. If it didn't exist, the interface is first created

setTimeDisplay

public void setTimeDisplay(boolean displayRunningTime)

Sets whether the execution time of this EzPlug should be displayed on the console

Parameters:

displayRunningTime -