The Sc21 eventhandling system works in the following way:
Events received by the SCView are passed on to the SCController. SCController in turn passes them on to its SCEventHandler, who finally handles them.
The eventhandler has an outlet nextEventHandler, which can be set to another SCEventHandler, thus forming a chain of event handlers: If an event is not handled by the first event handler, it will be passed on to the next one, and so on - until the event has either been handled or there are no more eventhandlers in the chain. If an event was not handled by the eventhandler chain, it is sent back to NSView, and thus passed on to Cocoa's responder chain.
This is one of the few ways where Sc21 behaves differently from Cocoa. In Cocoa, you have to subclass NSView and override a method for each event type you are interested in (mouseUp:, rightMouseDown: etc). There are two reasons why we are doing things differently:
- Sc21 needs a more flexible way to deal with events in order to handle cases where no view is present, i.e. fullscreen mode.
- We wanted to allow the application programmer to add their own event handling capabilities by simply writing her own eventhandler.
All Sc21 eventhandlers must be derived from the SCEventHandler class. Sc21 comes with two built-in eventhandlers: SCCoinHandler and SCExaminerHandler.
SCEventHandler is the superclass for eventhandlers that takes care of managing the eventhandler chain. When writing your own eventhandler, it should be derived from this class. [API doc]
SCEventHandler has two important methods:
- (BOOL)controller:(SCController *)controller handleEvent:(NSEvent *)event; - (void)update:(SCController *)controller; controller:handleEvent: is the actual eventhandling method.
update: is a post-render callback that allows you to do continuous animation (such as needed when simulating a fly mode).
SCCoinHandler takes incoming NSEvents, converts them to SoEvents, and sends them to the Coin scenegraph. [API doc]
SCExaminerHandler allows you to inspect the scene by rotating, panning, and zooming in and out. An IB inspector makes it possible to set the mouse/modifier key combinations to use.[API doc]
There is a tutorial outlinining the basics of how to use the Sc21 eventhandling system: the Sc21 Tutorial, Part 2 Eventhandling.
The CustomEventHandling example distributed as part of the Sc21 distributions demonstrates a slightly more advanced use case, including how to create your own custom event handler.