npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

electron-progressbar-customhtml

v1.1.2

Published

electron-progressbar extends

Downloads

5

Readme

NPM downloads NPM total downloads

electron-progressbar-customhtml

electron-progressbar provides an easy-to-use and highly customizable API, to show and manipulate progress bars on Electron applications.

With electron-progressbar, you can easily customize the appearance of the progress bars, including the visual aspects using CSS, as well as the text and any other visible information. Additionally, the library allows for customization of the Electron BrowserWindow that contains the progress bars.

electron-progressbar-customhtml will be customize your progressbar.

NPM


Demo

Indeterminate progress bar: Indeterminate progress bar

Determinate progress bar: Determinate progress bar

Custom progress bar:

example of the taskbar for an indeterminate progress bar: Taskbar for indeterminate progress bar

example of the taskbar for a determinate progress bar: Taskbar for determinate progress bar


Table of Contents

Installation

Install with npm:

$ npm i electron-progressbar-customhtml

Examples

Indeterminate progress bar

Example of an indeterminate progress bar - this progress bar is useful when your application cannot calculate how long the task will take to complete:

Indeterminate progress bar

const {app} = require('electron');
const ProgressBar = require('electron-progressbar');

app.on('ready', function() {
  var progressBar = new ProgressBar({
    text: 'Preparing data...',
    detail: 'Wait...'
  });
  
  progressBar
    .on('completed', function() {
      console.info(`completed...`);
      progressBar.detail = 'Task completed. Exiting...';
    })
    .on('aborted', function() {
      console.info(`aborted...`);
    });
  
  // launch a task...
  // launchTask();
  
  // when task is completed, set the progress bar to completed
  // ps: setTimeout is used here just to simulate an interval between
  // the start and the end of a task
  setTimeout(function() {
    progressBar.setCompleted();
  }, 3000);
});

Determinate progress bar

Example of a determinate progress bar - this progress bar is useful when your application can accurately calculate how long the task will take to complete:

Determinate progress bar

const {app} = require('electron');
const ProgressBar = require('electron-progressbar');

app.on('ready', function() {
  var progressBar = new ProgressBar({
    indeterminate: false,
    text: 'Preparing data...',
    detail: 'Wait...'
  });
  
  progressBar
    .on('completed', function() {
      console.info(`completed...`);
      progressBar.detail = 'Task completed. Exiting...';
    })
    .on('aborted', function(value) {
      console.info(`aborted... ${value}`);
    })
    .on('progress', function(value) {
      progressBar.detail = `Value ${value} out of ${progressBar.getOptions().maxValue}...`;
    });
  
  // launch a task and increase the value of the progress bar for each step completed of a big task;
  // the progress bar is set to completed when it reaches its maxValue (default maxValue: 100);
  // ps: setInterval is used here just to simulate the progress of a task
  setInterval(function() {
    if(!progressBar.isCompleted()){
      progressBar.value += 1;
    }
  }, 20);
});

custom progress bar

Example of a custom progress bar - This option can be useful when you create your own custom HTML:

const {app} = require('electron');
const ProgressBar = require('electron-progressbar');

