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
Example
Permissions
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.
1
interface WindowInfo {
2
    title: string;    // The current title of the window
3
    path: string;     // The name of the process running the window
4
    pid: number;      // The process id of the window
5
    x: number;        // The current x position of the window on the screen
6
    y: number;        // The current y position
7
    width: number;    // The current width of a window
8
    height: number;   // The current height of a window
9
}
10
​
11
type WindowActionBlur = 'blur';                 // Window loses focus
12
type WindowActionClosed = 'close';              // Window is closed (can also be a tab closing, or losing focus)
13
type WindowActionFocused = 'focus';             // Window gains focus
14
type WindowActionMoved = 'move';                // Window position is moved (can also be triggered by resize)
15
type WindowActionOpened = 'open';               // Window is opened (can also be a new tab, or a window gaining focus)
16
type WindowActionResize = 'resize';             // Window size is changed
17
type WindowActionTitleChanged = 'titleChange';  // The title of the window has changed
18
​
19
type WindowAction =
20
    | WindowActionBlur
21
    | WindowActionClosed
22
    | WindowActionFocused
23
    | WindowActionMoved
24
    | WindowActionOpened
25
    | WindowActionResize
26
    | WindowActionTitleChanged;
27
​
28
interface WindowEvent {
29
    info: WindowInfo;
30
    action: WindowAction;
31
}
Copied!
activeWindow
Get WindowInfo about the currently focused window when the function is called.
1
import { window } from '@oliveai/ldk';
2
​
3
// Retrieves information about the currently focused window.
4
window.activeWindow().then((windowInfo) => {
5
    console.log(JSON.stringify(windowInfo));
6
});
Copied!
all
Get a WindowInfo[] list of all windows on a system.
1
import { window } from '@oliveai/ldk';
2
​
3
// Retrieves information about all windows, whether they are focused or not
4
window.all().then((allWindows) => {
5
    console.log(JSON.stringify(allWindows[0]));
6
});
Copied!
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.
1
import { window } from '@oliveai/ldk';
2
​
3
let activeWindowStream: Cancellable;
4
​
5
window.listenActiveWindow((windowInfo) => {
6
    if (windowInfo) {
7
        console.debug(`This window become active: title=${windowInfo.title}`);
8
        activeWindowStream.cancel();
9
    }
10
}).then((cancellable: Cancellable) => {
11
    activeWindowStream = cancellable;
12
});
Copied!
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.
1
import { window } from '@oliveai/ldk';
2
​
3
let listenAllStream: Cancellable;
4
​
5
window.listenAll((windowEvent) => {
6
    if (windowEvent.action === 'move') {
7
        console.debug(`This window has moved: title=${windowEvent.info.title}`);
8
        listenAllStream.cancel();
9
    }
10
}).then((cancellable: Cancellable) => {
11
    listenAllStream = cancellable;
12
});
Copied!
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.
1
import { whisper, window } from '@oliveai/ldk';
2
​
3
const lookingFor = 'A very important tab';
4
​
5
// Any time that focus changes, the callback method will be called
6
const callback = (windowInfo) => {
7
    // If the windowInfo matches what we're looking for, we open a whisper
8
    if (windowInfo.title === lookingFor) {
9
        whisper.create({
10
            // Some really cool whisper
11
        });
12
    }
13
};
14
​
15
window.listenActiveWindow(callback);
Copied!
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:
1
import { window } from '@oliveai/ldk';
2
​
3
const lookingFor = 'Google Chrome';
4
​
5
// Any time any window action occurs, call this function
6
const callback = (windowEvent) => {
7
    // If the user is using Chrome and they click on a different window...
8
    if (windowEvent.info.path === lookingFor && windowEvent.action === 'blur') {
9
        // Do something cool
10
    }
11
};
12
​
13
window.listenAll(callback);
Copied!
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.
​
1
...
2
"ldk": {
3
  "permissions": {
4
    "window": {},
5
    ...
6
  }
7
},
8
...
Copied!

JSX Whispers

Next - Release Notes

What's New

Last modified 3mo ago

Copy link