Module: `wibox.widget.calendar`

Display a monthly or yearly calendar.

This module defines two widgets: a month calendar and a year calendar

The two widgets have a date property, in the form of a table {day=[number|nil], month=[number|nil], year=[number]}.

The year widget displays the whole specified year, e.g. {year=2006}.

The month widget displays the calendar for the specified month, e.g. {month=12, year=2006}, highlighting the specified day if the day is provided in the date, e.g. {day=22, month=12, year=2006}.

Cell and container styles can be overridden using the fn_embed callback function which is called before adding the widgets to the layouts. The fn_embed function takes three arguments, the original widget, the flag (string used to identified the widget) and the date (table). It returns another widget, embedding (and modifying) the original widget.

Usage:

local cal = wibox.widget.calendar.month(os.date("*t"))
cal.border_width = 1

Info:

Copyright: 2017 getzze
Originally authored by: getzze
(Full contributors list available on our github project)

Constructors

wibox.widget.calendar.month (date, font)	A month calendar widget.
wibox.widget.calendar.year (date, font)	A year calendar widget.

Object properties

date	table or nil	The calendar date.
font	font	The calendar font.
spacing	number	The calendar spacing.
week_numbers	boolean	Display the calendar week numbers.
start_sunday	boolean	Start the week on Sunday.
long_weekdays	boolean	Format the weekdays with three characters instead of two
fn_embed	function or nil	The widget encapsulating function.
flex_height	boolean	Allow cells to have flexible height
border_width	integer or table	Set the calendar border width.
border_color	color or table	Set the calendar border color.
empty_color	color or nil	Set the color for the empty cells.
empty_widget	widget or nil	Set a widget for the empty cells.
empty_cell_mode	string	How should the cells outside of the current month should be handled.

Theme variables

beautiful.calendar_font	string	The calendar font.
beautiful.calendar_spacing	number	The calendar spacing.
beautiful.calendar_week_numbers	boolean	Display the calendar week numbers.
beautiful.calendar_start_sunday	boolean	Start the week on Sunday.
beautiful.calendar_long_weekdays	boolean	Format the weekdays with three characters instead of two
beautiful.flex_height	boolean	Allow cells to have flexible height.
beautiful.calendar_empty_color	color	Set the color for the empty space where there are no date widgets.

Constructors

🔗 wibox.widget.calendar.month (date, font)

A month calendar widget.

A calendar widget is a grid containing the calendar for one month. If the day is specified in the date, its cell is highlighted.

Parameters:

Name		Type(s)	Description	Default value
date		table	Date of the calendar	Not applicable
year		number	Date year	Not applicable
month		number	Date month	Not applicable
day		number or nil	Date day	Not applicable
font	Optional	string	Font of the calendar	`"Monospace 10"`

Returns:

widget

🔗 wibox.widget.calendar.year (date, font)

A year calendar widget.

A calendar widget is a grid containing the calendar for one year.

Parameters:

Name		Type(s)	Description	Default value
date		table	Date of the calendar	Not applicable
year		number	Date year	Not applicable
month		number or nil	Date month	Not applicable
day		number or nil	Date day	Not applicable
font	Optional	string	Font of the calendar	`"Monospace 10"`

Returns:

widget

Usage:

local cal = wibox.widget {
    date         = os.date("*t"),
    font         = "Monospace 8",
    spacing      = 2,
    week_numbers = false,
    start_sunday = false,
    widget       = wibox.widget.calendar.year
}

Object properties

🔗 date table or nil

The calendar date.

E.g.. {day=21, month=2, year=2005}, {month=2, year=2005}, {year=2005}

Constraints:

Default value	: `nil`
Type description:
nil	: The current date.
Table keys:
year (number)	: Date year
month (number\|nil)	: Date month
day (number\|nil)	: Date day

🔗 font font · 1 theme variable

The calendar font.

Choose a monospace font for a better rendering.

Constraints:

Default value	: `"Monospace 10"`
Type description:
string	: A Pango font description.
string	: An XFT string, such as `"--dejavu sans mono-medium-r-normal---80-----iso10646-1"`.
Valid values	: Font of the calendar

Usage:

local cal = wibox.widget.calendar.month(
    os.date("*t"), "sans 12")

Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.calendar_font

🔗 spacing number · 1 theme variable

The calendar spacing.

The spacing between cells in the month. The spacing between months in a year calendar is twice this value.

Constraints:

Default value	: `5`
Unit	: pixel
Negative allowed	: false
Valid values	: Spacing of the grid

Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.calendar_spacing

