| Navigation: Language Reference > 13 - Built-in Functions >====== REGISTER (register event handler) ====== |    |
REGISTER( event, handler, object [,window] [,control] )
| REGISTER | Registers an event handling procedure. |
| event | An integer constant, variable, expression, or EQUATE containing an event number. A value in the range 400h to 0FFFh is a User-defined event. |
| handler | A LONG variable, or expression containing the return value from ADDRESS for the PROCEDURE to handle the event. |
| object | A LONG integer constant, variable, or expression containing any 32-bit unique value to identify the specific handler. This is generally the return value of ADDRESS(SELF) when the handler is a CLASS method. |
| window | The label of the WINDOW or REPORT whose event to handle. If omitted, the current target WINDOW or REPORT is assumed. |
| control | An integer constant, EQUATE, variable, or expression containing the field number of the specific control whose event to handle. If omitted, the event is handled for every control on the window. |
Can also be prototyped as REGISTEREVENT.
REGISTER registers an event handler PROCEDURE called internally by the currently active ACCEPT loop of the specified window whenever the specified event occurs. This may be a User-defined event, or any other event. User-defined event numbers can be defined as any integer between 400h and 0FFFh.
You may REGISTER multiple handlers for the same event if you choose–the handlers are called by ACCEPT in reverse order of their registration (the last one registered executes first). You may explicitly call UNREGISTER to remove the registration of any specific handler. The Clarion runtime library automatically unregisters all registered event handlers (for the WINDOW passed as the 4th parameter) as a part of the window's closing (when the outer most ACCEPT loop that is running in the window terminates its execution), so explicitly calling UNREGISTER is not required unless your program's logic requires it.
Anytime the event occurs, the handler procedure is called internally by the events processor running from within the ACCEPT statement. The value returned by the handler determines whether or not ACCEPT cycles for any additional event processing.
The handler procedure MUST have 1 parameter: when the handler is called the runtime library is passing the object value (the 3rd parameter in the call to REGISTER) as its parameter.
The handler PROCEDURE must not take any parameters and must return a BYTE containing one of the following EQUATEd values (these EQUATEs are defined in the ABERROR.INC file):
| Level:Benign | Calls any other handlers and the ACCEPT loop, if available. |
| Level:Notify | Doesn't call other handlers or the ACCEPT loop. This is like executing CYCLE when processing the event in an ACCEPT loop. |
| Level:Fatal | Doesn't call other handlers or the ACCEPT loop. This is like executing BREAK when processing the event in an ACCEPT loop. |
Example:
WindowResizeClass.Init PROCEDURE
CODE
REGISTER(EVENT:Sized,ADDRESS(SELF.TakeResize),ADDRESS(SELF))
!Other code follows
WindowResizeClass.TakeResize PROCEDURE
ReturnValue BYTE
CODE
ReturnValue = Level:Benign
RETURN(ReturnValue)
See Also: