nsh/desktop

nsh/desktop holds what only desktops have: the window and its title bar, the application menu and context menus. It works on macOS, Windows and Linux. Rust code finds the same in nsh_core::element::desktop: the window’s functions (set_title, set_title_bar, title_bar, minimize, … close_window), the application menu and context menus (set_application_menu, popup_menu, made of MenuItems), and marks draggable views with .window_drag(true); TSX imports nsh/desktop. The module can be imported on every platform, so one bundle runs everywhere: on iOS and Android its functions do nothing, and isAvailable tells you whether its window and menus are there.

use nsh_core::{
    desktop::{MenuRole, TitleBarStyle},
    element::desktop::{
        MenuItem, close_window, popup_menu, set_application_menu, set_title, set_title_bar, title_bar,
    },
    prelude::*,
};

import { isAvailable, Menu, titleBar, Window } from "nsh/desktop";

#isAvailable

const isAvailable: boolean;

true where this module’s window and menu APIs work: macOS, Windows and Linux; false elsewhere. Rust: os().is_desktop().

platform.desktop is the broader check for desktop behavior (desktop={{…}} props, platform.select({ desktop })): it also holds in browsers in the desktop idiom, which run in the browser’s own window. Gate desktop layout, density and input on platform.desktop, and calls of Window and Menu on isAvailable.

#Window

const Window: {
  setTitle(title: string): void;
  setTitleBar(options: { style: "default" | "hidden"; height?: number }): void;
  setMenuBar(mode: "shown" | "autoHide"): void;
  minimize(): void;
  toggleMaximize(): void;
  toggleFullScreen(): void;
  setFrame(frame: {
    origin?: Partial<Point>;
    size?: Partial<Size>;
    animated?: boolean;
  }): void;
  setLevel(level: "normal" | "floating" | "desktopIcon"): void;
  orderFront(): void;
  close(): void;
};

The Rust column names the functions of nsh_core::element::desktop.

Window sizing is supported on macOS, Windows and Linux; positioning and levels on macOS and Windows. Linux’s window manager controls placement and stacking. In GPUI apps, setFrame sets the window’s size and the platform places it; GPUI’s host chooses its position and level when opening the window.

When sizing a window from content measured with onLayout, allow room for window decorations on macOS and Windows. width and height accept positive finite numbers; x and y accept finite numbers. Invalid fields keep their previous values.

#A title bar of your own

With the title bar hidden, the app draws its own bar and says which parts of it move the window, with .window_drag(true) in Rust and desktop={{ windowDrag: true }} in TSX:

use nsh_core::{
    desktop::TitleBarStyle,
    element::{desktop::{set_title_bar, title_bar}}, prelude::*,
};

#[component]
fn TitleBar() -> impl IntoElement {
    set_title_bar(TitleBarStyle::Hidden, Some(px(40.0))); // a bar 40 points tall
    view()
        .window_drag(true)
        .h(move || match title_bar().top {
            top if top > px(0.0) => top,
            _ => px(40.0),
        })
        .pl(move || title_bar().left + px(8.0)) // macOS's traffic lights
        .pr(move || title_bar().right + px(8.0)) // the caption buttons on Windows, GTK's buttons
        .flex_row()
        .items_center()
        .child(text("My App"))
        .child(view().flex_1())
        .child(input().placeholder("Search").w(px(180.0)))
}

import { Text, View } from "nsh";
import { Input } from "nsh/base";
import { titleBar, Window } from "nsh/desktop";

Window.setTitleBar({ style: "hidden", height: 40 }); // a bar 40 points tall

function TitleBar() {
  return (
    <View
      desktop={{ windowDrag: true }}
      style={{
        height: titleBar().height || 40,
        paddingLeft: titleBar().left + 8, // macOS's traffic lights
        paddingRight: titleBar().right + 8, // the caption buttons on Windows, GTK's buttons
        flexDirection: "row",
        alignItems: "center",
      }}
    >
      <Text>My App</Text>
      <View style={{ flex: 1 }} />
      <Input placeholder="Search" style={{ width: 180 }} />
    </View>
  );
}

Pressing a view with windowDrag drags the window as the system’s title bar would: a double click maximizes it (or does what the user set: on macOS, “Double-click a window’s title bar to”), and on Windows and Linux a right click opens the window menu. In GPUI apps on Linux, a right click goes to the app instead when the draggable view under it, or a view inside that one, listens to onContextMenu; listeners on views around it, the root included, do not take the window menu away.

• The nearest view that sets windowDrag decides: .window_drag(false) (desktop={{ windowDrag: false }}) keeps a part of a draggable view clickable.
• Text fields and views with press or touch handlers (onPress, onTouch*, responders) inside a draggable view stay clickable without it: the search field and any buttons in the example above work as usual.
• windowDrag also works with the system’s title bar: a sidebar or toolbar can move the window too.

#titleBar

const titleBar: Accessor<{ height: number; left: number; right: number }>;

The hidden title bar’s area, in points (reactive): its height, and the widths the system’s window controls take at its left and right ends. Lay your bar out with it so that nothing goes under the controls. All three are 0 while the system shows its title bar (and in full screen, and off desktops). Rust: title_bar() -> Edges<Points>, whose top is the height and left and right the controls’ widths; reading it subscribes to changes.

On Windows the caption buttons are drawn by NSH in Windows 11’s style and follow the app’s appearance; hovering the maximize button shows Windows 11’s snap layouts. The window keeps its resize borders, shadow and rounded corners on every platform.

#Menu

const Menu: {
  setApplicationMenu(items: MenuItem[] | null): void;
  popup(items: MenuItem[], at?: Point): Promise<void>;
};

