org.scijava.plugin

Annotation Type Plugin

@Retention(value=RUNTIME)
@Target(value=TYPE)
public @interface Plugin

Annotation identifying a plugin, which gets loaded by SciJava's dynamic discovery mechanism.

Author:

Curtis Rueden

See Also:

SciJavaPlugin, PluginService

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
Class<? extends SciJavaPlugin>	type The type of plugin; e.g., Service.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
Attr[]	attrs A list of additional attributes which can be used to extend this annotation beyond its built-in capabilities.
String	description A longer description of the plugin (e.g., for use as a tool tip).
boolean	enabled When false, the plugin is grayed out in the user interface, if applicable.
boolean	headless Provides a "hint" as to whether the plugin would behave correctly in a headless context.
String	iconPath Path to the plugin's icon (e.g., shown in the menu structure).
String	initializer Defines a function that is called to initialize the plugin in some way.
String	label The human-readable label to use (e.g., in the menu structure).
Menu[]	menu Full menu path defining where the plugin is shown in the menu structure.
String	menuPath Abbreviated menu path defining where the plugin is shown in the menu structure.
String	menuRoot String identifier naming the menu to which this plugin belongs, or in the case of a tool, the context menu that should be displayed while the tool is active.
String	name The name of the plugin.
double	priority The plugin index returns plugins sorted by priority.
boolean	selectable Whether the plugin can be selected in the user interface.
String	selectionGroup For selectable plugins, specifies a name defining a group of linked plugins, only one of which is selected at any given time.
boolean	visible When false, the plugin is not displayed in the user interface.

Element Detail

type

public abstract Class<? extends SciJavaPlugin> type

The type of plugin; e.g., Service.

name

public abstract String name

The name of the plugin.

Default:

""

label

public abstract String label

The human-readable label to use (e.g., in the menu structure).

Default:

""

description

public abstract String description

A longer description of the plugin (e.g., for use as a tool tip).

Default:

""

menuPath

public abstract String menuPath

Abbreviated menu path defining where the plugin is shown in the menu structure. Uses greater than signs (>) as a separator; e.g.: "Image > Overlay > Properties..." defines a "Properties..." menu item within the "Overlay" submenu of the "Image" menu. Use either menuPath() or menu() but not both.

Default:

""

menu

public abstract Menu[] menu

Full menu path defining where the plugin is shown in the menu structure. This construction allows menus to be fully specified including mnemonics, accelerators and icons. Use either menuPath() or menu() but not both.

Default:

{}

menuRoot

public abstract String menuRoot

String identifier naming the menu to which this plugin belongs, or in the case of a tool, the context menu that should be displayed while the tool is active. The default value of UIDetails.APPLICATION_MENU_ROOT references the menu structure of the primary application window.

Default:

"app"

iconPath

public abstract String iconPath

Path to the plugin's icon (e.g., shown in the menu structure).

Default:

""

priority

public abstract double priority

The plugin index returns plugins sorted by priority. For example, this is useful for Services to control which service implementation is chosen when multiple implementations are present in the classpath, as well as to force instantiation of one service over another when the dependency hierarchy does not dictate otherwise.

Any double value is allowed, but for convenience, there are some presets:

• Priority.FIRST_PRIORITY
• Priority.VERY_HIGH_PRIORITY
• Priority.HIGH_PRIORITY
• Priority.NORMAL_PRIORITY
• Priority.LOW_PRIORITY
• Priority.VERY_LOW_PRIORITY
• Priority.LAST_PRIORITY

See Also:

Service

Default:

0.0

selectable

public abstract boolean selectable

Whether the plugin can be selected in the user interface. A plugin's selection state (if any) is typically rendered in the menu structure using a checkbox or radio button menu item (see selectionGroup()).

Default:

false

selectionGroup

public abstract String selectionGroup

For selectable plugins, specifies a name defining a group of linked plugins, only one of which is selected at any given time. Typically this is rendered in the menu structure as a group of radio button menu items. If no group is given, the plugin is assumed to be a standalone toggle, and typically rendered as a checkbox menu item.

Default:

""

enabled

public abstract boolean enabled

When false, the plugin is grayed out in the user interface, if applicable.

Default:

true

visible

public abstract boolean visible

When false, the plugin is not displayed in the user interface.

Default:

true

headless

public abstract boolean headless

Provides a "hint" as to whether the plugin would behave correctly in a headless context.

Plugin developers should not specify headless = true unless the plugin refrains from using any UI-specific features (e.g., AWT or Swing calls).

Of course, merely setting this flag does not guarantee that the plugin will not invoke any headless-incompatible functionality, but it provides an extra safety net for downstream headless code that wishes to be conservative in which plugins it allows to execute.

Default:

false

initializer

public abstract String initializer

Defines a function that is called to initialize the plugin in some way.

Default:

""

attrs

public abstract Attr[] attrs

A list of additional attributes which can be used to extend this annotation beyond its built-in capabilities.

Note to developers: when designing new plugin types, it is tempting to use this attribute to store additional information about each plugin. However, we suggest doing so only if you need that additional information before creating an instance of the plugin: e.g., to decide whether to instantiate one, or even whether to load the annotated plugin class at all. If you are going to create a plugin instance anyway, it is cleaner and more type-safe to add proper API methods to the plugin type's interface reporting the same information.

Default:

{}