ssCore.App.setNotify

Tell SWF Studio about an application event that you want to receive notifications for.


Availability:

First available in version 3.0 build 2039.


Input Parameters:

event - The event you want to receive notifications for. Valid values include: onData, onDesktopChange, onDeviceChange, onDialog, onDragDrop, onExitWindows, onOtherInstance, onQuit, onSysColorChange, onSystemCommand, and onWindow.

recurse - [Optional] - A boolean value that indicates whether SWF Studio should recurse through dropped folders or not (the default value is TRUE). Valid values include: true and false.


Output Parameters:

point - An optional parameter used with the OnDragDrop event to provide the point where drag drop operation was completed (i.e. the drop). The data is returned as a string in the form 'x,y', in pixels.

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.App.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.App.setNotify( paramsObject );


Notes:

None.


Events:

name - onData
type - triggered
result - "data"

The onData event is triggered when another SWF Studio application sends data to your application or broadcasts data to all running SWF Studio applications using App.sendData. The data receievd by the event handler is application specific and controlled by the sender.

ssCore.App.setNotify({event:"onData"}, {callback:onDataReceived});

function onDataReceived(ret_obj, cb_obj, err_obj)
{
    if (ret_obj.success)
    {
        v = ret_obj.result.split(",");
        ssDebug.trace("value: " + v[0]);
    }
}

name - onDesktopChange
type - triggered
result - none

onDesktopChange is triggered when a change is made to the desktop size or color depth. Before the event is actually triggered, the desktop and monitor related global variables are updated so you can use them in your event handler.

The global variables that may be affected by this event are: ssMonitorCount, ssMonitorInfo, ssDesktopWidth, ssDesktopHeight, ssDesktopColorDepth, ssDesktopRefreshRate, ssWorkAreaLeft, ssWorkAreaTop, ssWorkAreaRight, ssWorkAreaBottom, ssVirtualScreenLeft, ssVirtualScreenTop, ssVirtualScreenRight, ssVirtualScreenBottom and ssDesktopDisplayModes.

ssCore.App.setNotify({event:"onDesktopChange"}, {callback:onDesktopChange});

function onDesktopChange(ret_obj, cb_obj, err_obj)
{
    if (ret_obj.success)
    {
        ssDebug.trace("the desktop settings have changed");
    }
}

name - onDeviceChange
type - triggered
result - device,action,drive

onDeviceChange is triggered when a new drive or device (with a drive letter) is added or removed.

Possible values for the device setting are "DEVICE", "CD" and "VOLUME".

Possible values for the action setting are "ADDED" and "REMOVED".

Possible values for the drive setting are "A:", "B:", ... "Z:" or "UNKNOWN". Please note that unless auto insert notifications have been enabled for floppy drives (by default this feature is off), the onDeviceChange event will not be triggered when floppy drives are inserted and removed.

ssCore.App.setNotify({event:"onDeviceChange"}, {callback:onDeviceChange});

function onDeviceChange(ret_obj, cb_obj, err_obj)
{
    a = ret_obj.result.split(",");

    device = a[0];
    action = a[1];
    drive = a[2];

    if (ret_obj.success)
    {
        ssDebug.trace(device + " " + drive + " has been " + action);
    }
}

name - onDialog
type - triggered
result - "hwndDialog,isChild,captionDialog,captionParent"

onDialog is triggered when a dialog window appears. The data received by the event handler is a list of properties of the dialog window separated by commas. If the dialog that triggered the onDialog event is a child of your application then the dialog will be hidden automatically so you can decide whether it should be confirmed, cancelled or displayed for the user to deal with.

hwndDialog is the window handle of the new dialog. You will need to pass this value to App.confirmDialog, App.cancelDialog or App.showDialog. You can also use this window handle with other ssCore.Win functions that accept window handles.

isChild can be 'TRUE' or 'FALSE' and tells you whether the dialog is a child of your application window (TRUE) or whether it belongs to another window. You can use this to make decisions about when to cancel or confirm a dialog. If you do not confirm or cancel a child dialog you must display it by calling App.showDialog or it will remain hidden.

captionDialog is the caption of the dialog window and can help you to determine whether to cancel or confirm a dialog. In the example below we use this property to identify and automatically confirm print dialogs.

captionParent is the caption of the dialogs parent window. When the isChild property is FALSE you can use this to determine which window owns (opened) the dialog.

ssCore.App.setNotify({event:"onDialog"}, {callback:onDialog});

function onDialog(result_obj, callback_obj, error_obj)
{
    a = result_obj.result.split(",");

    hwndDialog = a[0];
    isChild = a[1];
    captionDialog = a[2];
    captionParent = a[3];

    // only mess with dialogs we own (our children)

    if (isChild == "TRUE")
    {
        if (captionDialog == "Print")
        {
            ssCore.App.confirmDialog({hwnd:hwndDialog});
        }
        else
        {
            ssCore.App.showDialog({hwnd:hwndDialog});
        }
    }
}

name - onDragDrop
type - triggered
result - "filelist"
point - "x,y"

onDragDrop is triggered when a user drags files and/or folders from the operating system onto your application. The data received by the event handler is a list of fully qualified files separated by ('\r') characters.

