org.netbeans.spi.editor

Class AbstractEditorAction

java.lang.Object

javax.swing.AbstractAction

javax.swing.text.TextAction

org.netbeans.spi.editor.AbstractEditorAction

All Implemented Interfaces:

ActionListener, Serializable, Cloneable, EventListener, Action, Presenter, Presenter.Menu, Presenter.Popup, Presenter.Toolbar

public abstract class AbstractEditorAction
extends TextAction
implements Presenter.Menu, Presenter.Popup, Presenter.Toolbar

Base class for editor actions that should be used together with EditorActionRegistration annotation.
It may be constructed and used in two ways: direct construction or construction upon invocation by a wrapper action:

• Direct construction - action is created directly when an editor kit gets constructed (its kit.getActions() gets used).
  Advantages: Action controls all its behavior and properties (including enabled status) since the begining.
  Disadvantages: Action's class is loaded by classloader at editor kit's construction.
  Example of registration:
  public static final class MyAction extends AbstractEditorAction {

@EditorActionRegistration(name = "my-action")
public static MyAction create(Map<String,?> attrs) {
return new MyAction(attrs);
}

private MyAction(Map<String,?> attrs) {
super(attrs);
...
}

protected void actionPerformed(ActionEvent evt, JTextComponent component) {
...
}

}

• Construction upon invocation - WrapperEditorAction is constructed upon editor kit's construction and the target action only gets created when the action needs to be executed (upon ActionListener.actionPerformed(java.awt.event.ActionEvent) call). Existing properties of the wrapper action (including Action.NAME property) get transferred into delegate action.
  Advantages: Action's class is only loaded upon action's execution.
  Disadvantages: Only a limited set of action's properties gets populated (those defined by EditorActionRegistration).
  Example of registration:
  @EditorActionRegistration(name = "my-action")
public static final class MyAction extends AbstractEditorAction {

public MyAction() {
// Here the properties are not yet set.
}

@Override
protected void valuesUpdated() {
// Here the wrapper action has transferred all its properties into this action
// so properties like Action.NAME etc. are now populated.
}

protected void actionPerformed(ActionEvent evt, JTextComponent component) {
...
}

}


Since:

1.14

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface org.openide.util.actions.Presenter

Presenter.Menu, Presenter.Popup, Presenter.Toolbar

Field Summary

Fields

Modifier and Type	Field and Description
static String	ASYNCHRONOUS_KEY Key of Boolean property containing a boolean whether the action should be performed asynchronously or synchronously.
static String	DISPLAY_NAME_KEY Key of String property containing a localized display name of the action.
static String	ICON_RESOURCE_KEY Key of String property containing a string path to icon.
static String	MENU_TEXT_KEY Key of String property containing a localized text to be displayed in a main menu for this action.
static String	MIME_TYPE_KEY Key of String property containing a mime type for which this action is registered.
static String	MULTI_ACCELERATOR_LIST_KEY Key of property containing a List < List < KeyStroke > > listing all multi-key bindings by which the action may be invoked.
static String	NO_ICON_IN_MENU Key of Boolean property which determines whether icon of this action should be displayed in menu (false or unset) or not (true).
static String	NO_KEY_BINDING Key of Boolean property which determines if this action should be displayed in key binding customizer (false or unset) or not (true).
static String	POPUP_TEXT_KEY Key of String property containing a localized text to be displayed in a popup menu for this action.
static String	PREFERENCES_DEFAULT_KEY Key of String property containing preferences key's default value.
static String	PREFERENCES_KEY_KEY Key of String property containing a name of a boolean key in preferences in which this action changes settings (according to PREFERENCES_NODE_KEY property).
static String	PREFERENCES_NODE_KEY Key of Preferences property containing a node in preferences in which this action changes settings.
static String	WRAPPER_ACTION_KEY Key of Boolean property determining whether this is just a wrapper action that is being used until the action needs to be executed.

Fields inherited from class javax.swing.AbstractAction

changeSupport, enabled

Fields inherited from interface javax.swing.Action

ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractEditorAction() Constructor typically used when action is constructed lazily upon its performing (the action is always enabled and its properties are declared in xml layer by annotation processor for @EditorActionRegistration).
protected	AbstractEditorAction(Map<String,?> attrs) Constructor that takes a map of attributes that are typically obtained from an xml layer when an action's creation method is annotated with @EditorActionRegistration.

Method Summary

