Application Menu

NativePHP allows you to configure the native menu of your application, as well as context menus or dock menus. You can use the Menu facade which provides you with a single re-usable abstraction for building all of these menus.

Copied!

1use Native\Laravel\Facades\Menu;

use Native\Laravel\Facades\Menu;

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

To create a new menu, you may use the Menu::new() method. This method returns the menu builder, which allows you to add additional items or submenus. Once you are done configuring the menu, you may call the register() method to register the menu with the native application.

Copied!

 1namespace App\Providers;
 2 
 3use Native\Laravel\Facades\Window;
 4use Native\Laravel\Menu\Menu;
 5 
 6class NativeAppServiceProvider
 7{
 8    /**
 9     * Executed once the native application has been booted.
10     * Use this method to open windows, register global shortcuts, etc.
11     */
12    public function boot(): void
13    {
14        Menu::new()
15            ->appMenu()
16            ->submenu('NativePHP', Menu::new()
17                ->link('https://nativephp.com', 'Documentation')
18            )
19            ->register();
20 
21        Window::open();
22    }
23}

namespace App\Providers;

use Native\Laravel\Facades\Window;
use Native\Laravel\Menu\Menu;

class NativeAppServiceProvider
{
    /**
     * Executed once the native application has been booted.
     * Use this method to open windows, register global shortcuts, etc.
     */
    public function boot(): void
    {
        Menu::new()
            ->appMenu()
            ->submenu('NativePHP', Menu::new()
                ->link('https://nativephp.com', 'Documentation')
            )
            ->register();

        Window::open();
    }
}

#
Predefined menus

NativePHP comes with a few predefined menus that you can use out of the box.

You may use the appMenu() method to create the default application menu. This menu contains all the default items that you would expect in an application menu (e.g. About, Services, Quit, etc.).

Copied!

1Menu::new()
2    ->appMenu()
3    ->register();

Menu::new()
    ->appMenu()
    ->register();

The appMenu will use the name of your application as its title.

You may use the editMenu() method to create the default edit menu. This menu contains all the default items and their functionality that you would expect in an edit menu (e.g. Undo, Redo, Cut, Copy, Paste, etc.).

The editMenu() enables a number of common keyboard shortcuts (like cut, copy, paste). Without it, you will need to define these yourself.

Copied!

1Menu::new()
2    ->editMenu()
3    ->register();

Menu::new()
    ->editMenu()
    ->register();

The edit menu uses "Edit" as its title by default. You may change this by passing a string to the editMenu() method.

Copied!

1Menu::new()
2    ->editMenu('My Edit Menu')
3    ->register();

Menu::new()
    ->editMenu('My Edit Menu')
    ->register();

You may use the viewMenu() method to create the default view menu. This menu contains all the default items and their functionality that you would expect in a view menu (e.g. Toggle Fullscreen, Toggle Developer Tools, etc.).

Copied!

1Menu::new()
2    ->viewMenu()
3    ->register();

Menu::new()
    ->viewMenu()
    ->register();

The view menu uses "View" as its title by default. You may change this by passing a string to the viewMenu() method.

Copied!

1Menu::new()
2    ->viewMenu('My View Menu')
3    ->register();

Menu::new()
    ->viewMenu('My View Menu')
    ->register();

You may use the windowMenu() method to create the default window menu. This menu contains all the default items and their functionality that you would expect in a window menu (e.g. Minimize, Zoom, etc.).

Copied!

1Menu::new()
2    ->windowMenu()
3    ->register();

Menu::new()
    ->windowMenu()
    ->register();

The window menu uses "Window" as its title by default. You may change this by passing a string to the windowMenu() method.

Copied!

1Menu::new()
2    ->windowMenu('My Window Menu')
3    ->register();

Menu::new()
    ->windowMenu('My Window Menu')
    ->register();

#
Combining the default menus

If you want to use multiple predefined menus, simply chain the methods together.

Copied!

1Menu::new()
2    ->appMenu()
3    ->editMenu()
4    ->viewMenu()
5    ->windowMenu()
6    ->register();

Menu::new()
    ->appMenu()
    ->editMenu()
    ->viewMenu()
    ->windowMenu()
    ->register();

#
Custom Submenus

You may use the submenu() method to create a submenu. This method accepts a title and a menu builder as its arguments.

Copied!

1Menu::new()
2    ->appMenu()
3    ->submenu('My Submenu', Menu::new()
4        ->link('https://nativephp.com', 'Documentation')
5    )
6    ->register();

Menu::new()
    ->appMenu()
    ->submenu('My Submenu', Menu::new()
        ->link('https://nativephp.com', 'Documentation')
    )
    ->register();

#
Available Submenu Items

#
Labels

NativePHP allows you to add labels to your menus. You may use the label() method to add a label to your menu. Clicking on a label will trigger the Native\Laravel\Events\Menu\MenuItemClicked event will be broadcast.

Copied!

1Menu::new()
2    ->appMenu()
3    ->submenu('My Submenu', Menu::new()
4        ->label('My Label')
5    )
6    ->register();

Menu::new()
    ->appMenu()
    ->submenu('My Submenu', Menu::new()
        ->label('My Label')
    )
    ->register();