The onDragDrop event also has an extra output parameter called point that is a string consisting of two values x and y that tell you where the file(s) were dropped on your application window.

ssCore.App.setNotify({event:"onDragDrop"}, {callback:onDragDrop});

function onDragDrop(ret_obj, cb_obj, err_obj)
{
    if (ret_obj.success)
    {
        // create an array called files that contains the list
        // of dropped files and folders
    
        files = ret_obj.result.split("\r");
    
        for (i=0; i<files.length; i++)
        {
            ssDebug.trace("file" + i + ": " + files[i]);
        }
    
        v = ret_obj.point.split(",");
        ssDebug.trace("files were dropped at x=" + v[0] + ", y=" + v[1]);
    }
}

name - onExitWindows
type - triggered
result - "method"

onExitWindows is triggered when the application receives a notification that Windows is about to shutdown or logoff the current user. The data received by the event handler indicates the exit method and can be "SHUTDOWN" or "LOGOFF".

As soon as you register to receieve this notification, any attempt to exit Windows or logoff the current user will be blocked. After the operation has been blocked, your event handler will be called and passed the exit method.

It is the job of your event handler to use the exit method information to decide how to continue. The application can prompt the user to allow/disallow the operation or you can simply use this as an opportunity to call some cleanup code before your application ends. If you want to allow the exit operation to continue, you must call App.forceExitWindows and pass it the exit method that was passed to your event handler.

ssCore.App.setNotify({event:"onExitWindows"}, {callback:onExitWindows});

function onExitWindows(ret_obj, cb_obj, err_obj)
{
    var r = ssCore.App.showMsgBox({prompt:"Windows Exit Method: " + ret_obj.result + "\r\n\r\nAllow this action?", buttons:"yesno"});

    if (r.result == "YES")
    {
        ssCore.App.forceExitWindows({method:ret_obj.result});
    }
}

name - onOtherInstance
type - triggered
result - "cmdline"

onOtherInstance is triggered when your application has been built with the only allow one instance of this application option from the Application Tab enabled and someone attempts to start another instance of your application on the same machine. The data received by the event handler is the command line of the instance that was trying to start. This allows data to be passed to a running instance of an application from a second instance.

ssCore.App.setNotify({event:"onOtherInstance"}, {callback:onOtherInstance});

function onOtherInstance(ret_obj, cb_obj, err_obj)
{
    if (ret_obj.success)
    {
        ssDebug.trace("another instance of this app has been started");
        ssDebug.trace("the command was: " + ret_obj.result);
    }
}

name - onQuit
type - triggered
result - none

onQuit is triggered when the application encounters a Quit FSCommand, when your application calls App.quit or when the user attempts to close the application from the title bar or taskbar. If you want to allow the application to end your event handler has to call App.forceQuit. In this example the isOkayToShutdown() function is something that you would supply to determine whether it is okay to quit your application or not.

ssCore.App.setNotify({event:"onQuit"}, {callback:onQuit});

function onQuit(ret_obj, cb_obj, err_obj)
{
    if (ret_obj.success)
    {
        if (isOkayToShutdown() == true)
        {
            ssCore.App.forceQuit();
        }
        else
        {
            ssCore.App.showMsgBox({prompt:"Sorry, you can't quit right now"});
        }
    }
}

name - onSysColorChange
type - triggered
result - none

onSysColorChange is triggered when a change is made to the system color settings. Before the event is actually triggered, the system color global variables are updated so you can synchronize the changes in the system colors to your application.

The global variables affected by this event are the ones that start with ssSysColor (e.g. ssSysColorButtonFace, ssSysColorWindow, etc.)

ssCore.App.setNotify({event:"onSysColorChange"}, {callback:onSysColorChange});

function onSysColorChange(ret_obj, cb_obj, err_obj)
{
    if (ret_obj.success)
    {
        // make the application background color match the current
        // system background color (obviously you'd want to apply
        // more than just this change in your application)
    
        ssCore.Win.setBackColor({color:ssGlobals.ssSysColor3DFace});
    
        // ssSysColor3DFace is the face color for three-dimensional display
        // elements and for dialog box backgrounds.
    }
}

name - onWindow
type - triggered
result - "hwnd,caption,class,style"

onWindow is triggered when a new window is created. The data received by the event handler is a list of properties of the window, separated by commas.

hwnd is the window handle of the new window. You can use this window handle with any ssCore.Win functions that accept window handles.

caption is the caption of the window and can help you to determine which application the window belongs to.

class is the class name of the window and can help you to determine which application the window belongs to.

style is a text version of some of the window style flags. Currently this value can be either HIDDEN or VISIBLE. Support for more window style flags may be added in the future.

ssCore.App.setNotify({event:"onWindow"}, {callback:onWindow});

function onWindow(result_obj, callback_obj, error_obj)
{
    // result_obj.result = "hwnd,caption,class,style"

    a = result_obj.result.split(",");

    hwnd = a[0];
    caption = a[1];
    classname = a[2]; // everything except "#32770" (dialog)
    style = a[3]; // "HIDDEN" or "VISIBLE"

    ssDebug.trace("hwnd: " + hwnd);
    ssDebug.trace("caption: " + caption);
    ssDebug.trace("class name: " + classname);
    ssDebug.trace("style: " + style);
}