updateMenu

Category: Application Menu

Namespace: web.appMenu.updateMenu

Description

Update existing menu items by enabling/disabling them or changing their properties. This allows dynamic menu updates without recreating the entire menu structure.

Syntax

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

Parameters

• items (optional) - Array of menu item updates. Each item can have:
  • id (string) - ID of the menu item to update
  • enabled (boolean) - Enable or disable the menu item
  • caption (string) - Update the menu item text
  • visible (boolean) - Show or hide the menu item

Returns

Promise<boolean> - Returns true when menu is updated

Example

Simple example

await web.appMenu.updateMenu({
    items: [
        { id: 'file.save', enabled: true }
    ]
});

Practical example

// Enable Save after document is modified
let isModified = false;

document.addEventListener('input', async () => {
    if (!isModified) {
        isModified = true;
        await web.appMenu.updateMenu({
            items: [
                { id: 'file.save', enabled: true },
                { id: 'edit.undo', enabled: true }
            ]
        });
    }
});

Advanced example

// Update menu based on application state
async function updateMenuState(state) {
    const updates = [];
    
    // File menu updates
    updates.push({ id: 'file.save', enabled: state.hasUnsavedChanges });
    updates.push({ id: 'file.saveAs', enabled: state.hasDocument });
    
    // Edit menu updates
    updates.push({ id: 'edit.undo', enabled: state.canUndo });
    updates.push({ id: 'edit.redo', enabled: state.canRedo });
    updates.push({ id: 'edit.cut', enabled: state.hasSelection });
    updates.push({ id: 'edit.copy', enabled: state.hasSelection });
    updates.push({ id: 'edit.paste', enabled: state.canPaste });
    
    // View menu updates
    if (state.isFullscreen) {
        updates.push({ id: 'view.fullscreen', caption: 'Exit Fullscreen' });
    } else {
        updates.push({ id: 'view.fullscreen', caption: 'Enter Fullscreen' });
    }
    
    await web.appMenu.updateMenu({ items: updates });
}

// Update menu when state changes
document.addEventListener('selectionchange', async () => {
    const hasSelection = window.getSelection().toString().length > 0;
    await web.appMenu.updateMenu({
        items: [
            { id: 'edit.cut', enabled: hasSelection },
            { id: 'edit.copy', enabled: hasSelection }
        ]
    });
});

Use Cases

• Enable/disable menu items based on application state
• Update menu captions dynamically
• Show/hide menu items conditionally
• Enable Save after document modification
• Enable Undo/Redo based on history
• Enable Cut/Copy when text is selected
• Update menu without recreating entire structure
• Reflect application state in menu

Error Handling

Returns false if update fails. Menu items must exist (created with createMenu()).

const success = await web.appMenu.updateMenu({
    items: [
        { id: 'file.save', enabled: true }
    ]
});

if (!success) {
    console.error('Failed to update menu');
}

Performance Tips

• Batch multiple updates in one call
• Only update items that changed
• Use for dynamic state changes
• More efficient than recreating menu
• Update menu items as needed, not on every change

Related Methods

• web.appMenu.createMenu() - Create initial menu structure
• web.events.onAppMenuItemClick - Handle menu clicks

Notes

• Menu must be created first with createMenu()
• Only updates specified properties
• Menu IDs must match those in createMenu()
• More efficient than recreating entire menu
• Can update multiple items at once
• Changes take effect immediately