menubar

by maxogden

maxogden /menubar

➖ high level way to create menubar desktop applications with electron

5.6K Stars 338 Forks Last release: about 5 years ago (v2.0.17) BSD 2-Clause "Simplified" License 263 Commits 56 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Build Status npm (scoped) dependencies Status npm bundle size npm bundle size Buy me a tree




➖ Menubar

High level way to create menubar desktop applications with Electron.




This module provides boilerplate for setting up a menubar application using Electron. All you have to do is point it at your

index.html
and
menubar
will handle the rest.

✅ Only one dependency, and one peer-dependency.

✅ Works on macOS, Windows and most Linuxes. See details.

✅ 💥 3.6kB minified + gzipped 💥

| | | | | :-----------------------------------------------------------: | :--------------------------------------------------------: | :------------------------------------------------------: | | macOS Mojave 10.14 | Windows 10 | Ubuntu 18.04 |

Installation

yarn add menubar

Usage

Starting with your own new project, run these commands:

$ yarn add menubar
$ touch myApp.js
$ touch index.html

Fill

index.html
with some HTML, and
myApp.js
like this:
const { menubar } = require('menubar');

const mb = menubar();

mb.on('ready', () => { console.log('app is ready'); // your app code here });

Then use

electron
to run the app:
$ electron myApp.js

Alternatively, see

examples/hello-world
folder for a simple working example.

Menubar
Class

The return value of

menubar()
is a
Menubar
class instance, which has these properties:
  • app
    : the Electron App instance,
  • window
    : the Electron Browser Window instance,
  • tray
    : the Electron Tray instance,
  • positioner
    : the Electron Positioner instance,
  • setOption(option, value)
    : change an option after menubar is created,
  • getOption(option)
    : get an menubar option,
  • showWindow()
    : show the menubar window,
  • hideWindow()
    : hide the menubar window

See the reference API docs.

menubar()
Options

You can pass an optional options object into the

menubar({ ... })
function:
  • dir
    (default
    process.cwd()
    ) - the app source directory
  • index
    (default
    file:// + opts.dir + index.html
    ) - The URL to load the menubar's browserWindow with. The url can be a remote address (e.g.
    http://
    ) or a path to a local HTML file using the
    file://
    protocol.
  • browserWindow
    - BrowserWindow options to be passed to the BrowserWindow constructor, see Electron docs. Some interesting fields to passed down are:
    • x
      (default
      undefined
      ) - the x position of the window
    • y
      (default
      undefined
      ) - the y position of the window
    • width
      (default 400) - window width
    • height
      (default 400) - window height
    • alwaysOnTop
      (default false) - if true, the window will not hide on blur
  • icon
    (default
    opts.dir + IconTemplate.png
    ) - the png icon to use for the menubar. A good size to start with is 20x20. To support retina, supply a 2x sized image (e.g. 40x40) with
    @2x
    added to the end of the name, so
    icon.png
    and
    [email protected]
    and Electron will automatically use your
    @2x
    version on retina screens.
  • tooltip
    (default empty) - menubar tray icon tooltip text
  • tray
    (default created on-the-fly) - an electron
    Tray
    instance. if provided
    opts.icon
    will be ignored
  • preloadWindow
    (default false) - Create BrowserWindow instance before it is used -- increasing resource usage, but making the click on the menubar load faster.
  • showOnAllWorkspaces
    (default true) - Makes the window available on all OS X workspaces.
  • windowPosition
    (default trayCenter and trayBottomCenter on Windows) - Sets the window position (x and y will still override this), check positioner docs for valid values.
  • showDockIcon
    (default false) - Configure the visibility of the application dock icon.
  • showOnRightClick
    (default false) - Show the window on 'right-click' event instead of regular 'click'

See the reference API docs.

Events

The

Menubar
class is an event emitter:
  • ready
    - when
    menubar
    's tray icon has been created and initialized, i.e. when
    menubar
    is ready to be used. Note: this is different than Electron app's
    ready
    event, which happens much earlier in the process
  • create-window
    - the line before
    new BrowserWindow()
    is called
  • after-create-window
    - the line after all window init code is done
  • show
    - the line before
    window.show()
    is called
  • after-show
    - the line after
    window.show()
    is called
  • hide
    - the line before
    window.hide()
    is called (on window blur)
  • after-hide
    - the line after
    window.hide()
    is called
  • after-close
    - after the
    .window
    (BrowserWindow) property has been deleted
  • focus-lost
    - emitted if always-on-top option is set and the user clicks away

Compatibility with Electron

| menubar | Electron | Notes | | -------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------- | | 9.x.x | 9.x.x | | | 8.x.x | 8.x.x | | | 7.x.x | 7.x.x | | | 6.x.x | 4.x.x | 5.x.x | 6.x.x | Not recommended for security reasons | | <= 5.x.x | <= 3.x.x | Please, please don't use these old versions |

API Docs

See the reference API docs.

Tips

  • Use
    mb.on('after-create-window', callback)
    to run things after your app has loaded. For example you could run
    mb.window.openDevTools()
    to open the developer tools for debugging, or load a different URL with
    mb.window.loadUrl()
  • Use
    mb.on('focus-lost')
    if you would like to perform some operation when using the option
    browserWindow.alwaysOnTop: true
  • To restore focus of previous window after menubar hide, use
    mb.on('after-hide', () => { mb.app.hide() } )
    or similar
  • To create a native menu, you can use
    tray.setContextMenu(contextMenu)
    , and pass this custom tray to menubar:
    const mb = menubar({ tray });
    . See this example for more information.
  • To avoid a flash when opening your menubar app, you can disable backgrounding the app using the following:
    mb.app.commandLine.appendSwitch('disable-backgrounding-occluded-windows', 'true');

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.