createMenu

Category: Application Menu

Namespace: web.appMenu.createMenu

Description

Create a custom application menu with File, Edit, Help, and other menu items. This replaces the default menu with your custom menu structure, allowing full control over menu items, submenus, separators, and click handlers.

Syntax

await web.appMenu.createMenu({
    items: array
});

Parameters

• items (required) - Array of menu item objects. Each item can have:
  • id (string) - Unique identifier for the menu item
  • caption (string) - Text displayed in the menu
  • enabled (boolean) - Whether the item is clickable (default: true)
  • visible (boolean) - Whether the item is shown (default: true)
  • items (array) - Submenu items (for dropdown menus)
  • separator (boolean) - Create a separator line (caption ignored)

Returns

Promise<string> - Resolves with success message or rejects with error

Example

Simple example

await web.appMenu.createMenu({
    items: [
        { id: 'file', caption: 'File' },
        { id: 'edit', caption: 'Edit' },
        { id: 'help', caption: 'Help' }
    ]
});

Practical example

await web.appMenu.createMenu({
    items: [
        {
            id: 'file',
            caption: 'File',
            items: [
                { id: 'file.new', caption: 'New' },
                { id: 'file.open', caption: 'Open...' },
                { id: 'file.save', caption: 'Save' },
                { separator: true },
                { id: 'file.exit', caption: 'Exit' }
            ]
        },
        {
            id: 'help',
            caption: 'Help',
            items: [
                { id: 'help.docs', caption: 'Documentation' },
                { id: 'help.about', caption: 'About' }
            ]
        }
    ]
});

// Handle menu clicks
web.events.onAppMenuItemClick = async (menuId) => {
    if (menuId === 'file.exit') {
        await web.app.close();
    } else if (menuId === 'file.open') {
        const file = await web.dialogs.openFile();
        if (file) await openFile(file);
    }
};

Advanced example

async function createApplicationMenu() {
    await web.appMenu.createMenu({
        items: [
            {
                id: 'file',
                caption: 'File',
                items: [
                    { id: 'file.new', caption: 'New', enabled: true },
                    { id: 'file.open', caption: 'Open...', enabled: true },
                    { id: 'file.save', caption: 'Save', enabled: false },
                    { id: 'file.saveAs', caption: 'Save As...', enabled: true },
                    { separator: true },
                    { id: 'file.recent', caption: 'Recent Files', items: [] },
                    { separator: true },
                    { id: 'file.exit', caption: 'Exit' }
                ]
            },
            {
                id: 'edit',
                caption: 'Edit',
                items: [
                    { id: 'edit.undo', caption: 'Undo', enabled: false },
                    { id: 'edit.redo', caption: 'Redo', enabled: false },
                    { separator: true },
                    { id: 'edit.cut', caption: 'Cut' },
                    { id: 'edit.copy', caption: 'Copy' },
                    { id: 'edit.paste', caption: 'Paste' }
                ]
            },
            {
                id: 'view',
                caption: 'View',
                items: [
                    { id: 'view.fullscreen', caption: 'Fullscreen' },
                    { id: 'view.zoom', caption: 'Zoom', items: [
                        { id: 'view.zoom.in', caption: 'Zoom In' },
                        { id: 'view.zoom.out', caption: 'Zoom Out' },
                        { id: 'view.zoom.reset', caption: 'Reset Zoom' }
                    ]}
                ]
            },
            {
                id: 'help',
                caption: 'Help',
                items: [
                    { id: 'help.docs', caption: 'Documentation' },
                    { id: 'help.updates', caption: 'Check for Updates' },
                    { separator: true },
                    { id: 'help.about', caption: 'About' }
                ]
            }
        ]
    });
}

// Handle all menu clicks
web.events.onAppMenuItemClick = async (menuId) => {
    switch (menuId) {
        case 'file.new':
            await createNewDocument();
            break;
        case 'file.open':
            const file = await web.dialogs.openFile();
            if (file) await openDocument(file);
            break;
        case 'file.exit':
            await web.app.close();
            break;
        case 'view.fullscreen':
            await web.app.enterFullScreen();
            break;
        case 'help.about':
            await web.app.showAbout();
            break;
    }
};

Use Cases

• Create custom File, Edit, View, Help menus
• Replace default menu with application-specific options
• Add nested submenus for complex operations
• Include separators to organize menu items
• Enable/disable menu items based on application state
• Create context-aware menus
• Implement standard application menu patterns
• Add keyboard shortcuts to menu items

Error Handling

Rejects promise if menu creation fails. Always provide valid menu structure.

try {
    await web.appMenu.createMenu({
        items: menuStructure
    });
    console.log('Menu created successfully');
} catch (error) {
    console.error('Failed to create menu:', error);
}

Performance Tips

• Create menu once at startup
• Use updateMenu() to modify existing items
• Keep menu structure simple for better performance
• Use separators to organize related items
• Provide clear, concise menu captions

Related Methods

• web.appMenu.updateMenu() - Update existing menu items
• web.events.onAppMenuItemClick - Handle menu clicks

Notes

• Replaces the entire application menu
• Menu items can be nested (submenus)
• Use separator: true for divider lines
• Menu IDs must be unique
• Click handler set via web.events.onAppMenuItemClick
• Menu structure is JSON-based