# 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