🔗 week_numbers boolean · 1 theme variable

Display the calendar week numbers.

Constraints:

Default value	: `false`
Valid values	: Display week numbers

Usage:

local cal = wibox.widget {
    date         = os.date("*t"),
    font         = "Monospace 10",
    week_numbers = true,
    widget       = wibox.widget.calendar.month
}

Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.calendar_week_numbers

🔗 start_sunday boolean · 1 theme variable

Start the week on Sunday.

Constraints:

Default value	: `false`
Valid values	: Start the week on Sunday

Usage:

local cal = wibox.widget {
    date         = os.date("*t"),
    font         = "Monospace 10",
    start_sunday = true,
    widget       = wibox.widget.calendar.month
}

Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.calendar_start_sunday

🔗 long_weekdays boolean · 1 theme variable

Format the weekdays with three characters instead of two

Constraints:

Default value	: `false`
Valid values	: Use three characters for the weekdays instead of two

Usage:

local cal = wibox.widget {
    date          = os.date("*t"),
    font          = "Monospace 10",
    long_weekdays = true,
    widget        = wibox.widget.calendar.month
}

Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.calendar_long_weekdays

🔗 fn_embed function or nil

The widget encapsulating function.

Function that takes a widget, flag (string) and date (table) as argument and returns a widget encapsulating the input widget.

Default value: function (widget, flag, date) return widget end

It is used to add a container to the grid layout and to the cells:

Constraints:

Default value	: `nil`
Type description:
nil	: Use an uncustomized wibox.widget.textbox.
Function prototype:
Parameters:
widget (widget)
flag (string)	: The type of widget. It is one of `"header"`, `"monthheader"`, `"weeknumber"` `"weekday"`, `"focus"`, `"month"` or `"normal"`.
date (table)	: A table with `day`, `month` and `year` keys.
Return (widget)	: A new widget to insert into the calendar.
Valid values	: Function to embed the widget depending on its flag.

Usage:

local styles = {}
local function rounded_shape(size, partial)
    if partial then
        return function(cr, width, height)
                   gears.shape.partially_rounded_rect(cr, width, height,
                        false, true, false, true, 5)
               end
    else
        return function(cr, width, height)
                   gears.shape.rounded_rect(cr, width, height, size)
               end
    end
end
styles.month   = { padding      = 5,
                   bg_color     = "#555555",
                   border_width = 2,
                   shape        = rounded_shape(10)
}
styles.normal  = { shape    = rounded_shape(5) }
styles.focus   = { fg_color = "#000000",
                   bg_color = "#ff9800",
                   markup   = function(t) return '<b>' .. t .. '</b>' end,
                   shape    = rounded_shape(5, true)
}
styles.header  = { fg_color = "#de5e1e",
                   markup   = function(t) return '<b>' .. t .. '</b>' end,
                   shape    = rounded_shape(10)
}
styles.weekday = { fg_color = "#7788af",
                   markup   = function(t) return '<b>' .. t .. '</b>' end,
                   shape    = rounded_shape(5)
}
local function decorate_cell(widget, flag, date)
    if flag=="monthheader" and not styles.monthheader then
        flag = "header"
    end
    local props = styles[flag] or {}
    if props.markup and widget.get_text and widget.set_markup then
        widget:set_markup(props.markup(widget:get_text()))
    end
    -- Change bg color for weekends
    local d = {year=date.year, month=(date.month or 1), day=(date.day or 1)}
    local weekday = tonumber(os.date("%w", os.time(d)))
    local default_bg = (weekday==0 or weekday==6) and "#232323" or "#383838"
    local ret = wibox.widget {
        {
            widget,
            margins = (props.padding or 2) + (props.border_width or 0),
            widget  = wibox.container.margin
        },
        shape        = props.shape,
        border_color = props.border_color or "#b9214f",
        border_width = props.border_width or 0,
        fg           = props.fg_color or "#999999",
        bg           = props.bg_color or default_bg,
        widget       = wibox.container.background
    }
    return ret
end
local cal = wibox.widget {
    date     = os.date("*t"),
    fn_embed = decorate_cell,
    widget   = wibox.widget.calendar.month
}

🔗 flex_height boolean · 1 theme variable

Allow cells to have flexible height

Constraints:

Default value	: `false`
Valid values	: Allow flex height.

Usage:

local cal = wibox.widget {
    date        = os.date("*t"),
    font        = "Monospace 10",
    flex_height = true,
    widget      = wibox.widget.calendar.month
}

Click to display more

Consumed theme variables:

Theme variable	Usage
beautiful.flex_height

