Tutorial: View.EventEmitter

View.EventEmitter

When an instance of fin.View is created, it inherits an EventEmitter with the below methods so that it is possible to listen to OpenFin events. The below methods are asynchronous as they must cross process boundaries and setup the listener in the browser process. When the EventEmitter receives an event from the browser process and emits on the renderer, all of the functions attached to that specific event are called synchronously. Any values returned by the called listeners are ignored and will be discarded. If the execution context of the window is destroyed by page navigation or reload, any events that have been setup in that context will be destroyed. It is important to keep in mind that when an ordinary listener function is called, the standard this keyword is intentionally set to reference the EventEmitter instance to which the listener is attached. It is possible to use ES6 Arrow Functions as listeners, however, when doing so, the this keyword will no longer reference the EventEmitter instance.

addListener(event, listener)

Adds a listener to the end of the listeners array for the specified event.

const view = await fin.View.getCurrent();

view.addListener("hidden", function(event) {
    console.log("The View was hidden.");
});

on(event, listener)

Adds a listener to the end of the listeners array for the specified event.

const view = await fin.View.getCurrent();

view.on("hidden", function(event) {
    console.log("The View was hidden.");
});

once(event, listener)

Adds a one time listener for the event. The listener is invoked only the first time the event is fired, after which it is removed.

const view = await fin.View.getCurrent();

view.once("hidden", function(event) {
    console.log("The View was hidden.");
});

prependListener(event, listener)

Adds a listener to the beginning of the listeners array for the specified event.

const view = await fin.View.getCurrent();

view.prependListener("hidden", function(event) {
    console.log("The View was hidden.");
});

prependOnceListener(event, listener)

Adds a one time listener for the event. The listener is invoked only the first time the event is fired, after which it is removed. The listener is added to the beginning of the listeners array.

const view = await fin.View.getCurrent();

view.prependListener("hidden", function(event) {
    console.log("The View was hidden.");
});

removeListener(event, listener)

Remove a listener from the listener array for the specified event. Caution: Calling this method changes the array indices in the listener array behind the listener.

const view = await fin.View.getCurrent();
const callback = function(event) {
  console.log('The View was hidden');
};

view.on('hidden', callback);
view.removeListener("hidden", callback);

removeAllListeners([event])

Removes all listeners, or those of the specified event.

const view = await fin.View.getCurrent();
view.removeAllListeners("hidden");

Supported View event types

  • blurred
  • certificate-error
  • certificate-selection-shown
  • crashed
  • created
  • destroyed
  • did-change-theme-color
  • did-finish-load
  • file-download-completed
  • file-download-progress
  • file-download-started
  • found-in-page
  • focused
  • hidden
  • host-context-changed
  • hotkey
  • navigation-rejected
  • options-changed
  • page-favicon-updated
  • page-title-updated
  • resource-load-failed
  • resource-response-received
  • shown
  • target-changed
  • url-changed
  • will-redirect

View Events

blurred

Generated when a view loses focus.

//This response has the following shape:
{
    name: "ViewName" // the name of the View
    topic: "view",
    type: "blurred",
    uuid: "454C7F31-A915-4EA2-83F2-CFA655453C52" // (string) the UUID of the Application the View belongs to.
}

certificate-error

Generated when navigating to a URL that fails certificate validation.

//This response has the following shape:
{
    name: "ViewName", //the name of the View
    topic: "view",
    type: "certificate-error",
    uuid: "AppUUID", //(string) the UUID of the application the window belongs to.
    error: "net::ERR_CERT_DATE_INVALID", //error detail
    url: "https://expired.badssl.com/", //url with the invalid certificate
    certificate: {}, //certificate object
}

certificate-selection-shown

Generated when the certificate selection dialog is shown.

//This response has the following shape:
{
    name: "ViewName", //the name of the View
    topic: "view",
    type: "certificate-selection-shown",
    uuid: "AppUUID", //(string) the UUID of the application the view belongs to.
    url: "https://expired.badssl.com/", //url requesting certificate
    certificates: [], //certificate list
}

crashed

Generated when a view has crashed.

//This response has the following shape:
{
    name: "ViewName" // the name of the View
    reason: "killed", //possible values:
                      //  "normal-termination"    zero exit status
                      //  "abnormal-termination"  non-zero exit status
                      //  "killed"                e.g. SIGKILL or task manager kill
                      //  "crashed"               e.g. Segmentation fault
                      //  "still-running"         child hasn't exited yet
                      //  "launch-failed"         child process never launched
                      //  "out-of-memory"         process died due to oom
    topic: "view",
    type: "crashed",
    uuid: "454C7F31-A915-4EA2-83F2-CFA655453C52" // (string) the UUID of the Application the View belongs to.
}

