nsh/desktop

nsh/desktop enthält, was es nur auf Desktops gibt: das Fenster und seine Titelleiste, das Anwendungsmenü und Kontextmenüs. Es funktioniert unter macOS, Windows und Linux. Rust-Code findet dasselbe in nsh_core::element::desktop: die Funktionen des Fensters (set_title, set_title_bar, title_bar, minimize, … close_window), das Anwendungsmenü und Kontextmenüs (set_application_menu, popup_menu, aufgebaut aus MenuItem-Objekten) und markiert ziehbare Views mit .window_drag(true); TSX importiert nsh/desktop. Das Modul lässt sich auf jeder Plattform importieren, sodass ein Bundle überall läuft: Unter iOS und Android tun seine Funktionen nichts, und isAvailable zeigt an, ob Fenster und Menüs vorhanden sind.

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, wo die Fenster- und Menü-APIs dieses Moduls funktionieren: unter macOS, Windows und Linux; anderswo false. Rust: os().is_desktop().

platform.desktop ist die umfassendere Prüfung auf Desktop-Verhalten (desktop={{…}}-Props, platform.select({ desktop })): Sie gilt auch in Browsern im Desktop-Idiom, die im eigenen Fenster des Browsers laufen. Machen Sie Desktop-Layout, Dichte und Eingabe von platform.desktop abhängig und Aufrufe von Window und Menu von isAvailable.

#Fenster

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

Die Rust-Spalte nennt die Funktionen von nsh_core::element::desktop.

Die Fenstergröße wird unter macOS, Windows und Linux unterstützt; Positionierung und Ebenen unter macOS und Windows. Unter Linux steuert der Fenstermanager Platzierung und Stapelreihenfolge. In GPUI-Apps legt setFrame die Größe des Fensters fest, und die Plattform platziert es; der Host von GPUI wählt Position und Ebene, wenn er das Fenster öffnet.

Wenn Sie ein Fenster anhand von Inhalt dimensionieren, der mit onLayout gemessen wurde, planen Sie unter macOS und Windows Platz für die Fensterdekoration ein. width und height akzeptieren positive endliche Zahlen; x und y akzeptieren endliche Zahlen. Ungültige Felder behalten ihre vorherigen Werte.

#Eine eigene Titelleiste

Bei ausgeblendeter Titelleiste zeichnet die App ihre eigene Leiste und legt mit .window_drag(true) in Rust und desktop={{ windowDrag: true }} in TSX fest, welche Teile davon das Fenster verschieben:

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

Ein Druck auf eine View mit windowDrag zieht das Fenster so, wie es die Titelleiste des Systems täte: Ein Doppelklick maximiert es (oder bewirkt, was der Benutzer eingestellt hat: unter macOS „Doppelklick auf die Titelleiste eines Fensters“), und unter Windows und Linux öffnet ein Rechtsklick das Fenstermenü.

• Die nächstliegende View, die windowDrag setzt, entscheidet: .window_drag(false) (desktop={{ windowDrag: false }}) hält einen Teil einer ziehbaren View anklickbar.
• Textfelder und Views mit Press- oder Touch-Handlern (onPress, onTouch*, Responder) innerhalb einer ziehbaren View bleiben auch ohne dieses Attribut anklickbar: Das Suchfeld und alle Buttons im obigen Beispiel funktionieren wie gewohnt.
• windowDrag funktioniert auch mit der Titelleiste des Systems: Eine Seitenleiste oder Toolbar kann das Fenster ebenfalls verschieben.

#titleBar

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

Der Bereich der ausgeblendeten Titelleiste in Punkten (reaktiv): ihre height sowie die Breiten, die die Fenstersteuerung des Systems an ihrem left- und right-Ende einnimmt. Richten Sie Ihre Leiste daran aus, damit nichts unter die Steuerelemente gerät. Alle drei Werte sind 0, solange das System seine Titelleiste anzeigt (sowie im Vollbildmodus und außerhalb von Desktops). Rust: title_bar() -> Edges<Points>, dessen top die Höhe ist und dessen left und right die Breiten der Steuerelemente sind; das Lesen abonniert Änderungen.

