Repository: trodi/electron-splashscreen
Branch: master
Commit: 3e688a4e7a82
Files: 17
Total size: 21.7 KB

Directory structure:
gitextract_fci6gxyl/

├── .github/
│   └── ISSUE_TEMPLATE/
│       └── bug_report.md
├── .gitignore
├── .travis.yml
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── api-doc/
│   ├── README.md
│   └── interfaces/
│       ├── config.md
│       └── dynamicsplashscreen.md
├── examples/
│   ├── example-app.html
│   ├── example-dynamic-splashscreen.html
│   ├── example-dynamic.ts
│   └── example.ts
├── index.ts
├── package.json
├── tsconfig.json
└── tslint.json

================================================
FILE CONTENTS
================================================

================================================
FILE: .github/ISSUE_TEMPLATE/bug_report.md
================================================
---
name: Bug report
about: Create a report to help us improve
title: ''
labels: ''
assignees: ''

---

**Describe the bug**

A clear and concise description of what the bug is.

**To Reproduce**

Steps to reproduce the behavior:

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

**Expected behavior**

A clear and concise description of what you expected to happen.

**Screenshots**

If applicable, add screenshots to help explain your problem.

**Desktop (please complete the following information):**

- OS: [e.g. Mac Big Sur 11.2.3]
- Browser [e.g. chrome, safari]
- @trodi/electron-splashscreen version [e.g. 1.0.0]
- Electron version: [e.g., 8.1.1]

**Additional context**

Add any other context about the problem here.


================================================
FILE: .gitignore
================================================
node_modules
*.js
*.d.ts


================================================
FILE: .travis.yml
================================================
language: node_js
node_js:
  - "node"
script: npm run build


================================================
FILE: CONTRIBUTING.md
================================================
# Contributing to electron-splashscreen

- Have an issue? Open an issue. PRs welcome.
- Have a feature request? Open an issue to see if the feature is in scope of the project.

*Please avoid publishing forked versions of this project instead of contributing to it directly!*


================================================
FILE: LICENSE
================================================
MIT License

Copyright (c) 2017 Troy McKinnon

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


================================================
FILE: README.md
================================================
<img src="https://raw.githubusercontent.com/trodi/electron-splashscreen/master/icon.svg?sanitize=true" width="200" height="200" align="right" />

# electron-splashscreen [![Build Status](https://travis-ci.org/trodi/electron-splashscreen.svg)](https://travis-ci.org/trodi/electron-splashscreen)

