windowMessages.js

/* Captures Window messages.
 *
 * Copyright 2017 Raising the Floor - International
 *
 * Licensed under the New BSD license. You may not use this file except in
 * compliance with this License.
 *
 * The R&D leading to these results received funding from the
 * Department of Education - Grant H421A150005 (GPII-APCP). However,
 * these results do not necessarily represent the policy of the
 * Department of Education, and you should not assume endorsement by the
 * Federal Government.
 *
 * You may obtain a copy of the License at
 * https://github.com/GPII/universal/blob/master/LICENSE.txt
 */

"use strict";

var fluid = require("gpii-universal"),
    ffi = require("ffi");

var gpii = fluid.registerNamespace("gpii");
fluid.registerNamespace("gpii.windows.messages");

require("../../WindowsUtilities/WindowsUtilities.js");

var windows = gpii.windows;

fluid.defaults("gpii.windows.messages", {
    gradeNames: ["fluid.component", "fluid.resolveRootSingle"],
    singleRootType: "gpii.windows.messages",
    events: {
        /**
         * Message received (see https://msdn.microsoft.com/library/ms633573)
         * @param hwnd {number} Window handle
         * @param msg {number} Message (WM_*)
         * @param wParam {number} Message specific data
         * @param lParam {void*}  Message specific data (ffi pointer, may not be valid after return)
         */
        "onMessage": null
    },
    listeners: {
        "onDestroy": {
            funcName: "gpii.windows.messages.stop",
            args: "{that}"
        }
    },
    invokers: {
        start: {
            funcName: "gpii.windows.messages.start",
            args: [
                "{that}",
                "{arguments}.0"
            ]
        },
        stop: {
            funcName: "gpii.windows.messages.stop",
            args: [
                "{that}",
                "{arguments}.0"
            ]
        },
        getWindowHandle: {
            funcName: "gpii.windows.messages.getWindowHandle",
            args: "{that}"
        }
    },
    members: {
        /** Message window class */
        windowClassname: "gpii-message-window",
        /** Window handle of the message window (multiple component instances use the same window). */
        messageWindow: null,
        /** A reference counter, so the window can be destroyed when no longer required. */
        references: []
    }
});

/**
 * Start listening for window messages. Create the message window if it's not already created.
 *
 * @param that {Component} The gpii.windows.messages instance.
 * @param component {Component} The component that's listening for messages.
 */
gpii.windows.messages.start = function (that, component) {
    var id = component.id;
    if (that.references.indexOf(id) === -1) {
        if (!that.messageWindow) {
            gpii.windows.messages.createMessageWindow(that);
        }
        that.references.push(id);
    }
};

/**
 * Stop listening for window messages. Destroy the message window if no other instance is using it.
 *
 * @param that {Component} The gpii.windows.messages instance.
 * @param component {Component} The component that's listening for messages, or null to stop completely.
 */
gpii.windows.messages.stop = function (that, component) {
    if (component) {
        var id = component.id;
        var index = that.references.indexOf(id);
        if (index > -1) {
            that.references.splice(index, 1);
        }
    } else {
        that.references = [];
    }

    if (that.references.length === 0) {
        gpii.windows.messages.destroyMessageWindow(that);
    }
};

/**
 * Gets the handle of the message window (hWnd).
 *
 * @param that {Component} The gpii.windows.messages instance.
 * @return {number} The handle, or 0 if there's no window.
 */
gpii.windows.messages.getWindowHandle = function (that) {
    return that.messageWindow || 0;
};

/**
 * The window procedure for the window. Fires the event, then passes the message to the default window procedure.
 *
 * WindowProc: https://msdn.microsoft.com/library/ms633573
 *
 * @param that {Component} The gpii.windows.messages instance.
 * @param hwnd {number} Window handle.
 * @param msg {number} The window message.
 * @param wParam {number} Message parameter.
 * @param lParam {number} Message parameter.
 */
gpii.windows.messages.windowProc = function (that, hwnd, msg, wParam, lParam) {
    that.events.onMessage.fire(hwnd, msg, wParam, lParam);
    return windows.user32.DefWindowProcW(hwnd, msg, wParam, lParam);
};

/**
 * Polls for messages - only required if not running under electron.
 *
 * @param that {Component} The gpii.windows.messages instance.
 */
gpii.windows.messages.messagePump = function (that) {

    var loop = function () {
        // sizeof(MSG) = 48 on 64-bit, 28 on 32-bit.
        var msg = Buffer.alloc(process.arch === "x64" ? 48 : 28);

        // Unable to use GetMessage because it blocks, and can't call via .async because it needs to be in the same
        // thread as the window.
        while (gpii.windows.user32.PeekMessageW(msg, 0, 0, 0, 1)) {
            gpii.windows.user32.TranslateMessage(msg);
            gpii.windows.user32.DispatchMessageW(msg);
        }

        if (that.messageWindow) {
            setTimeout(loop, 300);
        }
    };
    loop();
};

/**
 * Creates a window whose only purpose is to receive messages.
 *
 * The window has no visibility - it just exists.
 *
 * @param that {Component} The gpii.windows.messages instance.
 */
gpii.windows.messages.createMessageWindow = function (that) {
    if (that.messageWindow) {
        fluid.fail("Message window already created.");
    }

    var className = windows.stringToWideChar(that.windowClassname);

    // Window class only needs to be registered once.
    if (!gpii.windows.messages.windowProcPointer) {
        // Create the Window Class for the window
        var cls = new windows.WNDCLASSW();
        cls.ref().fill(0);

        cls.lpszClassName = className;

        // Create a pointer to the window procedure function.
        cls.lpfnWndProc = ffi.Callback(gpii.windows.types.HANDLE,
            [gpii.windows.types.HANDLE, gpii.windows.types.UINT, gpii.windows.types.UINT, gpii.windows.types.PVOID],
            function (hwnd, msg, wParam, lParam) {
                return gpii.windows.messages.windowProc(that, hwnd, msg, wParam, lParam);
            });

        // Keep a reference to the function pointer, otherwise the GC will free it.
        gpii.windows.messages.windowProcPointer = function () {
            cls.lpfnWndProc();
        };

        var result = gpii.windows.user32.RegisterClassW(cls.ref());
        if (!result) {
            fluid.fail("RegisterClass failed");
        }
    }

    // Start the message loop
    if (!process.versions.electron) {
        that.messageWindow = 1; // make the loop think there's already a window.
        gpii.windows.messages.messagePump(that);
    }

    // Create the Window.
    that.messageWindow =
        gpii.windows.user32.CreateWindowExW(0, className, className, 0, 0, 0, 0, 0, 0, 0, 0, 0);

    if (!that.messageWindow) {
        fluid.fail("CreateWindowEx failed");
    }
};

/**
 * Destroys the window created by createMessageWindow.
 *
 * @param that {Component} The gpii.windows.messages instance.
 * @return {boolean} false on failure.
 */
gpii.windows.messages.destroyMessageWindow = function (that) {
    var success = true;
    if (that.messageWindow) {
        // Destroy the window.
        success = !!windows.user32.DestroyWindow(that.messageWindow);
        that.messageWindow = null;
        that.references = [];
    }
    return success;
};

gpii.windows.messages();