Mouseeventhandler - Adobe ATMOSPHERE User Manual

272
APPENDIX E

MouseEventHandler

A MouseEventHandler allows the developer to specify a response when the user performs a mouse event in the
rendered window. The recognized mouse events include Click, Over, Out, and Move (which can be combined to also
create mouse "Drag").
A new MouseEventHandler() object should be created for each type of mouse event to which you desire to respond.
The event responses are separated by designating different Filtering Methods as their names indicate (shown
below). The Filtering Methods are also used to specify or limit the scope of world objects which will trigger the
MouseEventHandler response.
When a mouse event occurs, Atmosphere searches the list of user created MouseEventHandlers(with their Filtering
Methods) to determine if the '.OnEvent(event, what)' callback should be triggered. If triggered, the 'event' object
which is returned as the fi rst argument possesses numerous properties about the mouse event. The second argument
'what' contains a reference to the world object that was under the mouse during the event.
Two likely approaches may be used to respond to mouse events:
Create only a few event handlers(one for each type), and test the 'what' object that is returned to customize the
response based upon the object clicked. A "switch - case" statement would be useful for this type of approach.
Create many custom event handlers with a single object specifi ed in the Filtering Method.
Both of these approaches have their advantages, and your specifi c application will determine what's best for you.
Lastly, information on how various world objects respond to mouse events is shown below in the 'Local Methods'
section.
Global Methods
MouseEventHandler()
Creates a new MouseEventHandler which may be set to process all mouse events(default), or be limited to a
specifi c primitive, viewpoint object, or physical model.
// specify that the main world geometry, or 'stage' will receive click events
myEventHandler = MouseEventHandler();
myEventHandler.setFilterOnClick(stageModel.getSolidObject(0));
myEventHandler.onEvent = function(mouseEvent, what)
{
chat.print("Object = " + what);
}
Local Callbacks
onEvent(mouseEvent, what)
A method which defi nes what will happen when a mouse event occurs. A 'mouseEvent' object is returned which
possesses numerous properties, and the object under the mouse is returned as the second argument 'what' .
myEventHandler = MouseEventHandler();
myEventHandler.setFilterOnClick(stageModel.getSolidObject(0));