diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3b9e1c5..7a479af 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -## Before opening issues +## ๐Ÿ› Before opening issues **If you are asking a question**: @@ -16,7 +16,7 @@ Please provide the following information when opening issues: Thanks! -## Releases +## ๐Ÿšข Releases Releases are automated with [release-please](https://github.com/googleapis/release-please) and driven entirely from [Conventional Commits](https://www.conventionalcommits.org/) on `main`: diff --git a/README.md b/README.md index d848355..87225d0 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@
-## Features +## ๐Ÿ“ฆ Features - โšก๏ธ Quick start for creating menubar applications using Electron. - ๐Ÿš€ Zero runtime dependencies. @@ -32,7 +32,7 @@ > [!NOTE] > On native Wayland, the desktop compositor controls window placement, so the popover cannot be anchored to the tray icon and is positioned by the desktop (usually centered). This is a Wayland limitation, not something the library can override. Tray-relative positioning works under X11/XWayland. See [window positioning on Linux][platforms] for the detail and a workaround. -## Why electron-menubar? +## ๐Ÿ’ก Why electron-menubar? `electron-menubar` builds on [max-mapper/menubar][github-upstream-repo], with fixes and controls developed for [Gitify](https://github.com/gitify-app/gitify). The original provides the tray-app foundation. This fork brings more of the platform-specific behavior into the library so applications have less to implement themselves. @@ -47,7 +47,7 @@ | Packaging | Zero runtime dependencies, including a built-in positioner. Ships CommonJS and ESM entry points with TypeScript declarations. | | Verification | Unit tests, native Electron end-to-end tests on macOS, Windows, and Linux, and visual checks that the tray icon and window render. The [platform report][platforms] includes screenshots and positioning limitations. | -### Popup behavior without platform checks +### ๐ŸชŸ Popup behavior without platform checks Menubar manages popup stacking and focus on every platform. A plain `menubar()` dismisses on click-away and opens above the Windows hidden-icons panel. To keep it open, change one option: @@ -60,20 +60,20 @@ mb.setOption('hideOnBlur', true); // Resume click-away dismissal. Opening DevTools temporarily keeps the popup open. Closing DevTools restores the latest `hideOnBlur` preference. Options set before window creation also apply when the window is recreated. -#### Migrating from 10.x +#### ๐Ÿšš Migrating from 10.x These defaults apply starting with 11.0.0. Previously, menubar inferred dismissal from `window.isAlwaysOnTop()`. Use `hideOnBlur: false` for persistent popups instead of `browserWindow.alwaysOnTop: true` or runtime `window.setAlwaysOnTop(true)` calls. `browserWindow.alwaysOnTop` now controls stacking only; it does not disable dismissal. Setting `hideOnBlur: false` also keeps the popup on top on macOS and Linux. Remove Windows `pop-up-menu` workarounds and DevTools focus handlers from apps. Menubar owns stacking during window creation, showing, preference changes, and DevTools transitions. Apps can still customize DevTools dimensions and layout. See the [changelog](CHANGELOG.md) for released changes and the [API documentation](#api-documentation) for all options. -## Installation +## ๐Ÿš€ Installation ```bash pnpm add electron-menubar ``` -## Usage +## ๐Ÿ”ง Usage Starting with your own new project, run these commands: @@ -102,17 +102,17 @@ Then use `electron` to run the app: $ electron myApp.js ``` -## Examples +## ๐Ÿ“š Examples See [`examples`][examples] folder for a selection of working examples. -## API Documentation +## ๐Ÿ“– API Documentation -### `Menubar` Class +### ๐Ÿงฑ `Menubar` Class The return value of `menubar()` is a `Menubar` class instance, which exposes the following properties and methods. -#### Properties +#### ๐Ÿงพ Properties | Property | Description | | ------------ | ----------------------------------------------------------------------------- | @@ -121,7 +121,7 @@ The return value of `menubar()` is a `Menubar` class instance, which exposes the | `tray` | The [Electron Tray][electron-docs-tray] instance. | | `positioner` | The `Positioner` instance used to compute the window's on-screen coordinates. | -#### Methods +#### ๐Ÿงฐ Methods | Method | Description | | -------------------------------- | ------------------------------------------------------------------------------------------------------------ | @@ -137,7 +137,7 @@ The return value of `menubar()` is a `Menubar` class instance, which exposes the | `destroy()` | Tear down the menubar instance. | | `isDestroyed()` | Whether the menubar is currently destroyed. | -### `menubar()` Options +### ๐ŸŽ›๏ธ `menubar()` Options You can pass an optional options object into the `menubar({ ... })` function: @@ -163,7 +163,7 @@ You can pass an optional options object into the `menubar({ ... })` function: | `ignoreDoubleClickEvents` | `true` (macOS only) | Calls `tray.setIgnoreDoubleClickEvents(true)` so an accidental double-click doesn't race the close-on-blur handler and flicker the tray icon. Pass `false` to opt out. No-op on Linux/Windows. | | `globalShortcut` | | An [Accelerator][electron-docs-accelerator] string registered as a global keyboard shortcut that toggles the menubar window. Unregistered automatically on `destroy()`. Use `mb.setGlobalShortcut(accelerator)` to change or clear it at runtime. | -### Events +### ๐Ÿ“ก Events The `Menubar` class is an event emitter: @@ -180,7 +180,7 @@ The `Menubar` class is an event emitter: | `after-close` | After the `.window` (BrowserWindow) property has been deleted. | | `focus-lost` | Emitted on click-away when `hideOnBlur` is `false` or DevTools is open. | -## Tips +## ๐Ÿง  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 `hideOnBlur: false` @@ -188,7 +188,7 @@ The `Menubar` class is an event emitter: - To attach a native context menu, pass it as `contextMenu`: `menubar({ contextMenu })`. The library wires it via `setContextMenu` on Linux and `popUpContextMenu` on right-click on macOS/Windows so left-click still toggles the window. See [this example][examples-native] 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');` -## Acknowledgements +## ๐Ÿค Acknowledgements Originally created by [Max][github-upstream-creator] โ€” hard-forked from [max-mapper/menubar][github-upstream-repo].