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 dylib 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 is called by Shu when it loads the handler on startup.
    All initialization code should be placed here.
  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 gets called by Shu when the application is about to close so clean-up code can be placed here.
  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);

Once you have compilied the shared library, simply copy it into a directory "ext" which you distribute with your final application.

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();