nsh/desktop

nsh/desktop में वह सब है जो केवल डेस्कटॉप पर होता है: विंडो और उसका टाइटल बार, एप्लिकेशन मेनू और कॉन्टेक्स्ट मेनू। यह macOS, Windows और Linux पर काम करता है। Rust कोड यही nsh_core::element::desktop में पाता है: विंडो के फ़ंक्शन (set_title, set_title_bar, title_bar, minimize, … close_window), एप्लिकेशन मेनू और कॉन्टेक्स्ट मेनू (set_application_menu, popup_menu, जो MenuItem से बने होते हैं), और ड्रैग किए जा सकने वाले व्यू को .window_drag(true) से चिह्नित करना; TSX nsh/desktop इम्पोर्ट करता है। इस मॉड्यूल को हर प्लैटफ़ॉर्म पर इम्पोर्ट किया जा सकता है, इसलिए एक ही बंडल हर जगह चलता है: iOS और Android पर इसके फ़ंक्शन कुछ नहीं करते, और isAvailable बताता है कि इसकी विंडो और मेनू मौजूद हैं या नहीं।

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 वहाँ जहाँ इस मॉड्यूल के विंडो और मेनू API काम करते हैं: macOS, Windows और Linux; अन्यत्र false। Rust: os().is_desktop()।

platform.desktop डेस्कटॉप व्यवहार के लिए व्यापक जाँच है (desktop={{…}} props, platform.select({ desktop })): यह डेस्कटॉप शैली वाले ब्राउज़रों में भी सही होती है, जो ब्राउज़र की अपनी विंडो में चलते हैं। डेस्कटॉप लेआउट, डेंसिटी और इनपुट को platform.desktop पर, तथा Window और Menu के कॉल को isAvailable पर निर्भर रखें।

#विंडो

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

Rust कॉलम nsh_core::element::desktop के फ़ंक्शन के नाम बताता है।

विंडो का आकार बदलना macOS, Windows और Linux पर समर्थित है; स्थिति तय करना और स्तर macOS और Windows पर। Linux पर प्लेसमेंट और स्टैकिंग को विंडो मैनेजर नियंत्रित करता है। GPUI ऐप्स में setFrame विंडो का आकार तय करता है और प्लैटफ़ॉर्म उसे रखता है; विंडो खोलते समय GPUI का होस्ट उसकी स्थिति और स्तर चुनता है।

onLayout से मापी गई सामग्री के आधार पर विंडो का आकार तय करते समय macOS और Windows पर विंडो डेकोरेशन के लिए जगह छोड़ें। width और height धनात्मक परिमित संख्याएँ स्वीकार करते हैं; x और y परिमित संख्याएँ स्वीकार करते हैं। अमान्य फ़ील्ड अपने पिछले मान रखते हैं।

#अपना खुद का टाइटल बार

टाइटल बार छिपा होने पर ऐप अपना बार खुद बनाता है और बताता है कि उसके कौन से हिस्से विंडो को हिलाते हैं, Rust में .window_drag(true) और TSX में desktop={{ windowDrag: true }} से:

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

windowDrag वाले व्यू को दबाने पर विंडो वैसे ही ड्रैग होती है जैसे सिस्टम के टाइटल बार से होती: डबल क्लिक उसे maximize करता है (या वही करता है जो उपयोगकर्ता ने सेट किया है: macOS पर “Double-click a window’s title bar to”), और Windows व Linux पर राइट क्लिक विंडो मेनू खोलता है।

• windowDrag सेट करने वाला सबसे नज़दीकी व्यू तय करता है: .window_drag(false) (desktop={{ windowDrag: false }}) ड्रैग किए जा सकने वाले व्यू के एक हिस्से को क्लिक योग्य रखता है।
• टेक्स्ट फ़ील्ड और प्रेस या टच हैंडलर वाले व्यू (onPress, onTouch*, responders) ड्रैग किए जा सकने वाले व्यू के अंदर उसके बिना भी क्लिक योग्य रहते हैं: ऊपर के उदाहरण में सर्च फ़ील्ड और कोई भी बटन सामान्य रूप से काम करते हैं।
• windowDrag सिस्टम के टाइटल बार के साथ भी काम करता है: साइडबार या टूलबार भी विंडो को हिला सकता है।

#titleBar

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

छिपे हुए टाइटल बार का क्षेत्र, पॉइंट में (reactive): उसकी height, और उसके left और right सिरों पर सिस्टम के विंडो कंट्रोल जितनी चौड़ाई लेते हैं। अपना बार इसी के अनुसार लेआउट करें ताकि कुछ भी कंट्रोल के नीचे न जाए। जब तक सिस्टम अपना टाइटल बार दिखाता है (और फ़ुल स्क्रीन में, और डेस्कटॉप के बाहर), तीनों मान 0 रहते हैं। Rust: title_bar() -> Edges<Points>, जिसका top ऊँचाई है और left व right कंट्रोल की चौड़ाइयाँ; इसे पढ़ने से बदलावों की सदस्यता (subscription) हो जाती है।

