Module: awful.widget.calendar_popup

A popup wibox containing a wibox.widget.calendar widget.

Display a month or year calendar popup using calendar_popup.month or calendar_popup.year. The calendar style can be tweaked by providing tables of style properties at creation: style_year, style_month, style_yearheader, style_header, style_weekday, style_weeknumber, style_normal, style_focus (see cell_properties).

The wibox accepts arguments for the calendar widget: font, spacing, week_numbers, start_sunday, long_weekdays. It also accepts the extra arguments opacity, bg, screen and position. opacity and bg apply to the wibox itself, they are mainly useful to manage opacity by setting opacity for the false opacity or setting bg="#00000000" for compositor opacity. The screen argument forces the display of the wibox to this screen (instead of the focused screen by default). The position argument is a two-characters string describing the screen alignment "[vertical][horizontal]", e.g. "cc", "tr", "bl", ...

The wibox visibility can be changed calling the toggle method. The attach method adds mouse bindings to an existing widget in order to toggle the display of the wibox.

local month_calendar = awful.widget.calendar_popup.month()
month_calendar:attach( mytextclock, "tr" )
month_calendar:toggle()

Info:

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

Constructors

awful.widget.calendar_popup.month {[args]} A month calendar wibox.
awful.widget.calendar_popup.year {[args]} A year calendar wibox.

Object methods

:call_calendar (offset, position, screen) -> wibox Call the calendar with offset
:toggle () -> boolean Toggle calendar visibility.
:attach (widget, position, args) -> wibox Attach the calendar to a widget to display at a specific position.

Theme variables

beautiful.calendar_style cell_properties The generic calendar style table.

Tables

awful.widget.calendar_popup.cell_properties Cell properties.
awful.widget.calendar_popup.cell_flags Cell types (flags).


Constructors

🔗 awful.widget.calendar_popup.month {[args]} · 1 theme variable

A month calendar wibox.

It is highly customizable using the same options as for the widgets. The options are set once and for all at creation, though.

local mytextclock = wibox.widget.textclock()
local month_calendar = awful.widget.calendar_popup.month()
month_calendar:attach( mytextclock, "tr" )

Parameters:

Note: This constructors uses named parameters calling convention. It means you call it with {} and omit the parantheses. For example, calling this will all default argument would be month{}. This is a Lua shortcut syntax equivalent to month({}). args is only a placeholder name for the "lone table argument" used in named parameters calls.
Name Type(s) Description
args table Properties of the widget
position string Two-character position of the calendar in the screen
screen screen Screen where to display the calendar
opacity number Wibox opacity
bg string Wibox background color
font string Calendar font
spacing number Calendar spacing
margin number Margin around calendar widget
week_numbers boolean Show weeknumbers
start_sunday boolean Start week on Sunday
long_weekdays boolean Format the weekdays with three characters instead of two
style_month table Container style for the month calendar (see cell_properties)
style_header table Cell style for the month calendar header (see cell_properties)
style_weekday table Cell style for the weekday cells (see cell_properties)
style_weeknumber table Cell style for the weeknumber cells (see cell_properties)
style_normal table Cell style for the normal day cells (see cell_properties)
style_focus table Cell style for the current day cell (see cell_properties)

Returns:

    wibox A wibox containing the calendar

Click to display more

Consumed theme variables:

Theme variable Usage
beautiful.calendar_style
🔗 awful.widget.calendar_popup.year {[args]}

A year calendar wibox.

It is highly customizable using the same options as for the widgets. The options are set once and for all at creation, though.

globalkeys = gears.table.join(globalkeys, awful.key(
        { modkey, "Control" }, "c",  function () year_calendar:toggle() end))

Parameters:

Note: This constructors uses named parameters calling convention. It means you call it with {} and omit the parantheses. For example, calling this will all default argument would be year{}. This is a Lua shortcut syntax equivalent to year({}). args is only a placeholder name for the "lone table argument" used in named parameters calls.
Name Type(s) Description
args table Properties of the widget
position string Two-character position of the calendar in the screen
screen screen Screen where to display the calendar
opacity number Wibox opacity
bg string Wibox background color
font string Calendar font
spacing number Calendar spacing
margin number Margin around calendar widget
week_numbers boolean Show weeknumbers
start_sunday boolean Start week on Sunday
long_weekdays boolean Format the weekdays with three characters instead of two
style_year table Container style for the year calendar (see cell_properties)
style_month table Container style for the month calendar (see cell_properties). This field can also be called style_monthheader.
style_yearheader table Cell style for the year calendar header (see cell_properties)
style_header table Cell style for the month calendar header (see cell_properties)
style_weekday table Cell style for the weekday cells (see cell_properties)
style_weeknumber table Cell style for the weeknumber cells (see cell_properties)
style_normal table Cell style for the normal day cells (see cell_properties)
style_focus table Cell style for the current day cell (see cell_properties)

Returns:

    wibox A wibox containing the calendar

Object methods

🔗 :call_calendar (offset, position, screen) -> wibox
Call the calendar with offset

Parameters:

Name Type(s) Description
offset number Offset with respect to current month or year
position string Two-character position of the calendar in the screen
screen screen Screen where to display the calendar

Returns:

    wibox The wibox calendar
🔗 :toggle () -> boolean
Toggle calendar visibility.

Returns:

    boolean The new value of visible.
🔗 :attach (widget, position, args) -> wibox

Attach the calendar to a widget to display at a specific position. 

local mytextclock = wibox.widget.textclock()
local month_calendar = awful.widget.calendar_popup.month()
month_calendar:attach(mytextclock, 'tr')

Parameters:

Name Type(s) Description Default value
widget Widget to attach the calendar Not applicable
position Optional string Two characters string defining the position on the screen "tr"
args Optional table Additional options {}
on_hover Optional bool Show popup during mouse hover true

Returns:

    wibox The wibox calendar

Theme variables

🔗 beautiful.calendar_style cell_properties
The generic calendar style table.

Each table property can also be defined by beautiful.calendar_[flag]_[property]=val.

Type constraints:

Name Type(s) Description
table cell_properties Table of cell style properties

Click to display more

Used by:

  • month A month calendar wibox.

Tables

🔗 awful.widget.calendar_popup.cell_properties
Cell properties.

Fields:

Name Type(s) Description
markup Markup function or format string
fg_color Text foreground color
bg_color Text background color
shape Cell shape
padding Cell padding
border_width Calendar border width
border_color Calendar border color
opacity Cell opacity

Usage:

    local my_header_properties = {
    markup = function(text) return "<i>" .. text .. "</i>" end,
}
local my_options = { style_header = my_header_properties, }
local month_calendar = awful.widget.calendar_popup.month(my_options)
month_calendar:attach(my_text_clock, "tr")
🔗 awful.widget.calendar_popup.cell_flags
Cell types (flags).

Fields:

Name Type(s) Description
year Year calendar grid properties table
month Month calendar grid properties table
yearheader Year header cell properties table
header Month header cell properties table (called monthheader for a year calendar)
weekday Weekday cell properties table
weeknumber Weeknumber cell properties table
normal Normal day cell properties table
focus Current day cell properties table
generated by LDoc 1.5.0