> *Simple splashscreen for [Electron](http://electron.atom.io) applications.*

Ideally, your application loads instantaneously. However, some applications are larger and/or may be running on a slower machine, causing the load to take longer. If the application is taking a bit to load, `electron-splashscreen` will appear so the user knows the application is loading, but can't interact with a partially loaded application.

`electron-splashscreen` is simple to incorporate, while allowing you the freedom to customize with any look, feel, and functionality.

*No external dependencies.*

<p align="center"><img src="https://raw.githubusercontent.com/trodi/electron-splashscreen/master/demo.gif" width="400"></p>

## Install

```shell
npm install @trodi/electron-splashscreen
```

## Usage

### Typescript Usage (javascript would be similar)

*Example of your Electron browser process.*

```typescript
// import the module
import * as Splashscreen from "@trodi/electron-splashscreen";
const mainOpts: Electron.BrowserWindowConstructorOptions = ...
// configure the splashscreen
const config: Splashscreen.Config = {
    windowOpts: mainOpts;
    templateUrl: `${__dirname}/splash-screen.html`;
    splashScreenOpts: {
        width: 425,
        height: 325,
    },
};
// initialize the splashscreen handling
const main: BrowserWindow = Splashscreen.initSplashScreen(config);
// load your browser window per usual
main.loadURL(`file://index.html`);
```

You can run examples via `npm run example` and `npm run example-dynamic`.

## API

[API Documentation](https://github.com/trodi/electron-splashscreen/blob/master/api-doc/README.md)

## Build

`npm run build`

## Publish

* `npm version <patch|minor|major>`
* `npm publish`
* Commit and push changes to git

## License

[MIT License](LICENSE)


================================================
FILE: api-doc/README.md
================================================
[@trodi/electron-splashscreen - v1.0.0](README.md)

# @trodi/electron-splashscreen - v1.0.0

## Index

### Interfaces

* [Config](interfaces/config.md)
* [DynamicSplashScreen](interfaces/dynamicsplashscreen.md)

### Functions

* [initDynamicSplashScreen](README.md#const-initdynamicsplashscreen)
* [initSplashScreen](README.md#const-initsplashscreen)

## Functions

### `Const` initDynamicSplashScreen

▸ **initDynamicSplashScreen**(`config`: [Config](interfaces/config.md)): *[DynamicSplashScreen](interfaces/dynamicsplashscreen.md)*

Initializes a splashscreen that will show/hide smartly (and handle show/hiding of main window).
Use this function if you need to send/receive info to the splashscreen (e.g., you want to send
IPC messages to the splashscreen to inform the user of the app's loading state).

**Parameters:**

Name | Type | Description |
------ | ------ | ------ |
`config` | [Config](interfaces/config.md) | Configures splashscren |

**Returns:** *[DynamicSplashScreen](interfaces/dynamicsplashscreen.md)*

the main browser window and the created splashscreen

___

### `Const` initSplashScreen

▸ **initSplashScreen**(`config`: [Config](interfaces/config.md)): *BrowserWindow*

Initializes a splashscreen that will show/hide smartly (and handle show/hiding of main window).

**Parameters:**

Name | Type | Description |
------ | ------ | ------ |
`config` | [Config](interfaces/config.md) | Configures splashscren |

**Returns:** *BrowserWindow*

the main browser window ready for loading


================================================
FILE: api-doc/interfaces/config.md
================================================
[@trodi/electron-splashscreen - v1.0.0](../README.md) › [Config](config.md)

# Interface: Config

`electron-splashscreen` config object.

## Hierarchy

* **Config**

## Index

### Properties

* [closeWindow](config.md#optional-closewindow)
* [delay](config.md#optional-delay)
* [minVisible](config.md#optional-minvisible)
* [splashScreenOpts](config.md#splashscreenopts)
* [templateUrl](config.md#templateurl)
* [windowOpts](config.md#windowopts)

## Properties

### `Optional` closeWindow

• **closeWindow**? : *undefined | false | true*

Close window that is loading if splashscreen is closed by user (default: true).

___

### `Optional` delay

• **delay**? : *undefined | number*

Number of ms the window will load before splashscreen appears (default: 500ms).

___

### `Optional` minVisible

• **minVisible**? : *undefined | number*

Minimum ms the splashscreen will be visible (default: 500ms).

___

###  splashScreenOpts

• **splashScreenOpts**: *BrowserWindowConstructorOptions*

Full set of browser window options for the splashscreen. We override key attributes to
make it look & feel like a splashscreen; the rest is up to you!

___

###  templateUrl

• **templateUrl**: *string*

URL to the splashscreen template. This is the path to an `HTML` or `SVG` file.
If you want to simply show a `PNG`, wrap it in an `HTML` file.

___

###  windowOpts

• **windowOpts**: *BrowserWindowConstructorOptions*

Options for the window that is loading and having a splashscreen tied to.


================================================
FILE: api-doc/interfaces/dynamicsplashscreen.md
================================================
[@trodi/electron-splashscreen - v1.0.0](../README.md) › [DynamicSplashScreen](dynamicsplashscreen.md)

# Interface: DynamicSplashScreen

Return object for `initDynamicSplashScreen()`.

## Hierarchy

* **DynamicSplashScreen**

## Index

### Properties

* [main](dynamicsplashscreen.md#main)
* [splashScreen](dynamicsplashscreen.md#splashscreen)

## Properties

###  main

• **main**: *BrowserWindow*

The main browser window ready for loading

___

###  splashScreen

• **splashScreen**: *BrowserWindow*

The splashscreen browser window so you can communicate with splashscreen in more complex use cases.


================================================
FILE: examples/example-app.html
================================================
<!DOCTYPE html>
<meta charset="utf-8">
<html>
    <head></head>
    <body>
        <center>
            <img src="../icon.svg" height="300" width="300"></img>
        </center>
        <center>
            App loaded!
        </center>
    </body>
</html>


================================================
FILE: examples/example-dynamic-splashscreen.html
================================================
<!DOCTYPE html>
<meta charset="utf-8">
<html>
    <head></head>
    <body>
        <center>
            <img src="../icon.svg" width="200" height="200"></img>
        </center>
        <center>
            Loading...<span id="status"></span>
        </center>
    </body>
    <script>
        // Listen for data from browser process and update splashscreen
        var ipcRenderer = require("electron").ipcRenderer;
        ipcRenderer.on("update", function(event, status) {
            document.getElementById("status").innerText = status;
        })
    </script>
</html>


================================================
FILE: examples/example-dynamic.ts
================================================
import { app, BrowserWindow } from "electron";
import * as path from "path";
import * as url from "url";
import * as Splashscreen from "../index";

let window: BrowserWindow;
app.on("ready", () => {
    const windowOptions = {
        width: 500,
        height: 375,
        show: false,
    };
    const ret: Splashscreen.DynamicSplashScreen = Splashscreen.initDynamicSplashScreen({
        windowOpts: windowOptions,
        templateUrl: path.join(__dirname, "example-dynamic-splashscreen.html"),
        delay: 0, // force show immediately to better illustrate example
        splashScreenOpts: {
            height: 500,
            width: 500,
            backgroundColor: "white",
            webPreferences: {
                nodeIntegration: true,
            },
        },
    });
    window = ret.main;
    /** Send information to the splashscreen. */
    const update = (i: number): void => {
        ret.splashScreen.webContents.send("update", i);
        if (i > 0) {
            setTimeout(() => update(i - 1), 500);
        } else {
            // Done sending updates to mock progress while loading window, so
            // go ahead and load the main window.
            window.loadURL(`file://${path.join(__dirname, "example-app.html")}`);
        }
    };
    update(5);
});
app.on("window-all-closed", () => {
    app.quit();
});