Windows पर कैप्शन बटन NSH द्वारा Windows 11 की शैली में बनाए जाते हैं और ऐप की appearance का पालन करते हैं; maximize बटन पर होवर करने से Windows 11 के snap layouts दिखते हैं। विंडो हर प्लैटफ़ॉर्म पर अपने रीसाइज़ बॉर्डर, शैडो और गोल कोने बनाए रखती है।

#मेनू

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

Rust में set_application_menu(items) एक Vec<MenuItem> लेता है (None प्लैटफ़ॉर्म का डिफ़ॉल्ट मेनू बहाल करता है), और popup_menu(items) (पॉइंटर पर) तथा popup_menu_at(items, at) एक Answer<()> लौटाते हैं जो मेनू बंद होने पर आता है (उसे await करना वैकल्पिक है)। किसी आइटम का हैंडलर उस owner के अधीन चलता है जिसने मेनू सेट किया, जब तक वह owner जीवित है।

मेनू बदलने के लिए setApplicationMenu को फिर से कॉल करें। effect के अंदर यह उन signals का अनुसरण करता है जिन्हें यह पढ़ता है: ऐप की स्थिति पर निर्भर चेक मार्क या disabled स्थिति अद्यतन रहती है।

#मेनू आइटम

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

null, undefined और false आइटम छोड़ दिए जाते हैं, इसलिए cond && { … } सूची में काम करता है।

Rust में आइटम MenuItem::new(label), MenuItem::role(role), MenuItem::separator() या MenuItem::submenu(label, items) होता है, और फ़ील्ड मेथड के रूप में होते हैं: .shortcut("mod+n") (अमान्य शॉर्टकट पर यह सही वर्तनी के साथ panic करता है), .shortcut_when(When::Auto), .disabled(true), .checked(on), .on_select(f), और रोल वाले आइटम के लिए .label(..)।

मॉडिफ़ायर:

ऐप के अपने शॉर्टकट के लिए mod का उपयोग करें: यही वह कुंजी है जो हर प्लैटफ़ॉर्म के ऐप उनके लिए इस्तेमाल करते हैं (macOS पर ⌘N, Windows और Linux पर Ctrl+N), इसलिए एक ही वर्तनी हर जगह चलती है। Windows कुंजी और Super ज़्यादातर सिस्टम के हैं (Win+E, GNOME overview), इसलिए macOS के बाहर cmd शायद ही कभी सही होता है।

रोल:

रोल वाले आइटम का लेबल और शॉर्टकट प्लैटफ़ॉर्म का होता है, जब तक वह अपना खुद का सेट न करे (macOS about, hide और quit में ऐप का नाम जोड़ता है)।

मेनू शॉर्टकट पहले आते हैं, जैसा नेटिव ऐप्स में होता है: जो कुंजी कोई आइटम लेता है वह फ़ोकस वाले टेक्स्ट फ़ील्ड या NSH की अपनी कुंजियों तक कभी नहीं पहुँचती। केवल उसी कीस्ट्रोक की keymap की बाइंडिंग उनसे पहले आती है। इसलिए संपादन शॉर्टकट (mod+c, mod+v, mod+x, mod+a, mod+z) केवल edit रोल को दें, जो उन्हें टेक्स्ट फ़ील्ड तक पहुँचाते हैं, और बिना मॉडिफ़ायर वाली कुंजियों (escape, एरो कुंजियाँ, अक्षर) से बचें, जो उन्हें टेक्स्ट फ़ील्ड और बैक नेविगेशन से छीन लेंगी। GPUI बैकएंड पर when: "auto" किसी आइटम को टेक्स्ट फ़ील्ड के साथ कुंजी साझा करने देता है: delete या mod+z जब किसी फ़ील्ड के पास फ़ोकस न हो तब आइटम चुनते हैं और जब हो तब टेक्स्ट संपादित करते हैं।

GPUI बैकएंड पर, कीबोर्ड फ़ोकस वाला नेटिव कंपोनेंट हर कुंजी को सबसे पहले देखता है। जिस कुंजी को वह खुद संभाल ले, वह keymap या मेनू तक कभी नहीं पहुँचती। जिस कुंजी को वह जाने दे, वह keymap तक ऐसे पहुँचती है मानो कोई टेक्स्ट फ़ील्ड फ़ोकस में हो, फिर मेनू तक।

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

बटन के प्रेस से कॉन्टेक्स्ट मेनू:

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>