EventReceptor
One example of usage
would be when you want
a
callback to fire if
somebody clicks on a Construct. Above is a picture of two
PanelLabel (Host and Join) and one RoundedPanel (the backdrop for the
two buttons) Construct objects. Suppose you
want to have some message sent when the Host object is clicked.
The call used to make that happen is this:
[VisionCursor
EventReceptorOnAll:[EventReceptor
Object:HostButton
EventType:CURSOR1DOWN EvalType:CURSORPOSPOINT2D ResultType:ACTIVE
CallbackObject:Connector Callback:@selector(Host) Flags:0]];
What this code does is create an EventReceptor object and then assigns it to all Abstraction objects of the type VisionCursor. The EventReceptor is setup so that a the callback message - (void) Host will be sent to the object "Connector" when any CURSOR1DOWN events are created on the Abstraction objects that are attached to it if their two dimensional cursor positions (CURSORPOSPOINT2D) are over any pixel of the object HostButton at the time of the event and if it is the closest object in the z direction (a combination of ACTIVE and CURSORPOSPOINT2D) that receives CURSOR1DOWN events if evaluated in the same way (CURSORPOSPOINT2D) and also has a ResultType of ACTIVE. That might seem overly complicated and hard to understand but you will find that you will quickly need the flexibility and power that the EventReceptor class offers you.
EventReceptors are structures that you create when you want something to happen as a result of user input or other spontaneous events. Whenever the input produced by the connected devices produces events defined by Abstractions that the EventReceptor is attached to and that the EventReceptor wishes to respond to, its corresponding callbacks are fired. To create them you simply send a message to EventReceptor class with all the pertinent information. Parameters passed for the creation of EventReceptors are:
The Construct that you pass in for Object is the receiver of the evaluation test. It is also (along with the callback objects) attached to the EventReceptor during its lifespan (meaning that if any of those Constructs are deallocated then the EventReceptor objects will be too). The EventType is the Abstraction specific event that will trigger a positive evaluation for this EventReceptor. The EvalType is what kind of evaluation route should be used, such as always passing or passes only if the cursor is over at least one pixel of the rasterized object. The ResultType combined with the outcome of the evaluation test determine whether the callback for the EventReceptor will actually fire. CallbackObject is the object that receiver the message defined in Callback if it is determined that the EventReceptor should fire its callback. CallbackObjectNot and CallbackNot are fired only if it has been determined that the EventReceptor should not fire. Priority is an integer centered at zero which specifies an order to when this callback should fire in relation to other callbacks on the same Abstraction (this is useful if you have callbacks that might destroy other EventReceptors that can fire on the same event and you want those callbacks to be executed before they are destroyed). By default all EventReceptors have a priority of zero and are fired in order from lowest to highest. Flags is a field for passing in OR'ed parameters that dictate special state or function for an EventReceptor.