Context Menu Quick Reference

This guide provides a quick overview of how to create and display a context menu using our system.

---

ContextMenuItem Type

Define each menu item using the

ContextMenuItem

type:

type ContextMenuItem = {
  label?: string;
  type?: "separator" | "normal" | "submenu" | "checkbox" | "radio";
  role?: string; // Electron role (optional)
  click?: () => void; // Callback for item selection (not needed if role is set)
  submenu?: ContextMenuItem[]; // For nested menus
  checked?: boolean; // For checkbox or radio items
  visible?: boolean;
  enabled?: boolean;
  sublabel?: string;
};

---

Import and Show the Menu

Import the context menu module:

import { ContextMenuModel } from "@/app/store/contextmenu";

To display the context menu, call:

ContextMenuModel.getInstance().showContextMenu(menu, event);

• menu: An array of

  ContextMenuItem

  .
• event: The mouse event that triggered the context menu (typically from an onContextMenu handler).

---

Basic Example

A simple context menu with a separator:

const menu: ContextMenuItem[] = [
  {
    label: "New File",
    click: () => {
      /* create a new file */
    },
  },
  {
    label: "New Folder",
    click: () => {
      /* create a new folder */
    },
  },
  { type: "separator" },
  {
    label: "Rename",
    click: () => {
      /* rename item */
    },
  },
];

ContextMenuModel.getInstance().showContextMenu(menu, e);

---

Example with Submenu and Checkboxes

Toggle settings using a submenu with checkbox items:

const isClearOnStart = true; // Example setting

const menu: ContextMenuItem[] = [
  {
    label: "Clear Output On Restart",
    submenu: [
      {
        label: "On",
        type: "checkbox",
        checked: isClearOnStart,
        click: () => {
          // Set the config to enable clear on restart
        },
      },
      {
        label: "Off",
        type: "checkbox",
        checked: !isClearOnStart,
        click: () => {
          // Set the config to disable clear on restart
        },
      },
    ],
  },
];

ContextMenuModel.getInstance().showContextMenu(menu, e);

---

Editing a Config File Example

Open a configuration file (e.g.,

widgets.json

) in preview mode:

{
    label: "Edit widgets.json",
    click: () => {
        fireAndForget(async () => {
            const path = `${getApi().getConfigDir()}/widgets.json`;
            const blockDef: BlockDef = {
                meta: { view: "preview", file: path },
            };
            await createBlock(blockDef, false, true);
        });
    },
}

---

Summary

• Menu Definition: Use the

  ContextMenuItem

  type.
• Actions: Use

  click

  for actions; use

  submenu

  for nested options.
• Separators: Use

  type: "separator"

  to group items.
• Toggles: Use

  type: "checkbox"

  or

  "radio"

  with the

  checked

  property.
• Displaying: Use

  ContextMenuModel.getInstance().showContextMenu(menu, event)

  to render the menu.

Common Use Cases

File/Folder Operations

Context menus are commonly used for file operations like creating, renaming, and deleting files or folders.

Settings Toggles

Use checkbox menu items to toggle settings on and off, with the

checked

property reflecting the current state.

Nested Options

Use

submenu

to organize related options hierarchically, keeping the top-level menu clean and organized.

Conditional Items

Use the

visible

and

enabled

properties to dynamically show or disable menu items based on the current state.