Modifier and Type	Method and Description
protected String	actionName()
void	actionPerformed(ActionEvent evt)
protected abstract void	actionPerformed(ActionEvent evt, JTextComponent component) Implementation of the action must be defined by descendants.
protected boolean	asynchronous() Possibly allow asynchronous execution of this action by returning true.
protected Object	createValue(String key) This method is called when a value for the given property was not yet populated.
Object[]	getKeys()
JMenuItem	getMenuPresenter() Get presenter of this action in main menu.
JMenuItem	getPopupPresenter() Get presenter of this action in popup menu.
Component	getToolbarPresenter() Get presenter of this action in toolbar.
Object	getValue(String key)
boolean	isEnabled()
void	putValue(String key, Object value)
protected void	resetCaretMagicPosition(JTextComponent component) Reset caret's magic position.
void	setEnabled(boolean enabled)
String	toString()
protected void	valuesUpdated() Called when property values from wrapper action were transferred into delegate action (this action) so properties like Action.NAME will start to return correct values.

Methods inherited from class javax.swing.text.TextAction

augmentList, getFocusedComponent, getTextComponent

Methods inherited from class javax.swing.AbstractAction

addPropertyChangeListener, clone, firePropertyChange, getPropertyChangeListeners, removePropertyChangeListener

Methods inherited from class java.lang.Object

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

Field Detail

DISPLAY_NAME_KEY

public static final String DISPLAY_NAME_KEY

Key of String property containing a localized display name of the action.
It may be passed to getValue(java.lang.String) to obtain the property value.

See Also:

Constant Field Values

MENU_TEXT_KEY

public static final String MENU_TEXT_KEY

Key of String property containing a localized text to be displayed in a main menu for this action.
It may be passed to getValue(java.lang.String) to obtain the property value.

See Also:

Constant Field Values

POPUP_TEXT_KEY

public static final String POPUP_TEXT_KEY

Key of String property containing a localized text to be displayed in a popup menu for this action.
If this property is not set then MENU_TEXT_KEY is attempted.
It may be passed to getValue(java.lang.String) to obtain the property value.

See Also:

Constant Field Values

ICON_RESOURCE_KEY

public static final String ICON_RESOURCE_KEY

Key of String property containing a string path to icon.

See Also:

Constant Field Values

NO_ICON_IN_MENU

public static final String NO_ICON_IN_MENU

Key of Boolean property which determines whether icon of this action should be displayed in menu (false or unset) or not (true).
It may be passed to getValue(java.lang.String) to obtain the property value.

Since:

1.74

See Also:

Constant Field Values

NO_KEY_BINDING

public static final String NO_KEY_BINDING

Key of Boolean property which determines if this action should be displayed in key binding customizer (false or unset) or not (true).
It may be passed to getValue(java.lang.String) to obtain the property value.

Since:

1.74

See Also:

Constant Field Values

MULTI_ACCELERATOR_LIST_KEY

public static final String MULTI_ACCELERATOR_LIST_KEY

Key of property containing a List < List < KeyStroke > > listing all multi-key bindings by which the action may be invoked.
There may be multiple multi-key bindings to invoke a single action e.g. a code completion may be invoked by Ctrl+SPACE and also Ctrl+'\' (in fact each of these bindings could also consist of multiple keystrokes). The more straightforward (shorter) bindings should generally precede the longer ones so e.g. tooltip may just show the first binding of the list.

See Also:

Constant Field Values

ASYNCHRONOUS_KEY

public static final String ASYNCHRONOUS_KEY

Key of Boolean property containing a boolean whether the action should be performed asynchronously or synchronously.

See Also:

Constant Field Values

MIME_TYPE_KEY

public static final String MIME_TYPE_KEY

Key of String property containing a mime type for which this action is registered.
Note: action's mime-type is not necessarily the same like EditorKit.getContentType() for which the action was created because the kit may inherit some actions from a global mime-type "".
Value of this property is checked at action's initialization (it needs to be passed as part of 'attrs' parameter to constructor). Subsequent modifications of this property should be avoided and they will likely not affect its behavior.

See Also:

Constant Field Values

PREFERENCES_NODE_KEY

public static final String PREFERENCES_NODE_KEY

Key of Preferences property containing a node in preferences in which this action changes settings.

See Also:

Constant Field Values

PREFERENCES_KEY_KEY

public static final String PREFERENCES_KEY_KEY

Key of String property containing a name of a boolean key in preferences in which this action changes settings (according to PREFERENCES_NODE_KEY property).
Once this property is set then it's expected that PREFERENCES_NODE_KEY is also set to a valid value and checkbox menu presenter will be used automatically.

See Also:

Constant Field Values

PREFERENCES_DEFAULT_KEY

public static final String PREFERENCES_DEFAULT_KEY

Key of String property containing preferences key's default value.

See Also:

Constant Field Values

WRAPPER_ACTION_KEY

public static final String WRAPPER_ACTION_KEY

Key of Boolean property determining whether this is just a wrapper action that is being used until the action needs to be executed. Then the target action gets created and run.
Value of this property is checked at action's initialization (it needs to be passed as part of 'attrs' parameter to constructor). Subsequent modifications of this property should be avoided and they will likely not affect its behavior.

