نام (NAME)

rofi-script - حالت اسکریپت در rofi برای گسترش‌پذیری با اسکریپت‌ها

توضیحات (DESCRIPTION)

برنامه rofi از حالت‌هایی پشتیبانی می‌کند که در پس‌زمینه از اسکریپت‌های ساده برای تولید یک فهرست و پردازش نتیجه اقدامات کاربر استفاده می‌کنند. این سازوکار یک رابط ساده برای افزودن افزونه‌های سفارشی به rofi فراهم می‌آورد.

نحوه استفاده (USAGE)

برای تعیین یک حالت اسکریپتی، حالتی با ساختار نگارشی زیر تنظیم کنید: “{name}:{executable}”

به‌عنوان مثال:

rofi -show fb -modes "fb:file_browser.sh"

مقدار name باید یکتا باشد.

رابط برنامه‌نویسی (API)

برنامه Rofi هنگام راه‌اندازی فایل اجرایی را بدون آرگومان فراخوانی می‌کند. این اجرا باید فهرستی از گزینه‌ها را که با خط جدید (\n) از یکدیگر جدا شده‌اند تولید کند (این جداکننده توسط اسکریپت قابل تغییر است). اگر کاربر گزینه‌ای را انتخاب کند، rofi فایل اجرایی را همراه با متن آن گزینه به‌عنوان نخستین آرگومان فراخوانی می‌کند. اگر اسکریپت هیچ ورودی بازنگرداند، rofi بسته می‌شود.

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

#!/usr/bin/env bash
if [ x"$@" = x"quit" ]
then
    exit 0
fi
echo "reload"
echo "quit"

این اسکریپت دو مدخل reload و quit را نشان می‌دهد. هنگامی که مدخل quit انتخاب شود، rofi بسته خواهد شد.

محیط (Environment)

برنامه Rofi هنگام اجرای اسکریپت متغیرهای محیطی زیر را مقداردهی می‌کند:

ROFI_RETV

یک عدد صحیح که بیانگر وضعیت فعلی است:

•: 0: فراخوانی اولیه اسکریپت.
•: 1: یک مدخل انتخاب شده است.
•: 2: یک مدخل سفارشی انتخاب شده است.
•: 3: یک مدخل حذف شده است.
•: 10-28: کلیدهای میانبر سفارشی ۱-۱۹ (باید به‌طور صریح توسط اسکریپت فعال شده باشند).

ROFI_INFO

این متغیر محیطی هنگام انتخاب یک مدخل، با مقدار ویژگی گزینه سطر `info` (در صورت تنظیم) پر می‌شود.

ROFI_DATA

این متغیر محیطی هنگامی که اسکریپت گزینه data را در سرآیند تنظیم کند، مقداردهی می‌شود.

ارسال گزینه‌های حالت (Passing mode options)

گزینه‌های اضافی، مانند تنظیم اعلان (prompt)، می‌توانند توسط اسکریپت تنظیم شوند. گزینه‌های اضافی سطرهایی هستند که با یک نویسه NULL (\0) آغاز شده و پس از آن یک کلید، جداکننده (\x1f) و مقدار مربوطه قرار می‌گیرند.

برای نمونه، جهت تنظیم اعلان:

echo -en "\0prompt\x1fChange prompt\n"

گزینه‌های اضافی زیر موجود هستند:

•: prompt: به‌روزرسانی متن اعلان ورودی.
•: message: به‌روزرسانی متن پیام.
•: markup-rows: اگر برابر با `true` باشد، نشانه‌گذاری‌ها (markup) را در سطر رندر می‌کند.
•: urgent: علامت‌گذاری سطرها به‌عنوان اضطراری (urgent). (برای ساختار نگارشی به گزینه urgent در حالت dmenu مراجعه کنید)
•: active: علامت‌گذاری سطرها به‌عنوان فعال (active). (برای ساختار نگارشی به گزینه active در حالت dmenu مراجعه کنید)
•: delim: تعیین جداکننده برای سطرهای بعدی. مقدار پیش‌فرض `'` است و این گزینه باید با آن خاتمه یابد. این گزینه را فقط در نخستین فراخوانی اسکریپت اعمال کنید، چرا که برای فراخوانی‌های بعدی به خاطر سپرده می‌شود.
•: no-custom: اگر برابر با `true` تنظیم شود؛ تنها مدخل‌های فهرست‌شده پذیرفته می‌شوند و ورودی‌های سفارشی نادیده گرفته خواهند شد.
•: use-hot-keys: اگر برابر با true تنظیم شود، کلیدهای میانبر سفارشی را برای اسکریپت فعال می‌کند. هشدار: این کار روال معمول rofi را مختل می‌کند.
•: keep-selection: در صورت تنظیم، انتخاب به نخستین مدخل منتقل نمی‌شود، بلکه موقعیت فعلی حفظ می‌گردد. فیلتر پاک می‌شود.
•: keep-filter: در صورت تنظیم، فیلتر پاک نمی‌شود.
•: new-selection: در صورت تنظیم keep-selection، امکان بازنویسی مدخل انتخاب‌شده را (بر اساس موقعیت مطلق) فراهم می‌آورد.
•: data: داده‌ها را از طریق متغیر محیطی ROFI_DATA به اجرای بعدی اسکریپت منتقل می‌کند.
•: theme: قطعه‌پوسته کوچک، برای مثال جهت تغییر رنگ پس‌زمینه یک ویجت.

ویژگی theme نمی‌تواند رابط کاربری را هنگام اجرا دگرگون کند؛ این ویژگی تنها برای تغییرات جزئی کاربرد دارد، مانند رنگ پس‌زمینه ویجت‌هایی که حین نمایش به‌روزرسانی می‌شوند (نظیر رنگ سطر در listview).

تجزیه گزینه‌های سطر (Parsing row options)

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

به‌عنوان مثال:

echo -en "aap\0icon\x1ffolder\n"

گزینه‌های زیر پشتیبانی می‌شوند:

•: icon: تنظیم نماد (آیکون) برای آن سطر.
•: display: جایگزینی رشته نمایشی. (رشته اصلی همچنان برای فیلتر کردن استفاده خواهد شد)
•: meta: تعیین عبارت‌های جستجوی نامرئی برای فیلتر کردن.
•: nonselectable: اگر برابر با true باشد، سطر قابل فعال‌سازی و انتخاب نیست.
•: permanent: اگر برابر با true باشد، سطر همواره و مستقل از وضعیت فیلتر نمایش داده می‌شود.
•: info: اطلاعاتی که در صورت انتخاب سطر، درون متغیر محیطی ROFI_INFO قرار می‌گیرد. این مدخل در جستجو و فیلتر کردن لحاظ نمی‌شود.
•: urgent: تنظیم پرچم اضطراری روی مدخل (true/false)
•: active: تنظیم پرچم فعال روی مدخل (true/false)

چندین گزینه را می‌توان با استفاده از جداکننده \x1f منتقل کرد.

echo -en "aap\0icon\x1ffolder\x1finfo\x1ftest\n"

اجرای برنامه‌های خارجی (Executing external program)

اگر قصد دارید برنامه‌ای خارجی را از درون اسکریپت اجرا کنید، باید مطمئن شوید که در پس‌زمینه اجرا می‌شود. در غیر این صورت rofi در انتظار خروجی آن برنامه (جهت نمایش) باقی می‌ماند.

در bash بهترین روش برای انجام این کار، استفاده از coproc است.

coproc ( myApp  > /dev/null  2>&1 )

پوسته DASH (DASH shell)

اگر در اسکریپت خود از پوسته dash استفاده می‌کنید، به نحوه مدیریت مقادیر اسکیپ‌شده برای جداکننده‌ها در dash توجه ویژه داشته باشید. به گزارش شماره #1201 در گیت‌هاب رجوع کنید.