In Rust, set_application_menu(items) takes a Vec<MenuItem> (None restores the platform’s default menu), and popup_menu(items) (at the pointer) and popup_menu_at(items, at) return an Answer<()> that comes once the menu closes (awaiting it is optional). An item’s handler runs under the owner that set the menu, while that owner lives.

Call setApplicationMenu again to change the menu. Inside an effect it follows the signals it reads: a check mark or a disabled state that depends on app state stays current.

#Menu items

type MenuItem =
  | { type: "separator" }
  | {
      label?: string;
      role?: MenuRole;
      shortcut?: string;
      when?: "always" | "auto" | "notEditing";
      disabled?: boolean;
      checked?: boolean;
      onSelect?: () => void;
      submenu?: MenuItem[];
    };

null, undefined and false items are left out, so cond && { … } works in a list.

In Rust, an item is MenuItem::new(label), MenuItem::role(role), MenuItem::separator() or MenuItem::submenu(label, items), with the fields as methods: .shortcut("mod+n") (it panics on an invalid shortcut, with the right spelling), .shortcut_when(When::Auto), .disabled(true), .checked(on), .on_select(f), and .label(..) for a role’s item.

Modifiers:

Use mod for an app’s own shortcuts: it is the key each platform’s apps use for them (⌘N on macOS, Ctrl+N on Windows and Linux), so one spelling fits everywhere. The Windows key and Super mostly belong to the system (Win+E, the GNOME overview), so cmd is rarely right outside macOS.

Roles:

A role’s item has the platform’s label and shortcut unless it sets its own (macOS adds the app’s name to about, hide and quit).

Menu shortcuts come first, as in native apps: a key an item takes never reaches the focused text field or NSH’s own keys. Only a binding of keymap of the same keystroke comes before them. So give the editing shortcuts (mod+c, mod+v, mod+x, mod+a, mod+z) only to the edit roles, which pass them to the text field, and avoid keys without a modifier (escape, the arrows, letters), which would take them from text fields and from back navigation. On the GPUI backend, when: "auto" lets an item share a key with text fields: delete or mod+z choose the item while no field has the focus and edit the text while one has it.

On the GPUI backend, a native component with the keyboard focus sees each key first. A key it handles itself never reaches the keymap or the menu. A key it lets through reaches the keymap as if a text field were focused, then the menu.

use nsh_core::{
    desktop::MenuRole,
    element::desktop::{MenuItem, set_application_menu},
    platform::Os,
    prelude::*,
};

#[component]
fn AppMenu() -> impl IntoElement {
    let mac = os() == Os::MacOs;
    let wrap = signal(true);
    effect(move || {
        let mut menus = Vec::new();
        if mac {
            menus.push(MenuItem::submenu("My App", [
                MenuItem::role(MenuRole::About),
                MenuItem::separator(),
                MenuItem::role(MenuRole::Hide),
                MenuItem::role(MenuRole::HideOthers),
                MenuItem::separator(),
                MenuItem::role(MenuRole::Quit),
            ]));
        }
        let mut file = vec![
            MenuItem::new("New").shortcut("mod+n").on_select(create_document),
            MenuItem::new("Open…").shortcut("mod+o").on_select(open_document),
        ];
        if !mac {
            file.push(MenuItem::separator());
            file.push(MenuItem::role(MenuRole::Quit).label("Exit"));
        }
        menus.push(MenuItem::submenu("File", file));
        menus.push(MenuItem::submenu("Edit", [
            MenuItem::role(MenuRole::Undo),
            MenuItem::role(MenuRole::Redo),
            MenuItem::separator(),
            MenuItem::role(MenuRole::Cut),
            MenuItem::role(MenuRole::Copy),
            MenuItem::role(MenuRole::Paste),
        ]));
        menus.push(MenuItem::submenu("View", [
            MenuItem::new("Word Wrap")
                .checked(wrap.get())
                .on_select(move || wrap.update(|w| *w = !*w)),
            MenuItem::role(MenuRole::ToggleFullScreen),
        ]));
        set_application_menu(menus);
    });
    view()
}

import { effect, signal } from "nsh";
import { platform } from "nsh";
import { Menu } from "nsh/desktop";

const mac = platform.os === "macos";
const wrap = signal(true);

effect(() => {
  Menu.setApplicationMenu([
    mac && {
      label: "My App",
      submenu: [{ role: "about" }, { type: "separator" }, { role: "hide" }, { role: "hideOthers" }, { type: "separator" }, { role: "quit" }],
    },
    {
      label: "File",
      submenu: [
        { label: "New", shortcut: "mod+n", onSelect: () => createDocument() },
        { label: "Open…", shortcut: "mod+o", onSelect: () => openDocument() },
        !mac && { type: "separator" },
        !mac && { role: "quit", label: "Exit" },
      ],
    },
    {
      label: "Edit",
      submenu: [{ role: "undo" }, { role: "redo" }, { type: "separator" }, { role: "cut" }, { role: "copy" }, { role: "paste" }],
    },
    {
      label: "View",
      submenu: [
        { label: "Word Wrap", checked: wrap(), onSelect: () => wrap.update((w) => !w) },
        { role: "toggleFullScreen" },
      ],
    },
  ]);
});

A context menu, from a button’s press:

text("More").on_press(|| {
    let _ = popup_menu(vec![
        MenuItem::new("Rename").on_select(rename),
        MenuItem::new("Duplicate").on_select(duplicate),
        MenuItem::separator(),
        MenuItem::new("Delete").on_select(remove),
    ]);
})

<View
  onPress={() =>
    Menu.popup([
      { label: "Rename", onSelect: rename },
      { label: "Duplicate", onSelect: duplicate },
      { type: "separator" },
      { label: "Delete", onSelect: remove },
    ])
  }
>
  <Text>More</Text>
</View>