🔗 border_width integer or table

Set the calendar border width.

Constraints:

Default value	: `0`
Type description:
color	: Use the same value for inner and outer borders.
table:	: Specify a different value for the inner and outer borders.
inner (color)	: The border between the cells.
outer (color)	: The border around the calendar.
Negative allowed	: false

Constraints:

Default value	: `0`
Type description:
color	: Use the same value for inner and outer borders.
table:	: Specify a different value for the inner and outer borders.
inner (color)	: The border between the cells.
outer (color)	: The border around the calendar.

Constraints:

Default value	: `nil`
Type description:
string	: An hexadecimal color code, such as `"#ff0000"` for red.
string	: A color name, such as `"red"`.
table	: A gradient table.
cairo.pattern	: Any valid Cairo pattern.
cairo.pattern	: A texture build from an image by gears.color.create_png_pattern

Consumed theme variables:

Theme variable	Usage
beautiful.calendar_empty_color

🔗 empty_widget widget or nil

Set a widget for the empty cells.

Constraints:

Default value : nil

Constraints:

Default value	: `"merged"`
Valid values:
`"merged"`	: Merge all cells and display the `empty_widget` or `empty_color`.
`"split"`	: Display one `empty_widget` per day rather than merge them.
`"rolling"`	: Display the dates from the previous or next month.

Theme variables

🔗 beautiful.calendar_font string

The calendar font.

Type constraints:

Name		Type(s)	Description
font		string	Font of the calendar

Click to display more

Used by:

font The calendar font.

🔗 beautiful.calendar_spacing number

The calendar spacing.

Type constraints:

Name		Type(s)	Description
spacing		number	Spacing of the grid (twice this value for inter-month spacing)

Click to display more

Used by:

spacing The calendar spacing.

🔗 beautiful.calendar_week_numbers boolean

Display the calendar week numbers.

Type constraints:

Name		Type(s)	Description
boolean			Display week numbers

Click to display more

Used by:

week_numbers Display the calendar week numbers.

🔗 beautiful.calendar_start_sunday boolean

Start the week on Sunday.

Type constraints:

Name		Type(s)	Description
boolean			Start the week on Sunday

Click to display more

Used by:

start_sunday Start the week on Sunday.

🔗 beautiful.calendar_long_weekdays boolean

Format the weekdays with three characters instead of two

Type constraints:

Name		Type(s)	Description
boolean			Use three characters for the weekdays instead of two

Click to display more

Used by:

long_weekdays Format the weekdays with three characters instead of two

🔗 beautiful.flex_height boolean

Allow cells to have flexible height. Flexible height allow cells to adapt their height to fill the empty space at the bottom of the widget.

Type constraints:

Name		Type(s)	Description
boolean			Cells can skretch to fill the empty space.

Click to display more

Used by:

flex_height Allow cells to have flexible height

🔗 beautiful.calendar_empty_color color

Set the color for the empty space where there are no date widgets.

This happens when the month doesn't start on a Sunday or stop on a Saturday.

Type constraints:

Name		Type(s)	Description
color			The empty area color.

Click to display more

Used by:

empty_color Set the color for the empty cells.

border_color	Set the calendar border color.	object properties
wibox.layout.grid.border_width	The border width. (wibox.layout.grid)	object properties

border_width	Set the calendar border width.	object properties
wibox.layout.grid.border_color	The border color for the table outer border. (wibox.layout.grid)	object properties

awesome

Contents

Widgets

Core components

Input handling

Declarative rules

Widget containers

Widget layouts

Popups and bars

Utility libraries

Theme related libraries

Libraries

Sample files

Classes

Documentation

Module: wibox.widget.calendar

Usage:

Info:

Constructors

Object properties

Theme variables

Constructors

Parameters:

Returns:

Parameters:

Returns:

Usage:

Object properties

Constraints:

Constraints:

Usage:

Consumed theme variables:

Constraints:

Consumed theme variables:

Constraints:

Usage:

Consumed theme variables:

Constraints:

Usage:

Consumed theme variables:

Constraints:

Usage:

Consumed theme variables:

Constraints:

Usage:

Constraints:

Usage:

Consumed theme variables:

Constraints:

See also:

Constraints:

See also:

Constraints:

See also:

Consumed theme variables:

Constraints:

See also:

Constraints:

See also:

Theme variables

Type constraints:

Used by:

Type constraints:

Used by:

Type constraints:

Used by:

Type constraints:

Used by:

Type constraints:

Used by:

Type constraints:

Used by:

Type constraints:

Used by:

Module: `wibox.widget.calendar`