Module: wibox.widget.calendar

A calendar widget.

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 example

Usage:

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

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 date The calendar date.
font string 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 The widget encapsulating function.
flex_height boolean Allow cells to have flexible height

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.


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.

Usage example

Parameters:

  • date Date of the calendar
    • year number Date year
    • month number Date month
    • day number or nil Date day
  • font string Font of the calendar (default "Monospace 10")

Returns:

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

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

Usage example

Parameters:

  • date Date of the calendar
    • year number Date year
    • month number or nil Date month
    • day number or nil Date day
  • font string Font of the calendar (default "Monospace 10")

Returns:

    widget The year calendar 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 date
The calendar date.

A table representing the date {day=[number|nil], month=[number|nil], year=[number]}.

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

Type constraints:

  • table date Date table.
font string
The calendar font.

Choose a monospace font for a better rendering.

Usage example

Type constraints:

  • string Font of the calendar (default "Monospace 10")

Usage:

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

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

Type constraints:

  • number Spacing of the grid (default 5)
week_numbers boolean
Display the calendar week numbers.

Usage example

Type constraints:

  • boolean Display week numbers (default false)

Usage:

    local cal = wibox.widget {
    date         = os.date("*t"),
    font         = "Monospace 10",
    week_numbers = true,
    widget       = wibox.widget.calendar.month
}
start_sunday boolean
Start the week on Sunday.

Usage example

Type constraints:

  • boolean Start the week on Sunday (default false)

Usage:

    local cal = wibox.widget {
    date         = os.date("*t"),
    font         = "Monospace 10",
    start_sunday = true,
    widget       = wibox.widget.calendar.month
}
long_weekdays boolean
Format the weekdays with three characters instead of two

Usage example

Type constraints:

  • boolean Use three characters for the weekdays instead of two (default false)

Usage:

    local cal = wibox.widget {
    date          = os.date("*t"),
    font          = "Monospace 10",
    long_weekdays = true,
    widget        = wibox.widget.calendar.month
}
fn_embed function
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:

Usage example

Type constraints:

  • function 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
Allow cells to have flexible height

Usage example

Type constraints:

  • boolean Allow flex height. (default false)

Usage:

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

Theme variables

beautiful.calendar_font string
The calendar font.

Type constraints:

  • font string Font of the calendar
beautiful.calendar_spacing number
The calendar spacing.

Type constraints:

  • spacing number Spacing of the grid (twice this value for inter-month spacing)
beautiful.calendar_week_numbers boolean
Display the calendar week numbers.

Type constraints:

  • boolean Display week numbers
beautiful.calendar_start_sunday boolean
Start the week on Sunday.

Type constraints:

  • boolean Start the week on Sunday
beautiful.calendar_long_weekdays boolean
Format the weekdays with three characters instead of two

Type constraints:

  • boolean Use three characters for the weekdays 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:

  • boolean Cells can skretch to fill the empty space.
generated by LDoc 1.4.6 Last updated 2021-11-13 00:35:50