.\" Generated by scdoc 1.11.3
.\" 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" "2024-05-06" "waybar-clock" "User Manual"
.PP
.SH NAME
.PP
waybar - clock module
.PP
.SH DESCRIPTION
.PP
\fBclock\fR module displays current date and time
.PP
.SH FILES
.PP
$XDG_CONFIG_HOME/waybar/config 
.br
	Per user configuration file
.PP
.SH CONFIGURATION
.PP
1.\& Addressed by \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.
T{
\fBOption\fR
T}	T{
\fBTypeof\fR
T}	T{
\fBDefault\fR
T}	T{
\fBDescription\fR
T}
T{
\fBinterval\fR
T}	T{
integer
T}	T{
60
T}	T{
The interval in which the information gets polled
T}
T{
\fBformat\fR
T}	T{
string
T}	T{
\fB{:%H:%M}\fR
T}	T{
The format, how the date and time should be displayed.\& See format options below
T}
T{
\fBtimezone\fR
T}	T{
string
T}	T{

T}	T{
The timezone to display the time in, e.\&g.\& America/New_York.\& "" represents the system'\&s local timezone.\& See Wikipedia'\&s unofficial list of timezones <https://en.\&wikipedia.\&org/wiki/List_of_tz_database_time_zones>
T}
T{
\fBtimezones\fR
T}	T{
list of strings
T}	T{

T}	T{
A list of timezones (as in \fBtimezone\fR) to use for time display, changed using the scroll wheel.\& Do not specify \fBtimezone\fR option when \fBtimezones\fR is specified.\& "" represents the system'\&s local timezone
T}
T{
\fBlocale\fR
T}	T{
string
T}	T{

T}	T{
A locale to be used to display the time.\& Intended to render times in custom timezones with the proper language and format
T}
T{
\fBmax-length\fR
T}	T{
integer
T}	T{

T}	T{
The maximum length in character the module should display
T}
T{
\fBrotate\fR
T}	T{
integer
T}	T{

T}	T{
Positive value to rotate the text label
T}
T{
\fBon-click\fR
T}	T{
string
T}	T{

T}	T{
Command to execute when clicked on the module
T}
T{
\fBon-click-middle\fR
T}	T{
string
T}	T{

T}	T{
Command to execute when you middle clicked on the module using mousewheel
T}
T{
\fBon-click-right\fR
T}	T{
string
T}	T{

T}	T{
Command to execute when you right-click on the module
T}
T{
\fBon-scroll-up\fR
T}	T{
string
T}	T{

T}	T{
Command to execute when scrolling up on the module
T}
T{
\fBon-scroll-down\fR
T}	T{
string
T}	T{

T}	T{
Command to execute when scrolling down on the module
T}
T{
\fBsmooth-scrolling-threshold\fR
T}	T{
double
T}	T{

T}	T{
Threshold to be used when scrolling
T}
T{
\fBtooltip\fR
T}	T{
bool
T}	T{
true
T}	T{
Option to enable tooltip on hover
T}
T{
\fBtooltip-format\fR
T}	T{
string
T}	T{
same as format
T}	T{
Tooltip on hover
T}
.TE
.sp 1
View all valid format options in \fBstrftime(3)\fR or have a look https://en.\&cppreference.\&com/w/cpp/chrono/duration/formatter
.PP
2.\& Addressed by \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.
T{
\fBOption\fR
T}	T{
\fBTypeof\fR
T}	T{
\fBDefault\fR
T}	T{
\fBDescription\fR
T}
T{
\fBmode\fR
T}	T{
string
T}	T{
month
T}	T{
Calendar view mode.\& Possible values: year|month
T}
T{
\fBmode-mon-col\fR
T}	T{
integer
T}	T{
3
T}	T{
Relevant for \fBmode=year\fR.\& Count of months per row
T}
T{
\fBweeks-pos\fR
T}	T{
integer
T}	T{

T}	T{
The position where week numbers should be displayed.\& Disabled when is empty.\& Possible values: left|right
T}
T{
\fBon-scroll\fR
T}	T{
integer
T}	T{
1
T}	T{
Value to scroll months/years forward/backward.\& Can be negative.\& Is configured under \fBon-scroll\fR option
T}
.TE
.sp 1
3.\& Addressed by \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{
\fBOption\fR
T}	T{
\fBTypeof\fR
T}	T{
\fBDefault\fR
T}	T{
\fBDescription\fR
T}
T{
\fBmonths\fR
T}	T{
string
T}	T{

T}	T{
Format is applied to months header(January, February,.\&.\&.\&etc.\&)
T}
T{
\fBdays\fR
T}	T{
string
T}	T{

T}	T{
Format is applied to days
T}
T{
\fBweeks\fR
T}	T{
string
T}	T{
\fB{:%U}\fR
T}	T{
Format is applied to week numbers.\& When weekday format is not provided then is used default format: '\&{:%W}'\& when week starts with Monday, '\&{:%U}'\& otherwise
T}
T{
\fBweekdays\fR
T}	T{
string
T}	T{

T}	T{
Format is applied to weeks header(Su,Mo,.\&.\&.\&etc.\&)
T}
T{
\fBtoday\fR
T}	T{
string
T}	T{
\fB<b><u>{}</u></b>\fR
T}	T{
Format is applied to Today
T}
.TE
.sp 1
.SS Actions
.PP
.TS
allbox;c c
l l
l l
l l
l l
l l.
T{
\fBString\fR
T}	T{
\fBAction\fR
T}
T{
\fBmode\fR
T}	T{
Switch calendar mode between year/month
T}
T{
\fBtz_up\fR
T}	T{
Switch to the next provided time zone
T}
T{
\fBtz_down\fR
T}	T{
Switch to the previously provided time zone
T}
T{
\fBshift_up\fR
T}	T{
Switch to the next calendar month/year
T}
T{
\fBshift_down\fR
T}	T{
Switch to the previous calendar month/year
T}
.TE
.sp 1
.SH FORMAT REPLACEMENTS
.PP
.PD 0
.IP \(bu 4
\fB{calendar}\fR: Current month calendar
.IP \(bu 4
\fB{tz_list}\fR: List of time in the rest timezones, if more than one timezone is set in the config
.IP \(bu 4
\fB{ordinal_date}\fR: The current day in (English) ordinal form, e.\&g.\& 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
.SH STYLE
.PP
.PD 0
.IP \(bu 4
\fB#clock\fR
.PD
.PP
.SH Troubleshooting
.PP
If clock module is disabled at startup with locale::facet::_S_create_c_locale 
.br
name not valid error message try one of the following:
.PP
.PD 0
.IP \(bu 4
check if LC_TIME is set properly (glibc)
.IP \(bu 4
set locale to C in the config file (musl)
.PD
.PP
The locale option must be set for {calendar} to use the correct start-of-week, regardless of system locale.\&
.PP
.SS Calendar in Chinese. Alignment
.PP
In order to have aligned Chinese calendar there are some useful recommendations:
.PP
.PD 0
.IP 1. 4
Use "WenQuanYi Zen Hei Mono" which is provided in most Linux distributions
.IP 2. 4
Try different font sizes and find best for you.\& size = 9pt should be fine
.IP 3. 4
In case when "WenQuanYi Zen Hei Mono" font is used disable monospace font pango tag
.PD
.PP
Example of working config
.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>