================================================
FILE: examples/example.ts
================================================
import { app, BrowserWindow } from "electron";
import * as path from "path";
import * as url from "url";
import * as Splashscreen from "../index";

let window: BrowserWindow;
app.on("ready", () => {
    const windowOptions = {
        width: 500,
        height: 375,
        show: false,
    };
    window = Splashscreen.initSplashScreen({
        windowOpts: windowOptions,
        templateUrl: path.join(__dirname, "..", "icon.svg"),
        delay: 0, // force show immediately since example will load fast
        minVisible: 1500, // show for 1.5s so example is obvious
        splashScreenOpts: {
            height: 500,
            width: 500,
            transparent: true,
        },
    });
    window.loadURL(`file://${path.join(__dirname, "example-app.html")}`);
});
app.on("window-all-closed", () => {
    app.quit();
});


================================================
FILE: index.ts
================================================
/**
 * Module handles configurable splashscreen to show while app is loading.
 */

import { BrowserWindow } from "electron";

/**
 * When splashscreen was shown.
 * @ignore
 */
let splashScreenTimestamp: number = 0;
/**
 * Splashscreen is loaded and ready to show.
 * @ignore
 */
let splashScreenReady = false;
/**
 * Main window has been loading for a min amount of time.
 * @ignore
 */
let slowStartup = false;
/**
 * True when expected work is complete and we've closed splashscreen, else user prematurely closed splashscreen.
 * @ignore
 */
let done = false;
/**
 * Show splashscreen if criteria are met.
 * @ignore
 */
const showSplash = () => {
    if (splashScreen && splashScreenReady && slowStartup) {
        splashScreen.show();
        splashScreenTimestamp = Date.now();
    }
};
/**
 * Close splashscreen / show main screen. Ensure screen is visible for a min amount of time.
 * @ignore
 */
const closeSplashScreen = (main: Electron.BrowserWindow, min: number): void => {
    if (splashScreen) {
        const timeout = min - (Date.now() - splashScreenTimestamp);
        setTimeout(() => {
            done = true;
            if (splashScreen) {
                splashScreen.isDestroyed() || splashScreen.close(); // Avoid `Error: Object has been destroyed` (#19)
                splashScreen = null;
            }
            main.show();
        }, timeout);
    }
};
/** `electron-splashscreen` config object. */
export interface Config {
    /** Options for the window that is loading and having a splashscreen tied to. */
    windowOpts: Electron.BrowserWindowConstructorOptions;
    /**
     * URL to the splashscreen template. This is the path to an `HTML` or `SVG` file.
     * If you want to simply show a `PNG`, wrap it in an `HTML` file.
     */
    templateUrl: string;
    /**
     * Full set of browser window options for the splashscreen. We override key attributes to
     * make it look & feel like a splashscreen; the rest is up to you!
     */
    splashScreenOpts: Electron.BrowserWindowConstructorOptions;
    /** Number of ms the window will load before splashscreen appears (default: 500ms). */
    delay?: number;
    /** Minimum ms the splashscreen will be visible (default: 500ms). */
    minVisible?: number;
    /** Close window that is loading if splashscreen is closed by user (default: true). */
    closeWindow?: boolean;
}
/**
 * The actual splashscreen browser window.
 * @ignore
 */
