.\" Generated by scdoc 1.11.5
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "waybar\-custom" "5" "2026\-08\-31"
.SH "نام (NAME)"
.PP
waybar\-custom \- ماژول سفارشی (custom) در waybar
.PP
.SH "توضیحات (DESCRIPTION)"
.PP
ماژول \fBcustom\fR خروجی یک اسکریپت یا متن ایستا (static) را نمایش می‌دهد.\&
برای نمایش متن ایستا، فقط فیلد \fBformat\fR را مشخص کنید.\&
.PP
.SH "پیکربندی (CONFIGURATION)"
.PP
با \fBcustom/<name>\fR آدرس‌دهی می‌شود.\&
.PP
\fBexec\fR:
.br
نوع: رشته (string)
.br
مسیر اسکریپتی که باید اجرا شود.\&
.PP
\fBexec\-if\fR:
.br
نوع: رشته (string)
.br
مسیر اسکریپتی که مشخص می‌کند آیا اسکریپت موجود در \fBexec\fR باید اجرا شود یا خیر.\&
.br
اگر کد خروج (exit code) اسکریپت \fBexec\-if\fR برابر 0 باشد، \fBexec\fR اجرا خواهد شد.\&
.PP
\fBhide\-empty\-text\fR:
.br
نوع: بولی (bool)
.br
هنگامی که خروجی خالی باشد، ماژول را غیرفعال می‌کند؛ حتی اگر قالب (format) حاوی محتوای ایستای اضافی باشد.\&
.PP
\fBexec\-on\-event\fR:
.br
نوع: بولی (bool)
.br
پیش‌فرض: true
.br
اگر یک دستور رویداد تنظیم شده باشد (مانند \fBon\-click\fR یا \fBon\-scroll\-up\fR)، پس از اجرای دستور رویداد، اسکریپت را دوباره اجرا می‌کند.\&
.PP
\fBreturn\-type\fR:
.br
نوع: رشته (string)
.br
به بخش \fBنوع بازگشتی (RETURN\-TYPE)\fR مراجعه کنید.\&
.PP
\fBinterval\fR:
.br
نوع: عدد صحیح یا ممیز شناور (integer or float)
.br
بازه زمانی (بر حسب ثانیه) که اطلاعات در آن به صورت دوره‌ای دریافت می‌شوند (poll).\&
.br
حداقل مقدار 0.\&001 (یک میلی‌ثانیه) است. مقادیر کوچک‌تر از 1ms به 1ms تنظیم خواهند شد.\&
.br
اگر می‌خواهید ماژول فقط هنگام راه‌اندازی اجرا شود، از \fBonce\fR استفاده کنید.\&
.br
می‌توانید آن را به صورت دستی با یک سیگنال به‌روزرسانی کنید.\& اگر هیچ \fBinterval\fR یا \fBsignal\fR تعریف نشده باشد، فرض می‌شود که خود اسکریپت خروجی در یک حلقه اجرا می‌شود.\&
.br
اگر یک \fBsignal\fR تعریف شده باشد، اسکریپت یک بار هنگام راه‌اندازی اجرا شده و فقط با دریافت سیگنال به‌روزرسانی خواهد شد.\&
.PP
\fBrestart\-interval\fR:
.br
نوع: عدد صحیح یا ممیز شناور (integer or float)
.br
بازه زمانی راه‌اندازی مجدد (بر حسب ثانیه).\&
.br
حداقل مقدار 0.\&001 (یک میلی‌ثانیه) است. مقادیر کوچک‌تر از 1ms به 1ms تنظیم خواهند شد.\&
.br
نمی‌تواند همراه با گزینه \fBinterval\fR استفاده شود، بنابراین فقط برای اسکریپت‌های پیوسته (continuous) کاربرد دارد.\&
.br
به محض خروج اسکریپت، پس از گذشت زمان \fBrestart\-interval\fR مجدداً اجرا خواهد شد.\&
.PP
\fBsignal\fR:
.br
نوع: عدد صحیح (integer)
.br
شماره سیگنال مورد استفاده برای به‌روزرسانی ماژول.\&
.br
این عدد بین 1 و N معتبر است، به طوری که \fBSIGRTMIN+N\fR = \fBSIGRTMAX\fR.\&
.br
اگر هیچ بازه‌ای تعریف نشده باشد، سیگنال تنها راه برای به‌روزرسانی ماژول خواهد بود.\&
.PP
\fBformat\fR:
.br
نوع: رشته (string)
.br
پیش‌فرض: {text}
.br
قالب نحوه نمایش اطلاعات.\& داده‌ها در جای {text} درج می‌شوند.\&
.PP
\fBformat\-icons\fR:
.br
نوع: آرایه (array)
.br
بر اساس درصد تنظیم‌شده، آیکون مربوطه انتخاب می‌شود.\& ترتیب از \fBlow\fR (کم) به \fBhigh\fR (زیاد) است.\&
.PP
\fBrotate\fR:
.br
نوع: عدد صحیح (integer)
.br
مقدار مثبت برای چرخاندن برچسب متنی (در گام‌های ۹۰ درجه).\&
.PP
\fBmax\-length\fR:
.br
نوع: عدد صحیح (integer)
.br
حداکثر طول بر حسب کاراکتر که ماژول باید نمایش دهد.\&
.PP
\fBmin\-length\fR:
.br
نوع: عدد صحیح (integer)
.br
حداقل طول بر حسب کاراکتر که ماژول باید بپذیرد.\&
.PP
\fBalign\fR:
.br
نوع: ممیز شناور (float)
.br
تراز برچسب درون ماژول، که در آن 0 چپ‌چین و 1 راست‌چین است. اگر ماژول چرخانده شود، از جهت متن پیروی می‌کند.\&
.PP
\fBjustify\fR:
.br
نوع: رشته (string)
.br
تراز متن درون برچسب ماژول، که گزینه‌های '\&left'\& (چپ)، '\&right'\& (راست) یا '\&center'\& (وسط) را برای تعیین موقعیت می‌پذیرد.\&
.PP
\fBon\-click\fR:
.br
نوع: رشته (string)
.br
دستوری که هنگام کلیک روی ماژول اجرا می‌شود.\&
.PP
\fBon\-click\-middle\fR:
.br
نوع: رشته (string)
.br
دستوری که هنگام کلیک میانی با چرخ ماوس روی ماژول اجرا می‌شود.\&
.PP
\fBon\-click\-right\fR:
.br
نوع: رشته (string)
.br
دستوری که هنگام راست‌کلیک روی ماژول اجرا می‌شود.\&
.PP
\fBon\-update\fR:
.br
نوع: رشته (string)
.br
دستوری که هنگام به‌روزرسانی ماژول اجرا می‌شود.\&
.PP
\fBon\-scroll\-up\fR:
.br
نوع: رشته (string)
.br
دستوری که هنگام اسکرول به بالا روی ماژول اجرا می‌شود.\&
.PP
\fBon\-scroll\-down\fR:
.br
نوع: رشته (string)
.br
دستوری که هنگام اسکرول به پایین روی ماژول اجرا می‌شود.\&
.PP
\fBsmooth\-scrolling\-threshold\fR:
.br
نوع: ممیز شناور با دقت مضاعف (double)
.br
آستانه مورد استفاده هنگام اسکرول.\&
.PP
\fBtooltip\fR:
.br
نوع: بولی (bool)
.br
پیش‌فرض: true
.br
گزینه‌ای برای غیرفعال کردن راهنمای شناور (tooltip) در هنگام نگه داشتن ماوس.\&
.PP
\fBtooltip\-format\fR:
.br
نوع: رشته (string)
.br
قالب راهنمای شناور (tooltip).\& در صورت تعیین، بر هرگونه خروجی راهنمای شناور ارسال‌شده از اسکریپت موجود در \fBexec\fR اولویت دارد.\&
.br
از همان جایگزین‌های قالب \fBformat\fR استفاده می‌کند.\&
.PP
\fBescape\fR:
.br
نوع: بولی (bool)
.br
پیش‌فرض: false
.br
گزینه‌ای برای فعال کردن اسکیپ‌سازی (escaping) کاراکترها در خروجی اسکریپت.\&
.PP
\fBmenu\fR:
.br
نوع: رشته (string)
.br
عملی که منو را باز می‌کند.\&
.PP
\fBmenu\-file\fR:
.br
نوع: رشته (string)
.br
مسیر فایل توصیف‌کننده منو.\& باید عنصری از نوع
.RS 4
GtkMenu با شناسه \fBmenu\fR وجود داشته باشد.\&
.PP
.RE
\fBmenu\-actions\fR:
.br
نوع: آرایه (array)
.br
کنش‌های متناظر با دکمه‌های منو.\&
.PP
\fBexpand\fR:
.br
نوع: بولی (bool)
.br
پیش‌فرض: false
.br
امکان مصرف پویای تمامی فضای باقی‌مانده توسط این ماژول را فعال می‌کند.\&
.PP
.SH "نوع بازگشتی (RETURN\-TYPE)"
.PP
هنگامی که \fBreturn\-type\fR بر روی \fBjson\fR تنظیم شود، Waybar انتظار دارد که اسکریپت \fBexec\fR داده‌های خود را در قالب JSON خروجی دهد.\&
این خروجی باید به این شکل باشد:
.PP
.nf
.RS 4
{"text": "$text", "tooltip": "$tooltip", "class": "$class", "percentage": $percentage }
.fi
.RE
.PP
پارامتر \fBclass\fR همچنین آرایه‌ای از رشته‌ها را می‌پذیرد.\&
.PP
اگر چیزی مشخص نشده باشد یا یک گزینه نامعتبر تعیین شود، Waybar انتظار خروجی به سبک i3blocks را دارد.\& مقادیر با \fBخط جدید\fR (newline) از یکدیگر جدا می‌شوند.\&
این خروجی باید به این شکل باشد:
.PP
.nf
.RS 4
$text\n$tooltip\n$class*
.fi
.RE
.PP
\fBclass\fR یک کلاس CSS است، برای اعمال استایل‌های گوناگون در \fBstyle.\&css\fR
.PP
.SH "جایگزین‌های قالب‌بندی (FORMAT REPLACEMENTS)"
.PP
\fB{text}\fR: خروجی اسکریپت.\&
.PP
\fB{percentage}\fR: درصدی که می‌تواند از طریق نوع بازگشتی json تنظیم شود.\&
.PP
\fB{icon}\fR: یک آیکون از '\&format\-icons'\& بر اساس درصد.\&
.PP
.SH "مثال‌ها (EXAMPLES)"
.PP
.SS Spotify:
.PP
.nf
.RS 4
"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"
}
.fi
.RE
.PP
.SS mpd:
.PP
.nf
.RS 4
"custom/mpd": {
	"format": "♪ {text}",
	//"max\-length": 15,
	"interval": 10,
	"exec": "mpc current",
	"exec\-if": "pgrep mpd",
	"on\-click": "mpc toggle",
	"on\-click\-right": "sonata"
}
.fi
.RE
.PP
.SS cmus:
.PP
.nf
.RS 4
"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
}
.fi
.RE
.PP
.SS Pacman
.PP
.nf
.RS 4

"custom/pacman": {
	"format": "{text}  ",
	"interval": "once",
	"exec": "pacman_packages",
	"on\-click": "update\-system",
	"signal": 8
}
.fi
.RE
.PP
.SS Alternate Pacman
.PP
.nf
.RS 4
"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
}
.fi
.RE
.PP
با این فرض که بازه زمانی (interval) تعریف نشده است، می‌توانید از سیگنال استفاده کرده و تعداد بسته‌های موجود را با \fBpkill \-RTMIN+8 waybar\fR به‌روزرسانی کنید.\&
.PP
.SH "استایل (STYLE)"
.PP
.PD 0
.IP \(bu 4
\fB#custom\-<name>\fR
.IP \(bu 4
\fB#custom\-<name>.\&<class>\fR
.IP \(bu 4
\fB<class>\fR می‌تواند توسط اسکریپت تعیین شود.\& برای اطلاعات بیشتر به بخش \fBنوع بازگشتی (RETURN\-TYPE)\fR مراجعه کنید.\&