created

Generated when a View is created.

//This response has the following shape:
{
    name: "ViewName" // the name of the View
    target: {uuid: '454C7F31-A915-4EA2-83F2-CFA655453C52', name: 'windowName'}, // the Window this View is attached to
    topic: "view",
    type: "created",
    uuid: "454C7F31-A915-4EA2-83F2-CFA655453C52" // (string) the UUID of the Application the View belongs to.
}

destroyed

Generated when a View is destroyed.

//This response has the following shape:
{
    name: "ViewName" // the name of the View
    target: {uuid: '454C7F31-A915-4EA2-83F2-CFA655453C52', name: 'windowName'}, // the Window this View was attached to
    topic: "view",
    type: "destroyed",
    uuid: "454C7F31-A915-4EA2-83F2-CFA655453C52" // (string) the UUID of the Application the View belongs to.
}

did-change-theme-color

Emitted when a page's theme color changes. This is usually due to encountering a meta tag: 

{
    color: "#FF0000",
    name: "ViewName" // the name of the View
    target: {uuid: '454C7F31-A915-4EA2-83F2-CFA655453C52', name: 'windowName'}, // the Window this View is attached to
    topic: "view",
    type: "did-change-theme-color",
    uuid: "454C7F31-A915-4EA2-83F2-CFA655453C52" // (string) the UUID of the Application the View belongs to.
}

did-finish-load

Emitted when the navigation is done, i.e. the spinner of the tab will stop spinning, and the onload event is dispatched.

{
    topic: "view",
    type: "did-finish-load",
    uuid: "AppUUID" //(string) the UUID of the application the window belongs to.
}

file-download-completed

Generated when a file download has completed.

//This response has the following shape:
{
    type: "file-download-completed",
    state: "started" | "completed" | "cancelled" |  "interrupted" | "paused"
    url: "https://download-location/file.pdf", //the url where the file is being downloaded from.
    mimeType: "application/pdf", //the file mime type.
    fileName: "file(1).pdf", //the name of the file as chosen by the user.
    originalFileName: "file.pdf", //the original name of the file.
    totalBytes: 347110, //the total size in bytes of the file.
    startTime: 1537994725.335115, //the number of seconds since the UNIX epoch when the download was started.
    contentDisposition: "", //the Content-Disposition field from the response header.
    lastModifiedTime: "Fri, 24 Aug 2018 03:12:32 GMT", //the Last-Modified header value.
    eTag: `W"54be6-16569eb4bad"`, //the ETag header value.
    downloadedBytes: 347110, //the downloaded bytes of the download item.
    topic: "view",
    uuid: "AppUUID", //(string) the UUID of the application the View belongs to.
    name: "viewOne" //the name of the View.
}

file-download-progress

Generated during file download progress.

//This response has the following shape:
{
    type: "file-download-progress",
    state: "started" | "completed" | "cancelled" |  "interrupted" | "paused"
    url: "https://download-location/file.pdf", //the url where the file is being downloaded from.
    mimeType: "application/pdf", //the file mime type.
    fileName: null, //the name of the file as chosen by the user, can be null for progress events.
    originalFileName: "file.pdf", //the original name of the file.
    totalBytes: 347110, //the total size in bytes of the file.
    startTime: 1537994725.335115, //the number of seconds since the UNIX epoch when the download was started.
    contentDisposition: "", //the Content-Disposition field from the response header.
    lastModifiedTime: "Fri, 24 Aug 2018 03:12:32 GMT", //the Last-Modified header value.
    eTag: `W"54be6-16569eb4bad"`, //the ETag header value.
    downloadedBytes: 23820, //the downloaded bytes of the download item.
    topic: "view",
    uuid: "AppUUID", //(string) the UUID of the application the View belongs to.
    name: "viewOne" //the name of the View.
}

file-download-started

Generated when a file download has started.

//This response has the following shape:
{
    type: "file-download-started",
    state: "started" | "completed" | "cancelled" |  "interrupted" | "paused"
    url: "https://download-location/file.pdf", //the url where the file is being downloaded from.
    mimeType: "application/pdf", //the file mime type.
    fileName: null, //the name of the file as chosen by the user, will be null for started events
    originalFileName: "file.pdf", //the original name of the file.
    totalBytes: 347110, //the total size in bytes of the file.
    startTime: 1537994725.335115, //the number of seconds since the UNIX epoch when the download was started.
    contentDisposition: "", //the Content-Disposition field from the response header.
    lastModifiedTime: "Fri, 24 Aug 2018 03:12:32 GMT", //the Last-Modified header value.
    eTag: `W"54be6-16569eb4bad"`, //the ETag header value.
    downloadedBytes: 23820, //the downloaded bytes of the download item.
    topic: "view",
    uuid: "AppUUID", //(string) the UUID of the application the View belongs to.
    name: "viewOne" //the name of the View.
}

