ssCore.Joystick.setNotify

Tell SWF Studio about a Joystick event notification that you'd like to receive.


Availability:

First available in version 3.0 build 2039.


Input Parameters:

event - The name of the event notification you want enabled. Valid values include: onJoyMove,onJoyPOV,onJoySingleButton,onJoyAnyButton,onJoyButtonMask,onJoyCombo.

button - [Optional] - A button id from 0.. maxbuttons (see Joystick.getInfo). Used with the onJoySingleButton event.

mask - [Optional] - A button mask that identifies a combination of joystick buttons. Used with the onJoyCombo event.


Output Parameters:

result - Notification data for the specified event (see description of events for more detail).


Asynchronous Mode:

When this method is called asynchronously, a return object containing the output parameters is passed to the specified callback function.

ssCore.Joystick.setNotify( paramsObject [, callbackParamsObject] [, errorParamsObject] );


Synchronous Mode:

When this method is called synchronously, a return object containing the output parameters is returned to the caller immediately.

var returnObject = ssCore.Joystick.setNotify( paramsObject );


Notes:

Button events are only sent as frequently as determined by Joystick.setPeriod, as a result of user interaction beyond the set threshold (see Joystick.setThreshold). If the user does not move the joystick or press buttons, no events are triggered.

Notification data is returned as a string of comma separated values. In the listings below, the field names have the following meanings:

To cancel notifications about an event, use Joystick.clearNotify.

To activate the event notification system, use Joystick.start. To temporarily stop the joystick from generating events, use Joystick.stop.

Joystick.setNotify may be called before Joystick.start if you wish to define the required event notifications before starting the notification system. Also, there is no need to temporarily stop the notification system before making changes to registered events.


Events:

name - onJoyMove
type - triggered
result - "id,x,y,z,r,u,v,pov"

The onJoyMove event is triggered when the joystick position on the x, y, z, r, u, v axes or the pov changes.

ssCore.Joystick.setNotify({event:"onJoyMove"}, {callback:onJoystickMoved});

function onJoystickMoved(ret_obj, cb_obj, err_obj)
{
    if (ret_obj.success)
    {
        var v = ret_obj.result.split(",");
        ssDebug.trace("joystick id: " + v[0]);
        ssDebug.trace("x: " + v[1]);
        ssDebug.trace("y: " + v[2]);
        ssDebug.trace("z: " + v[3]);
        ssDebug.trace("r: " + v[4]);
        ssDebug.trace("u: " + v[5]);
        ssDebug.trace("v: " + v[6]);
        ssDebug.trace("pov: " + v[7]);
    }
}

name - onJoyPOV
type - triggered
result - "id,pov"

The onJoyPOV event is triggered when the joystick POV data changes.

ssCore.Joystick.setNotify({event:"onJoyPOV"}, {callback:onJoystickPOVChanged});

function onJoystickPOVChanged(ret_obj, cb_obj, err_obj)
{
    if (ret_obj.success)
    {
        var v = ret_obj.result.split(",");
        ssDebug.trace("joystick id: " + v[0]);
        ssDebug.trace("pov: " + v[1]);
    }
}

name - onJoySingleButton
parameter - button
type - triggered
result - "id,state"

The onJoySingleButton event is triggered only when a specific button (passed as a parameter to Joystick.setNotify) is pressed or released.

ssCore.Joystick.setNotify({event:"onJoySingleButton"}, {callback:onJoystickSingleButton});

function onJoystickSingleButton(ret_obj, cb_obj, err_obj)
{
    if (ret_obj.success)
    {
        var v = ret_obj.result.split(",");
        ssDebug.trace("joystick id: " + v[0]);
        ssDebug.trace("state: " + v[1]);
    }
}

name - onJoyAnyButton
type - triggered
result - "id,button,state"

The onJoyAnyButton event is triggered when any button is pressed. The notification data contains information about which joystick and which button triggered the event as well as the button state ("0" for up or "1" for down).

ssCore.Joystick.setNotify({event:"onJoyAnyButton"}, {callback:onJoystickAnyButton});

function onJoystickAnyButton(ret_obj, cb_obj, err_obj)
{
    if (ret_obj.success)
    {
        var v = ret_obj.result.split(",");
        ssDebug.trace("joystick id: " + v[0]);
        ssDebug.trace("button: " + v[1]);
        ssDebug.trace("state: " + v[2]);
    }
}

name - onJoyButtonMask
type - triggered
result - "id,mask"

The onJoyButtonMask event is triggered when any button is pressed or released, but unlike onJoyAnyButton a button mask representing the state of all the joystick buttons is returned e.g. "10010000000000000000000000000000", where "1" means the button is down and "0" means the button is up. The position of the 0/1 in the string matches the button number from 0 (leftmost) to 31 (rightmost). The mask returned by onJoyButton mask is always 32 characters long.

ssCore.Joystick.setNotify({event:"onJoyButtonMask"}, {callback:onJoystickButtonMask});

function onJoystickButtonMask(ret_obj, cb_obj, err_obj)
{
    if (ret_obj.success)
    {
        var v = ret_obj.result.split(",");
        ssDebug.trace("joystick id: " + v[0]);
    
        for (var n = 0 ; n < v[1].length ; n++)
        {
            if (v[1].substr(n, 1) == '0')
                ssDebug.trace("button " + n + " is up.");
            else
                ssDebug.trace("button " + n + " is down.");
        }
    }
}

name - onJoyCombo
parameter - mask
type - triggered
result - "id,mask"

The onJoyCombo event is triggered when a specified combination of buttons are pressed at the same time. Button masks passed to the onJoyCombo handler can be anywhere from 1 to 32 characters long. Trailing zeros are ignored so "1001" is the same mask as "10010000" or "10010000000000000000000000000000".

ssCore.Joystick.setNotify({event:"onJoyCombo"}, {callback:onJoystickCombo});

function onJoystickCombo(ret_obj, cb_obj, err_obj)
{
    if (ret_obj.success)
    {
        var v = ret_obj.result.split(",");
        ssDebug.trace("joystick id: " + v[0]);
        ssDebug.trace("button combo pressed: " + v[1]);
    }
}