Window

The Window Aptitude provides the ability to obtain information about windows on a user's desktop (position, name, etc.) as well as listen to window events (gaining focus, losing focus, etc.).

API

Each call to the Window Aptitude is providing you with one of two types of information. It either returns WindowInfo or a WindowEvent. Let's take a moment to define these two things.

interface WindowInfo {
    title: string;    // The current title of the window
    path: string;     // The name of the process running the window
    pid: number;      // The process id of the window
    x: number;        // The current x position of the window on the screen
    y: number;        // The current y position
    width: number;    // The current width of a window
    height: number;   // The current height of a window
}

type WindowActionBlur = 'blur';                 // Window loses focus
type WindowActionClosed = 'close';              // Window is closed (can also be a tab closing, or losing focus)
type WindowActionFocused = 'focus';             // Window gains focus
type WindowActionMoved = 'move';                // Window position is moved (can also be triggered by resize)
type WindowActionOpened = 'open';               // Window is opened (can also be a new tab, or a window gaining focus)
type WindowActionResize = 'resize';             // Window size is changed
type WindowActionTitleChanged = 'titleChange';  // The title of the window has changed

type WindowAction =
    | WindowActionBlur
    | WindowActionClosed
    | WindowActionFocused
    | WindowActionMoved
    | WindowActionOpened
    | WindowActionResize
    | WindowActionTitleChanged;

interface WindowEvent {
    info: WindowInfo;
    action: WindowAction;
}

activeWindow

Get WindowInfo about the currently focused window when the function is called.

import { window } from '@oliveai/ldk';

// Retrieves information about the currently focused window.
window.activeWindow().then((windowInfo) => {
    console.log(JSON.stringify(windowInfo));
});

all

Get a WindowInfo[] list of all windows on a system.

import { window } from '@oliveai/ldk';

// Retrieves information about all windows, whether they are focused or not
window.all().then((allWindows) => {
    console.log(JSON.stringify(allWindows[0]));
});

listenActiveWindow

Triggers whenever focus is given to a different window. Takes a callback function as an argument, which sends a WindowInfo whenever called. A promise is triggered after setting the listener that provides access to a Cancellable stream, so that you can turn off the listener.

import { window } from '@oliveai/ldk';

let activeWindowStream: Cancellable;

window.listenActiveWindow((windowInfo) => {
    if (windowInfo) {
        console.debug(`This window become active: title=${windowInfo.title}`);
        activeWindowStream.cancel();
    }
}).then((cancellable: Cancellable) => {
    activeWindowStream = cancellable;
});

listenAll

Receive a notification whenever a window is opened, closed, focused, unfocused, moved, resized, or its title changes as a WindowEvent. A window that is opened with focus will generate an Opened event and a Focused event.

import { window } from '@oliveai/ldk';

let listenAllStream: Cancellable;

window.listenAll((windowEvent) => {
    if (windowEvent.action === 'move') {
        console.debug(`This window has moved: title=${windowEvent.info.title}`);
        listenAllStream.cancel();
    }
}).then((cancellable: Cancellable) => {
    listenAllStream = cancellable;
});

Example

Let's say that you want to trigger a Whisper if the user focuses on a window with a specific title. In this case, let's say that it's the title of a browser tab.

If you were to use listenActiveWindow(), the callback method you provided would be triggered any time that a new window receives focus, which might look like this.

import { whisper, window } from '@oliveai/ldk';

const lookingFor = 'A very important tab';

// Any time that focus changes, the callback method will be called
const callback = (windowInfo) => {
    // If the windowInfo matches what we're looking for, we open a whisper
    if (windowInfo.title === lookingFor) {
        whisper.create({
            // Some really cool whisper
        });
    }
};

window.listenActiveWindow(callback);

But, what if you wanted something to trigger when a window is something other than focused? That's where listenAll() comes into play! Not only can it give you the same WindowInfo that something like listenActiveWindow() provides, it also tells you which WindowAction (mentioned above) occurred.

So, let's say you wanted to trigger something when a user stops interacting with a specific program, like say Google Chrome. It would look something like this:

import { window } from '@oliveai/ldk';

const lookingFor = 'Google Chrome';

// Any time any window action occurs, call this function
const callback = (windowEvent) => {
    // If the user is using Chrome and they click on a different window...
    if (windowEvent.info.path === lookingFor && windowEvent.action === 'blur') {
        // Do something cool
    }
};

window.listenAll(callback);

Permissions

To use the Window Aptitude, simply set the following permissions in your package.json under the ldk object.

Please see our Permissions page for more information.

...
"ldk": {
  "permissions": {
    "window": {},
    ...
  }
},
...