GPI Message Routing

When a GPI is initialised, it may hook into one or more notification functions supplied by ShapeUp. These can be mouse action in the map window, adding menu items and toolbars and get notified when the user selects an item, etc.

A callback function is supplied to ShapeUp in fnInit() to set the function which should be notified on the subscribed events. This is the pfnHook member of the SUImport supplied in the SUExport argument to the function.

SURESULT __cdecl fnInit(SUExport *pExport)
{
    ...
    pExport->import.pfnHook = MyHookFunc;
    ...
}

For the purpose of adding notification hooks, the ShapeUp API exposes several functions on the form ShapeUp_AddXxxHook(), see example_hooks.cpp.

As an example, study the following:

SURESULT __cdecl fnInit(SUExport *pExport)
{
    ...
    ShapeUp_AddPostDrawHook(0);
    ...
}

This will tell ShapeUp to notify the GPI when the map has been refreshed to allow the plug-in to overlay its own graphics.

A sample of the hook function might look like:

SURESULT __cdecl MyHookFunc(SUHANDLE hWorkspace, int hookType, SUHookData *args)
{
    switch (hookType)
    {
    case HOOKTYPE_POSTDRAW:
        DrawSomething();
        break;
    default:
        break;
    }
    return SURESULT_OK;
}

Here, the value found in args->userData, is the same value used when adding the hook. Some of the handlers have more information in the args data. Check each HOOKTYPE for what the args really points to. It is however always safe to treat the args as a pointer to a SUHookData struct.

Make sure you have first read the introduction.

---