XDG-DESKTOP-MENU(1) xdg-desktop-menu Manual XDG-DESKTOP-MENU(1)

xdg-desktop-menu - ابزار خط فرمان برای نصب یا حذف موارد منوی میزکار

xdg-desktop-menu install [--noupdate] [--novendor] [--mode mode] directory-file(s) desktop-file(s)

xdg-desktop-menu uninstall [--noupdate] [--mode mode] directory-file(s) desktop-file(s)

xdg-desktop-menu forceupdate [--mode mode]

xdg-desktop-menu {--help | --manual | --version}

برنامهٔ xdg-desktop-menu می‌تواند برای نصب مدخل‌های منوی جدید در منوی برنامه‌های میزکار استفاده شود.

منوی برنامه‌ها بر اساس «مشخصات منوی میزکار XDG» کار می‌کند که در نشانی زیر در دسترس است: http://www.freedesktop.org/wiki/Specifications/menu-spec

install

نصب یک یا چند برنامه در یک زیرمنو از سامانهٔ منوی میزکار.

desktop-file: یک فایل desktop نشان‌دهندهٔ یک مدخل منفرد در منو است. فایل‌های desktop بر اساس «مشخصات مدخل میزکار» freedesktop.org تعریف می‌شوند. مهم‌ترین جنبه‌های فایل‌های *.desktop در ادامه خلاصه شده‌اند.

مدخل‌های منو می‌توانند به دو روش گوناگون به سامانهٔ منو افزوده شوند. آن‌ها می‌توانند بر اساس یک یا چند کلیدواژهٔ دسته‌بندی به یک زیرمنوی از پیش‌تعریف‌شده اضافه شوند، یا اینکه به یک زیرمنوی جدید اضافه گردند.

برای افزودن مدخل منو به یک زیرمنوی از پیش‌تعریف‌شده، فایل desktop که نمایندهٔ آن مدخل است باید شامل مدخل Categories= باشد که یک یا چند کلیدواژه را فهرست می‌کند. مورد منو بر اساس کلیدواژه‌های ذکرشده در زیرمنوی مناسب قرار خواهد گرفت.

برای افزودن موارد منو به یک زیرمنوی جدید، پیش از desktop-fileها باید یک directory-file قرار گیرد که آن زیرمنو را توصیف می‌کند. اگر چند desktop-file مشخص شده باشد، همهٔ مدخل‌ها به همان منو افزوده می‌شوند. اگر مدخل‌ها در منویی نصب شوند که پیش‌تر با فراخوانی دیگری از xdg-desktop-menu ایجاد شده است، موارد جدید به مدخل‌های موجود اضافه خواهند شد.

directory-file: فایل *.directory که توسط directory-file مشخص می‌شود، بیانگر یک زیرمنو است. فایل directory نام و شمایل (آیکون) زیرمنو را فراهم می‌کند. نام فایل directory برای شناسایی زیرمنو به کار می‌رود.

در صورتی که چند فایل directory ارائه شوند، هر فایل نمایندهٔ یک زیرمنو درون منوی پیش از خود خواهد بود و سلسله‌مراتبی تودرتو از منوها (زیر-زیرمنوها) ایجاد می‌کند. خود مدخل‌های منو به آخرین زیرمنو افزوده خواهند شد.

فایل‌های directory از ساختار نحوی تعریف‌شده در «مشخصات مدخل میزکار» freedesktop.org پیروی می‌کنند.

uninstall

حذف برنامه‌ها یا زیرمنوهایی از سامانهٔ منوی میزکار که پیش‌تر با xdg-desktop-menu install نصب شده‌اند.

یک زیرمنو و فایل directory مربوط به آن تنها زمانی حذف می‌شوند که آن زیرمنو دیگر حاوی هیچ مدخل منویی نباشد.

forceupdate

اجبار به به‌روزرسانی سامانهٔ منو.

این دستور تنها در صورتی کاربرد دارد که آخرین فراخوانی xdg-desktop-menu با گزینهٔ --noupdate همراه بوده باشد.

--noupdate

به‌روزرسانی سامانهٔ منو را به تعویق می‌اندازد. اگر چندین به‌روزرسانی در سامانهٔ منو به صورت پیاپی انجام می‌شود، این پرچم می‌تواند برای مشخص کردن این‌که تغییرات دیگری نیز در راه است و نیازی به به‌روزرسانی فوری سامانهٔ منو نیست، استفاده شود.

--novendor

