diff --git a/docs/common/glib_timedate_format.ldoc b/docs/common/glib_timedate_format.ldoc new file mode 100644 index 00000000..5a9476dd --- /dev/null +++ b/docs/common/glib_timedate_format.ldoc @@ -0,0 +1,28 @@ +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +--
FormatDescription
%aThe abbreviated weekday name according to the current locale
%Athe full weekday name according to the current locale
%bThe abbreviated month name according to the current locale
%BThe full month name according to the current locale
%dThe day of the month as a decimal number (range 01 to 31)
%eThe day of the month as a decimal number (range 1 to 31)
%FEquivalent to %Y-%m-%d (the ISO 8601 date format)
%HThe hour as a decimal number using a 24-hour clock (range 00 to 23)
%IThe hour as a decimal number using a 12-hour clock (range 01 to 12)
%kThe hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank
%lThe hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank
%mThe month as a decimal number (range 01 to 12)
%MThe minute as a decimal number (range 00 to 59)
%pEither "AM" or "PM" according to the given time value, or the corresponding strings for the current locale. Noon is treated as "PM" and midnight as "AM".
%PLike %p but lowercase: "am" or "pm" or a corresponding string for the current locale
%rThe time in a.m. or p.m. notation
%RThe time in 24-hour notation (%H:%M)
%SThe second as a decimal number (range 00 to 60)
%TThe time in 24-hour notation with seconds (%H:%M:%S)
%yThe year as a decimal number without the century
%YThe year as a decimal number including the century
%%A literal % character
diff --git a/lib/wibox/widget/textclock.lua b/lib/wibox/widget/textclock.lua index 5dff77d6..2a4c2596 100644 --- a/lib/wibox/widget/textclock.lua +++ b/lib/wibox/widget/textclock.lua @@ -1,6 +1,42 @@ --------------------------------------------------------------------------- --- Text clock widget. -- +-- The `wibox.widget.textclock` widget is part of the Awesome WM's widget +-- system (see @{03-declarative-layout.md}). +-- +-- This widget displays a text clock formatted by the +-- [GLib Date Time format](https://developer.gnome.org/glib/stable/glib-GDateTime.html#g-date-time-format) +-- and [GTimeZone](https://developer.gnome.org/glib/stable/glib-GTimeZone.html#g-time-zone-new). +-- +-- The `wibox.widget.textclock` inherits from `wibox.widget.textbox`. It means +-- that, once created, the user will receive a derivated instance of +-- `wibox.widget.textbox` associated with a private `gears.timer` to manage +-- timed updates of the displayed clock. +-- +-- Use a `wibox.widget.textclock` +-- --- +-- +-- @DOC_wibox_widget_defaults_textclock_EXAMPLE@ +-- +-- Alternatively, you can declare the `textclock` widget using the +-- declarative pattern (Both codes are strictly equivalent): +-- +-- @DOC_wibox_widget_declarative-pattern_textclock_EXAMPLE@ +-- +-- The GLib DateTime format +-- --- +-- +-- The time displayed by the textclock widget can be formated by the GLib +-- DateTime format. +-- +-- Here is a short list with commonly used format specifiers (extracted from +-- the Glib API references): +-- +--@DOC_glib_timedate_format_COMMON@ +-- +-- You can read more on the GLib DateTime format in the +-- [GLib documentation](https://developer.gnome.org/glib/stable/glib-GDateTime.html#g-date-time-format). +-- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2009 Julien Danjou -- @widgetmod wibox.widget.textclock diff --git a/tests/examples/wibox/widget/declarative-pattern/textclock.lua b/tests/examples/wibox/widget/declarative-pattern/textclock.lua new file mode 100644 index 00000000..a53cc1f3 --- /dev/null +++ b/tests/examples/wibox/widget/declarative-pattern/textclock.lua @@ -0,0 +1,12 @@ +--DOC_NO_USAGE +local parent = ... --DOC_HIDE +local wibox = require("wibox") --DOC_HIDE + + local my_textclock = wibox.widget { + format = '%a %b %d, %H:%M', + widget = wibox.widget.textclock + } + +parent:add(my_textclock) --DOC_HIDE + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/widget/defaults/textclock.lua b/tests/examples/wibox/widget/defaults/textclock.lua new file mode 100644 index 00000000..716978bf --- /dev/null +++ b/tests/examples/wibox/widget/defaults/textclock.lua @@ -0,0 +1,10 @@ +--DOC_GEN_IMAGE +--DOC_NO_USAGE +local parent = ... --DOC_HIDE +local wibox = require("wibox") --DOC_HIDE + + local my_textclock = wibox.widget.textclock('%a %b %d, %H:%M') + +parent:add(my_textclock) --DOC_HIDE + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80