#
Links

You may add a link to your menu by using the link() method. This method accepts a URL and a title as its arguments. When the user clicks on the link, the URL will be opened in the default browser and the Native\Laravel\Events\Menu\MenuItemClicked event will be dispatched.

The payload of the event will contain the following data:

id: The internal ID of the menu item.
label: The label of the menu item.

Copied!

1Menu::new()
2    ->submenu('My Submenu', Menu::new()
3        ->link('https://nativephp.com', 'Learn more')
4    )
5    ->register();

Menu::new()
    ->submenu('My Submenu', Menu::new()
        ->link('https://nativephp.com', 'Learn more')
    )
    ->register();

#
Separators

You may add separators to your menu by using the separator() method. A separator is a horizontal line that separates menu items.

Copied!

1Menu::new()
2    ->submenu('My Submenu', Menu::new()
3        ->link('https://nativephp.com', 'Learn more')
4        ->separator()
5        ->link('https://nativephp.com', 'Documentation')
6    )
7    ->register();

Menu::new()
    ->submenu('My Submenu', Menu::new()
        ->link('https://nativephp.com', 'Learn more')
        ->separator()
        ->link('https://nativephp.com', 'Documentation')
    )
    ->register();

Event menu items automatically trigger the specified event when clicked.

Copied!

1Menu::new()
2    ->submenu('My Submenu', Menu::new()
3        ->event(App\Events\MyEvent::class, 'Trigger my event')
4    )
5    ->register();

Menu::new()
    ->submenu('My Submenu', Menu::new()
        ->event(App\Events\MyEvent::class, 'Trigger my event')
    )
    ->register();

You may register listeners for your custom events in your EventServiceProvider class.

Copied!

 1/**
 2 * The event listener mappings for the application.
 3 *
 4 * @var array
 5 */
 6protected $listen = [
 7    App\Events\MyEvent::class => [
 8        'App\Listeners\MyMenuItemWasClicked',
 9    ],
10    // ...
11];

/**
 * The event listener mappings for the application.
 *
 * @var array
 */
protected $listen = [
    App\Events\MyEvent::class => [
        'App\Listeners\MyMenuItemWasClicked',
    ],
    // ...
];

You may add a checkbox item to your menu by using the checkbox() method. The checkbox() method accepts a label and a boolean value for the initial state of the checkbox as its arguments.

When the user clicks on the checkbox item, the checkbox will be toggled and the Native\Laravel\Events\Menu\MenuItemClicked event will be dispatched.

The payload of the event will contain the following data:

id: The internal ID of the menu item.
checked: Whether the checkbox is checked or not.
label: The label of the menu item.

Copied!

1Menu::new()
2    ->submenu('My Submenu', Menu::new()
3        ->checkbox('My Checkbox', true)
4    )
5    ->register();

Menu::new()
    ->submenu('My Submenu', Menu::new()
        ->checkbox('My Checkbox', true)
    )
    ->register();

#
Quit

You may add a quit item to your menu by using the quit() method. When the user clicks on the quit item, the application will quit.

Copied!

1Menu::new()
2    ->submenu('My Submenu', Menu::new()
3        ->quit()
4    )
5    ->register();

Menu::new()
    ->submenu('My Submenu', Menu::new()
        ->quit()
    )
    ->register();

#
Hotkeys

NativePHP allows you to register hotkeys along with your menu items. The checkbox(), event() and link() methods accept a hotkey as their last argument.

The hotkey must be a string that contains the modifiers and the key separated by a + sign.

For example, if you want to register a hotkey that triggers the MyEvent event when the user presses Cmd+Shift+D, you may do the following:

Copied!

1Menu::new()
2    ->submenu('My Submenu', Menu::new()
3        ->event(App\Events\MyEvent::class, 'Trigger my event', 'CmdOrCtrl+Shift+D')
4    )
5    ->register();

Menu::new()
    ->submenu('My Submenu', Menu::new()
        ->event(App\Events\MyEvent::class, 'Trigger my event', 'CmdOrCtrl+Shift+D')
    )
    ->register();

You can find a list of available hotkey modifiers in the global hotkey documentation section

#
Configuring the Application Menu

#
Creating a menu

#
Predefined menus

#
The default application menu

#
The default edit menu

#
The default view menu

#
The default window menu

#
Combining the default menus

#
Custom Submenus

#
Available Submenu Items

#
Labels

#
Links

#
Separators

#
Event-based menu items

#
Checkbox menu items

#
Quit

#
Hotkeys

#Configuring the Application Menu

#Creating a menu

#Predefined menus

#The default application menu

#The default edit menu

#The default view menu

#The default window menu

#Combining the default menus

#Custom Submenus

#Available Submenu Items

#Labels

#Links

#Separators

#Event-based menu items

#Checkbox menu items

#Quit

#Hotkeys

#
Configuring the Application Menu

#
Creating a menu

#
Predefined menus

#
The default application menu

#
The default edit menu

#
The default view menu

#
The default window menu

#
Combining the default menus

#
Custom Submenus

#
Available Submenu Items

#
Labels

#
Links

#
Separators

#
Event-based menu items

#
Checkbox menu items

#
Quit

#
Hotkeys