به‌طور معمول، xdg-desktop-menu بررسی می‌کند تا اطمینان حاصل شود هر فایل *.directory و *.desktop که قرار است نصب شود دارای پیشوند سازنده (vendor prefix) باشد. این گزینه می‌تواند برای غیرفعال کردن این بررسی به کار رود.

یک پیشوند سازنده شامل نویسه‌های الفبایی ([a-zA-Z]) بوده و با یک خط تیره ("-") خاتمه می‌یابد. به شرکت‌ها و سازمان‌ها توصیه می‌شود که از یک کلمه یا عبارت، ترجیحاً نام سازمان که علامت تجاری آن را در اختیار دارند، به عنوان پیشوند سازندهٔ خود استفاده کنند. هدف از پیشوند سازنده، جلوگیری از تداخل نام‌ها است.

--mode mode

mode می‌تواند user یا system باشد. در حالت کاربر (user)، فایل فقط برای کاربر فعلی نصب یا حذف می‌شود. در حالت سیستم (system)، فایل برای تمام کاربران روی سیستم نصب یا حذف می‌شود. معمولاً تنها کاربر ریشه (root) اجازه دارد در حالت سیستم نصب را انجام دهد.

حالت پیش‌فرض این است که هنگام فراخوانی توسط root از حالت سیستم استفاده شود و هنگام فراخوانی توسط کاربری غیر از root از حالت کاربر استفاده گردد.

--help

نمایش خلاصهٔ دستور.

--manual

نمایش این صفحهٔ راهنما.

--version

نمایش اطلاعات نسخهٔ xdg-utils.

یک مورد برنامه در منوی برنامه‌ها توسط یک فایل *.desktop نشان داده می‌شود. یک فایل *.desktop شامل یک سرآیند [Desktop Entry] است که به دنبال آن چندین سطر Key=Value قرار دارد.

یک فایل *.desktop می‌تواند نام و توصیفی را برای یک برنامه به چندین زبان مختلف ارائه دهد. این کار با افزودن کد زبان، همان‌طور که توسط LC_MESSAGES استفاده می‌شود، در کروشه‌ها پس از Key انجام می‌گیرد. به این ترتیب می‌توان بسته به زبان انتخاب‌شدهٔ فعلی، مقادیر متفاوتی را برای همان Key تعیین کرد.

کلیدهای زیر اغلب استفاده می‌شوند:

Type=Application

این یک فیلد اجباری است که مشخص می‌کند فایل *.desktop یک راه‌انداز برنامه را توصیف می‌کند.

Name=Application Name

نام برنامه. برای نمونه: Mozilla

GenericName=Generic Name

شرح عمومی برنامه. برای نمونه: Web Browser

Comment=Comment

فیلد اختیاری برای تعیین یک راهنمای ابزار (tooltip) برای برنامه. برای نمونه: Visit websites on the Internet

Icon=Icon File

شمایلی که برای برنامه استفاده می‌شود. این می‌تواند یک مسیر مطلق به یک فایل تصویری یا یک icon-name باشد. اگر یک icon-name مشخص شده باشد، جستجوی تصویر بر اساس نام در تم شمایل فعلی کاربر انجام می‌شود. از دستور xdg-icon-resource می‌توان برای نصب فایل‌های تصویری در تم‌های شمایل استفاده کرد. مزیت استفاده از یک icon-name به جای مسیر مطلق این است که با نام شمایل، می‌توان شمایل برنامه را در چندین اندازهٔ مختلف و همچنین در سبک‌های متفاوتی از تم ارائه داد.

Exec=Command Line

خط فرمان برای راه‌اندازی برنامه. اگر برنامه می‌تواند فایل‌ها را باز کند، جای‌نگهدار %f باید مشخص شود. هنگامی که فایلی روی راه‌انداز برنامه رها (drop) می‌شود، %f با مسیر فایلِ رهاشده جایگزین می‌شود. اگر بتوان چندین فایل را در خط فرمان مشخص کرد، باید به جای %f از جای‌نگهدار %F استفاده شود. اگر برنامه علاوه بر فایل‌های محلی قادر به باز کردن URLها نیز باشد، می‌توان به جای %f یا %F از %u یا %U استفاده کرد.

Categories=Categories

فهرستی از دسته‌ها که با نقطه-ویرگول از یکدیگر جدا شده‌اند. یک دسته، کلیدواژه‌ای است که برنامه را توصیف و طبقه‌بندی می‌کند. به‌طور پیش‌فرض، برنامه‌ها در منوی برنامه‌ها بر اساس دسته سازمان‌دهی می‌شوند. هنگامی که مدخل‌های منو صریحاً به یک زیرمنوی جدید اختصاص داده شده باشند، نیازی به ذکر هیچ دسته‌ای نیست.