Unter Windows werden die Caption-Buttons von NSH im Stil von Windows 11 gezeichnet und folgen dem Erscheinungsbild der App; beim Überfahren des Maximieren-Buttons erscheinen die Snap-Layouts von Windows 11. Das Fenster behält auf jeder Plattform seine Resize-Ränder, seinen Schatten und seine abgerundeten Ecken.

#Menü

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

In Rust nimmt set_application_menu(items) ein Vec<MenuItem> entgegen (None stellt das Standardmenü der Plattform wieder her), und popup_menu(items) (am Mauszeiger) und popup_menu_at(items, at) geben ein Answer<()> zurück, das eintrifft, sobald das Menü schließt (darauf zu warten ist optional). Der Handler eines Eintrags läuft unter dem Owner, der das Menü festgelegt hat, solange dieser Owner lebt.

Rufen Sie setApplicationMenu erneut auf, um das Menü zu ändern. Innerhalb eines effect folgt es den Signals, die es liest: Ein Häkchen oder ein deaktivierter Zustand, der vom App-Zustand abhängt, bleibt aktuell.

#Menüeinträge

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

Einträge vom Typ null, undefined und false werden ausgelassen, sodass cond && { … } in einer Liste funktioniert.

In Rust ist ein Eintrag MenuItem::new(label), MenuItem::role(role), MenuItem::separator() oder MenuItem::submenu(label, items), wobei die Felder als Methoden vorliegen: .shortcut("mod+n") (bei einem ungültigen Tastenkürzel löst es einen Panic aus, mit der richtigen Schreibweise), .shortcut_when(When::Auto), .disabled(true), .checked(on), .on_select(f) und .label(..) für den Eintrag einer Rolle.

Modifikatoren:

Verwenden Sie mod für eigene Tastenkürzel einer App: Es ist die Taste, die die Apps jeder Plattform dafür nutzen (⌘N unter macOS, Strg+N unter Windows und Linux), sodass eine Schreibweise überall passt. Die Windows-Taste und Super gehören größtenteils dem System (Win+E, die GNOME-Übersicht), daher ist cmd außerhalb von macOS selten die richtige Wahl.

Rollen:

Der Eintrag einer Rolle hat die Beschriftung und das Tastenkürzel der Plattform, sofern er keine eigenen setzt (macOS ergänzt bei about, hide und quit den Namen der App).

Menü-Tastenkürzel haben Vorrang, wie in nativen Apps: Eine Taste, die ein Eintrag belegt, erreicht weder das fokussierte Textfeld noch die eigenen Tasten von NSH. Nur ein Binding von keymap mit demselben Tastenanschlag kommt vor ihnen. Geben Sie die Bearbeitungskürzel (mod+c, mod+v, mod+x, mod+a, mod+z) daher nur den Bearbeiten-Rollen, die sie an das Textfeld weiterreichen, und vermeiden Sie Tasten ohne Modifikator (escape, die Pfeile, Buchstaben), die sie Textfeldern und der Zurück-Navigation wegnehmen würden. Im GPUI-Backend lässt when: "auto" einen Eintrag eine Taste mit Textfeldern teilen: delete oder mod+z wählen den Eintrag, solange kein Feld den Fokus hat, und bearbeiten den Text, solange eines ihn hat.

Im GPUI-Backend sieht eine native Komponente mit Tastaturfokus jede Taste zuerst. Eine Taste, die sie selbst verarbeitet, erreicht weder die Keymap noch das Menü. Eine Taste, die sie durchlässt, erreicht die Keymap, als hätte ein Textfeld den Fokus, und danach das Menü.

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" },
      ],
    },
  ]);
});

Ein Kontextmenü, ausgelöst durch den Druck auf einen Button:

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>