DXMEvent Class

Creates an object that represents an event. Events identify specific times, states or user actions and are used to specify when given actions should occur. Typically, you use events with the until and untilNotify methods to create behaviors that change as a result of the event. For example, you can change the color of an object when the user presses a mouse button by specifying the mouse button event in a call to the until method of the ColorBvr class. Every event, when it occurs, returns some event data. This data may or may not be meaningful. The data returned, for example, by leftButtonDown has no meaning.

You can combine existing events to create new, more complex events. For example, the andEvent method lets you combine two events so that the resulting event occurs only if both of the original events occur simultaneously.

For relevant methods and fields from the Statics class, see the following topics.

DXMEvent Methods

DXMEvent Constructs a DXMEvent object.

attachData Takes an arbitrary object and produces a new event.

notifyEvent Creates a new event.

registerCallback Causes an external action when an event occurs in Microsoft® DirectAnimation® for Java and is used in conjunction with the EventCallbackObject.

snapshotEvent When called on an instance of a behavior, samples the given behavior and returns it as a constant behavior with the value as data.

newUninitBvr Enables you to refer to a DXMEvent behavior before that behavior has been defined.

DXMEvent

DXMEvent Class

Constructs a DXMEvent object.

Syntax

public DXMEvent( );

attachData

DXMEvent Class

Takes an arbitrary object and produces a new event. The new event occurs at the same time as the original event, but its data is now the data that was specified in the call to attachData.

Syntax

public DXMEvent attachData( Object object );

Parameters

object
Arbitrary object.

Return Value

Returns a DXMEvent object. The event data is the event data of the new event.

Remarks

This method allows an application to associate arbitrary client data with an event and know that it will be delivered to the notifier when the event occurs. In the following example, the behavior is red until the left mouse button is pressed. It then passes either green or yellow, depending on what is returned by the notifier.
DXMEvent greenLeft = leftButtonDown.attachData(green);
DXMEvent yellowright = rightButtonDown.attachData(yellow);
ColorBvr myBvr = (ColorBvr)untilNotify
(red, orEvent(greenLeft, yellowRight), notifier);

notifyEvent

DXMEvent Class

Creates a new event. This occurs when the original event occurs. It then calls the notifier and uses the result as its event data.

Syntax

public DXMEvent notifyEvent( UntilNotifier notifier );

Parameters

notifier
Returns the new behavior.

Return Value

Returns the DXMEvent object. The event data is the time the event fired and the new behavior.

registerCallback

DXMEvent Class

Causes an external action when an event occurs in DirectAnimation for Java and is used in conjunction with the EventCallbackObject. Whenever that event occurs, the invoke method of the callback is called with the event data produced by the event.

Syntax

public Object registerCallback(
     EventCallbackObject object,
     BvrsToRun extraBvrsToRun,
     boolean bool
);

Parameters

object
Object that implements the EventCallback interface.
extraBvrsToRun
Behaviors that are not part of the model.
bool
If true, the first occurrence of the event will trigger invoke. If false, every occurrence of the event will trigger invoke.

Return Value

Returns an object of type java.lang.Object. This object can be used to unregister the callback.

Remarks

An example of where this method is used is displaying a GUI window when the mouse moves to a particular area.

snapshotEvent

DXMEvent Class

When called on an instance of a behavior, samples the given behavior and returns it as a constant behavior with the value as data. The event time of the new event is when the original event occurs.

Syntax

public DXMEvent snapshotEvent( Behavior a );

Parameters

a
Behavior object which will be sampled when the method is invoked.

Return Value

Returns the DXMEvent object. The event data is the value of the behavior at the time it was sampled, returned as a constant behavior.

Example

In the following example, the value of n is localTime until the left mouse button is pressed. It then becomes whatever the value of localTime was when the event occurred:
n=until(localTime, leftButtonDown.snapshotEvent(localTime));

newUninitBvr

DXMEvent Class

Enables you to refer to a DXMEvent behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

Syntax

public static newUninitBvr( );

Return Value

Returns the DXMEvent object.