nsh/desktop

nsh/desktop raccoglie ciò che esiste solo sui desktop: la finestra e la sua barra del titolo, il menu dell’applicazione e i menu contestuali. Funziona su macOS, Windows e Linux. Il codice Rust trova le stesse cose in nsh_core::element::desktop: le funzioni della finestra (set_title, set_title_bar, title_bar, minimize, … close_window), il menu dell’applicazione e i menu contestuali (set_application_menu, popup_menu, composti da MenuItem), e contrassegna le view trascinabili con .window_drag(true); TSX importa nsh/desktop. Il modulo può essere importato su ogni piattaforma, quindi un solo bundle funziona ovunque: su iOS e Android le sue funzioni non fanno nulla, e isAvailable indica se la finestra e i menu sono presenti.

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 dove le API di finestra e menu di questo modulo funzionano: macOS, Windows e Linux; false altrove. Rust: os().is_desktop().

platform.desktop è il controllo più ampio per il comportamento desktop (proprietà desktop={{…}}, platform.select({ desktop })): vale anche nei browser nell’idioma desktop, che girano nella finestra del browser stesso. Condiziona layout, densità e input desktop con platform.desktop, e le chiamate a Window e Menu con isAvailable.

#Finestra

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;
};

La colonna Rust indica i nomi delle funzioni di nsh_core::element::desktop.

Il ridimensionamento della finestra è supportato su macOS, Windows e Linux; posizionamento e livelli su macOS e Windows. Il window manager di Linux controlla posizionamento e sovrapposizione. Nelle app GPUI, setFrame imposta la dimensione della finestra e la piattaforma la posiziona; l’host di GPUI sceglie posizione e livello all’apertura della finestra.

Quando dimensioni una finestra a partire dal contenuto misurato con onLayout, lascia spazio per le decorazioni della finestra su macOS e Windows. width e height accettano numeri finiti positivi; x e y accettano numeri finiti. I campi non validi mantengono i valori precedenti.

#Una barra del titolo personalizzata

Con la barra del titolo nascosta, l’app disegna una propria barra e indica quali sue parti spostano la finestra, con .window_drag(true) in Rust e 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>
  );
}

Premere una view con windowDrag trascina la finestra come farebbe la barra del titolo di sistema: un doppio clic la ingrandisce (o fa ciò che l’utente ha impostato: su macOS, “Fai doppio clic sulla barra del titolo di una finestra per”), e su Windows e Linux un clic destro apre il menu della finestra.

• La view più vicina che imposta windowDrag decide: .window_drag(false) (desktop={{ windowDrag: false }}) mantiene cliccabile una parte di una view trascinabile.
• I campi di testo e le view con gestori di pressione o tocco (onPress, onTouch*, responder) dentro una view trascinabile restano cliccabili di per sé: il campo di ricerca e gli eventuali pulsanti nell’esempio sopra funzionano normalmente.
• windowDrag funziona anche con la barra del titolo di sistema: anche una sidebar o una toolbar può spostare la finestra.

#titleBar

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

L’area della barra del titolo nascosta, in punti (reattiva): la sua height, e le larghezze occupate dai controlli di finestra del sistema alle estremità left e right. Usala per disporre la tua barra in modo che nulla finisca sotto i controlli. Tutti e tre valgono 0 mentre il sistema mostra la sua barra del titolo (e a schermo intero, e fuori dai desktop). Rust: title_bar() -> Edges<Points>, il cui top è l’altezza e left e right le larghezze dei controlli; leggerlo sottoscrive le modifiche.

Su Windows i caption button sono disegnati da NSH nello stile di Windows 11 e seguono l’aspetto dell’app; passando il mouse sul pulsante di ingrandimento compaiono gli snap layout di Windows 11. La finestra mantiene bordi di ridimensionamento, ombra e angoli arrotondati su ogni piattaforma.

#Menu

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

In Rust, set_application_menu(items) accetta un Vec<MenuItem> (None ripristina il menu predefinito della piattaforma), e popup_menu(items) (al puntatore) e popup_menu_at(items, at) restituiscono un Answer<()> che arriva alla chiusura del menu (attenderlo è facoltativo). Il gestore di una voce viene eseguito sotto l’owner che ha impostato il menu, finché quell’owner è vivo.

Chiama di nuovo setApplicationMenu per cambiare il menu. Dentro un effect segue i signal che legge: un segno di spunta o uno stato disabilitato che dipende dallo stato dell’app resta aggiornato.

#Voci di menu

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

Le voci null, undefined e false vengono omesse, quindi cond && { … } funziona in una lista.

In Rust, una voce è MenuItem::new(label), MenuItem::role(role), MenuItem::separator() o MenuItem::submenu(label, items), con i campi come metodi: .shortcut("mod+n") (va in panic con una scorciatoia non valida, indicando la grafia corretta), .shortcut_when(When::Auto), .disabled(true), .checked(on), .on_select(f), e .label(..) per la voce di un ruolo.

Modificatori:

Usa mod per le scorciatoie proprie dell’app: è il tasto che le app di ogni piattaforma usano per esse (⌘N su macOS, Ctrl+N su Windows e Linux), quindi un’unica grafia va bene ovunque. Il tasto Windows e Super appartengono per lo più al sistema (Win+E, la panoramica di GNOME), quindi cmd è raramente la scelta giusta fuori da macOS.

Ruoli:

Una voce con ruolo ha l’etichetta e la scorciatoia della piattaforma a meno che non ne imposti di proprie (macOS aggiunge il nome dell’app a about, hide e quit).

Le scorciatoie di menu hanno la precedenza, come nelle app native: un tasto preso da una voce non raggiunge mai il campo di testo con il focus né i tasti propri di NSH. Solo un binding di keymap con la stessa combinazione ha la precedenza su di esse. Quindi assegna le scorciatoie di modifica (mod+c, mod+v, mod+x, mod+a, mod+z) solo ai ruoli di modifica, che le passano al campo di testo, ed evita i tasti senza modificatore (escape, le frecce, le lettere), che li toglierebbero ai campi di testo e alla navigazione indietro. Nel backend GPUI, when: "auto" permette a una voce di condividere un tasto con i campi di testo: delete o mod+z scelgono la voce quando nessun campo ha il focus e modificano il testo quando ce l’ha uno.

Nel backend GPUI, un componente nativo con il focus della tastiera vede ogni tasto per primo. Un tasto che gestisce da sé non raggiunge mai la keymap né il menu. Un tasto che lascia passare raggiunge la keymap come se un campo di testo avesse il focus, poi il 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" },
      ],
    },
  ]);
});

Un menu contestuale, dalla pressione di un pulsante:

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>