نام (NAME)

waybar-custom - ماژول سفارشی (custom) در waybar

توضیحات (DESCRIPTION)

ماژول custom خروجی یک اسکریپت یا متن ایستا (static) را نمایش می‌دهد. برای نمایش متن ایستا، فقط فیلد format را مشخص کنید.

پیکربندی (CONFIGURATION)

با custom/<name> آدرس‌دهی می‌شود.

exec:
نوع: رشته (string)
مسیر اسکریپتی که باید اجرا شود.

exec-if:
نوع: رشته (string)
مسیر اسکریپتی که مشخص می‌کند آیا اسکریپت موجود در exec باید اجرا شود یا خیر.
اگر کد خروج (exit code) اسکریپت exec-if برابر 0 باشد، exec اجرا خواهد شد.

hide-empty-text:
نوع: بولی (bool)
هنگامی که خروجی خالی باشد، ماژول را غیرفعال می‌کند؛ حتی اگر قالب (format) حاوی محتوای ایستای اضافی باشد.

exec-on-event:
نوع: بولی (bool)
پیش‌فرض: true
اگر یک دستور رویداد تنظیم شده باشد (مانند on-click یا on-scroll-up)، پس از اجرای دستور رویداد، اسکریپت را دوباره اجرا می‌کند.

return-type:
نوع: رشته (string)
به بخش نوع بازگشتی (RETURN-TYPE) مراجعه کنید.

interval:
نوع: عدد صحیح یا ممیز شناور (integer or float)
بازه زمانی (بر حسب ثانیه) که اطلاعات در آن به صورت دوره‌ای دریافت می‌شوند (poll).
حداقل مقدار 0.001 (یک میلی‌ثانیه) است. مقادیر کوچک‌تر از 1ms به 1ms تنظیم خواهند شد.
اگر می‌خواهید ماژول فقط هنگام راه‌اندازی اجرا شود، از once استفاده کنید.
می‌توانید آن را به صورت دستی با یک سیگنال به‌روزرسانی کنید. اگر هیچ interval یا signal تعریف نشده باشد، فرض می‌شود که خود اسکریپت خروجی در یک حلقه اجرا می‌شود.
اگر یک signal تعریف شده باشد، اسکریپت یک بار هنگام راه‌اندازی اجرا شده و فقط با دریافت سیگنال به‌روزرسانی خواهد شد.

restart-interval:
نوع: عدد صحیح یا ممیز شناور (integer or float)
بازه زمانی راه‌اندازی مجدد (بر حسب ثانیه).
حداقل مقدار 0.001 (یک میلی‌ثانیه) است. مقادیر کوچک‌تر از 1ms به 1ms تنظیم خواهند شد.
نمی‌تواند همراه با گزینه interval استفاده شود، بنابراین فقط برای اسکریپت‌های پیوسته (continuous) کاربرد دارد.
به محض خروج اسکریپت، پس از گذشت زمان restart-interval مجدداً اجرا خواهد شد.

signal:
نوع: عدد صحیح (integer)
شماره سیگنال مورد استفاده برای به‌روزرسانی ماژول.
این عدد بین 1 و N معتبر است، به طوری که SIGRTMIN+N = SIGRTMAX.
اگر هیچ بازه‌ای تعریف نشده باشد، سیگنال تنها راه برای به‌روزرسانی ماژول خواهد بود.

format:
نوع: رشته (string)
پیش‌فرض: {text}
قالب نحوه نمایش اطلاعات. داده‌ها در جای {text} درج می‌شوند.

format-icons:
نوع: آرایه (array)
بر اساس درصد تنظیم‌شده، آیکون مربوطه انتخاب می‌شود. ترتیب از low (کم) به high (زیاد) است.

rotate:
نوع: عدد صحیح (integer)
مقدار مثبت برای چرخاندن برچسب متنی (در گام‌های ۹۰ درجه).

max-length:
نوع: عدد صحیح (integer)
حداکثر طول بر حسب کاراکتر که ماژول باید نمایش دهد.

min-length:
نوع: عدد صحیح (integer)
حداقل طول بر حسب کاراکتر که ماژول باید بپذیرد.

align:
نوع: ممیز شناور (float)
تراز برچسب درون ماژول، که در آن 0 چپ‌چین و 1 راست‌چین است. اگر ماژول چرخانده شود، از جهت متن پیروی می‌کند.

justify:
نوع: رشته (string)
تراز متن درون برچسب ماژول، که گزینه‌های 'left' (چپ)، 'right' (راست) یا 'center' (وسط) را برای تعیین موقعیت می‌پذیرد.

on-click:
نوع: رشته (string)
دستوری که هنگام کلیک روی ماژول اجرا می‌شود.

on-click-middle:
نوع: رشته (string)
دستوری که هنگام کلیک میانی با چرخ ماوس روی ماژول اجرا می‌شود.

