.\" 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\-clock" "5" "2026\-08\-31" "waybar\-clock" "User Manual"
.PP
.SH "نام (NAME)"
.PP
waybar\-clock \- ماژول ساعت در waybar
.PP
.SH "توضیحات (DESCRIPTION)"
.PP
ماژول \fBclock\fR تاریخ و زمان کنونی را نمایش می‌دهد.\&
.PP
.SH "فایل‌ها (FILES)"
.PP
$XDG_CONFIG_HOME/waybar/config
.br
فایل پیکربندی اختصاصی هر کاربر
.PP
.SH "پیکربندی (CONFIGURATION)"
.PP
1.\& آدرس‌دهی شده با \fBclock\fR
.TS
allbox;c c c c
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l.
T{
\fBگزینه (Option)\fR
T}	T{
\fBنوع (Typeof)\fR
T}	T{
\fBپیش‌فرض (Default)\fR
T}	T{
\fBتوضیحات (Description)\fR
T}
T{
\fBinterval\fR
T}	T{
integer
T}	T{
60
T}	T{
بازهٔ زمانی (بر حسب ثانیه) برای دریافت و به‌روزرسانی اطلاعات.\&
T}
T{
\fBformat\fR
T}	T{
string
T}	T{
\fB{:%H:%M}\fR
T}	T{
قالب نحوهٔ نمایش تاریخ و زمان.\& گزینه‌های قالب‌بندی را در زیر مشاهده کنید.\&
T}
T{
\fBtimezone\fR
T}	T{
string
T}	T{

T}	T{
منطقهٔ زمانی برای نمایش زمان؛ برای نمونه America/New_York.\& مقدار "" بیانگر منطقهٔ زمانی محلی سامانه است.\& فهرست غیررسمی مناطق زمانی در ویکی‌پدیا را ببینید: <https://en.\&wikipedia.\&org/wiki/List_of_tz_database_time_zones>
T}
T{
\fBtimezones\fR
T}	T{
list of strings
T}	T{

T}	T{
فهرستی از مناطق زمانی (مشابه \fBtimezone\fR) برای استفاده در نمایش زمان، که با چرخ اسکرول ماوس جابه‌جا می‌شوند.\& هنگام تعیین گزینهٔ \fBtimezones\fR، گزینهٔ \fBtimezone\fR را مشخص نکنید.\& مقدار "" بیانگر منطقهٔ زمانی محلی سامانه است.\&
T}
T{
\fBtimezone\-tooltip\-format\fR
T}	T{
string
T}	T{

T}	T{
قالب مورد استفاده برای نمایش مناطق زمانی در راهنمای شناور (tooltip).\& در صورت تنظیم، امکان نمایش اطلاعات منطقهٔ زمانی (مانند اختصارات منطقهٔ زمانی) را در راهنمای شناور فراهم می‌کند در حالی که نمایشگر اصلی خلوت می‌ماند.\& از همان گزینه‌های قالب‌بندی \fBformat\fR استفاده می‌کند.\&
T}
T{
\fBlocale\fR
T}	T{
string
T}	T{

T}	T{
مکان‌تنظیم (locale) برای نمایش زمان.\& برای رندر زمان در مناطق زمانی سفارشی با زبان و قالب مناسب به کار می‌رود.\&
T}
T{
\fBmax\-length\fR
T}	T{
integer
T}	T{

T}	T{
بیشینهٔ طول (بر حسب نویسه) که پودمان باید نمایش دهد.\&
T}
T{
\fBrotate\fR
T}	T{
integer
T}	T{

T}	T{
مقدار مثبت برای چرخاندن برچسب متنی (با گام‌های ۹۰ درجه).\&
T}
T{
\fBon\-click\fR
T}	T{
string
T}	T{

T}	T{
دستوری که هنگام کلیک بر روی پودمان اجرا می‌شود.\&
T}
T{
\fBon\-click\-middle\fR
T}	T{
string
T}	T{

T}	T{
دستوری که هنگام کلیک وسط (با چرخ ماوس) بر روی پودمان اجرا می‌شود.\&
T}
T{
\fBon\-click\-right\fR
T}	T{
string
T}	T{

T}	T{
دستوری که هنگام کلیک راست بر روی پودمان اجرا می‌شود.\&
T}
T{
\fBon\-scroll\-up\fR
T}	T{
string
T}	T{

T}	T{
دستوری که هنگام اسکرول به بالا بر روی پودمان اجرا می‌شود.\&
T}
T{
\fBon\-scroll\-down\fR
T}	T{
string
T}	T{

T}	T{
دستوری که هنگام اسکرول به پایین بر روی پودمان اجرا می‌شود.\&
T}
T{
\fBsmooth\-scrolling\-threshold\fR
T}	T{
double
T}	T{

T}	T{
آستانهٔ مورد استفاده هنگام اسکرول روان.\&
T}
T{
\fBtooltip\fR
T}	T{
bool
T}	T{
true
T}	T{
گزینه‌ای برای فعال‌سازی راهنمای شناور (tooltip) هنگام نگه داشتن نشانگر ماوس.\&
T}
T{
\fBtooltip\-format\fR
T}	T{
string
T}	T{
مشابه format
T}	T{
راهنمای شناور هنگام نگه داشتن نشانگر ماوس.\&
T}
T{
\fBmenu\fR
T}	T{
string
T}	T{

T}	T{
اقدامی که منو را باز می‌کند.\&
T}
T{
\fBmenu\-file\fR
T}	T{
string
T}	T{

T}	T{
مسیر فایل توصیف‌گر منو.\& باید عنصری از نوع GtkMenu با شناسهٔ \fBmenu\fR وجود داشته باشد.\&
T}
T{
\fBmenu\-actions\fR
T}	T{
array
T}	T{

T}	T{
اقدامات متناظر با دکمه‌های منو.\&
T}
T{
\fBexpand\fR:
T}	T{
bool
T}	T{
false
T}	T{
به این پودمان امکان می‌دهد تمام فضای باقی‌مانده را به‌صورت پویا مصرف کند.\&
T}
.TE
.sp 1
تمامی گزینه‌های معتبر قالب‌بندی را در \fBstrftime(3)\fR مشاهده کنید یا به نشانی https://en.\&cppreference.\&com/w/cpp/chrono/duration/formatter مراجعه فرمایید.\&
.PP
2.\& آدرس‌دهی شده با \fBclock: calendar\fR
.TS
allbox;c c c c
l l l l
l l l l
l l l l
l l l l
l l l l.
T{
\fBگزینه (Option)\fR
T}	T{
\fBنوع (Typeof)\fR
T}	T{
\fBپیش‌فرض (Default)\fR
T}	T{
\fBتوضیحات (Description)\fR
T}
T{
\fBmode\fR
T}	T{
string
T}	T{
month
T}	T{
حالت نمایش تقویم.\& مقادیر ممکن: year|month
T}
T{
\fBmode\-mon\-col\fR
T}	T{
integer
T}	T{
3
T}	T{
مرتبط با \fBmode=year\fR.\& تعداد ماه‌ها در هر سطر.\&
T}
T{
\fBweeks\-pos\fR
T}	T{
string
T}	T{

T}	T{
موقعیتی که شماره‌های هفته باید نمایش داده شوند.\& هنگام خالی بودن غیرفعال است.\& مقادیر ممکن: left|right
T}
T{
\fBon\-scroll\fR
T}	T{
integer
T}	T{
1
T}	T{
مقدار اسکرول ماه‌ها/سال‌ها به جلو/عقب.\& می‌تواند منفی باشد.\& تحت گزینهٔ \fBon\-scroll\fR پیکربندی می‌شود.\&
T}
T{
\fBiso8601\fR
T}	T{
bool
T}	T{
false
T}	T{
هنگام فعال بودن، تقویم از استاندارد ISO 8601 پیروی می‌کند: هفته‌ها از دوشنبه آغاز می‌شوند و نخستین هفتهٔ سال با شمارهٔ ۱ شماره‌گذاری می‌شود.\& قالب پیش‌فرض هفته '\&{:%V}'\& است.\&
T}
.TE
.sp 1
3.\& آدرس‌دهی شده با \fBclock: calendar: format\fR
.TS
allbox;c c c c
l l l l
l l l l
l l l l
l l l l
l l l l.
T{
\fBگزینه (Option)\fR
T}	T{
\fBنوع (Typeof)\fR
T}	T{
\fBپیش‌فرض (Default)\fR
T}	T{
\fBتوضیحات (Description)\fR
T}
T{
\fBmonths\fR
T}	T{
string
T}	T{

T}	T{
قالب اعمال‌شده بر سرآیند ماه‌ها (January، February و غیره).\&
T}
T{
\fBdays\fR
T}	T{
string
T}	T{

T}	T{
قالب اعمال‌شده بر روزها.\&
T}
T{
\fBweeks\fR
T}	T{
string
T}	T{
\fB{:%U}\fR
T}	T{
قالب اعمال‌شده بر شماره‌های هفته.\& هنگامی که قالب روزهای هفته ارائه نشده باشد، از قالب پیش‌فرض استفاده می‌شود: در صورتی که هفته با دوشنبه آغاز شود '\&{:%W}'\& و در غیر این صورت '\&{:%U}'\&.\&
T}
T{
\fBweekdays\fR
T}	T{
string
T}	T{

T}	T{
قالب اعمال‌شده بر سرآیند روزهای هفته (Su، Mo و غیره).\&
T}
T{
\fBtoday\fR
T}	T{
string
T}	T{
\fB<b><u>{}</u></b>\fR
T}	T{
قالب اعمال‌شده بر روز جاری (امروز).\&
T}
.TE
.sp 1
.SS "اقدامات (ACTIONS)"
.PP
.TS
allbox;c c
l l
l l
l l
l l
l l.
T{
\fBرشته (String)\fR
T}	T{
\fBاقدام (Action)\fR
T}
T{
\fBmode\fR
T}	T{
تغییر حالت تقویم بین سال/ماه (year/month)
T}
T{
\fBtz_up\fR
T}	T{
تغییر به منطقهٔ زمانی مشخص‌شدهٔ بعدی
T}
T{
\fBtz_down\fR
T}	T{
تغییر به منطقهٔ زمانی مشخص‌شدهٔ قبلی
T}
T{
\fBshift_up\fR
T}	T{
انتقال به ماه/سال تقویمی بعدی
T}
T{
\fBshift_down\fR
T}	T{
انتقال به ماه/سال تقویمی قبلی
T}
.TE
.sp 1
.SH "جایگزین‌های قالب‌بندی (FORMAT REPLACEMENTS)"
.PP
.PD 0
.IP \(bu 4
\fB{calendar}\fR: تقویم ماه کنونی
.IP \(bu 4
\fB{tz_list}\fR: فهرست زمان در سایر مناطق زمانی، در صورتی که بیش از یک منطقهٔ زمانی در پیکربندی تنظیم شده باشد
.IP \(bu 4
\fB{ordinal_date}\fR: روز جاری در شکل ترتیبی (انگلیسی)، مانند 21st
.PD
.PP
.SH "مثال‌ها (EXAMPLES)"
.PP
1.\& عمومی (General)
.PP
.nf
.RS 4
"clock": {
	"interval": 60,
	"format": "{:%H:%M}",
	"max\-length": 25
}
.fi
.RE
.PP
2.\& تقویم (Calendar)
.PP
.nf
.RS 4
"clock": {
	"format": "{:%H:%M}  ",
	"format\-alt": "{:%A, %B %d, %Y (%R)}  ",
	"tooltip\-format": "<tt><small>{calendar}</small></tt>",
	"calendar": {
		"mode"          : "year",
		"mode\-mon\-col"  : 3,
		"weeks\-pos"     : "right",
		"on\-scroll"     : 1,
		"on\-click\-right": "mode",
		"format": {
			"months":     "<span color=\&'#ffead3\&'><b>{}</b></span>",
			"days":       "<span color=\&'#ecc6d9\&'><b>{}</b></span>",
			"weeks":      "<span color=\&'#99ffdd\&'><b>W{}</b></span>",
			"weekdays":   "<span color=\&'#ffcc66\&'><b>{}</b></span>",
			"today":      "<span color=\&'#ff6699\&'><b><u>{}</u></b></span>"
		}
	},
	"actions": {
		"on\-click\-right": "mode",
		"on\-click\-forward": "tz_up",
		"on\-click\-backward": "tz_down",
		"on\-scroll\-up": "shift_up",
		"on\-scroll\-down": "shift_down"
	}
},
.fi
.RE
.PP
3.\& نمایش تاریخ کامل هنگام نگه داشتن نشانگر ماوس (Full date on hover)
.PP
.nf
.RS 4
"clock": {
	"interval": 60,
	"tooltip": true,
	"format": "{:%H\&.%M}",
	"tooltip\-format": "{:%Y\-%m\-%d}",
}
.fi
.RE
.PP
4.\& نمایش منطقهٔ زمانی فقط در راهنمای شناور (Show timezone in tooltip only)
.PP
.nf
.RS 4
"clock": {
	"interval": 60,
	"format": "{:%H:%M}",
	"timezone\-tooltip\-format": "{:%H:%M %Z}",
	"timezones": [
		"",
		"America/Chicago",
		"America/Los_Angeles",
		"Europe/Paris",
		"UTC"
	],
	"tooltip": true,
	"tooltip\-format": "{tz_list}"
}
.fi
.RE
.PP
.SH "استایل (STYLE)"
.PP
.PD 0
.IP \(bu 4
\fB#clock\fR
.PD
.PP
.SH "عیب‌یابی (TROUBLESHOOTING)"
.PP
اگر پودمان clock در زمان راه‌اندازی با پیام خطای locale::facet::_S_create_c_locale
.br
name not valid غیرفعال شد، یکی از موارد زیر را امتحان کنید:
.PP
.PD 0
.IP \(bu 4
بررسی کنید که متغیر LC_TIME به‌درستی تنظیم شده باشد (glibc)
.IP \(bu 4
تنظیم locale به C در فایل پیکربندی (musl)
.PD
.PP
گزینهٔ locale باید تنظیم شود تا {calendar} بدون توجه به مکان‌تنظیم سامانه، از شروع هفتهٔ صحیح استفاده کند.\&
.PP
.SS "تقویم به زبان چینی. تراز (Calendar in Chinese. Alignment)"
.PP
به منظور داشتن یک تقویم چینی تراز شده، توصیه‌های مفیدی وجود دارد:
.PP
.PD 0
.IP 1. 4
از قلم "WenQuanYi Zen Hei Mono" استفاده کنید که در اکثر توزیع‌های لینوکس ارائه شده است.\&
.IP 2. 4
اندازه‌های مختلف قلم را آزمایش کنید و بهترین را برای خود بیابید؛ اندازهٔ size = 9pt مناسب خواهد بود.\&
.IP 3. 4
در صورتی که از قلم "WenQuanYi Zen Hei Mono" استفاده می‌شود، تگ pango مربوط به قلم مونو‌اسپیس (monospace) را غیرفعال کنید.\&
.PD
.PP
نمونه‌ای از پیکربندی کارآمد
.PP
.nf
.RS 4
"clock": {
	"format": "{:%H:%M}  ",
	"format\-alt": "{:%A, %B %d, %Y (%R)}  ",
	"tooltip\-format": "n<span size=\&'9pt\&' font=\&'WenQuanYi Zen Hei Mono\&'>{calendar}</span>",
	"calendar": {
		"mode"          : "year",
		"mode\-mon\-col"  : 3,
		"weeks\-pos"     : "right",
		"on\-scroll"     : 1,
		"on\-click\-right": "mode",
		"format": {
			"months":     "<span color=\&'#ffead3\&'><b>{}</b></span>",
			"days":       "<span color=\&'#ecc6d9\&'><b>{}</b></span>",
			"weeks":      "<span color=\&'#99ffdd\&'><b>W{}</b></span>",
			"weekdays":   "<span color=\&'#ffcc66\&'><b>{}</b></span>",
			"today":      "<span color=\&'#ff6699\&'><b><u>{}</u></b></span>"
		}
	},
	"actions": {
		"on\-click\-right": "mode",
		"on\-click\-forward": "tz_up",
		"on\-click\-backward": "tz_down",
		"on\-scroll\-up": "shift_up",
		"on\-scroll\-down": "shift_down"
	}
},
.fi
.RE
.PP
.SH "نویسنده (AUTHOR)"
.PP
Alexis Rouillard <contact@arouillard.\&fr>