Shu Extensions API

Overview

For advanced usage of Shu we have provided an Extensions API which allows you to add custom commands to your Shu based application.

An Shu extension is a dynamic library (DLL on Windows and a loadable bundle on Mac) written in C/C++ that exports functions which execute when called from actionscript/javascript.
To enable an exported function, it must be registered in Shu as a handler (a handler is a data type that holds a name mapped to a function).

Example

Here is an example of the source file for a custom extension that executes the system beep.

beep.cpp 
// 1.
#include "extapi.h"

// 2.

XXHandler beepHandler;

// 3.
XXFunctions *gHostFuncs;

// 4.
XXError SXP_Init(XXFunctions *hostFuncs)
{
    // 5.
    XX_DEFINE_HANDLER(&beepHandler, &myBeep, "my.beep");

    // 6.
    hostFuncs->registerHandler(&beepHandler);

    // 7.

    gHostFuncs = hostFuncs;

    return XXNoError;
}

// 8.
void SXP_Shutdown(void)
{
}

// 9.
XXParams* myBeep(XXParams *params)
{
    XXParams *r;
    XX_ALLOC_PARAMS(r);
#ifdef __APPLE__
    SysBeep(kDefaultSysBeep);
#else // windows
    int freq = 1000;
    int duration = 1000;
    if(params->count == 2)
    {
        freq = atoi(params->values[0]);
        duration = atoi(params->values[1]);
    }
    Beep(freq, duration);
#endif
    // 10.
    XX_PARAM_ADD(r, "true");
    return r;
}
  1. Include the extapi.h file which declares needed functions and macros.
    This file should be read through to understand the data-types and macros used.
  2. Create a handler object.
  3. Define a global variable to hold the host functions.
  4. This function will need exporting.
  5. Define the hander.
    The first parameter is the address of our handler, the next is the address of our actual hander function and finaly the name of the handler.
    The name should be as unique as possible to avoid a clash with any other handlers.
  6. Here we register our handler with Shu.
  7. Store the host functions to our global variable.
    We do this in case we need to call any of the host functions later.
  8. This function will need exporting.
  9. Our actual handler function implementation.
  10. Here we are adding a single parameter to the return value.
    This must be in JSON notation as it will be converted into an appropriate actionscript type. In this example a Boolean of true.
    When more than one parameter is added to the return parameters, an Array is returned to the calling actionscript.

Calling your extension

You can make use of this shared library with actionscript like:

  • var result = shu.Extension.call("my.beep", 750, 500);

On Windows, once you have compilied your DLL, simply copy it into a directory "ext" which you distribute with your final application.
On Mac, copy the bundle into a directory "ext" inside your application package's Resources folder.

Important note about displaying any GUI

If during the execution of your handler function you need to display any GUI (eg a dialog or window), it is very important ro wrap the calls with the macros: XX_GUI_ENTER() and XX_GUI_LEAVE()
E.g.

  • XX_GUI_ENTER();
// Your code goes here that displays a dialog.
// When the dialog is closed you then call...
XX_GUI_LEAVE();