on-click-right:
نوع: رشته (string)
دستوری که هنگام راست‌کلیک روی ماژول اجرا می‌شود.

on-update:
نوع: رشته (string)
دستوری که هنگام به‌روزرسانی ماژول اجرا می‌شود.

on-scroll-up:
نوع: رشته (string)
دستوری که هنگام اسکرول به بالا روی ماژول اجرا می‌شود.

on-scroll-down:
نوع: رشته (string)
دستوری که هنگام اسکرول به پایین روی ماژول اجرا می‌شود.

smooth-scrolling-threshold:
نوع: ممیز شناور با دقت مضاعف (double)
آستانه مورد استفاده هنگام اسکرول.

tooltip:
نوع: بولی (bool)
پیش‌فرض: true
گزینه‌ای برای غیرفعال کردن راهنمای شناور (tooltip) در هنگام نگه داشتن ماوس.

tooltip-format:
نوع: رشته (string)
قالب راهنمای شناور (tooltip). در صورت تعیین، بر هرگونه خروجی راهنمای شناور ارسال‌شده از اسکریپت موجود در exec اولویت دارد.
از همان جایگزین‌های قالب format استفاده می‌کند.

escape:
نوع: بولی (bool)
پیش‌فرض: false
گزینه‌ای برای فعال کردن اسکیپ‌سازی (escaping) کاراکترها در خروجی اسکریپت.

menu:
نوع: رشته (string)
عملی که منو را باز می‌کند.

menu-file:
نوع: رشته (string)
مسیر فایل توصیف‌کننده منو. باید عنصری از نوع

menu-actions:
نوع: آرایه (array)
کنش‌های متناظر با دکمه‌های منو.

expand:
نوع: بولی (bool)
پیش‌فرض: false
امکان مصرف پویای تمامی فضای باقی‌مانده توسط این ماژول را فعال می‌کند.

نوع بازگشتی (RETURN-TYPE)

هنگامی که return-type بر روی json تنظیم شود، Waybar انتظار دارد که اسکریپت exec داده‌های خود را در قالب JSON خروجی دهد. این خروجی باید به این شکل باشد:

{"text": "$text", "tooltip": "$tooltip", "class": "$class", "percentage": $percentage }

پارامتر class همچنین آرایه‌ای از رشته‌ها را می‌پذیرد.

اگر چیزی مشخص نشده باشد یا یک گزینه نامعتبر تعیین شود، Waybar انتظار خروجی به سبک i3blocks را دارد. مقادیر با خط جدید (newline) از یکدیگر جدا می‌شوند. این خروجی باید به این شکل باشد:

$text0tooltip0class*

class یک کلاس CSS است، برای اعمال استایل‌های گوناگون در style.css

جایگزین‌های قالب‌بندی (FORMAT REPLACEMENTS)

{text}: خروجی اسکریپت.

{percentage}: درصدی که می‌تواند از طریق نوع بازگشتی json تنظیم شود.

{icon}: یک آیکون از 'format-icons' بر اساس درصد.

مثال‌ها (EXAMPLES)

"custom/spotify": {
	"format": " {text}",
	"max-length": 40,
	"interval": 30, // Remove this if your script is endless and write in loop
	"exec": "$HOME/.config/waybar/mediaplayer.sh 2> /dev/null", // Script in resources folder
	"exec-if": "pgrep spotify",
	"return-type": "json"
}

"custom/mpd": {
	"format": "♪ {text}",
	//"max-length": 15,
	"interval": 10,
	"exec": "mpc current",
	"exec-if": "pgrep mpd",
	"on-click": "mpc toggle",
	"on-click-right": "sonata"
}

"custom/cmus": {
	"format": "♪ {text}",
	//"max-length": 15,
	"interval": 10,
	"exec": "cmus-remote -C "format_print '%a - %t'"", // artist - title
	"exec-if": "pgrep cmus",
	"on-click": "cmus-remote -u",                        //toggle pause
	"escape": true                                       //handle markup entities
}

"custom/pacman": {
	"format": "{text}  ",
	"interval": "once",
	"exec": "pacman_packages",
	"on-click": "update-system",
	"signal": 8
}

"custom/pacman": {
	"format": "{text}  ",
	"exec": "checkupdates | wc -l",       // # of updates
	"exec-if": "exit 0",                  // always run; consider advanced run conditions
	"on-click": "termite -e 'sudo pacman -Syu'; pkill -SIGRTMIN+8 waybar", // update system
	"signal": 8
}

استایل (STYLE)

• #custom-<name>
• #custom-<name>.<class>
• <class> می‌تواند توسط اسکریپت تعیین شود. برای اطلاعات بیشتر به بخش نوع بازگشتی (RETURN-TYPE) مراجعه کنید.