electron-tween v1.0.2

"electron-tween"

"electron-tween" is a Node Library specifically created to add tween functionality to Electron BrowserWindows.

Coming from a need at work to have more dynamic "native" window animations and nothing else being available, I decided to pull together my own tween library primarily for Electron.

Installation

To install "electron-tween", use npm. The preferred method is to install "electron-tween" as a dependency, alongside Electron being a development dependency.

npm install --save electron-tween

Usage

As a TWEEN library, "electron-tween" has been written so that as little items from Electron are used. To do so, all functionality of "electron-tween" relies upon being given a BrowserWindow object. Although this can be done through using Electrons remote module, it is recommended to make use of IPC events instead to access windows/this library from the main process.

The current functionality includes:

• Fade: Fades a BrowserWindow from a given opacity to another.
• FadeIn: Fades a BrowserWindow IN to full opacity.
• FadeOut: Fades a BrowserWindow OUT to full transparency.
• Resize: Resizes a BrowserWindow to given size.
• Move: Moves a BrowserWindow to given position.

Fade

With any BrowserWindow instance, you could fade a window from it's current opacity to another using:

const { BrowserWindow } = require('electron');
const { ElectronTWEEN } = require('electron-tween');
let browserWin = BrowserWindow.getFocusedWindow();

ElectronTWEEN.Fade({
    win: browserWin,                    // must set a valid BrowserWindow
    from: browserWin.getOpacity(),      // retrieve the current windows opacity
    to: 0.86,                           // change to this opacity
    time: 500,                          // time it takes to transition
    easing: "QUAD_IN_OUT",              // type of easing
    start: true,                        // start immediately (otherwise returned object can be started manually
    onComplete: () => { /* ... */ }     // callback function to call when transition is complete
});

Note: It is also good to note that the BrowserWindow used here could come from the Main or Renderer process. However it is advised to run all fade methods from the Main process and keep the remote module disabled.

FadeIn

A wrapper function for Fade to fade a given BrowserWindow to full opacity (alpha = 1).

const { BrowserWindow } = require('electron');
const { ElectronTWEEN } = require('electron-tween');
let browserWin = BrowserWindow.getFocusedWindow();

ElectronTWEEN.FadeIn({
    win: browserWin,                    // must set a valid BrowserWindow
    time: 500,                          // time it takes to transition
    easing: "LINEAR",                   // type of easing
    start: true,                        // start immediately (otherwise returned object can be started manually
    onComplete: () => { /* ... */ }     // callback function to call when transition is complete
});

FadeOut

A wrapper function for Fade to fade a given BrowserWindow to full transparency (alpha = 0).

const { BrowserWindow } = require('electron');
const { ElectronTWEEN } = require('electron-tween');
let browserWin = BrowserWindow.getFocusedWindow();

ElectronTWEEN.FadeOut({
    win: browserWin,                    // must set a valid BrowserWindow
    time: 500,                          // time it takes to transition
    easing: "CIRC_IN_OUT",              // type of easing
    start: true,                        // start immediately (otherwise returned object can be started manually
    onComplete: () => { /* ... */ }     // callback function to call when transition is complete
});

Resize

Resize() utilises the BrowserWindow.setBounds() method to change the BrowserWindows size. This was chosen as the native DOM window object can only resize a window to a set limit, and used over the setSize() method as if a BrowserWindow is NOT resizeable then only setBounds() will work. This method can be used as:

const { ElectronTWEEN } = require('electron-tween');

ElectronTWEEN.Resize({
    from: { x: 1024, y: 768 },  // if not set uses current BrowserWindow size, otherwise JUMPS to this size
    to: { x: 640, y: 480 },     // must provide an XY object such as this
    time: 1000,                 // transition time
    easing: 'LINEAR',           // type of easing
    start: true,                // automatically start
    onComplete: () => { }       // callback for tween completion
});

Move

Move() utilises the BrowserWindow.setBounds() method to change the BrowserWindows position. This method can be used as:

const { ElectronTWEEN } = require('electron-tween');

ElectronTWEEN.Move({
    from: { x: 0, y: 0 },       // if not set uses current BrowserWindow position, otherwise JUMPS to a position
    to: { x: 250, y: 250 },     // must provide an XY object such as this
    time: 1000,                 // transition time
    easing: 'EXPO_IN',           // type of easing
    start: true,                // automatically start
    onComplete: () => { }       // callback for tween completion
});

Easing Types

There are multiple easing types available. These have been sourced from easings.net which has helpful displays and information for web based easings.

• Linear -> LINEAR
• Quadratic -> QUAD
• Cubic -> CUBIC
• Quartic -> QUART
• Quintic -> QUINT
• Exponential -> EXPO
• Sine -> SINE
• Circular -> CIRC
• Back -> BACK
• Elastic -> ELASTIC
• Bounce -> BOUNCE

Alongside this, qualifiers of IN, OUT and IN_OUT are to be used to generate the full range of easing types:

These should be reference as:

let easing = "QUART_IN";
easing = "BOUNCE_IN_OUT";
easing = "LINEAR"; // the only exception

Promise Example

Tween's can also be promise chained by utilising the onComplete() input property. This allows for an ease of chaining tween's after each other. In future, this will be expanded on to allow for tween chaining regardless of utilizing built-in promises (however doing so does open up more versatility in terms of asynchronicity).

const { ElectronTWEEN } = require('electron-tween');
let browserWin = BrowserWindow.getFocusedWindow();

new Promise(resolve => {
    ElectronTWEEN.FadeOut({
        win: browserWin,
        onComplete: () => {
            resolve();
        }
    });
}).then(() => {
    return new Promise(resolve => {
        ElectronTWEEN.FadeIn({
            win: browserWin,
            onComplete: () => {
                resolve();
            }
        });
    });
}).then(() => {
    // continue as desired
}).catch(err => {
    // error handling
});

IPC Method

Although using Electron's remote module is a quick way to get access to BrowserWindows in the Renderer Process, it is recommended to actually run all of "electron-tween" methods from the Main Process instead. This is because the remote module is considered harmful, and has is a security liability waiting to occur.

As such the below method is what would be considered conventional when using this library.

renderer.js

// other code...
const { ipcRenderer } = require('electron');

ipcRenderer.send('tween-window', {
    // your options should go here
});

main.js

// previous code...
const { ipcMain, BrowserWindow } = require('electron');
const { ElectronTWEEN } = require('electron-tween');

ipcMain.on('tween-window', (event, opts) => {
    const windowToTween = BrowserWindow.getFocusedWindow();
    ElectronTWEEN.Resize({
        win: windowToTween, // presumably given ElectronTWEEN the appropriate window to be tweened
        ...opts // destructuring options, otherwise add as desired
    });
});

Demo Example

To try a demo example, run the following:

git clone https://github.com/rroessler/electron-tween # clone the project repo
npm install # ensure all Electron dependencies are included (and spectre.css styling)
npm start # and run electron

License

MIT