let splashScreen: Electron.BrowserWindow | null;
/**
 * Initializes a splashscreen that will show/hide smartly (and handle show/hiding of main window).
 * @param config - Configures splashscreen
 * @returns {BrowserWindow} the main browser window ready for loading
 */
export const initSplashScreen = (config: Config): BrowserWindow => {
    const xConfig: Required<Config> = {
        windowOpts: config.windowOpts,
        templateUrl: config.templateUrl,
        splashScreenOpts: config.splashScreenOpts,
        delay: config.delay ?? 500,
        minVisible: config.minVisible ?? 500,
        closeWindow: config.closeWindow ?? true,
    };
    xConfig.splashScreenOpts.frame = false;
    xConfig.splashScreenOpts.center = true;
    xConfig.splashScreenOpts.show = false;
    xConfig.windowOpts.show = false;
    const window = new BrowserWindow(xConfig.windowOpts);
    splashScreen = new BrowserWindow(xConfig.splashScreenOpts);
    splashScreen.loadURL(`file://${xConfig.templateUrl}`);
    xConfig.closeWindow && splashScreen.on("close", () => {
        if (window) {
            done || window.isDestroyed() || window.close(); // Avoid `Error: Object has been destroyed` (#25)
        }
    });
    // Splashscreen is fully loaded and ready to view.
    splashScreen.webContents.on("did-finish-load", () => {
        splashScreenReady = true;
        showSplash();
    });
    // Startup is taking enough time to show a splashscreen.
    setTimeout(() => {
        slowStartup = true;
        showSplash();
    }, xConfig.delay);
    window.webContents.on("did-finish-load", (): void => {
        closeSplashScreen(window, xConfig.minVisible);
    });
    return window;
};
/** Return object for `initDynamicSplashScreen()`. */
export interface DynamicSplashScreen {
    /** The main browser window ready for loading */
    main: BrowserWindow;
    /** The splashscreen browser window so you can communicate with splashscreen in more complex use cases. */
    splashScreen: Electron.BrowserWindow;
}
/**
 * Initializes a splashscreen that will show/hide smartly (and handle show/hiding of main window).
 * Use this function if you need to send/receive info to the splashscreen (e.g., you want to send
 * IPC messages to the splashscreen to inform the user of the app's loading state).
 * @param config - Configures splashscreen
 * @returns {DynamicSplashScreen} the main browser window and the created splashscreen
 */
export const initDynamicSplashScreen = (config: Config): DynamicSplashScreen => {
    return {
        main: initSplashScreen(config),
        // initSplashScreen initializes splashscreen so this is a safe cast.
        splashScreen: splashScreen as Electron.BrowserWindow,
    };
};


================================================
FILE: package.json
================================================
{
  "name": "@trodi/electron-splashscreen",
  "version": "1.0.2",
  "description": "Simple splashscreen for electron applications",
  "main": "index.js",
  "types": "index.d.ts",
  "scripts": {
    "generate-api-doc": "typedoc --readme none --mode file --theme markdown --hideSources --excludePrivate --out api-doc/ index.ts",
    "prebuild": "tslint --config tslint.json *.ts",
    "build": "tsc",
    "prepublish": "npm run build && npm run generate-api-doc",
    "preexample": "npm run build",
    "example": "electron examples/example.js",
    "preexample-dynamic": "npm run build",
    "example-dynamic": "electron examples/example-dynamic.js"
  },
  "files": [
    "index.js",
    "index.d.ts"
  ],
  "repository": "trodi/electron-splashscreen",
  "keywords": [
    "electron",
    "splashscreen",
    "splash-screen",
    "loading-screen"
  ],
  "author": "Troy McKinnon",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/trodi/electron-splashscreen/issues"
  },
  "homepage": "https://github.com/trodi/electron-splashscreen#readme",
  "devDependencies": {
    "electron": "^11.0.1",
    "tslint": "^5.7.0",
    "typedoc": "^0.15.6",
    "typedoc-plugin-markdown": "^2.2.16",
    "typescript": "^3.7.4"
  }
}


