Synopsis
Hook a function to a display event.
Format
MDISPHOOKFCTPTR MdispHookFunction(DisplayId, HookType, HookHandlerPtr, UserDataPtr)
| MIL_ID DisplayId | Display identifier |
| long HookType; | Type of event to hook |
| MDISPHOOKFCTPTR HookHandlerPtr; | Pointer to hook function |
| void MPTYPE *UserDataPtr; | User data pointer |
Description
This function allows you to attach or detach a user-defined function to a specified display event. Once a hook-handler function is defined and then hooked to an event, it is automatically called when the event occurs during the execution of a MIL application.
Note, you must chain all hook functions. Before hooking an event, use MdispInquire to check if another function is hooked to the same event. If the hook-handler pointer is not M_NULL, save the hook-handler pointer and the user data pointer, then call MdispHookFunction. You must ensure that your hook function calls the previous hook function with the saved user data pointer and, when unhooking your function, restores it with a call to MdispHookFunction, using the saved parameters.
The DisplayId parameter specifies the identifier of the target display for the hook.
The HookType parameter specifies the display event type. This parameter can be set to the following:
| M_FRAME_START | Call the hook-handler function each time a new frame is displayed. |
The HookHandlerPtr parameter specifies the address of the function that should be called when an event occurs.
The hook-handler function, pointed to by HookHandlerPtr, must be declared as follows:
long MFTYPE HookHandler(HookType, EventId, UserDataPtr);
| long HookType; | Type of event hooked |
| MIL_ID EventId; | Reserved for future use |
| void MPTYPE *UserDataPtr; | Pointer that was passed by MdispHookFunction |
Upon successful completion, the hook-handler function should return M_NULL. Note, MDISPHOOKFCTPTR, MFTYPE and MPTYPE are reserved MIL predefine types for function and data pointers.
The UserDataPtr parameter specifies the address of the user data that you want to make available to the hook-handler function. This address is passed to the hook-handler function, through its UserDataPtr parameter, when the specified event occurs. Set this parameter to M_NULL if not used.
Returned value
The returned value is the address of the hook-handler function (if any) that was previously hooked to the specified type of event. This allows you to chain hooked functions, or to restore the old hook function when unhooking.
See also