const customHTML = `<!DOCTYPE html>
<html lang="en-us">
<head>
    <meta charset="UTF-8">
    <style>
        * {
            margin: 0;
            padding: 0;
            box-sizing: border-box;
        }

        html,
        body {
            width: 100%;
            height: 100%;
        }

        body,
        table {
            word-break: break-word;
            word-wrap: break-word;
        }

        body {
            display: flex;
            flex-direction: column;
            align-items: center;
            justify-content: center;
            margin: 0;
            padding: 0 50px;
            margin-bottom: 0;
        }

       (...)
    </style>
</head>

<body>
    <div id="text"></div>
    <div id="detail"></div>
    <div id="progressBarContainer"></div>
    <script>

        var currentValue = {
            progress: null,
            text: null,
            detail: null
        };

        var elements = {
            text: document.querySelector("#text"),
            detail: document.querySelector("#detail"),
            progressBarContainer: document.querySelector("#progressBarContainer"),
            progressBar: null // set by createProgressBar()
        };

        function createProgressBar(settings) {

            if (settings.indeterminate) {
                var progressBar = document.createElement("div");
                progressBar.setAttribute("id", "progressBar");
                progressBar.setAttribute("indeterminate", "t");

                var progressBarValue = document.createElement("div");
                progressBarValue.setAttribute("id", "progressBarValue");
                progressBar.appendChild(progressBarValue);

                elements.progressBar = progressBar;
                elements.progressBarContainer.appendChild(elements.progressBar);
            } else {
                var progressBar = document.createElement("progress");
                progressBar.setAttribute("id", "progressBar");
                progressBar.max = settings.maxValue;

                elements.progressBar = progressBar;
                elements.progressBarContainer.appendChild(elements.progressBar);
            }

            elements.text.innerHTML = currentValue.text;
            elements.detail.innerHTML = currentValue.detail;

            window.requestAnimationFrame(synchronizeUi);
        }

        function synchronizeUi() {
            elements.progressBar.value = currentValue.progress;
            window.requestAnimationFrame(synchronizeUi);
        }
        const settings = {
            abortOnError: false,
            debug: false,

            indeterminate: true,
            initialValue: 0,
            maxValue: 100,
            closeOnComplete: true,
            title: 'Wait...',
            text: 'Wait...',
            detail: null,
            lang: '',
            customHTML: '',

            style: {
                text: {},
                detail: {},
                bar: {
                    'width': '100%',
                    'background': '#BBE0F1'
                },
                value: {
                    'background': '#0976A9'
                }
            },

            browserWindow: {
                parent: null,
                modal: true,
                resizable: false,
                closable: false,
                minimizable: false,
                maximizable: false,
                width: 500,
                height: 170,
                webPreferences: {
                    nodeIntegration: true,
                    contextIsolation: false,
                },
            },

            remoteWindow: null
        };

        ipcRenderer.on("CREATE_PROGRESS_BAR", (event, settings) => {
            createProgressBar(settings);
        });

        ipcRenderer.on("SET_PROGRESS", (event, value) => {
            currentValue.progress = value;
        });

        ipcRenderer.on("SET_COMPLETED", (event) => {
            elements.progressBar.classList.add('completed');
        });

        ipcRenderer.on("SET_TEXT", (event, value) => {
            currentValue.text = value;
        });

        ipcRenderer.on("SET_DETAIL", (event, value) => {
            currentValue.detail = value;
        });
    </script>
</body>

</html>

`

app.on('ready', function() {
  var progressBar = new ProgressBar({
    indeterminate: false,
    customHTML: customHTML
  });

  progressBar
    .on('completed', function() {
      console.info(`completed...`);
      progressBar.detail = 'Task completed. Exiting...';
    })
    .on('aborted', function(value) {
      console.info(`aborted... ${value}`);
    })
    .on('progress', function(value) {
      progressBar.detail = `Value ${value} out of ${progressBar.getOptions().maxValue}...`;
    });


  // Please Note Indeterminate progress bar example or Determinate progress bar example.
});

More examples are available in folder examples.

API

Methods

new ProgressBar(options, [electronApp])

Create a new progress bar. It's necessary to wait for the ready event to be emitted by Electron's BrowserWindow, since the progress bar is displayed within it. Optionally, you can pass the electron app as a second parameter (parameter electronApp) when creating the progress bar. Check the sample code on this page for detailed examples on how to set properties to options.

You can define most of the characteristics of the progress bar using the options parameter. Below is a list of properties that you can set for the options parameter.

