nsh/desktop

nsh/desktop reúne o que só os desktops têm: a janela e sua barra de título, o menu do aplicativo e os menus de contexto. Funciona no macOS, no Windows e no Linux. O código Rust encontra o mesmo em nsh_core::element::desktop: as funções da janela (set_title, set_title_bar, title_bar, minimize, … close_window), o menu do aplicativo e os menus de contexto (set_application_menu, popup_menu, compostos por MenuItem) e marca as views arrastáveis com .window_drag(true); TSX importa nsh/desktop. O módulo pode ser importado em todas as plataformas, então um único bundle roda em qualquer lugar: no iOS e no Android suas funções não fazem nada, e isAvailable informa se a janela e os menus existem.

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 onde as APIs de janela e de menu deste módulo funcionam: macOS, Windows e Linux; false nos demais. Rust: os().is_desktop().

platform.desktop é a verificação mais ampla para o comportamento de desktop (props desktop={{…}}, platform.select({ desktop })): ela também vale em navegadores no idioma desktop, que rodam na janela do próprio navegador. Condicione o layout, a densidade e a entrada de desktop a platform.desktop, e as chamadas de Window e Menu a isAvailable.

#Janela

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

A coluna Rust indica as funções de nsh_core::element::desktop.

O dimensionamento de janela é suportado no macOS, no Windows e no Linux; o posicionamento e os níveis, no macOS e no Windows. O gerenciador de janelas do Linux controla o posicionamento e o empilhamento. Em apps GPUI, setFrame define o tamanho da janela e a plataforma a posiciona; o host do GPUI escolhe sua posição e seu nível ao abrir a janela.

Ao dimensionar uma janela a partir de conteúdo medido com onLayout, reserve espaço para as decorações da janela no macOS e no Windows. width e height aceitam números finitos positivos; x e y aceitam números finitos. Campos inválidos mantêm seus valores anteriores.

#Uma barra de título própria

Com a barra de título oculta, o app desenha sua própria barra e indica quais partes dela movem a janela, com .window_drag(true) em Rust e desktop={{ windowDrag: true }} em 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>
  );
}

Pressionar uma view com windowDrag arrasta a janela como a barra de título do sistema faria: um clique duplo a maximiza (ou faz o que o usuário definiu: no macOS, “Dar um clique duplo na barra de título da janela para”), e no Windows e no Linux um clique com o botão direito abre o menu da janela.

• A view mais próxima que define windowDrag decide: .window_drag(false) (desktop={{ windowDrag: false }}) mantém clicável uma parte de uma view arrastável.
• Campos de texto e views com handlers de pressionar ou tocar (onPress, onTouch*, responders) dentro de uma view arrastável continuam clicáveis sem isso: o campo de busca e quaisquer botões do exemplo acima funcionam normalmente.
• windowDrag também funciona com a barra de título do sistema: uma barra lateral ou uma barra de ferramentas também pode mover a janela.

#titleBar

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

A área da barra de título oculta, em pontos (reativa): seu height e as larguras que os controles de janela do sistema ocupam nas extremidades left e right. Monte o layout da sua barra com ela para que nada fique sob os controles. Os três valores são 0 enquanto o sistema mostra sua barra de título (e em tela cheia, e fora de desktops). Rust: title_bar() -> Edges<Points>, cujo top é a altura e cujos left e right são as larguras dos controles; lê-lo assina as mudanças.

No Windows, os botões de legenda são desenhados pelo NSH no estilo do Windows 11 e seguem a aparência do app; passar o mouse sobre o botão de maximizar mostra os layouts de encaixe do Windows 11. A janela mantém suas bordas de redimensionamento, sua sombra e seus cantos arredondados em todas as plataformas.

#Menu

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

Em Rust, set_application_menu(items) recebe um Vec<MenuItem> (None restaura o menu padrão da plataforma), e popup_menu(items) (no ponteiro) e popup_menu_at(items, at) retornam um Answer<()> que chega quando o menu fecha (aguardá-lo é opcional). O handler de um item roda sob o owner que definiu o menu, enquanto esse owner viver.

Chame setApplicationMenu de novo para mudar o menu. Dentro de um effect, ele acompanha os signals que lê: uma marca de seleção ou um estado desabilitado que depende do estado do app se mantém atualizado.

#Itens de menu

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

Itens null, undefined e false são ignorados, então cond && { … } funciona em uma lista.

Em Rust, um item é MenuItem::new(label), MenuItem::role(role), MenuItem::separator() ou MenuItem::submenu(label, items), com os campos como métodos: .shortcut("mod+n") (entra em panic com um atalho inválido, indicando a grafia correta), .shortcut_when(When::Auto), .disabled(true), .checked(on), .on_select(f) e .label(..) para o item de uma role.

Modificadores:

Use mod para os atalhos próprios de um app: é a tecla que os apps de cada plataforma usam para eles (⌘N no macOS, Ctrl+N no Windows e no Linux), então uma única grafia serve em todo lugar. A tecla Windows e Super pertencem em grande parte ao sistema (Win+E, a visão geral do GNOME), então cmd raramente é a escolha certa fora do macOS.

Roles:

Um item de role tem o rótulo e o atalho da plataforma, a menos que defina os seus (o macOS adiciona o nome do app a about, hide e quit).

Os atalhos de menu vêm primeiro, como nos apps nativos: uma tecla que um item usa nunca chega ao campo de texto em foco nem às teclas do próprio NSH. Apenas um binding de keymap com o mesmo atalho vem antes deles. Portanto, dê os atalhos de edição (mod+c, mod+v, mod+x, mod+a, mod+z) apenas às roles de edição, que os repassam ao campo de texto, e evite teclas sem modificador (escape, as setas, letras), que as tirariam dos campos de texto e da navegação de volta. No backend GPUI, when: "auto" permite que um item compartilhe uma tecla com campos de texto: delete ou mod+z escolhem o item enquanto nenhum campo tem o foco e editam o texto enquanto um tem.

No backend GPUI, um componente nativo com o foco do teclado vê cada tecla primeiro. Uma tecla que ele trata por conta própria nunca chega ao keymap nem ao menu. Uma tecla que ele deixa passar chega ao keymap como se um campo de texto estivesse em foco, e depois ao 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" },
      ],
    },
  ]);
});

Um menu de contexto, a partir do pressionar de um botão:

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>