هنگام استفاده از دسته‌ها، توصیه می‌شود یکی از دسته‌های زیر گنجانده شود: AudioVideo، Development، Education، Game، Graphics، Network، Office، Settings، System، Utility.

برای اطلاعات بیشتر در مورد دسته‌های اضافی، به پیوست A از مشخصات منوی دسکتاپ XDG مراجعه کنید: http://standards.freedesktop.org/menu-spec/menu-spec-1.0.html#category-registry

MimeType=Mimetypes

فهرستی از نوع‌های MIME که با نقطه-ویرگول از هم جدا شده‌اند. این فیلد برای مشخص کردن نوع فایل‌هایی که برنامه قادر به باز کردن آن‌ها است، به کار می‌رود.

برای بررسی کامل قالب فایل *.desktop لطفاً پیوند زیر را ببینید: http://www.freedesktop.org/wiki/Specifications/desktop-entry-spec.SH "فایل‌های دایرکتوری (DIRECTORY FILES)"

ظاهر زیرمنو در منوی برنامه‌ها توسط یک فایل *.directory تأمین می‌شود. به طور خاص، این فایل عنوان زیرمنو و در صورت وجود، آیکون آن را مشخص می‌کند. یک فایل *.directory شامل سرآیند [Desktop Entry] است که در پی آن چندین خط Key=Value می‌آیند.

یک فایل *.directory می‌تواند عنوان (نام) زیرمنو را به چندین زبان مختلف ارائه دهد. این کار با افزودن یک کد زبان مشابه آنچه توسط LC_MESSAGES استفاده می‌شود در کروشه پس از Key انجام می‌پذیرد. بدین ترتیب می‌توان مقادیر مختلفی را برای یک Key یکسان بسته به زبان انتخاب‌شده فعلی تعیین کرد.

کلیدهای زیر برای زیرمنوها کاربرد دارند:

Type=Directory

این فیلد اجباری است و مشخص می‌کند که فایل *.directory یک زیرمنو را توصیف می‌کند.

Name=Menu Name

عنوان زیرمنو. برای مثال Mozilla

Comment=Comment

فیلدی اختیاری برای تعیین یک پیش‌نمایش متنی (tooltip) برای زیرمنو.

Icon=Icon File

آیکونی که برای زیرمنو استفاده می‌شود. این مقدار می‌تواند یک مسیر مطلق به یک فایل تصویر یا یک icon-name باشد. اگر یک icon-name ارائه شود، جستجوی تصویر بر اساس نام در تم آیکون فعلی کاربر انجام می‌گیرد. از دستور xdg-icon-resource می‌توان برای نصب فایل‌های تصویری در تم‌های آیکون استفاده کرد. مزیت استفاده از icon-name به جای مسیر مطلق این است که با یک icon-name، آیکون زیرمنو می‌تواند در چندین اندازه مختلف و همچنین در چندین سبک و تم متفاوت ارائه شود.

دستور xdg-desktop-menu از متغیرهای محیطی زیر پیروی می‌کند:

XDG_UTILS_DEBUG_LEVEL

تنظیم این متغیر محیطی روی یک مقدار عددی غیرصفر باعث می‌شود xdg-desktop-menu گزارش‌های پرجزئیات‌تری را در stderr ارائه دهد. تنظیم مقادیر بالاتر، میزان جزئیات را افزایش می‌دهد.

XDG_UTILS_INSTALL_MODE

این متغیر محیطی می‌تواند توسط کاربر یا مدیر سیستم برای لغو و تغییر حالت نصب (installation mode) استفاده شود. مقادیر معتبر عبارتند از user و system.

کد خروج 0 نشان‌دهنده موفقیت است، در حالی که کد خروج غیرصفر بیانگر شکست عملیات است. کدهای خطای زیر ممکن است بازگردانده شوند:

1

خطا در نحو (syntax) خط فرمان.

2

یکی از فایل‌های داده‌شده در خط فرمان وجود نداشت.

3

یک ابزار مورد نیاز یافت نشد.

4

عملیات با شکست مواجه شد.

5

مجوز لازم برای خواندن یکی از فایل‌های داده‌شده در خط فرمان وجود ندارد.

xdg-desktop-icon(1), xdg-icon-resource(1), xdg-mime(1), Desktop entry specification[1], Desktop menu specification[2]