| Option name | Type | Default value | Description | | --- | --- | --- | --- | | debug | boolean | false | Specifies whether debugging should be enabled. If set to true, the browser's DevTools panel will automatically open when the progress bar is created. This can be helpful when debugging and/or dealing with issues. | | abortOnError | boolean | false | Specifies whether the progress bar should automatically abort and close if an error occurs internally. | | indeterminate | boolean | true | Specifies whether the progress bar should be indeterminate. If set to false, the progress bar will be determinate. | | initialValue | number | 0 | The initial value for the progress bar. This parameter is only applicable for determinate progress bars. | | maxValue | number | 100 | The maximum value for the progress bar. When the progress bar's value reaches this number, the progress bar will be considered complete and the complete event will be fired. This parameter is only applicable for determinate progress bars. | | closeOnComplete | boolean | true | Specifies whether the progress bar window should be automatically closed after the progress bar completes. If set to false, the progress bar will remain visible until the close method is called by your application. | | lang | string | empty | Specifies the value for the lang attribute of the BrowserWindow's <html> tag. This option has no default value, and the lang attribute is only added to <html> when lang is explicitly set. This option can also be helpful in case of font rendering issues. | | customHTML | string | empty | This is a function that allows you to display a progressbar by customizing HTML. You can insert the entire HTML code starting with the <html> tag in the customHTML attribute. Please insert the contents within the <body> tag by referring to the example. | title | string | "Wait..." | Specifies the text shown on the progress bar window's title bar. | | text | string | "Wait..." | Specifies the text shown inside the progress bar window, next to the progress bar. | | detail | string | empty | Specifies the text shown between text and the progress bar element. It can be used to display detailed information, such as the current progress of a task. When used for this purpose, it is usually more useful to set this property later so that your application can calculate and display, in real time, the current progress of the task. | | style | object | | Specifices the visual styles for the text, detail, bar, and value elements. All properties and values are pure CSS format, in the exact same way they would be used in a CSS file. Check the options for style below. | | style.text | object | | An object containing CSS properties for styling the text element. | | style.detail | object | | An object containing CSS properties for styling the detail element. | | style.bar | object | {"width":"100%", "background-color":"#BBE0F1"} | An object containing CSS properties for styling the bar element of the progress bar. | | style.value | object | {"background-color":"#0976A9"} | An object containing CSS properties for styling the value element in the progress bar. | | remoteWindow | instance of BrowserWindow | null | Specifies the BrowserWindow where the progress bar will be displayed. If null/undefined/empty or not specified, a new BrowserWindow will be created to show the progress bar. | | browserWindow | object | | Specifies the options for Electron's BrowserWindow. Check the options for browserWindow below. P.S.: although only a few options are set by default, you can specify any of Electron's BrowserWindow options. | browserWindow.parent | instance of BrowserWindow | null | A BrowserWindow instance to be used as the parent of the progress bar's window. If specified, the progress bar window will always be on top of the given parent window and will block user interaction in parent window until the progress bar is completed (or aborted) and closed. | | browserWindow.modal | boolean | true | Specifies whether the progress bar's window is a modal window. Note that this property only works when the progress bar's window is a child window, i.e., when browserWindow.parent is specified. | | browserWindow.resizable | boolean | false | Specifies whether the user can resize the progress bar's window. | | browserWindow.closable | boolean | false | Specifies whether the user can close the progress bar's window. | | browserWindow.minimizable | boolean | false | Specifies whether the user can minimize the progress bar's window. | | browserWindow.maximizable | boolean | false | Specifies whether the user can maximize the progress bar's window. | | browserWindow.width | number | 450 | Specifies the width of the progress bar's window in pixels. Only numeric values are accepted, for example: 600. | | browserWindow.height | number | 175 | Specifies the height of the progress bar's window in pixels. Only numeric values are accepted, for example: 600. | | browserWindow.webPreferences.nodeIntegration | boolean | true | Specifies whether node integration is enabled. | | browserWindow.webPreferences.contextIsolation | boolean | false | Specifies whether contextIsolation is enabled. |


getOptions()object

Return a copy of all the current options.


on(eventName, listener)reference to this

Add the listener function to the end of the listeners array for the event named eventName, and then return a reference to this so that next calls can be chained. P.S.: there are no checks to verify if listener has already been added. If you call the same combination of eventName and listener multiple times, the listener will be added and executed multiple times as well.

Events

| Event name | Receives parameter | Description | | --- | --- | --- | | ready | none | This event is fired when the progress bar has been created and is ready to be used and manipulated. | | progress | value | This event is available only for determinate progress bars. It is fired every time the progress bar's value is changed. The listener receives, as its first parameter, the current value of the progress bar. | | completed | value | This event is fired when the progress bar is completed, i.e., its value reaches maxValue or the complete method is called. The listener receives, as its first parameter, the current value of the progress bar. | | aborted | value | This event is fired if the progress bar is closed before it's completed, i.e., when user closes the progress bar window or the close method is called before the progress bar reaches completion. The listener receives, as its first parameter, the current value of the progress bar. |


setCompleted()

Set the progress bar as complete, indicating that the task has finished.

If progress bar is indeterminate, a manual call to this method is required since it's the only way to trigger the completed event and indicate that the task has finished. Otherwise, the progress bar will continue to be displayed indefinitely.


close()

Close the progress bar window. If progress bar has not been completed yet, it will be aborted, and the aborted event will be fired.


isInProgress()boolean

Return true if the progress bar is currently in progress, meaning that it has not been completed or aborted yet; otherwise it will return false;


isCompleted()boolean

Return true if the progress bar is completed, otherwise false.


Properties

valuenumber

This property allows getting or setting the progress bar's current value. It is only applicable and available for determinate progress bars.


textstring

This property allows getting or setting the progress bar's text information that is shown above the progress bar element.


detailstring

This property allows getting or setting the progress bar's detail information that is shown between text and the progress bar element. Useful to display detailed information, such as the current status, in real time, or the current progress of the task.


Changelog

Changelog

License

MIT. See LICENSE.md for details.(oinochoe)
MIT. See LICENSE.md for details(AndersonMamede).