Monday, February 25, 2008

Using boolean state actions in NetBeans RCP

This post can be categorized as a code snippet and shows how to work with CallableSystemAction and BooleanStateAction.

If you create a new action through the new action wizard your code looks something like:


public final class SomeAction extends CallableSystemAction {

public void performAction() {
// TODO implement action body
}

public String getName() {
return NbBundle.getMessage(SomeAction.class, "CTL_SomeAction");
}

@Override
protected String iconResource() {
return "path/to/your/icon.png";
}

public HelpCtx getHelpCtx() {
return HelpCtx.DEFAULT_HELP;
}

@Override
protected boolean asynchronous() {
return false;
}
}


The action allows you to execute some code (in the performAction() method) when the used clicks the button.
On the other side, a boolean action is like a toggle button. Imagine a play button, it can be pushed to indicate the music is playing and in normal state (not pushed) indicating the player is stopped. This can be achieved with a BooleanStateAction instead of a CallableSystemAction. Modify the previous code to:


public final class SomeAction extends BooleanStateAction implements PropertyChangeListener
{

public SomeAction()
{
// Set the initial state
setBooleanState(true);

// Register as a property listener
addPropertyChangeListener(this);
}

public String getName()
{
return NbBundle.getMessage(SomeAction.class, "CTL_SomeAction");
}

@Override
protected String iconResource()
{
return "path/to/your/icon.png";
}

public HelpCtx getHelpCtx()
{
return HelpCtx.DEFAULT_HELP;
}

public void propertyChange(PropertyChangeEvent evt)
{
// Check if the boolean state has changed.
if(BooleanStateAction.PROP_BOOLEAN_STATE.equals(evt.getPropertyName())) {

Boolean state = (Boolean) evt.getNewValue();
if (state.equals(Boolean.TRUE)) {
// Button has been pressed
}
else {
// Button has been releases
}
}
}
}


How it works?
Both CallableSystemAction and BooleanStateAction are direct subclasses of org.openide.util.actions.SystemAction. When a system action is executed its abstract actionPerformed method is invoked.

// In SystemAction...
public abstract void actionPerformed(ActionEvent ev);


In the case of CallableSystemAction, the override method makes some work and finally invokes the performAction which is the method you need to code.

public void actionPerformed(ActionEvent ev) {
if (isEnabled()) {
org.netbeans.modules.openide.util.ActionsBridge.doPerformAction(
this,
new org.netbeans.modules.openide.util.ActionsBridge.ActionRunnable(ev, this, asynchronous()) {
public void run() {
performAction();
}
}
);
} else {
// Should not normally happen.
Toolkit.getDefaultToolkit().beep();
}
}


In the case of BooleanStateAction, this class maintains a property which represents the state of the button. When the override actionPerformed method is execute it changes the property state and fires a property change event to be cached by the BooleanStateAction listeners:

public void actionPerformed(java.awt.event.ActionEvent ev) {
setBooleanState(!getBooleanState());
}

public void setBooleanState(boolean value) {
Boolean newValue = value ? Boolean.TRUE : Boolean.FALSE;
Boolean oldValue = (Boolean) putProperty(PROP_BOOLEAN_STATE, newValue);

firePropertyChange(PROP_BOOLEAN_STATE, oldValue, newValue);
}


As you can see in the SomeAction code the tip resides in registering the class as its own listener and handle the state change in the propertyChange method.

Monday, February 18, 2008

Changing default action's icon in NetBeans RCP

If you are developing an application using NetBeans RCP probably you are using default actions like Delete, Cut or Save that uses its own icons. This post talks about two techniques so change the default icons associated to an existent action.

Branding
The first method to change the default icon is through the branding directory in your module suite. To allow this, you need to know in which Java package is stored the icon resource used by the action you want to change its icon. A good way to know this is downloading the NetBeans platform (or other module) source code, looking for the action code and get the icon's resource path.

For example, the Cut and Delete actions are in the package org.openide.action. If you want to override it with your own icons all you need to is is to create, in your module suite branding directory, a folder called org-openide-action.jar, create a subfolder hierarchy representing the package structure and put your own icons with the same name the action code uses.



Wrapping
The second method implies to create a new action that wraps the target action you want to change its icons.
The below present a little class WrapperCutAction that wraps the NetBeans CutAction. The idea is pretty simple, the wrapper action can have any desired icon and when it is executed only you need to do is redirect the event to the target action.


package yourpackage;

import java.awt.event.ActionEvent;
import org.openide.actions.CutAction;
import org.openide.util.HelpCtx;
import org.openide.util.NbBundle;
import org.openide.util.actions.CallbackSystemAction;

public final class WrapperCutAction extends CallbackSystemAction {

public static final String ICON_PATH = "org/balloon/ui/icons/edit-cut.png";
// Wrap the target action
private CutAction ca = new CutAction();

public String getName() {
return NbBundle.getMessage(WrapperCutAction.class, "CTL_WrapperCutAction");
}

protected String iconResource() {
return ICON_PATH;
}

public HelpCtx getHelpCtx() {
return HelpCtx.DEFAULT_HELP;
}

protected boolean asynchronous() {
return false;
}

// Wrap the target methods
public void actionPerformed(ActionEvent e) {
ca.actionPerformed(e);
}

public Object getActionMapKey() {
return ca.getActionMapKey();
}
}

Sunday, February 17, 2008

R2D2 Translator

I have just received an email from a friend with an amazing feature: the R2D2 translator.

If you are a friki, freak, nerd or geek (like me?) probably this like you a lot.