شرکت ShinyThings Inc. برنامه‌ای به نام «WebMirror» توسعه داده است و می‌خواهد آن را به منوی برنامه‌ها اضافه کند. این شرکت از «shinythings» به عنوان vendor id خود استفاده خواهد کرد. برای افزودن برنامه به منو، وجود یک فایل .desktop با یک مدخل Categories مناسب الزامی است:

shinythings-webmirror.desktop:
  [Desktop Entry]
  Encoding=UTF-8
  Type=Application
  Exec=webmirror
  Icon=webmirror
  Name=WebMirror
  Name[nl]=WebSpiegel
  Categories=Network;WebDevelopment;

اکنون می‌توان از ابزار xdg-desktop-menu برای افزودن فایل shinythings-webmirror.desktop به منوی برنامه‌های میزکار استفاده کرد:

xdg-desktop-menu install ./shinythings-webmirror.desktop

توجه داشته باشید که در این مثال، موارد منو به دو زبان انگلیسی و هلندی ارائه شده‌اند. کد زبان هلندی nl است.

در مثال بعد، شرکت ShinyThings Inc. زیرمنوی اختصاصی خود را که شامل یک مورد منوی «WebMirror» و یک مورد منوی «WebMirror Admin Tool» است، به منوی برنامه‌های میزکار اضافه خواهد کرد.

ابتدا این شرکت باید دو فایل .desktop ایجاد کند که این دو مورد منو را توصیف می‌کنند. از آنجا که این موارد قرار است به یک زیرمنوی جدید اضافه شوند، نیازی به قرار دادن خط Categories= نیست:

shinythings-webmirror.desktop:
  [Desktop Entry]
  Encoding=UTF-8
  Type=Application
  Exec=webmirror
  Icon=shinythings-webmirror
  Name=WebMirror
  Name[nl]=WebSpiegel
shinythings-webmirror-admin.desktop:
  [Desktop Entry]
  Encoding=UTF-8
  Type=Application
  Exec=webmirror-admintool
  Icon=shinythings-webmirror-admintool
  Name=WebMirror Admin Tool
  Name[nl]=WebSpiegel Administratie Tool

علاوه بر این، برای مشخص کردن عنوان و آیکون خودِ زیرمنو، باید یک فایل .directory نیز ایجاد شود:

shinythings-webmirror.directory:
  [Desktop Entry]
  Encoding=UTF-8
  Icon=shinythings-webmirror-menu
  Name=WebMirror
  Name[nl]=WebSpiegel

اکنون می‌توان این فایل‌ها را با دستور زیر نصب کرد:

xdg-desktop-menu install ./shinythings-webmirror.directory \
      ./shinythings-webmirror.desktop ./shinythings-webmirror-admin.desktop

همچنین می‌توان مدخل‌های منو را به صورت تک‌تک نصب کرد:

xdg-desktop-menu install --noupdate ./shinythings-webmirror.directory \
      ./shinythings-webmirror.desktop
xdg-desktop-menu install --noupdate ./shinythings-webmirror.directory \
      ./shinythings-webmirror-admin.desktop
xdg-desktop-menu forceupdate

اگرچه نتیجه یکسان است، ولی نصب هم‌زمان همهٔ فایل‌ها کمی بهینه‌تر است.

فایل‌های *.desktop و *.directory به آیکون‌هایی با نام‌های webmirror، webmirror-admin و webmirror-menu ارجاع می‌دهند که آن‌ها نیز باید نصب شوند. در این مثال، آیکون‌ها در دو اندازهٔ مختلف نصب می‌شوند: یک‌بار با اندازهٔ 22x22 پیکسل و یک‌بار با اندازهٔ 64x64 پیکسل:

xdg-icon-resource install --size 22 ./wmicon-22.png shinythings-webmirror
xdg-icon-resource install --size 22 ./wmicon-menu-22.png shinythings-webmirror-menu
xdg-icon-resource install --size 22 ./wmicon-admin-22.png shinythings-webmirror-admin
xdg-icon-resource install --size 64 ./wmicon-64.png shinythings-webmirror
xdg-icon-resource install --size 64 ./wmicon-menu-64.png shinythings-webmirror-menu
xdg-icon-resource install --size 64 ./wmicon-admin-64.png shinythings-webmirror-admin

Kevin Krammer

نویسنده.

Jeremy White

نویسنده.

کپی‌رایت © 2006

1.
مشخصات Desktop entry
http://www.freedesktop.org/wiki/Specifications/desktop-entry-spec
2.
مشخصات Desktop menu
http://www.freedesktop.org/wiki/Specifications/menu-spec
12/06/2025 xdg-utils 1.0