# 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 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.

  ### 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 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 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](../widgets/wibox.widget.textbox.html#font).
  string | : An [XFT string](https://wiki.archlinux.org/title/X_Logical_Font_Description), 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

  ### See also:

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

🔗 border_color color or table
  Set the calendar border color.

  ### 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.

  ### See also:

  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

🔗 empty_color color or nil · 1 theme variable
  Set the color for the empty cells.

  ### 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](../theme_related_libraries/gears.color.html).
  cairo.pattern | : Any valid [Cairo pattern](https://cairographics.org/manual/cairo-cairo-pattern-t.html).
  cairo.pattern | : A texture build from an image by [gears.color.create\_png\_pattern](../theme_related_libraries/gears.color.html#create_png_pattern)

  ### See also:

  empty_widget | Set a widget for the empty cells. | object properties
  empty_cell_mode | How should the cells outside of the current month should be handled. | object properties

  Click to display more

  ### 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`

  ### See also:

  empty_color | Set the color for the empty cells. | object properties
  empty_cell_mode | How should the cells outside of the current month should be handled. | object properties

🔗 empty_cell_mode string
  How should the cells outside of the current month should be handled.

  ### 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.

  ### See also:

  empty_widget | Set a widget for the empty cells. | object properties
  empty_color | Set the color for the empty cells. | object properties

## 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.

generated by LDoc 1.5.0