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 حيث تعمل واجهات النافذة والقوائم في هذه الوحدة: macOS وWindows وLinux؛ وfalse في غيرها. في Rust: os().is_desktop().

platform.desktop هو الفحص الأوسع لسلوك سطح المكتب (خصائص desktop={{…}}، platform.select({ desktop })): فهو يصدق أيضًا في المتصفحات بنمط سطح المكتب، وهي تعمل داخل نافذة المتصفح نفسه. اعتمد على platform.desktop في تخطيط سطح المكتب وكثافته وإدخاله، وعلى isAvailable في استدعاءات Window وMenu.

#النافذة

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 أرقامًا محدودة. تحتفظ الحقول غير الصالحة بقيمها السابقة.

#شريط عنوان خاص بك

عند إخفاء شريط العنوان يرسم التطبيق شريطه بنفسه ويحدد أي أجزائه تحرّك النافذة، باستخدام .window_drag(true) في Rust وdesktop={{ windowDrag: true }} في 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>
  );
}

الضغط على عرض يحمل windowDrag يسحب النافذة كما يفعل شريط عنوان النظام: النقر المزدوج يكبّرها (أو يفعل ما ضبطه المستخدم: في macOS، “Double-click a window’s title bar to”)، وعلى Windows وLinux يفتح النقر الأيمن قائمة النافذة.

• يحسم الأمر أقرب عرض يضبط windowDrag: .window_drag(false) (desktop={{ windowDrag: false }}) يُبقي جزءًا من عرض قابل للسحب قابلًا للنقر.
• تبقى حقول النص والعروض ذات معالجات الضغط أو اللمس (onPress، onTouch*، المستجيبات) داخل عرض قابل للسحب قابلة للنقر بدونه: حقل البحث وأي أزرار في المثال أعلاه تعمل كالمعتاد.
• يعمل windowDrag أيضًا مع شريط عنوان النظام: يمكن لشريط جانبي أو شريط أدوات أن يحرّك النافذة كذلك.

#titleBar

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

مساحة شريط العنوان المخفي بالنقاط (تفاعلية): height الخاص به، وعرض ما تشغله أزرار تحكم النظام عند طرفيه left وright. صمّم شريطك بالاعتماد عليها كي لا يقع شيء تحت الأزرار. القيم الثلاث كلها 0 ما دام النظام يعرض شريط عنوانه (وفي وضع ملء الشاشة، وخارج أجهزة سطح المكتب). في Rust: title_bar() -> Edges<Points>، حيث top هو الارتفاع وleft وright عرضا الأزرار؛ وقراءته تشترك في التغييرات.

على Windows يرسم NSH أزرار العنوان بنمط Windows 11 وتتبع مظهر التطبيق؛ ويعرض تمرير المؤشر فوق زر التكبير تخطيطات الالتقاط (snap layouts) في Windows 11. تحتفظ النافذة بحدود تغيير الحجم والظل والزوايا المستديرة على كل منصة.

#القائمة

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<()> تكتمل بعد إغلاق القائمة (الانتظار عليها اختياري). يعمل معالج العنصر ضمن المالك (owner) الذي ضبط القائمة، ما دام هذا المالك حيًا.

استدعِ setApplicationMenu مجددًا لتغيير القائمة. وداخل effect تتبع القائمةُ الإشاراتِ التي تقرؤها: فتبقى علامة الاختيار أو حالة التعطيل المعتمدة على حالة التطبيق محدّثة.

#عناصر القائمة

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 لاختصارات تطبيقك الخاصة: فهو المفتاح الذي تستخدمه تطبيقات كل منصة لها (⌘N على macOS وCtrl+N على Windows وLinux)، فتناسب صيغة واحدة الجميع. مفتاح Windows وSuper يخصّان النظام في الغالب (Win+E، نظرة GNOME العامة)، لذا نادرًا ما يكون cmd مناسبًا خارج macOS.

الأدوار:

لعنصر الدور تسمية المنصة واختصارها ما لم يضبط تسميته الخاصة (يضيف macOS اسم التطبيق إلى about وhide وquit).

لاختصارات القوائم الأولوية، كما في التطبيقات الأصلية: المفتاح الذي يأخذه عنصر لا يصل أبدًا إلى حقل النص المركَّز عليه ولا إلى مفاتيح NSH نفسها. ولا يسبقها إلا ارتباط من keymap لضغطة المفاتيح نفسها. لذا امنح اختصارات التحرير (mod+c، mod+v، mod+x، mod+a، mod+z) لأدوار التحرير وحدها، فهي تمررها إلى حقل النص، وتجنّب المفاتيح بلا مُعدِّل (escape، الأسهم، الحروف) لأنها ستسلبها من حقول النص ومن التنقل للخلف. في واجهة GPUI الخلفية يتيح when: "auto" للعنصر أن يشارك حقول النص المفتاحَ نفسه: delete أو mod+z يختاران العنصر ما دام لا حقل يملك التركيز، ويحرّران النص حين يملكه حقل.

في واجهة GPUI الخلفية يرى المكوّن الأصلي الذي يملك تركيز لوحة المفاتيح كل مفتاح أولًا. والمفتاح الذي يعالجه بنفسه لا يصل أبدًا إلى خريطة المفاتيح ولا إلى القائمة. والمفتاح الذي يتركه يصل إلى خريطة المفاتيح كما لو كان حقل نص مركَّزًا عليه، ثم إلى القائمة.

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>