org.bs.mdi
Class Action

java.lang.Object
  org.bs.mdi.Action

Direct Known Subclasses:

CompositeAction

public abstract class Action

extends Object

Actions are the means of communication between Data and View objects. An Action encapsulates information about a modification which took place either in the View or in the Data object. An Action is supposed to remember enough information about the modification to be able to undo it at a later time, unless its isUndoable() method returns false.

In order to keep everything synchronized, the View has to inform the Data whenever it has been modified, and vice versa. This bi-directional communication between View and Data is done by using Action objects as some kind of adaptors which know how to change data and view to reflect the changes done by the user.

Constructor Summary

protected	Action(ActionObservable source) Action is an abstract class and cannot be instantiated.
protected	Action(ActionObservable source, boolean retarded) Action is an abstract class and cannot be instantiated.

Method Summary

abstract void	applyTo(Data data) Applies this action to a Data object.
abstract void	applyTo(View view) Applies this action to a View object.
boolean	clustersWith(Action action) Returns true if this action should be clustered together with the action given as the parameter.
abstract String	getName() Returns the name of the action type.
ActionObservable	getSource() Returns the source of this action.
boolean	isRetarded() Returns true if this is a so-called "retarded" action.
boolean	isUndoable() Returns true if the action can be made undone.
void	setRetarded(boolean retarded) Changes the retarded status of this Action.
abstract String	toString() Returns a string representation of this action.
abstract void	undoFrom(Data data) Undoes this Action from a Data object.
abstract void	undoFrom(View view) Undoes this Action from a View object.

Methods inherited from class java.lang.Object

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

Constructor Detail

Action

protected Action(ActionObservable source)

Action is an abstract class and cannot be instantiated.

Parameters:

source - the ActionObservable which this Action originated from

Action

protected Action(ActionObservable source,
                 boolean retarded)

Action is an abstract class and cannot be instantiated.

Parameters:

source - the ActionObservable which this Action originated from

retarded - true if the action is retarded, i.e. if the View is already updated and the purpose of this action is just to update the Data "en retard".

Method Detail

getSource

public ActionObservable getSource()

Returns the source of this action.

Returns:

the ActionObservable which this Action originated from

isRetarded

public boolean isRetarded()

Returns true if this is a so-called "retarded" action.

Retarded actions originate from a View which has been modified and which has already made these modifications visible to the user. This is different from the usual behaviour, where the View detects a modification (e.g. user input) which is not initially visible to the user. In this scenario, the View would notify the Data, and the Data would in turn notify the View, hence making the modifications visible. If the action is retarded however, a part of this notification chain can be omitted: Only the Data objects which this action did not originate from are notified of the changes.

A good example for the use of retarded actions is a text editor. Whenever the user types text into a text area, the input becomes visible immediately. The Data and perhaps other View objects have to be notified of the modifications, but not the text area where the modified text is already visible.

Returns:

true if this is a retarded action, false otherwise

setRetarded

public void setRetarded(boolean retarded)

Changes the retarded status of this Action. There should be no need to call this method from outside the Java MDI Framework.

Parameters:

retarded - true if this Action should be considered regarded, false otherwise

applyTo

public abstract void applyTo(Data data)

Applies this action to a Data object. Subclasses of Action should implement this method to initiate a state change on the given data object.

Parameters:

data - the Data object

applyTo

public abstract void applyTo(View view)

Applies this action to a View object. Subclasses of Action should implement this method to initiate a state change on the given view object.

Parameters:

view - the View object

undoFrom

public abstract void undoFrom(Data data)

Undoes this Action from a Data object. Subclasses of Action should implement this method to initiate a state change on the given data object.

Parameters:

data - the Data object

undoFrom

public abstract void undoFrom(View view)

Undoes this Action from a View object. Subclasses of Action should implement this method to initiate a state change on the given view object.

Parameters:

view - the View object

isUndoable

public boolean isUndoable()

Returns true if the action can be made undone. An action should identify itself as non-undoable if it includes too few information in order to be able to undo the changes.

Returns:

true if this action is undoable

clustersWith

public boolean clustersWith(Action action)

Returns true if this action should be clustered together with the action given as the parameter. This mechanism allows you to "glue" similar consecutive actions together to one "action cluster". This is done by combining them to a CompositeAction. The actual clustering is done by the RootData object. The usual calling convention is: oldAction.clustersWith(newAction).

Parameters:

action - the Action to be tested whether it can be clustered or not

Returns:

true if clustering is desirable, false otherwise

getName

public abstract String getName()

Returns the name of the action type. If this action performs text insertion in a text editor for example, this method should return something like "text insertion".

Returns:

the name this action type

toString

public abstract String toString()

Returns a string representation of this action. The returned string should describe exactly what this action does.

Returns:

the string representation of this action.