================================================
FILE: tsconfig.json
================================================
{
  "compilerOptions": {
    /* Basic Options */
    "target": "es5",                          /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', or 'ESNEXT'. */
    "module": "commonjs",                     /* Specify module code generation: 'none', commonjs', 'amd', 'system', 'umd', 'es2015', or 'ESNext'. */
    // "lib": [],                             /* Specify library files to be included in the compilation:  */
    // "allowJs": true,                       /* Allow javascript files to be compiled. */
    // "checkJs": true,                       /* Report errors in .js files. */
    // "jsx": "preserve",                     /* Specify JSX code generation: 'preserve', 'react-native', or 'react'. */
    "declaration": true,                   /* Generates corresponding '.d.ts' file. */
    // "sourceMap": true,                     /* Generates corresponding '.map' file. */
    // "outFile": "./",                       /* Concatenate and emit output to single file. */
    // "outDir": "./",                        /* Redirect output structure to the directory. */
    // "rootDir": "./",                       /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */
    // "removeComments": true,                /* Do not emit comments to output. */
    // "noEmit": true,                        /* Do not emit outputs. */
    // "importHelpers": true,                 /* Import emit helpers from 'tslib'. */
    // "downlevelIteration": true,            /* Provide full support for iterables in 'for-of', spread, and destructuring when targeting 'ES5' or 'ES3'. */
    // "isolatedModules": true,               /* Transpile each file as a separate module (similar to 'ts.transpileModule'). */

    /* Strict Type-Checking Options */
    "strict": true                            /* Enable all strict type-checking options. */
    // "noImplicitAny": true,                 /* Raise error on expressions and declarations with an implied 'any' type. */
    // "strictNullChecks": true,              /* Enable strict null checks. */
    // "noImplicitThis": true,                /* Raise error on 'this' expressions with an implied 'any' type. */
    // "alwaysStrict": true,                  /* Parse in strict mode and emit "use strict" for each source file. */

    /* Additional Checks */
    // "noUnusedLocals": true,                /* Report errors on unused locals. */
    // "noUnusedParameters": true,            /* Report errors on unused parameters. */
    // "noImplicitReturns": true,             /* Report error when not all code paths in function return a value. */
    // "noFallthroughCasesInSwitch": true,    /* Report errors for fallthrough cases in switch statement. */

    /* Module Resolution Options */
    // "moduleResolution": "node",            /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */
    // "baseUrl": "./",                       /* Base directory to resolve non-absolute module names. */
    // "paths": {},                           /* A series of entries which re-map imports to lookup locations relative to the 'baseUrl'. */
    // "rootDirs": [],                        /* List of root folders whose combined content represents the structure of the project at runtime. */
    // "typeRoots": [],                       /* List of folders to include type definitions from. */
    // "types": [],                           /* Type declaration files to be included in compilation. */
    // "allowSyntheticDefaultImports": true,  /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */
    // "preserveSymlinks": true,              /* Do not resolve the real path of symlinks. */

    /* Source Map Options */
    // "sourceRoot": "./",                    /* Specify the location where debugger should locate TypeScript files instead of source locations. */
    // "mapRoot": "./",                       /* Specify the location where debugger should locate map files instead of generated locations. */
    // "inlineSourceMap": true,               /* Emit a single file with source maps instead of having a separate file. */
    // "inlineSources": true,                 /* Emit the source alongside the sourcemaps within a single file; requires '--inlineSourceMap' or '--sourceMap' to be set. */

    /* Experimental Options */
    // "experimentalDecorators": true,        /* Enables experimental support for ES7 decorators. */
    // "emitDecoratorMetadata": true,         /* Enables experimental support for emitting type metadata for decorators. */
  }
}

================================================
FILE: tslint.json
================================================
{
    "defaultSeverity": "error",
    "extends": [
        "tslint:recommended"
    ],
    "jsRules": {},
    "rules": {
        "object-literal-sort-keys": false,
        "interface-name": false,
        "no-unused-expression": false
    },
    "rulesDirectory": []
}