advanced-electron-titlebar v1.1.0

Custom Electron titlebar

A custom Electron titlebar with high customizability. Current features:

• Create menus and submenus with ease just from an Object
• Connect a method to the click of a submenu button
• Custom titlebar background color, title label color, buttons hover color
• Automatic shrink - if the window is too narrow to display the whole menu bar, then it is shrunk and the hidden ones are put in a submenu of a button with dots (Similar to VS Code)
• Currently Fontawesome is used for icons on the titlebar so it will look the same on all platforms
• Draw separation lines between buttons in submenus

Dependencies

• jQuery ^3.5.1

Prerequisites

The module doesn't depend on Fontawesome but it uses its icons for the window buttons and the right chevron for the submenu buttons. To install and setup Fontawesome, please follow these instructions.

How to install

To install run the following command in the terminal in the project folder:

npm install --save advanced-electron-titlebar

How to use

First create the BrowserWindow in Electron and remove its frame as follows:

const win = new BrowserWindow({
    // Other properties

    //Remove the frame
    frame: false
  })

To use the titlebar, first require the module in a JavaScript file (for example in render.js):

const titlebar = require("advanced-electron-titlebar")

Make sure that the script is included in the index.html file with the defer tag as follows:

<script defer src="render.js"></script>

Then in the file where you have required the module, create the titlebar by using the .create() function:

titlebar.create(settings, menu, current_window)

The arguments for this function are as follows:

The settings argument

You can change different properties of the titlebar using the settings argument.

The menu argument

You can use this to set a menu for the titlebar.

The following format is used:

let menu = {
    "Button/subbutton label": {
        // Arguments
    }
}

There are currently 3 types of buttons:

• The "standard" which is used to do some action
• The "submenu" which is used to open a submenu on hover
• The "separator" which draws a separation line between buttons

These are the current available arguments: | Argument | Type | Values | Required for | Description | |----------|------|--------|--------------|-------------| | type | String |standard, submenu | All buttons | The type of the button - "standard" for a standard button, "submenu" for a submenu button | | command | String | any | Standard buttons | This is displayed on the right side of a submenu button. Could be used to show what keyboard combination could be used instead of clicking on the button | | method | One line function that calls another function | null or a function name | Standard button | Used to call a function when a standard button is clicked | | submenu | Object | - | Submenu button | The submenu which is opened when hover over the button |

The "standard" button

The format for the "standard" button is the following:

"Button label": {
    type: "standard",
    command: "any",
    method: () => functionName(),
}

If you do not want the button to call a function (for example you don't have the function yet), then you can use:

"Button label": {
    type: "standard",
    command: "any",
    method: () => null,
}

The "submenu" button

The format for the "standard" button is the following:

"Button label": {
    type: "submenu",
    submenu: {
        //Another Object which is the submenu
    }
}

The "separator" button

The format for the "separator" button is the following:

"separator#": {
    type: "separator",
}

Note: Keep in mind that because this is inside an object, the keys must be unique and if you insert 2 elements with the same key for a separator, the first one will not be drawn. An easy way to deal wit that is to name the separator as separator# and replacing the # with a number and making sure the same number is not used twice in the same object.

The current_window argument

You have to pass the current Electron window to the function. For example you can use this to pass the current window:

const remote = require("electron").remote
titlebar.create(settings, menu, remote.getCurrentWindow())

Note: If you use this method to pass the current window in Electron 10, then the enableRemoteModule is false by default and the titlebar won't be displayed. To enable it, set enableRemoteModule to true in the webPreferences for the BrowserWindow like so:

const win = new BrowserWindow({
    // Other properties

    webPreferences: {
      nodeIntegration: true,
      enableRemoteModule: true
    },

    //Remove the frame
    frame: false
  })

Functions

You can call a function as follows:

titlebar.functionName(*args)

List of the available functions: | Function | Arguments | Description | |----------|-----------|-------------| | .create() | settings - the settings for the titlebar, menu - the object that holds the menu structure, current_window - the current Electron window | Creates and adds the titlebar to the current window |

Contributions

Currently this is in early development. You are more than welcome to contribute if you want! I am open to ideas and suggestion how to improve and expand the module.

License

This module is licensed under MIT.