found-in-page

Generated when a result is available when calling View.findInPage

//This response has the following shape:
{
    name: "ViewName", //the name of the view
    result: {
        requestId: 1, // request id returned by the findInPage call.
        activeMatchOrdinal: 2, // Position of the active match.
        matches: 5, // Number of Matches.
        selectionArea: {
            height: 17,
            width: 10,
            x: 124,
            y: 173
        }, // Rectangle - Coordinates of first match region.
        finalUpdate: true
    }, // Event details,
    topic: 'view',
    type: "found-in-page",
    uuid: "AppUUID", //(string) the UUID of the application the view belongs to.
}

focused

Generated when a view gains focus.

//This response has the following shape:
{
    name: "ViewName" // the name of the View
    topic: "view",
    type: "focused",
    uuid: "454C7F31-A915-4EA2-83F2-CFA655453C52" // (string) the UUID of the Application the View belongs to.
}

hidden

Generated when a View is hidden.

//This response has the following shape:
{
    name: "ViewName" // the name of the View
    target: {uuid: '454C7F31-A915-4EA2-83F2-CFA655453C52', name: 'windowName'}, // the Window this View is attached to
    topic: "view",
    type: "hidden",
    uuid: "454C7F31-A915-4EA2-83F2-CFA655453C52" // (string) the UUID of the Application the View belongs to.
}

host-context-changed

Generated when the context of a View's host window changes, either due to a call to Platform.setWindowContext, or because the View has moved to a new window. Only available on Views in a Platform.

//This response has the following shape:
{
    topic: "view",
    type: "host-context-changed",
    uuid: "appUuid",
    name: "viewName",
    context: {
        // context can be any shape
    },
    reason: "updated", // possible reasons are "reparented" or "updated"
}

hotkey

Generated when a keyboard shortcut defined in the hotkeys array in View options is pressed inside the view. For reference on keyboard event properties see KeyboardEvent.

//This response has the following shape:
{
    name: "ViewName", // the name of the View
    target: {uuid: '454C7F31-A915-4EA2-83F2-CFA655453C52', name: 'windowName'}, // the Window this View is attached to
    topic: "view",
    type: "hotkey",
    uuid: "454C7F31-A915-4EA2-83F2-CFA655453C52", // (string) the UUID of the Application the View belongs to.
    altKey: false,
    code: "KeyT",
    ctrlKey: true,
    inputType: "keyUp", // "keyUp" or "keyDown"
    key: "t",
    metaKey: false,
    repeat: false,
    shiftKey: false
}

navigation-rejected

Generated when view navigation is rejected as per contentNavigation whitelist/blacklist rules.

{
    name: "view1", //the name of the view.
    topic: "view",
    type: "navigation-rejected",
    url: "http://blocked-content.url",
    uuid: "AppUUID" // (string) the UUID of the Application the View belongs to.
}

options-changed

Generated when a view's options are updated.

