#

Working with the Menu Bar

NativePHP allows you to create a native application menu bar for your application. This can be used as an addition to your existing application that already uses windows, or as a standalone (menu-bar only) application.

When the user clicks on the menu bar icon, the menu bar window will open and show the given URL or route.

The configuration of your MenuBar should happen in the boot method of your NativeAppServiceProvider.

#

Creating a stand-alone Menu Bar application

To create a menu bar for your application, you may use the MenuBar facade. When creating the menu bar, NativePHP will automatically open the root URL of your application. By default, adding a menu bar will automatically hide the dock icon of your application.

 1namespace App\Providers;
 2 
 3use Native\Laravel\Facades\MenuBar;
 4 
 5class NativeAppServiceProvider
 6{
 7    public function boot(): void
 8    {
 9        MenuBar::create();
10    }
11}

#

Creating a Menu Bar for an application that already uses windows

You may also create a menu bar for an application that already uses windows. Usually you will want to show the dock icon of your application in this case. To do so, you may use the MenuBar::create() method, but this time call the showDockIcon() method.

 1namespace App\Providers;
 2 
 3use Native\Laravel\Facades\MenuBar;
 4 
 5class NativeAppServiceProvider
 6{
 7    public function boot(): void
 8    {
 9        MenuBar::create()
10            ->showDockIcon();
11    }
12}

#

Opening the Menu Bar

You may use the MenuBar::show() method to manually open the menu bar window.

1MenuBar::show();

#

Hiding the Menu Bar

You may use the MenuBar::hide() method to manually close the menu bar window.

1MenuBar::hide();

#

Menu Bar Labels

By default, the menu bar will only show the configured menu bar icon. Additionally, you may add a label to the menu bar that will be shown next to the icon.

This label can be changed at any time by using the label() method.

1MenuBar::label('Status: Online');

You may also use the label() method while creating the menu bar to set the initial label.

1MenuBar::create()
2    ->label('Status: Online');

To remove the label, you may pass an empty string to the label() method.

1MenuBar::label('');

#

Tooltip

Add a tooltip to the menu bar icon:

1MenuBar::tooltip('Click to open');

#

Configuring the Menu Bar

#

Menu Bar URL

By default, the MenuBar::create() method will configure your menu bar to show the root URL of your application when clicked. If you would like to open a different URL, you may use the route() method to specify the route name to open.

1MenuBar::create()
2    ->route('home');

You may also pass an absolute URL to the url() method:

1MenuBar::create()
2    ->url('https://google.com');

#

Menu Bar Icon

The default menu bar icon is the NativePHP logo. You may change this icon by using the icon() method. This method accepts an absolute path to an image file.

When providing an icon, you should make sure that the image is a PNG file with a transparent background. The recommended size for the icon is 22x22 pixels, as well as 44x44 pixels for retina displays.

The file name for the retina display icon should be the same as the regular icon, but with @2x appended to the file name.

Example:

1menuBarIcon.png
2[email protected]

On macOS, it is recommended to use a so-called "Template Image".
This is an image that is rendered as a white or black image with a transparent background.

NativePHP can automatically convert your image to a template image. To do so, you may name your image file with Template appended to the file name.

Example:

1menuBarIconTemplate.png
2[email protected]

You do not need to manually append @2x to the file name, as NativePHP will automatically detect the retina display icon and use it when available.

1MenuBar::create()
2    ->icon(storage_path('app/menuBarIconTemplate.png'));

#

Vibrancy and Background Color

For macOS, you may use the vibrancy method to apply window vibrancy effects:

1MenuBar::create()->vibrancy('light');

To create a solid background color instead:

1MenuBar::create()->backgroundColor('#ffffff');

#

Menu Bar Window Sizes

The default size of the menu bar window is 400x400 pixels. You may use the width() and height() methods to specify the size of the window that will be opened when the user clicks on the menu bar icon.

1MenuBar::create()
2    ->width(800)
3    ->height(600);

#

Resizable Window

Allow or prevent resizing of the menu bar window:

1MenuBar::resizable(false);

#

Positioning

You may manually set the position of the menu bar window:

1MenuBar::create()
2    ->x(100)
3    ->y(200);

#

Menu Bar on Top

When developing a menu bar application, you may want to make sure that the menu bar window is always open and on top of all other windows. This makes it easier to develop your application, as you do not have to click on the menu bar icon every time you want to see the window.

To do so, you may use the alwaysOnTop() method on the MenuBar.

1MenuBar::create()
2    ->alwaysOnTop();

#

Menu Bar Context Menu

You may add a context menu to your menu bar icon. This context menu will be shown when the user right-clicks on the menu bar icon.

#

Adding a Context Menu

To add a context menu to your Menu Bar app, you may use the withContextMenu() method on the MenuBar.

This method accepts a Native\Laravel\Menu\Menu instance, which can be created using the Menu::make() method of the Menu facade.

 1use Native\Laravel\Facades\Menu;
 2 
 3MenuBar::create()
 4    ->withContextMenu(
 5        Menu::make(
 6            Menu::label('My Application'),
 7            Menu::separator(),
 8            Menu::link('https://nativephp.com', 'Learn more…')
 9                ->openInBrowser(),
10            Menu::separator(),
11            Menu::quit()
12        )
13    );

To learn more about the Menu facade, please refer to the Application Menu documentation.

#

Events

NativePHP provides a simple way to listen for menu bar events. All events get dispatched as regular Laravel events, so you may use your EventServiceProvider to register listeners.

Sometimes you may want to listen and react to window events in real-time, which is why NativePHP also broadcasts all window events to the nativephp broadcast channel.

To learn more about NativePHP's broadcasting capabilities, please refer to the Broadcasting section.

#

Listening for Custom Events

Attach a custom event that should be fired when the menu bar icon is clicked. This only works when combined with onlyShowContextMenu():

 1MenuBar::create()->event(MenuBarClicked::class);
 2 
 3class MenuBarClicked
 4{
 5    public function __construct(public array $combo, public array $bounds, public array $position)
 6    {
 7        // $combo - details of any combo keys pressed when the click occurred
 8        // $bounds - the current absolute bounds of the menu bar icon at the time of the event
 9        // $position - the absolute cursor position at the time of the event
10    }
11}

#

MenuBarShown

The Native\Laravel\Events\MenuBar\MenuBarShown event will be dispatched when the user clicks on the menu bar icon and the menu bar window opens, or when the menu bar gets shown by using the MenuBar::show() method.

#

MenuBarHidden

The Native\Laravel\Events\MenuBar\MenuBarHidden event will be dispatched when the user clicks out of the menu bar window and the menu bar window closes, or when the menu bar gets hidden by using the MenuBar::hide() method.

#

MenuBarContextMenuOpened

The Native\Laravel\Events\MenuBar\MenuBarContextMenuOpened event will be dispatched when the user right-clicks on the menu bar icon and the context menu opens.

#

Context Menu Only

Show only the context menu without opening a window when the menu bar icon is clicked:

1MenuBar::onlyShowContextMenu();