See Also:

Constant Field Values

Constructor Detail

AbstractEditorAction

protected AbstractEditorAction(Map<String,?> attrs)

Constructor that takes a map of attributes that are typically obtained from an xml layer when an action's creation method is annotated with @EditorActionRegistration.
Example:
public static final class MyAction extends AbstractEditorAction {

@EditorActionRegistration(name = "my-action")
public static MyAction create(Map<String,?> attrs) {
return new MyAction(attrs);
}

private MyAction(Map<String,?> attrs) {
super(attrs);
...
}

protected void actionPerformed(ActionEvent evt, JTextComponent component) {
...
}

}


Parameters:

attrs - non-null attributes that hold action's properties. The map is expected to be constant (no key-value changes).

AbstractEditorAction

protected AbstractEditorAction()

Constructor typically used when action is constructed lazily upon its performing (the action is always enabled and its properties are declared in xml layer by annotation processor for @EditorActionRegistration).
Example:
@EditorActionRegistration(name = "my-action")
public static final class MyAction extends AbstractEditorAction {

public MyAction() {
// Here the properties are not yet set.
}

@Override
protected void valuesUpdated() {
// Here the wrapper action has transferred all its properties into this action
// so properties like Action.NAME etc. are now populated.
}

protected void actionPerformed(ActionEvent evt, JTextComponent component) {
...
}

}


Method Detail

actionPerformed

protected abstract void actionPerformed(ActionEvent evt,
                                        JTextComponent component)

Implementation of the action must be defined by descendants.

Parameters:

evt - action event (may be null).

component - "active" text component obtained by TextAction.getFocusedComponent(). It may be null.

valuesUpdated

protected void valuesUpdated()

Called when property values from wrapper action were transferred into delegate action (this action) so properties like Action.NAME will start to return correct values.

See Also:

AbstractEditorAction()

asynchronous

protected boolean asynchronous()

Possibly allow asynchronous execution of this action by returning true.

Returns:

Value of ASYNCHRONOUS_KEY property is returned but subclasses may possibly implement some more elaborate algorithm.

resetCaretMagicPosition

protected final void resetCaretMagicPosition(JTextComponent component)

Reset caret's magic position.
Magic caret position is useful when going through empty lines with Down/Up arrow then the caret returns on original horizontal column when a particular line has sufficient number of characters.

Parameters:

component - target text component.

getMenuPresenter

public JMenuItem getMenuPresenter()

Get presenter of this action in main menu.
Default implementation uses MENU_TEXT_KEY for menu item's text and the presenter is placed in the menu according to rules given in the corresponding EditorActionRegistration.
Moreover the default presenter is sensitive to currently active text component and if the active editor kit has that action redefined it uses the active action's properties for this presenter.

Specified by:

getMenuPresenter in interface Presenter.Menu

Returns:

instance of menu presenter for this action.

getPopupPresenter

public JMenuItem getPopupPresenter()

Get presenter of this action in popup menu.
Default implementation uses POPUP_TEXT_KEY for popup menu item's text and the presenter is placed in the popup menu according to rules given in the corresponding EditorActionRegistration.

Specified by:

getPopupPresenter in interface Presenter.Popup

Returns:

instance of popup menu presenter for this action.

getToolbarPresenter

public Component getToolbarPresenter()

Get presenter of this action in toolbar.

Specified by:

getToolbarPresenter in interface Presenter.Toolbar

Returns:

instance of toolbar presenter for this action.

actionName

protected final String actionName()

Returns:

value of Action.NAME property.

actionPerformed

public final void actionPerformed(ActionEvent evt)

Specified by:

actionPerformed in interface ActionListener

getValue

public final Object getValue(String key)

Specified by:

getValue in interface Action

Overrides:

getValue in class AbstractAction

createValue

protected Object createValue(String key)

This method is called when a value for the given property was not yet populated.
This method is only called once for the given property. Even if this method returns null for the given property the infrastructure remembers the returned value and no longer queries this method (the property can still be modified by putValue(java.lang.String, java.lang.Object).)
Calling of this method and remembering of the returned value does not trigger AbstractAction.firePropertyChange(java.lang.String, java.lang.Object, java.lang.Object).

Parameters:

key - key of the property.

Returns:

value of the property or null.

putValue

public final void putValue(String key,
                           Object value)

Specified by:

putValue in interface Action

Overrides:

putValue in class AbstractAction

isEnabled

public boolean isEnabled()

Specified by:

isEnabled in interface Action

Overrides:

isEnabled in class AbstractAction

setEnabled

public void setEnabled(boolean enabled)

Specified by:

setEnabled in interface Action

Overrides:

setEnabled in class AbstractAction

getKeys

public Object[] getKeys()

Overrides:

getKeys in class AbstractAction

toString

public String toString()

Overrides:

toString in class Object