{
    diff: { autoResize: { // The diff shows which options were updated, and what their old and new values are
        oldVal: {horizontal: false, width: false, vertical: false, height: false},
        newVal: {horizontal: true, width: true},
    },
    invalidOptions: ["notARealOption"], // Array of invalid options
    name: "view1", //the name of the view.
    options: { // The updated options object.
        autoResize: {width: true, height: false, horizontal: false, vertical: false},
        backgroundColor: "#FFF"
        // ...
    },
    topic: "view",
    type: "options-changed",
    uuid: "AppUUID" // (string) the UUID of the Application the View belongs to.
}

page-favicon-updated

Emitted when page receives favicon urls.

{
    favicons: [
        "http://www.openfin.co/favicon.ico"
    ],
    name: "ViewName" // the name of the View
    target: {uuid: '454C7F31-A915-4EA2-83F2-CFA655453C52', name: 'windowName'}, // the Window this View is attached to
    topic: "view",
    type: "page-favicon-updated",
    uuid: "454C7F31-A915-4EA2-83F2-CFA655453C52" // (string) the UUID of the Application the View belongs to.
}

page-title-updated

Fired when page title is set during navigation. explicitSet is false when title is synthesized from file url.

{
    explicitSet: true, // false when title is synthesized from file url.
    name: "ViewName" // the name of the View
    target: {uuid: '454C7F31-A915-4EA2-83F2-CFA655453C52', name: 'windowName'}, // the Window this View is attached to
    title: "testTitle",
    topic: "view",
    type: "page-title-updated",
    uuid: "454C7F31-A915-4EA2-83F2-CFA655453C52" // (string) the UUID of the Application the View belongs to.
}

resource-load-failed

Generated when an HTTP load was cancelled or failed.

{
    name: "ViewName",
    target: {uuid: '454C7F31-A915-4EA2-83F2-CFA655453C52', name: 'windowName'}, // the Window this View is attached to
    topic: "view",
    type: "resource-response-failed",
    uuid: "454C7F31-A915-4EA2-83F2-CFA655453C52", // (string) the UUID of the Application the View belongs to.
    errorCode: -102,                              //the Chromium error code
    errorDescription: "",
    validatedURL: "http://bad-domain/dead-link.html",
    isMainFrame: true
}

resource-response-received

Generated when an HTTP resource request has received response details.

{
    name: "ViewName",
    target: {uuid: '454C7F31-A915-4EA2-83F2-CFA655453C52', name: 'windowName'}, // the Window this View is attached to
    topic: "view",
    type: "resource-response-received",
    uuid: "454C7F31-A915-4EA2-83F2-CFA655453C52", // (string) the UUID of the Application the View belongs to.
    status: false,
    newUrl: "https://www.google.com/?gws_rd=ssl", //the URL of the responded resource
    originalUrl: "http://www.google.com/",        //the requested URL
    httpResponseCode: 200,
    requestMethod: "GET",
    referrer: "",                                 //the URL of the referrer
    headers: {                                    //HTTP response headers
        "cache-control": [
            "private, max-age=0"
        ],
        "content-type": [
            "text/html; charset=UTF-8"
        ]
    },
    resourceType: "mainFrame"                     //"mainFrame", "subFrame",
                                                  //"styleSheet", "script", "image",
                                                  //"object", "xhr", or "other"
}

shown

Generated when a View is shown. This event will fire during creation of a View.

//This response has the following shape:
{
    name: "ViewName" // the name of the View
    target: {uuid: '454C7F31-A915-4EA2-83F2-CFA655453C52', name: 'windowName'}, // the Window this View is attached to
    topic: "view",
    type: "shown",
    uuid: "454C7F31-A915-4EA2-83F2-CFA655453C52" // (string) the UUID of the Application the View belongs to.
}

target-changed

Generated when a View changes its Window target. This event will fire during creation of a View. In that case, previousTarget identity will be the same as target identity.

//This response has the following shape:
{
    name: "ViewName" // the name of the View
    previousTarget: {uuid: '454C7F31-A915-4EA2-83F2-CFA655453C52', name: 'previousWindowName'}, // the Window this View was previously attached to
    target: {uuid: '454C7F31-A915-4EA2-83F2-CFA655453C52', name: 'windowName'}, // the Window this View will attach to
    topic: "view",
    type: "target-changed",
    uuid: "454C7F31-A915-4EA2-83F2-CFA655453C52" // (string) the UUID of the Application the View belongs to.
}

url-changed

Generated when navigation or redirect is completed. Also emitted for in-page navigations, examples of this occurring are when anchor links are clicked or when the DOM hashchange event is triggered, indicated by isInPage=true. Note that navigating to a url with an anchor in it like http://openfin.co/#my-inpage-anchor will fire 2 events indicating the original navigation (isInPage=false) and then the in-page navigation event (isInPage=true).

// top-level navigation/redirect
{
    url: "http://openfin.co",
    isInPage: false,
    httpResponseCode: 200,
    httpStatusText: "",
    topic: "view",
    type: "url-changed",
    uuid: "AppUUID" //(string) the UUID of the application the window belongs to.
}
// in-page navigation anchor links or window.location.hash changes (hashchange event)
{
    url: "http://openfin.co/#my-inpage-anchor",
    isInPage: true,
    topic: "view",
    type: "url-changed",
    uuid: "AppUUID" //(string) the UUID of the application the window belongs to.
}

will-redirect

Generated when view is being redirected as per contentRedirect whitelist/blacklist rules.

{
    blocked: true,
    isInPlace: false,
    name: "ViewName", // the name of the View
    topic: "view",
    type: "will-redirect",
    url: "http://blocked-content.url",
    uuid: "AppUUID" // (string) the UUID of the application the View belongs to.
}