doc(wibox.widget.textclock): Widget definition.

docs/common/glib_timedate_format.ldoc

@@ -0,0 +1,28 @@
+--<table class='widget_list' border=1>
+-- <tr>
+--   <th align='center'>Format</th>
+--   <th align='center'>Description</th>
+-- </tr>
+--   <tr><td>%a</td><td>The abbreviated weekday name according to the current locale</td></tr>
+--   <tr><td>%A</td><td>the full weekday name according to the current locale</td></tr>
+--   <tr><td>%b</td><td>The abbreviated month name according to the current locale</td></tr>
+--   <tr><td>%B</td><td>The full month name according to the current locale</td></tr>
+--   <tr><td>%d</td><td>The day of the month as a decimal number (range 01 to 31)</td></tr>
+--   <tr><td>%e</td><td>The day of the month as a decimal number (range 1 to 31)</td></tr>
+--   <tr><td>%F</td><td>Equivalent to %Y-%m-%d (the ISO 8601 date format)</td></tr>
+--   <tr><td>%H</td><td>The hour as a decimal number using a 24-hour clock (range 00 to 23)</td></tr>
+--   <tr><td>%I</td><td>The hour as a decimal number using a 12-hour clock (range 01 to 12)</td></tr>
+--   <tr><td>%k</td><td>The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank</td></tr>
+--   <tr><td>%l</td><td>The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank</td></tr>
+--   <tr><td>%m</td><td>The month as a decimal number (range 01 to 12)</td></tr>
+--   <tr><td>%M</td><td>The minute as a decimal number (range 00 to 59)</td></tr>
+--   <tr><td>%p</td><td>Either "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".</td></tr>
+--   <tr><td>%P</td><td>Like %p but lowercase: "am" or "pm" or a corresponding string for the current locale</td></tr>
+--   <tr><td>%r</td><td>The time in a.m. or p.m. notation</td></tr>
+--   <tr><td>%R</td><td>The time in 24-hour notation (%H:%M)</td></tr>
+--   <tr><td>%S</td><td>The second as a decimal number (range 00 to 60)</td></tr>
+--   <tr><td>%T</td><td>The time in 24-hour notation with seconds (%H:%M:%S)</td></tr>
+--   <tr><td>%y</td><td>The year as a decimal number without the century</td></tr>
+--   <tr><td>%Y</td><td>The year as a decimal number including the century</td></tr>
+--   <tr><td>%%</td><td>A literal % character</td></tr>
+-- </table>

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

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

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