Callbacks and the I.M. Manager

The MVO library includes a class for managing 3dGS I.M. code which enforces an object-oriented approach to using 3dGS’ callbacks. We also encourage a naming convention on callbacks which will improve the ability of developers to share and follow each others callbacks.

Let’s look at the example of where we have a number of simple callbacks in our application that we wish to register with the I.M. manager. Since the callbacks are all fairly straigtforward we will include them in one class called HImMyAppUtility, for stylistic purposes all IM class names are pre-pended with HIm. HImMyAppUtility will consist of a static function for each callback and a separate function which registers the callbacks with the I.M. Manager object which is called HImManager. Here’s the code:

class MVO_API HImMyAppUtility
{
        private:
                HImMyAppUtility() {};

        public:
                static void RegisterCallbacks();
                static void my_callback1(struct ht_net_rendition *nr, struct ht_segment_info  *si);
                static void my_callback2(struct ht_net_rendition *rendition, union ht_geometry *geo3);
};

If the IM callbacks had any specific datatypes that were specific to it you could also define and include them here. The callback functions will be identical to your current IM callbacks while the code to RegisterCallbacks should look like this:

void HImMyAppUtility::RegisterCallbacks()
{
        HImRegisterCallback("HImMyAppUtility_my_callback1", my_callback1);
        HImRegisterCallback("HImMyAppUtility_my_callback2", my_callback2);
}

You should use the HImRegisterCallback macro which is defined in HImManager.h to register your callbacks, this ensures that the callbacks are registered with the IM Manager. Also, notice that we now follow a very specific naming convention for callbacks with the name being the classname it resides in followed by the function name. We follow this convention to make it easier for developers to track down the location of callbacks. This naming convention is done for stylistic reasons and though recommended it does not have to be followed in order to use the IM Manager. Also, notice that you can register more than one name for a specific callback, this can be used to support legacy data which may be using the old callback name.

Now that we have created our callback object all we need to do in our application is call HImMyAppUtility::RegisterCallbacks to register the callbacks with the IM Manager. In many cases an operator may have a callback associated with it. In these cases you should add a RegisterCallback method to the operator class and simply register it at the same time that you register your other callbacks:

void CMyApp::InitInstance()
{
        .
        .
        // let's register our callbacks
        HImMyAppUtility::RegisterCallbacks();
        HOpMyFunkyOperator::RegisterCallbacks();
        .
        .
}