API Reference | developer.brewmp.com API Reference | developer.brewmp.com


API Reference


Brew Release
Brew MP 1.0.2
See Also
- ICanvas - IHandler_SetHandler - HANDLERDESC_Call - HandlerDesc
This type definition specifies the prototype for the function pointer an application may register as a custom event handler for an object. The application may hook a custom event handling routine into the normal event handling chain, providing the opportunity to either override or alter the normal event handling mechanism for a given object. For example, an object wishing to handle the pressing of a specific key in a non-standard way (every press of the '*' key would, for example, cause the application to play the sound of a duck quacking) could register a custom event handler that would trap for key events and act accordingly when that specific key is pressed. The custom event handler would perform its action and could choose to end normal event handling at that point by returning TRUE (or FALSE, if the action taken merited further event processing). Or, the custom event handler could pass the event onto the next event handler in the chain by calling HANDLERDESC_Call().
The widgets framework will call the PFNHANDLER with the same parameters normally passed into a BREW event handler, and additionally passes an extra parameter that identifies a pointer to private data owned and managed by the application. The custom event handler may use this pointer to access private data that has been created by the object implementing the handler interface.
  • pCxt:     A pointer to private data allocated and managed by the caller that
                 has registered the event handler.  This data pointer is passed into
                 the event handler, providing the callback with access to this private
  • evt:      The event code being sent into the event handler.
  • wParam:   16-bit event-specific parameter.
  • dwParam:  32-bit event-specific parameter.
  •    TRUE  --  The custom event handler was able to handle the event.
       FALSE --  The event was not handled by the custom event handler.
  •     typedef boolean (*PFNHANDLER)(void *pCxt, AEEEvent evt, uint16 wParam, uint32 dwParam);
The custom event handler is registered by an object implementing the handler interface by initializing the 'pfn' field of a HandlerDesc data structure and calling that object's implementation of the IHandler_SetHandler() function. This will hook the custom event handler into that object's normal event handling process. Upon registering the event handler, IHandler_SetHandler() will return a pointer to a HandlerDesc data structure that contains a pointer to the event handler that would have been called had the new handler not been registered. The PFNHANDLER function should pass this HandlerDesc pointer to the old event handler by calling HANDLERDESC_Call() in order to ensure that normal event processing will still take place.