| Customize Help
| Save Settings

MgraHookFunction


Function Map
Syntax
Description
Parameters
- GraListId
- HookType
Table: For specifying the 2D graphics list event
+ combination: For detaching the hook-handler function
- HookHandlerPtr
- UserDataPtr
Compilation information
Synopsis
Hook a function to a 2D graphics list event.
Syntax
void MgraHookFunction(
MIL_ID GraListId, //in
MIL_INT HookType, //in
MIL_GRA_HOOK_FUNCTION_PTR HookHandlerPtr, //in
void *UserDataPtr //in-out
)
Description

This function allows you to attach or detach a user-defined function to a specified 2D graphics list event (for example, a modification to the 2D graphics list's contents). Once a hook-handler function is defined and hooked to an event, it is automatically called when the event occurs.

You can hook more than one function to an event by making separate calls to MgraHookFunction() for each function that you want to hook. MIL automatically chains and keeps an internal list of all these hooked functions. When a function is hooked, this new function is added to the end of the list. When the event happens, all user-defined functions in the list will be executed in the same order that they were hooked to the event. You can also remove any function from the list; in this case, MIL preserves the order of the remaining functions in the list.

Unlike most other functions that modify a MIL object, you can call this function concurrently from multiple threads on the same MIL 2D graphics list (GraListId) without using an M_MUTEX object, as long as all the other parameters of the concurrent calls do not also share data.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see which MIL system’s documentation you should use in its place and any possible differences.
Parameters
This function is not supported on the selected boards.
This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.
Parameters
GraListId

Specifies the identifier of the 2D graphics list to which to hook a function. The 2D graphics list must have been previously allocated on the required system using MgraAllocList().

HookType

Specifies the 2D graphics list event to which to hook the function. This parameter can be set to one of the following values:

function map For specifying the 2D graphics list event
Click to summarizeValue Description
Click to summarize M_GRAPHIC_LIST_MODIFIED +

Calls the hook-handler function each time the specified 2D graphics list is modified in any way, either by a MIL function or by interactive manipulations. Any of the other events will also trigger this event, and it will always be the last event to be triggered.

(summarize)
Click to summarize M_GRAPHIC_MODIFIED +

Calls the hook-handler function each time the specified 2D graphics list's graphics are modified by a MIL function or by interactive manipulations. This includes the creation of a new graphic (for example, using MgraLine() or by interactive manipulations), its deletion (using MgraControlList() with M_DELETE or MgraClear()) and any modification to a graphic using MgraControlList(), except for changing the selection (MgraControlList() with M_GRAPHIC_SELECTED).

Note that this event can be triggered even if no modification occurred. For example, calling MgraControlList() with M_POSITION_X and passing the current value returned by MgraInquireList() with M_POSITION_X will not modify the graphic, but will still trigger the event.

(summarize)
Click to summarize M_GRAPHIC_SELECTION_MODIFIED +

Calls the hook-handler function each time a graphic is selected or deselected, either by a MIL function or by interactive manipulations.
Click to summarize M_INTERACTIVE_GRAPHIC_STATE_MODIFIED +

Calls the hook-handler function each time the specified 2D graphics list's interactive state is modified by a MIL function or by interactive manipulations.
Combination value for the values listed in For specifying the 2D graphics list event.

You can add the following value to the above-mentioned values to set whether to detach the hook-handler function.

function map For detaching the hook-handler function
Click to summarizeCombination value Description
Click to summarize M_UNHOOK

Unhooks the specified function if hooked to the specified event.
HookHandlerPtr

Specifies the address of the function that should be called when the specified event occurs. The hook-handler function must be declared as follows:

MIL_INT MFTYPE HookHandler(
MIL_INT HookType,
MIL_ID EventId,
void *UserDataPtr
)

Parameters
HookType

Type of 2D graphics list event that generated the call.

EventId

Event identifier to pass to MgraGetHookInfo() when inquiring about the hooked event.

UserDataPtr

User data pointer that was passed to the UserDataPtr parameter of MgraHookFunction().

Upon successful completion, the hook-handler function should return M_NULL. Note MFTYPE and MIL_GRA_HOOK_FUNCTION_PTR are reserved MIL predefined types for functions and data pointers.

UserDataPtr

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.

Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
GRAPHIC LIST MODIFIED GRAPHIC MODIFIED GRAPHIC SELECTION MODIFIED INTERACTIVE GRAPHIC STATE MODIFIED UNHOOK